Shared bindings between Scheme and C
====================================

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

Scheme shared binding interface
-------------------------------

 -- Scheme procedure: shared-binding? object returns boolean
 -- Scheme procedure: shared-binding-is-import? shared-binding returns boolean
     Shared-binding? is the disjoint type predicate for all shared bindings, imported or exported; shared-binding-is-import? returns true if SHARED-BINDING was imported into Scheme from C, and false if it has the converse direction.

 -- Scheme procedure: shared-binding-ref shared-binding returns value
 -- Scheme procedure: shared-binding-set! shared-binding value returns unspecified
     Shared-binding-ref returns the value of SHARED-BINDING; shared-binding-set! sets the value of SHARED-BINDING to be VALUE.

 -- Scheme procedure: lookup-imported-binding name returns shared-binding
 -- Scheme procedure: define-imported-binding name value returns unspecified
 -- Scheme procedure: undefine-imported-binding name returns unspecified
     Lookup-imported-binding returns the binding imported from C to Scheme with the given name; a binding is created if none exists. Define-imported-binding creates a new such binding, anomalously from within Scheme; such bindings are usually created instead from within C using the C s48_define_exported_binding function. Undefine-imported-binding removes the shared binding whose name is NAME from the table of imported bindings.

 -- Scheme procedure: lookup-exported-binding name returns shared-binding
 -- Scheme procedure: define-exported-binding name value returns unspecified
 -- Scheme procedure: undefine-exported-binding name returns unspecified
     Equivalents of the above three procedures, but for bindings exported from Scheme to C.  Define-imported-binding, unlike define-exported-binding, is customary to use in Scheme, as its intended use is to make a Scheme value available to C code from within Scheme.

 -- Scheme procedure: find-undefined-imported-bindings returns vector
     Returns a vector of all bindings imported into Scheme from C with undefined values, ie those created implicitly by lookups that have not yet been assigned rather than those created explicitly by the shared binding definers (define-exported-binding, etc).

C shared binding interface
--------------------------

 -- C macro: s48_value S48_SHARED_BINDING_P (s48_value OBJ)
 -- C macro: s48_value S48_SHARED_BINDING_NAME (s48_value SHARED_BINDING)
 -- C macro: s48_value S48_SHARED_BINDING_IS_IMPORTP (s48_value SHARED-BINDING)
 -- C macro: s48_value S48_SHARED_BINDING_REF (s48_value SHARED_BINDING)
 -- C macro: void S48_SHARED_BINDING_SET (s48_value SHARED_BINDING, s48_value VALUE)
     These macros are C counterparts to Scheme's shared-binding?, shared-binding-name, shared-binding-is-import?, shared-binding-ref, and shared-binding-set!, respectively.

 -- C macro: statement S48_SHARED_BINDING_CHECK (s48_value BINDING)
     Signals an exception if and only if BINDING's value is Scheme48's `unspecific' value.

     Huh?: Undefined shared bindings are not initialized with the `unspecific' value, but rather with an entirely different special token referred to internally as `undefined,' used in circumstances such as this --- yet S48_SHARED_BINDING_CHECK, as defined in scheme48.h, definitely checks whether BINDING's value is the `unspecific' value.

 -- C function: s48_value s48_get_imported_binding (char *NAME)
     Returns the shared binding defined in Scheme for NAME, creating it if necessary.

 -- C function: void s48_define_exported_binding (char *NAME, s48_value VALUE)
     Defines a shared binding named NAME with the value VALUE that can be accessed from Scheme.

 -- C macro: void S48_EXPORT_FUNCTION (FN)
     This is a convenience for the common case of exporting a C function to Scheme.  This expands into

          s48_define_exported_binding("FN",
                                      s48_enter_pointer(FN)) example

          which boxes the function into a Scheme48 byte vector and then exports
          it as a shared binding.  Note that s48_enter_pointer allocates
          space in the Scheme heap and may trigger a garbage collection;
          see Interacting with the Scheme heap in C.