Shared bindings

Shared bindings are the means by which named values are shared between Scheme code and C code. There are two separate tables of shared bindings, one for values defined in Scheme and accessed from C and the other for values going the other way. Shared bindings actually bind names to cells, to allow a name to be looked up before it has been assigned. This is necessary because C initialization code may be run before or after the corresponding Scheme code, depending on whether the Scheme code is in the resumed image or is run in the current session.

Exporting Scheme values to C

• (define-exported-binding name value) -> shared-binding 

• s48_value s48_get_imported_binding(char *name)
• s48_value S48_SHARED_BINDING_REF(s48_value shared_binding)

Define-exported-binding makes value available to C code under as name which must be a string, creating a new shared binding if necessary. The C function s48_get_imported_binding returns the shared binding defined for name, again creating it if necessary. The C macro S48_SHARED_BINDING_REF dereferences a shared binding, returning its current value.

Exporting C values to Scheme

• void s48_define_exported_binding(char *name, s48_value v)

• (lookup-imported-binding string) -> shared-binding 
• (shared-binding-ref shared-binding) -> value 

These are used to define shared bindings from C and to access them from Scheme. Again, if a name is looked up before it has been defined, a new binding is created for it.

The common case of exporting a C function to Scheme can be done using the macro S48_EXPORT_FUNCTION(name). This expands into

s48_define_exported_binding("name",
                               s48_enter_pointer(name))

which boxes the function into a Scheme byte vector and then exports it. Note that s48_enter_pointer allocates space in the Scheme heap and might trigger a garbage collection.

• (import-definition name)

  syntax

   

• (import-definition name c-name)

  syntax

(define name (lookup-imported-binding c-name))

where c-name is as supplied for the second form. For the first form c-name is derived from name by replacing `-' with `_' and converting letters to lowercase. For example, (import-definition my-foo) expands into

(define my-foo (lookup-imported-binding "my_foo"))

Complete shared binding interface

There are a number of other Scheme functions related to shared bindings; these are in the structure shared-bindings.

• (shared-binding? x) -> boolean 
• (shared-binding-name shared-binding) -> string 
• (shared-binding-is-import? shared-binding) -> boolean 
• (shared-binding-set! shared-binding value) 
• (define-imported-binding string value) 
• (lookup-exported-binding string) 
• (undefine-imported-binding string) 
• (undefine-exported-binding string) 

Shared-binding? is the predicate for shared-bindings. Shared-binding-name returns the name of a binding. Shared-binding-is-import? is true if the binding was defined from C. Shared-binding-set! changes the value of a binding. Define-imported-binding and lookup-exported-binding are Scheme versions of s48_define_exported_binding and s48_lookup_imported_binding. The two undefine- procedures remove bindings from the two tables. They do nothing if the name is not found in the table.

The following C macros correspond to the Scheme functions above.

• int S48_SHARED_BINDING_P(x)
• int S48_SHARED_BINDING_IS_IMPORT_P(s48_value s_b)
• s48_value S48_SHARED_BINDING_NAME(s48_value s_b)
• void S48_SHARED_BINDING_SET(s48_value s_b, s48_value v)

Previous: Shared bindings | Next: Shared bindings