s48-refman/c-ffi/node.texi

@node C interface
@chapter C interface

@i{(This chapter was derived from work copyrighted @copyright{}
1993--2005 by Richard Kelsey, Jonathan Rees, and Mike Sperber.)}

@texonlyindent
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.

@menu
@include c-ffi/menu.texi
@end menu

@section Overview of the C interface

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

@itemize @bullet
@item Scheme code can call C functions.
@item The external interface provides full introspection for all Scheme
objects.  External code may inspect, modify, and allocate Scheme
objects arbitrarily.
@item External code may raise exceptions back to Scheme48 to signal
errors.
@item External code may call back into Scheme.  Scheme48 correctly
unrolls the process stack on non-local exits.
@item 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.
@end itemize

@subsection Scheme structures

@stindex external-calls
@stindex load-dynamic-externals
@stindex shared-bindings
@stindex dynamic-externals
On the Scheme side of the C interface, there are three pertinent
structures: @embedref{Shared bindings between Scheme and C,
@code{shared-bindings}}, which provides the Scheme side of the
facility for sharing data between Scheme and C; @embedref{Calling C
functions from Scheme, @code{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 @embedref{Dynamic loading of C modules,
@code{load-dynamic-externals}}, which provides a dynamic external
object loading facility.  Also, the old dynamic loading facility is
still available from the @code{dynamic-externals} structure, but its
use is deprecated, and it will most likely vanish in a later release.

@subsection C naming conventions

@cindex C naming conventions
Scheme48's C bindings all have strict naming conventions.  Variables
& procedures have @code{s48_} prefixed to them; macros, @code{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 @code{?}
suffix, generally appended to predicates, is converted to @code{_p} (or
@code{_P} in macro names).  Trailing @code{!} is dropped.  For example,
the C macro that corresponds with Scheme's @code{pair?} predicate is
named @code{S48_PAIR_P}, and the C macro to assign the car of a pair is
named @code{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 @file{c/scheme48.h} of Scheme48's standard
distribution.  The C type for Scheme values is defined there to be
@code{s48_value}.

@subsection 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, @pxref{Interacting with the Scheme
heap in C}.

@include c-ffi/shared.texi
@include c-ffi/c-from-scm.texi
@include c-ffi/dynload.texi
@include c-ffi/scm-from-c.texi
@include c-ffi/heap.texi
@include c-ffi/record.texi
@include c-ffi/extern-exn.texi
@include c-ffi/unsafe.texi