Scheme 48 Manual -- Shared bindings

Scheme 48 Manual | Contents | In Chapter: Mixing Scheme 48 and C
Previous: Shared bindings | Next: Shared bindings

## 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

These macros simplify importing definitions from C to Scheme. They expand into

`(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