11.4.3 Calling back to Scheme

In order to arrange for a foreign library to callback to a Scheme function we need a suitable Scheme function and the signature of the procedure the foreign library expects. The signature must usually be hard–coded in the program.

Using the signature, the FFI determines how native values are converted to and from Scheme values; a signature is composed of two parts: a Scheme symbol specifying the return type, a list of Scheme symbols specifying the argument types. The signature format is the same as the one used for callouts; ffi call out for details.

Note that a callback function is indistinguishable from other native procedures whose address is obtained using dlsym or similar means. In particular, such native pointers can be passed to callout generators resulting in a Scheme procedure that calls out to the native procedure that in turn calls back into Scheme.

The following example shows how to create an identity function for native integers composed by a Scheme function calling out to a foreign function, calling back to the Scheme function values:

#!r6rs
(import (vicare)
  (prefix (vicare ffi) ffi::))

(define callout-maker
  (ffi::make-c-callout-maker  'unsigned-int '(unsigned-int)))

(define callback-maker
  (ffi::make-c-callback-maker 'unsigned-int '(unsigned-int)))

(define identity
  (callout-maker (callback-maker values)))

(identity 123)  ⇒ 123

using the FFI we build a callback function generator which can be used to create any number of callback functions having the same signature. Generated callback functions are not garbage collected like the other Scheme values.

Function: make-c-callback-maker ret-type arg-types

Build and return a function to be used to generate callback functions following the C language conventions for calling, arguments and return values and wrapping Scheme functions.

The returned generator function accepts as single argument the Scheme function to be wrapped; the value returned by the generator function is a pointer object referencing a native function. The wrapper native function takes care of marshaling Scheme values as appropriate for the underlying platform.

ret-type must be a Scheme symbol specifying the type of the returned value; if the callback function must return no value: ret-type must be the symbol void.

arg-types must be a list of Scheme symbols specifying the type of the arguments; if the callback function must accept no arguments: arg-types must be nil or the list (void).

ffi call types for the specification of accepted type symbols.

Function: free-c-callback c-callback-pointer

Release the resources associated to the given C pointer referencing a callback function. If the pointer is not a callback pointer: raise an assertion violation.

Function: c-callback? obj

Function: false-or-c-callback? obj

Return #t if obj is a callback pointer (or #f); otherwise return #f. These predicates only test if obj is a pointer object; at present there is no way to distinguish a callback pointer from a non–callback pointer.

Function: maybe-callback? obj

Return #t if obj is a callback object or #!void, return #f otherwise. This predicate only tests if obj is a pointer object; at present there is no way to distinguish a callback pointer from a non–callback pointer.