C interface
***********

(This chapter was derived from work copyrighted © 1993--2005 by Richard Kelsey, Jonathan Rees, and Mike Sperber.)

This chapter describes an interface for calling C functions from Scheme, calling Scheme procedures from C, and working with the Scheme heap in C.  Scheme48 manages stub functions in C that negotiate between the calling conventions of Scheme & C and the memory allocation policies of both worlds.  No stub generator is available yet, but writing stubs is a straightforward task.

Overview of the C interface
===========================

The following facilities are available for interfacing between Scheme48 & C:

  * Scheme code can call C functions.

  * The external interface provides full introspection for all Scheme objects.  External code may inspect, modify, and allocate Scheme objects arbitrarily.

  * External code may raise exceptions back to Scheme48 to signal errors.

  * External code may call back into Scheme.  Scheme48 correctly unrolls the process stack on non-local exits.

  * External modules may register bindings of names to values with a central registry accessible from Scheme.  Conversely, Scheme code can register shared bindings for access by C code.

Scheme structures
-----------------

On the Scheme side of the C interface, there are three pertinent structures: Shared bindings between Scheme and C, shared-bindings, which provides the Scheme side of the facility for sharing data between Scheme and C; Calling C functions from Scheme, external-calls, which exports several ways to call C functions from Scheme, along with some useful facilities, such as object finalizers, which are also available from elsewhere; and Dynamic loading of C modules, load-dynamic-externals, which provides a dynamic external object loading facility.  Also, the old dynamic loading facility is still available from the dynamic-externals structure, but its use is deprecated, and it will most likely vanish in a later release.

C naming conventions
--------------------

Scheme48's C bindings all have strict naming conventions.  Variables & procedures have s48_ prefixed to them; macros, S48_. Whenever a C name is derived from a Scheme identifier, hyphens are replaced with underscores.  Also, procedures or variables are converted to lowercase, while macros are converted to uppercase.  The ? suffix, generally appended to predicates, is converted to _p (or _P in macro names).  Trailing ! is dropped.  For example, the C macro that corresponds with Scheme's pair? predicate is named S48_PAIR_P, and the C macro to assign the car of a pair is named S48_SET_CAR.  Procedures and macros that do not verify the types of their arguments have `unsafe' in their names.

All of the C functions and macros described have prototypes or definitions in the file c/scheme48.h of Scheme48's standard distribution.  The C type for Scheme values is defined there to be s48_value.

Garbage collection
------------------

Scheme48 uses a copying garbage collector.  The collector must be able to locate all references to objects allocated in the Scheme48 heap in order to ensure that storage is not reclaimed prematurely and to update references to objects moved by the collector.  The garbage collector may run whenever an object is allocated in the heap.  C variables whose values are Scheme48 objects and which are live across heap allocation calls need to be registered with the garbage collector.  For more information, see Interacting with the Scheme heap in C.

     [file shared.texi not included]
     [file c-from-scm.texi not included]
     [file dynload.texi not included]
     [file scm-from-c.texi not included]
     [file heap.texi not included]
     [file record.texi not included]
     [file extern-exn.texi not included]
     [file unsafe.texi not included]