% Part of Scheme 48 1.9.  See file COPYING for notices and license.

% Authors:
% Richard Kelsey, Marcus Crestani, Mike Sperber, Robert Ransom

\chapter{Mixing Scheme 48 and C}
\label{external-chapter}

This chapter describes the foreign-function interface for calling C
functions from Scheme, calling Scheme functions from C, and allocating
storage in the Scheme heap.  Scheme~48 manages stub functions in C
that negotiate between the calling conventions of Scheme and C and the
memory allocation policies of both worlds.  No stub generator is
available yet, but writing stubs is a straightforward task.

The foreign-function interface is modeled after the Java Native
Interface (JNI), more information can be found at
\urlhd{http://java.sun.com/javase/6/docs/technotes/guides/jni/index.html}{Sun's
  JNI Page}
{http://java.sun.com/javase/6/docs\-/technotes/guides/jni/index.html}.

Currently, Scheme~48 supports two foreign-function interfaces: The old
GCPROTECT-style and the new JNI-style interface (this chapter) live
side by side.  The old interface is deprecated and will go away in a
future release.  Section~\ref{sec:gcprotect-conversion-recipe} gives a
recipe how to convert external code from the old to the new interface.

\section{Available facilities}
\label{sec:facilities}

The following facilities are available for interfacing between
 Scheme~48 and C:
%
\begin{itemize}
\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 Scheme~48 to
  signal errors.
\item External code may call back into Scheme.  Scheme~48
  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}

The structure \code{external-calls} has 
 most of the Scheme functions described here.
The others are in 
 \code{load-dynamic-externals}, which has the functions for dynamic loading and
 name lookup from
Section~\ref{dynamic-externals},
 and \code{shared-bindings}, which has the additional shared-binding functions
 described in
section~\ref{more-shared-bindings}.


\subsection{C naming conventions}

The names of all of Scheme~48's visible C bindings begin with
`\code{s48\_}' (for procedures, variables, and macros).  Note that the
new foreign-function interface does not distinguish between procedures
and macros.  Whenever a C name is derived from a Scheme identifier, we
replace `\code{-}' with `\code{\_}' and convert letters to lowercase.
A final `\code{?}'  converted to `\code{\_p}', a final `\code{!}' is
dropped.  As a naming convention, all functions and macros of the new
foreign-function interface end in `\code{\_2}' (for now) to make them
distinguishable from the old interface's functions and macros.  Thus
the C macro for Scheme's \code{pair?} is \code{s48\_pair\_p\_2} and
the one for \code{set-car!}  is \code{s48\_set\_car\_2}.  Procedures
and macros that do not check the types of their arguments have
`\code{unsafe}' in their names.

All of the C functions and macros described have prototypes or
definitions in the file \code{c/scheme48.h}.


\subsection{Garbage collection and reference objects}
\label{sec:reference-objects}

Scheme~48 uses a precise, copying garbage collector.  The garbage
collector may run whenever an object is allocated in the heap.  The
collector must be able to locate all references to objects allocated
in the Scheme~48 heap in order to ensure that storage is not reclaimed
prematurely and to update references to objects moved by the
collector.  This interface takes care of communicating to the garbage
collector what objects it uses in most situations.  It relieves the
programmer from having to think about garbage collector interactions
in the common case.

This interface does not give external code direct access to Scheme
objects.  It introduces one level of indirection as external code never
accepts or returns Scheme values directly.  Instead, external code
accepts or returns \emph{reference objects} of type \code{s48\_ref\_t}
that refer to Scheme values (their C type is defined to be
\code{s48\_value}).  This indirection is only needed as an interface
to external code, interior pointers in Scheme objects are unaffected.

There are two types of reference objects:
%
\begin{description}
\item[local references] A local reference is valid for the duration of
  a function call from Scheme to external code and is automatically
  freed after the external function returns to the virtual machine.

\item[global references] A global reference remains valid until
  external code explicitly frees it.
\end{description}
%
Scheme objects that are passed to external functions are
passed as local references.  External functions return Scheme objects
as local references.  External code has to manually manage Scheme
objects that outlive a function call as global references.  Scheme
objects outlive a function call if they are assigned to a global
variable of the external code or stored in long-living external
objects, see section~\ref{sec:global-references}.

A local reference is valid only within the dynamic context of the
native method that creates it.  Therefore, a local reference behaves
exactly like a local variable in the external code: It is live as long
as external code can access it.  To achieve this, every external
function in the interface that accepts or returns reference objects
takes a \emph{call object} of type \code{s48\_call\_t} as its first
argument.  A call object corresponds to a particular call from Scheme
to C.  The call object holds all the references that belong to a call
(like the call's arguments and return value) to external code from
Scheme.  External code may pass a local reference through multiple
external functions.  The foreign-function interface automatically
frees all the local references a call object owns, along with the call
object itself, when an external call returns to Scheme.

This means that in the common case of Scheme calling an external
function that does some work on its arguments and returns without
stashing any Scheme objects in global variables or global data
structures, the external code does not need to do any bookkeeping,
since all the reference objects the external code accumulates are
local references.  Once the call returns, the foreign-function
interface frees all the local references.

For example, the functions to construct and access pairs are declared
like this:

\begin{protos}
\cproto{s48\_ref\_t s48\_cons\_2(s48\_call\_t call, s48\_ref\_t car, s48\_ref\_t cdr);}
\cproto{s48\_ref\_t s48\_car\_2(s48\_call\_t call, s48\_ref\_t pair);}
\cproto{s48\_ref\_t s48\_cdr\_2(s48\_call\_t call, s48\_ref\_t pair);}
\end{protos}

This foreign-function interface takes a significant burden off the
programmer as it handles most common cases automatically.  If all the
Scheme objects are live for the extent of the current external call,
the programmer does not have to do anything at all.  Since the
lifetime of the Scheme objects is then identical with the lifetime of
the according reference objects.  In this case, the systems
automatically manages both for the programmer.  Using this
foreign-function interface does not make the code more complex; the
code stays compact and readable.  The programmer has to get accustomed
to passing the call argument around.

How to manage Scheme objects that outlive the current call is described
in section~\ref{sec:global-references}.

Section~\ref{sec:gcprotect-conversion-recipe} gives a recipe how to
convert external code from the old GCPROTECT-style interface to the
new JNI-style interface.


\section{Shared bindings}
\label{sec: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.

\subsection{Exporting Scheme values to C}
\label{sec:export-scheme-to-c}

\begin{protos}
\proto{define-exported-binding}{ name value}{shared-binding}
\end{protos}

\begin{protos}
\cproto{s48\_ref\_t s48\_get\_imported\_binding\_2(char *name)}
\cproto{s48\_ref\_t s48\_get\_imported\_binding\_local\_2(s48\_call\_t call, char *name)}
\cproto{s48\_ref\_t s48\_shared\_binding\_ref\_2(s48\_call\_t call, s48\_ref\_t shared\_binding)}
\end{protos}

\noindent\code{Define-exported-binding} makes \cvar{value} available to C code
under \cvar{name}, which must be a \cvar{string}, creating a new
shared binding if necessary.  The C function
\code{s48\_get\_imported\_binding\_2} returns a global reference to
the shared binding defined for \code{name}, again creating it if
necessary, \code{s48\_get\_imported\_binding\_local\_2} returns a
local reference to the shared binding (see
section~\ref{sec:reference-objects} for details on reference objects).
The C macro \code{s48\_shared\_binding\_ref\_2} dereferences a shared
binding, returning its current value.

\subsection{Exporting C values to Scheme}
\label{sec:export-c-to-scheme}

Since shared bindings are defined during initialization, i.e. outside
an external call, there is no call object.  Therefore, exporting
shared bindings from C does not use the new foreign-function
interfaces specifications.

\begin{protos}
\cproto{void s48\_define\_exported\_binding(char *name, s48\_value v)}
\end{protos}

\begin{protos}
\proto{lookup-imported-binding}{ string}{shared-binding}
\proto{shared-binding-ref}{ shared-binding}{value}
\end{protos}

\noindent 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 \code{s48\_export\_function(\cvar{name})}.
This expands into
\begin{example}
s48\_define\_exported\_binding("\cvar{name}",
                               s48\_enter\_pointer(\cvar{name}))
\end{example}

\noindent which boxes the function pointer into a Scheme byte vector and then
 exports it.
Note that \code{s48\_enter\_pointer} allocates space in the Scheme heap
 and might trigger a 
garbage collection; see Section~\ref{gc}.

\begin{protos}
\syntaxprotonoresult{import-definition}{ \cvar{name}}
\syntaxprotonoresultnoindex{import-definition}{ \cvar{name c-name}}
\end{protos}
These macros simplify importing definitions from C to Scheme.
They expand into

\code{(define \cvar{name} (lookup-imported-binding \cvar{c-name}))}

\noindent{}where \cvar{c-name} is as supplied for the second form.
For the first form \cvar{c-name} is derived from \cvar{name} by
 replacing `\code{-}' with `\code{\_}' and converting letters to lowercase.
For example, \code{(import-definition my-foo)} expands into

\code{(define my-foo (lookup-imported-binding "my\_foo"))}

\subsection{Complete shared binding interface}
\label{more-shared-bindings}

There are a number of other Scheme functions related to shared bindings;
 these are in the structure \code{shared-bindings}.

\begin{protos}
\proto{shared-binding?}{ x}{boolean}
\proto{shared-binding-name}{ shared-binding}{string}
\proto{shared-binding-is-import?}{ shared-binding}{boolean}
\protonoresultnoindex{shared-binding-set!}{ shared-binding value}\mainschindex{shared-binding-set"!}
\protonoresult{define-imported-binding}{ string value}
\protonoresult{lookup-exported-binding}{ string}
\protonoresult{undefine-imported-binding}{ string}{}
\protonoresult{undefine-exported-binding}{ string}{}
\end{protos}

\noindent\code{Shared-binding?} is the predicate for shared-bindings.
\code{Shared-binding-name} returns the name of a binding.
\code{Shared-binding-is-import?} is true if the binding was defined from C.
\code{Shared-binding-set!} changes the value of a binding.
\code{Define-imported-binding} and \code{lookup-exported-binding} are
 Scheme versions of \code{s48\_define\_exported\_binding}
 and \code{s48\_lookup\_imported\_binding}.
The two \code{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.

\begin{protos}
\cproto{int\ \ \ \ \ \ \ s48\_shared\_binding\_p(s48\_call\_t call, x)}
\cproto{int\ \ \ \ \ \ \ s48\_shared\_binding\_is\_import\_p(s48\_call\_t call, s48\_ref\_t s\_b)}
\cproto{s48\_ref\_t s48\_shared\_binding\_name(s48\_call\_t call, s48\_ref\_t s\_b)}
\cproto{void\ \ \ \ \ \ s48\_shared\_binding\_set(s48\_call\_t call, s48\_ref\_t s\_b, s48\_ref\_t v)}
\end{protos}

\section{Calling C functions from Scheme}
\label{sec:external-call}

There are different ways to call C functions from Scheme, depending on
 how the C function was obtained.

\begin{protos}
\proto{call-imported-binding-2}{ binding arg$_0$ \ldots}{value}
\end{protos}
\noindent
Each of these applies its first argument, a C function that accepts
and/or returns objects of type \code{s48\_ref\_t} and has its first
argument of type \code{s48\_call\_t}, to the rest of the arguments.
For \code{call-imported-binding-2} the function argument must be an
imported binding.

For all of these, the interface passes the current call object and
 the \cvar{arg$_i$} values to the C function and the value returned is
 that returned by C procedure.
No automatic representation conversion occurs for either arguments or
 return values.
Up to twelve arguments may be passed.
There is no method supplied for returning multiple values to
 Scheme from C (or vice versa) (mainly because C does not have multiple return
 values).

Keyboard interrupts that occur during a call to a C function are ignored
 until the function returns to Scheme (this is clearly a
 problem; we are working on a solution).

\begin{protos}
\syntaxprotonoresult{import-lambda-definition-2}
{ \cvar{name} (\cvar{formal} \ldots)}
\syntaxprotonoresultnoindex{import-lambda-definition-2}
{ \cvar{name} (\cvar{formal} \ldots)\ \cvar{c-name}}
\end{protos}
\noindent{}These macros simplify importing functions from C that
 follow the return value and argument conventions of the
 foreign-function interface and use \code{s48\_call\_t} and
 \code{s48\_ref\_t} as their argument and return types.
They define \cvar{name} to be a function with the given formals that
 applies those formals to the corresponding C binding.
\cvar{C-name}, if supplied, should be a string.
These expand into

\begin{example}
(define temp (lookup-imported-binding \cvar{c-name}))
(define \cvar{name}
  (lambda (\cvar{formal} \ldots)
    (call-imported-binding-2 temp \cvar{formal} \ldots)))
\end{example}

\noindent{}
If \cvar{c-name} is not supplied, it is derived from \cvar{name} by converting
 all letters to lowercase and replacing `\code{-}' with `\code{\_}'.

\section{Dynamic loading}
\label{dynamic-externals}

External code can be loaded into a running Scheme~48---at least on
most variants of Unix and on Windows.  The required Scheme functions
are in the structure \code{load-dynamic-externals}.

To be suitable for dynamic loading, the externals code must reside in
a shared object.  The shared object must define a function:
%
\begin{protos}
  \cproto{void s48\_on\_load(void)}
\end{protos}
%
The \code{s48\_on\_load} is run upon loading the shared objects.  It
typically contains invocations of \code{S48\_EXPORT\_FUNCTION} to
make the functionality defined by the shared object known to
Scheme~48. 

The shared object may also define either or both of the following
functions:
%
\begin{protos}
   \cproto{void s48\_on\_unload(void)}
   \cproto{void s48\_on\_reload(void)}
\end{protos}
Scheme~48 calls \code{s48\_on\_unload} just before it unloads the
shared object.  If \code{s48\_on\_reload} is present, Scheme~48 calls
it when it loads the shared object for the second time, or some new
version thereof.  If it is not present, Scheme~48 calls
\code{s48\_on\_load} instead.  (More on that later.)

For Linux, the following commands compile \code{foo.c} into a file
\code{foo.so} that can be loaded dynamically.
\begin{example}
\% gcc -c -o foo.o foo.c
\% ld -shared -o foo.so foo.o
\end{example}
%
The following procedures provide the basic functionality for loading
shared objects containing dynamic externals:
%
\begin{protos}
\proto{load-dynamic-externals}{ string plete?
  rrepeat? rresume?}{dynamic-externals}
\proto{unload-dynamic-externals}{ string}{ dynamic-externals}
\protonoresult{reload-dynamic-externals}{ dynamic-externals}
\end{protos}
%
\code{Load-dynamic-externals} loads the named shared objects.  The
\cvar{plete?} argument determines whether Scheme~48 appends the
OS-specific suffix (typically \code{.so} for Unix, and \code{.dll} for
Windows) to the name.  The \cvar{rrepeat?}  argument determines how
\code{load-dynamic-externals} behaves if it is called again with the
same argument: If this is true, it reloads the shared object (and
calls its \code{s48\_on\_unload} on unloading if present, and, after
reloading, \code{s48\_on\_reload} if present or \code{s48\_on\_load}
if not), otherwise, it will not do anything.  The \cvar{rresume?}
argument determines if an image subsequently dumped will try to load
the shared object again automatically.  (The shared objects will be
loaded before any record resumers run.)  \code{Load-dynamic-externals}
returns a handle identifying the shared object just loaded.

\code{Unload-dynamic-externals} unloads the shared object associated
with the handle passed as its argument, previously calling its
\code{s48\_on\_unload} function if present.  Note that this invalidates
all external bindings associated with the shared object; referring to
any of them will probably crash the program.

\code{Reload-dynamic-externals} will reload the shared object named by
its argument and call its \code{s48\_on\_unload} function before
unloading, and, after reloading, \code{s48\_on\_reload} if present or
\code{s48\_on\_load} if not.

\begin{protos}
\proto{import-dynamic-externals}{ string}{dynamic-externals}  
\end{protos}
%
This procedure represents the expected most usage for loading
dynamic-externals.  It is best explained by its definition:
%
\begin{example}
(define (import-dynamic-externals name)
  (load-dynamic-externals name #t #f #t))
\end{example}

\section{Accessing Scheme data from C}
\label{sec:scheme-data}

The C header file \code{scheme48.h} provides
 access to Scheme~48 data structures.
The type \code{s48\_ref\_t} is used for reference objects that 
 refer to Scheme values.
When the type of a value is known, such as the integer returned
 by \code{vector-length} or the boolean returned by \code{pair?},
 the corresponding C procedure returns a C value of the appropriate
 type, and not a \code{s48\_ref\_t}.
Predicates return \code{1} for true and \code{0} for false.

\subsection{Constants}
\label{sec:constants}

The following macros denote Scheme constants:
%
\begin{itemize}
\item \code{s48\_false\_2(s48\_call\_t)} is \verb|#f|.
\item \code{s48\_true\_2(s48\_call\_t)} is \verb|#t|.
\item \code{s48\_null\_2(s48\_call\_t)} is the empty list.
\item \code{s48\_unspecific\_2(s48\_call\_t)} is a value used for functions which have no
  meaningful return value
 (in Scheme~48 this value returned by the nullary procedure \code{unspecific}
 in the structure \code{util}).
\item \code{s48\_eof\_2(s48\_call\_t)} is the end-of-file object
 (in Scheme~48 this value is returned by the nullary procedure \code{eof-object}
 in the structure \code{i/o-internal}).
\end{itemize}

\subsection{Converting values}

The following macros and functions convert values between Scheme and C
 representations.
The `extract' ones convert from Scheme to C and the `enter's go the other
 way.

\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_extract\_boolean\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{long\ \ \ \ \ \ s48\_extract\_char\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{char * \ \ \ s48\_extract\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{long \ \ \ \ \ s48\_extract\_long\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{long \ \ \ \ \ s48\_extract\_unsigned\_long\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{double \ \ \ s48\_extract\_double\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_enter\_boolean\_2(s48\_call\_t, int)}
\cproto{s48\_ref\_t s48\_enter\_char\_2(s48\_call\_t, long)}
\cgcproto{s48\_ref\_t s48\_enter\_byte\_vector\_2(s48\_call\_t, char *, long)}
\cgcproto{s48\_ref\_t s48\_enter\_long\_2(s48\_call\_t, long)}
\cgcproto{s48\_ref\_t s48\_enter\_long\_as\_fixnum\_2(s48\_call\_t, long)}
\cgcproto{s48\_ref\_t s48\_enter\_double\_2(s48\_call\_t, double)}
\end{protos}

\noindent{}\code{s48\_extract\_boolean\_2} is false if its argument is
 \code{\#f} and true otherwise.
 \code{s48\_enter\_boolean\_2} is \code{\#f} if its argument is zero
  and \code{\#t} otherwise.

The \code{s48\_extract\_char\_2} function extracts the scalar value from
a Scheme character as a C \code{long}.  Conversely,
\code{s48\_enter\_char\_2} creates a Scheme character from a scalar
value.  (Note that ASCII values are also scalar values.)

The \code{s48\_extract\_byte\_vector\_2} function needs to deal with
 the garbage collector to avoid invalidating the returned pointer.
 For more details see section~\ref{sec:byte-vectors}.

The second argument to \code{s48\_enter\_byte\_vector\_2} is the length of
 byte vector.

\code{s48\_enter\_long\_2()} needs to allocate storage when
 its argument is too large to fit in a Scheme~48 fixnum.
In cases where the number is known to fit within a fixnum (currently 30 
 bits on a 32-bits architecture and 62 bit on a 64-bits architecture 
 including the sign), the following procedures can be used.
These have the disadvantage of only having a limited range, but
 the advantage of never causing a garbage collection.
\code{s48\_fixnum\_p\_2(s48\_call\_t)} is a macro that true if its argument is a fixnum
 and false otherwise.

\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_fixnum\_p\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_enter\_long\_as\_fixnum\_2(s48\_call\_t, long)}
\cproto{long \ \ \ \ \ S48\_MAX\_FIXNUM\_VALUE}
\cproto{long \ \ \ \ \ S48\_MIN\_FIXNUM\_VALUE}
\end{protos}

\noindent An error is signaled if the argument to
 \code{s48\_enter\_fixnum} is less than \code{S48\_MIN\_FIXNUM\_VALUE}
 or greater than \code{S48\_MAX\_FIXNUM\_VALUE} ($-2^{29}$ and
 $2^{29}-1$ on a 32-bits architecture and $-2^{61}$ and $2^{62}-1$ on 
 a 64-bits architecture).

\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_true\_p\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{int \ \ \ \ \ \ s48\_false\_p\_2(s48\_call\_t, s48\_ref\_t)}
\end{protos}

\noindent \code{s48\_true\_p} is true if its argument is \code{s48\_true}
 and \code{s48\_false\_p} is true if its argument is \code{s48\_false}.

\begin{protos}
\cgcproto{s48\_ref\_t s48\_enter\_string\_latin\_1\_2(s48\_call\_t, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_latin\_1\_n\_2(s48\_call\_t, char*, long);}
\cproto{long\ \ \ \ \ \ s48\_string\_latin\_1\_length\_2(s48\_call\_t, s48\_ref\_t);}
\cproto{long\ \ \ \ \ \ s48\_string\_latin\_1\_length\_n\_2(s48\_call\_t, s48\_ref\_t, long, long);}
\cproto{void\ \ \ \ \ \ s48\_copy\_latin\_1\_to\_string\_2(s48\_call\_t, char*, s48\_ref\_t);}
\cproto{void\ \ \ \ \ \ s48\_copy\_latin\_1\_to\_string\_n\_2(s48\_call\_t, char*, long, s48\_ref\_t);}
\cproto{void\ \ \ \ \ \ s48\_copy\_string\_to\_latin\_1\_2(s48\_call\_t, s48\_ref\_t, char*);}
\cproto{void\ \ \ \ \ \ s48\_copy\_string\_to\_latin\_1\_n\_2(s48\_call\_t, s48\_ref\_t, long, long, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_utf\_8\_2(s48\_call\_t, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_utf\_8\_n\_2(s48\_call\_t, char*, long);}
\cproto{long\ \ \ \ \ \ s48\_string\_utf\_8\_length\_2(s48\_call\_t, s48\_ref\_t);}
\cproto{long\ \ \ \ \ \ s48\_string\_utf\_8\_length\_n\_2(s48\_call\_t, s48\_ref\_t, long, long);}
\cproto{long\ \ \ \ \ \ s48\_copy\_string\_to\_utf\_8\_2(s48\_call\_t, s48\_ref\_t, char*);}
\cproto{long\ \ \ \ \ \ s48\_copy\_string\_to\_utf\_8\_n\_2(s48\_call\_t, s48\_ref\_t, long, long, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_utf\_16be\_2(s48\_call\_t, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_utf\_16be\_n\_2(s48\_call\_t, char*, long);}
\cproto{long\ \ \ \ \ \ s48\_string\_utf\_16be\_length\_2(s48\_call\_t, s48\_ref\_t);}
\cproto{long\ \ \ \ \ \ s48\_string\_utf\_16be\_length\_n\_2(s48\_call\_t, s48\_ref\_t, long, long);}
\cproto{long\ \ \ \ \ \ s48\_copy\_string\_to\_utf\_16be\_2(s48\_call\_t, s48\_ref\_t, char*);}
\cproto{long\ \ \ \ \ \ s48\_copy\_string\_to\_utf\_16be\_n\_2(s48\_call\_t, s48\_ref\_t, long, long, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_utf\_16le\_2(s48\_call\_t, char*);}
\cgcproto{s48\_ref\_t s48\_enter\_string\_utf\_16le\_n\_2(s48\_call\_t, char*, long);}
\cproto{long\ \ \ \ \ \ s48\_string\_utf\_16le\_length\_2(s48\_call\_t, s48\_ref\_t);}
\cproto{long\ \ \ \ \ \ s48\_string\_utf\_16le\_length\_n\_2(s48\_call\_t, s48\_ref\_t, long, long);}
\cproto{long\ \ \ \ \ \ s48\_copy\_string\_to\_utf\_16le\_2(s48\_call\_t, s48\_ref\_t, char*);}
\cproto{long\ \ \ \ \ \ s48\_copy\_string\_to\_utf\_16le\_n\_2(s48\_call\_t, s48\_ref\_t, long, long, char*);}
\end{protos}
%
The \code{s48\_enter\_string\_latin\_1\_2} function creates a Scheme
string, initializing its contents from its NUL-terminated,
Latin-1-encoded argument.  The \code{s48\_enter\_string\_latin\_1\_n\_2}
function does the same, but allows specifying the length explicitly---no NUL
terminator is necessary.

The \code{s48\_string\_latin\_1\_length\_2} function computes the
length that the Latin-1 encoding of its argument (a Scheme string)
would occupy, not including NUL termination.  The
\code{s48\_string\_latin\_1\_length\_2} function does the same, but
allows specifying a starting index and a count into the input string.

The \code{s48\_copy\_latin\_1\_to\_string\_2} function copies
Latin-1-encoded characters from its second NUL-terminated argument to
the Scheme string that is its third argument.  The
\code{s48\_copy\_latin\_1\_to\_string\_n\_2} does the same, but allows
specifying the number of characters explicitly.  The
\code{s48\_copy\_string\_to\_latin\_1\_2} function converts the
characters of the Scheme string specified as the second argument into
Latin-1 and writes them into the string specified as the third
argument.  (Note that it does not NUL-terminate the result.)  The
\code{s48\_copy\_string\_to\_latin\_1\_n\_2} function does the same, but
allows specifying a starting index and a character count into the
source string.

The \code{s48\_extract\_latin\_1\_from\_string\_2} function returns a
buffer that contains the Latin-1 encoded characters including NUL
termination of the Scheme string specified.  The buffer that is
returned is a local buffer managed by the foreign-function interface
and is automatically freed on the return of the current call.

The \code{s48\_enter\_string\_utf\_8\_2} function creates a Scheme
string, initializing its contents from its NUL-terminated,
UTF-8-encoded argument.  The \code{s48\_enter\_string\_utf\_8\_n\_2}
function does the same, but allows specifying the length
explicitly---no NUL terminator is necessary.

The \code{s48\_string\_utf\_8\_length\_2} function computes the length
that the UTF-8 encoding of its argument (a Scheme string) would
occupy, not including NUL termination.  The
\code{s48\_string\_utf\_8\_length\_2} function does the same, but allows
specifying a starting index and a count into the input string.

The \code{s48\_copy\_string\_to\_utf\_8\_2} function converts the
characters of the Scheme string specified as the second argument into
UTF-8 and writes them into the string specified as the third
argument.  (Note that it does not NUL-terminate the result.)  The
\code{s48\_copy\_string\_to\_utf\_8\_n\_2} function does the same, but
allows specifying a starting index and a character count into the
source string.  Both return the length of the written encodings in
bytes.

The \code{s48\_extract\_utf\_8\_from\_string\_2} function returns a
buffer that contains the UTF-8 encoded characters including NUL
termination of the Scheme string specified.  The buffer that is
returned is a local buffer managed by the foreign-function interface
and is automatically freed on the return of the current call.

The functions with \code{utf\_16} in their names work analogously to
their \code{utf\_8} counterparts, but implement the UTF-16 encodings.
The lengths returned be the \code{\_length} and
\code{copy\_string\_to} functions are in terms of UTF-16 code units.
The \code{extract} function returns a local buffer that contains
UTF-16 code units including NUL termination.

\subsection{C versions of Scheme procedures}

The following macros and procedures are C versions of Scheme procedures.
The names were derived by replacing `\code{-}' with `\code{\_}',
 `\code{?}' with `\code{\_p}', and dropping `\code{!}.

\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_eq\_p\_2(s48\_call\_t, s48\_ref\_t, s48\_ref\_t)}
\cproto{int \ \ \ \ \ \ s48\_char\_p\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{int \ \ \ \ \ \ s48\_null\_p\_2(s48\_call\_t, s48\_ref\_t)}
\end{protos}
\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_pair\_p\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_car\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_cdr\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void \ \ \ \ \ s48\_set\_car\_2(s48\_call\_t, s48\_ref\_t, s48\_ref\_t)}
\cproto{void \ \ \ \ \ s48\_set\_cdr\_2(s48\_call\_t, s48\_ref\_t, s48\_ref\_t)}
\cgcproto{s48\_ref\_t s48\_cons\_2(s48\_call\_t, s48\_ref\_t, s48\_ref\_t)}
\cproto{long \ \ \ \ \ s48\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\end{protos}
\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_vector\_p\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{long \ \ \ \ \ s48\_vector\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{s48\_ref\_t s48\_vector\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_vector\_set\_2(s48\_call\_t, s48\_ref\_t, long, s48\_ref\_t)} 
\cgcproto{s48\_ref\_t s48\_make\_vector\_2(s48\_call\_t, long, s48\_ref\_t)}
\end{protos}
\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_string\_p\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{long \ \ \ \ \ s48\_string\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{long \ \ \ \ \ s48\_string\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_string\_set\_2(s48\_call\_t, s48\_ref\_t, long, long)} 
\cgcproto{s48\_ref\_t s48\_make\_string\_2(s48\_call\_t, long, char)}
\end{protos}
\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_symbol\_p\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{s48\_ref\_t s48\_symbol\_to\_string\_2(s48\_call\_t, s48\_ref\_t)} 
\end{protos}
\begin{protos}
\cproto{int \ \ \ \ \ \ s48\_byte\_vector\_p\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{long \ \ \ \ \ s48\_byte\_vector\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{char \ \ \ \ \ s48\_byte\_vector\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_byte\_vector\_set\_2(s48\_call\_t, s48\_ref\_t, long, int)} 
\cgcproto{s48\_ref\_t s48\_make\_byte\_vector\_2(s48\_call\_t, long, int)}
\end{protos}

\section{Calling Scheme functions from C}
\label{sec:external-callback}

External code that has been called from Scheme can call back to Scheme
 procedures using the following function.

\begin{protos}
\cproto{s48\_ref\_t s48\_call\_scheme\_2(s48\_call\_t, s48\_ref\_t p, long nargs, \ldots)}
\end{protos}
\noindent{}This calls the Scheme procedure \code{p} on \code{nargs}
 arguments, which are passed as additional arguments to \code{s48\_call\_scheme\_2}.
There may be at most twelve arguments.
The value returned by the Scheme procedure is returned by the C procedure.
Invoking any Scheme procedure may potentially cause a garbage collection.

There are some complications that occur when mixing calls from C to Scheme
 with continuations and threads.
C only supports downward continuations (via \code{longjmp()}).
Scheme continuations that capture a portion of the C stack have to follow the
 same restriction.
For example, suppose Scheme procedure \code{s0} captures continuation \code{a}
 and then calls C procedure \code{c0}, which in turn calls Scheme procedure
 \code{s1}.
Procedure \code{s1} can safely call the continuation \code{a}, because that
 is a downward use.
When \code{a} is called Scheme~48 will remove the portion of the C stack used
 by the call to \code{c0}.
On the other hand, if \code{s1} captures a continuation, that continuation
 cannot be used from \code{s0}, because by the time control returns to
 \code{s0} the C stack used by \code{c0} will no longer be valid.
An attempt to invoke an upward continuation that is closed over a portion
 of the C stack will raise an exception.

In Scheme~48 threads are implemented using continuations, so the downward
 restriction applies to them as well.
An attempt to return from Scheme to C at a time when the appropriate
 C frame is not on top of the C stack will cause the current thread to
 block until the frame is available.
For example, suppose thread \code{t0} calls a C procedure which calls back
 to Scheme, at which point control switches to thread \code{t1}, which also
 calls C and then back to Scheme.
At this point both \code{t0} and \code{t1} have active calls to C on the
 C stack, with \code{t1}'s C frame above \code{t0}'s.
If thread \code{t0} attempts to return from Scheme to C it will block,
 as its frame is not accessible.
Once \code{t1} has returned to C and from there to Scheme, \code{t0} will
 be able to resume.
The return to Scheme is required because context switches can only occur while
 Scheme code is running.
\code{T0} will also be able to resume if \code{t1} uses a continuation to
 throw past its call to C.

\section{Interacting with the Scheme heap}
\label{sec:heap-allocation}
\label{gc}

Scheme~48 uses a copying, precise garbage collector.
Any procedure that allocates objects within the Scheme~48 heap may trigger
 a garbage collection.

Local object references refer to values in the Scheme~48 heap and are
 automatically registered with the garbage collector by the interface
 for the duration of a function call from Scheme to C so that the
 values will be retained and the references will be updated if the
 garbage collector moves the object.

Global object references need to be created and freed explicitly for
 Scheme values that need to survive one function call, e.g. that are
 stored in global variables, global data structures or are passed to
 libraries.  See section~\ref{sec:global-references} for details.

Additionally, the interface provides \emph{local buffers} that are malloc'd regions
 of memory valid for the duration of a function call and are freed automatically upon
 return from the external code.  This relieves the programmer from explicitly freeing
 locally allocated memory.  See section~\ref{sec:local-bufs} for details.

The interface treats byte vectors in a special way, since the garbage
 collector has no facility for updating pointers to the interiors of
 objects, so that such pointers, for example the ones returned by
 \code{s48\_unsafe\_extract\_byte\_vector\_2}, will likely become
 invalid when a garbage collection occurs.  The interface provides a
 facility to prevent a garbage collection from invalidating pointers to
 byte vector's memory region, see section~\ref{sec:byte-vectors} for 
 details.

\subsection{Registering global references}
\label{sec:global-references}

When external code needs a reference object to survive the current
call, the external code needs to do explicit bookkeeping.  Local
references must not be stored in global variables of the external code
or passed to other threads, since all local references are freed once
the call returns, which leads to a dangling pointer in the global
variable or other thread respectively.  Instead, promote a local
reference to a global reference and store it in a global variable or
pass to another thread as global references will survive the current
call.  Since the foreign-function interface never automatically frees
global references, the programmer must free them at the right time.

\begin{protos}
\cproto{s48\_ref\_t s48\_make\_global\_ref(s48\_value obj)}
\cproto{void \ \ \ \ \ s48\_free\_global\_ref(s48\_ref\_t ref)}
\cproto{s48\_ref\_t s48\_local\_to\_global\_ref(s48\_ref\_t ref)}
\end{protos}

\noindent{}\code{s48\_make\_global\_ref} permanently registers the
Scheme value \cvar{obj} as a global reference with the garbage
collector.  Basic Scheme values are \code{\_s48\_value\_true},
\code{\_s48\_value\_false}, \code{\_s48\_value\_null},
\code{\_s48\_value\_unspecific}, \code{\_s48\_value\_undefined}, and
\code{\_s48\_value\_eof}.

To free a global reference an to unregister it with the
garbage collector, use \code{s48\_free\_global\_ref}.  The function
\code{s48\_local\_to\_global\_ref} promotes a local reference object
to a global reference object.

For example, to maintain a global list of values, declare a static
global variable

\begin{verbatim}
  s48_ref_t global_list = NULL;
\end{verbatim}

\noindent{}and initialize it in the external code's initialization function

\begin{verbatim}
  global_list = s48_make_global_ref(_s48_value_null);
\end{verbatim}

\noindent{}Note that you need to use a Scheme value (not a reference
object) as the argument for \code{s48\_make\_global\_ref}, since there
is not yet a call object at the time external code gets initialized.
To add \code{new\_value} to the list, you can use the following
snippet:

\begin{verbatim}
  temp = global_list;
  global_list =  s48_local_to_global_ref(s48_cons_2(call, new_value, global_list))
  s48_free_global_ref(temp);
\end{verbatim}

\noindent{}You have to remember to always promote reference objects to
global references when assigning to a global variable (and later, to
free them manually).  Note that it is more efficient to free the
previous head of the list when adding a new element to the list.

\subsection{Local buffers}
\label{sec:local-bufs}

The foreign-function interface supports the programmer with allocating
memory in external code: The programmer can request chunks of memory,
called local buffers, that are automatically freed on return from the
current call.

\begin{protos}
\cproto{void *s48\_make\_local\_buf (s48\_call\_t, size\_t)}
\cproto{void s48\_free\_local\_buf (s48\_call\_t, void *)}
\end{protos}

The function \code{s48\_make\_local\_buf} returns a block of memory of
the given size in bytes.  This memory freed by the foreign-function
interface when the current call returns.  To free the buffer manually,
use \code{s48\_free\_local\_buf}.

\subsection{Special treatment for byte vectors}
\label{sec:byte-vectors}

The interface treats byte vectors in a special way, since the garbage
collector has no facility for updating pointers to the interiors of
objects, so that such pointers, for example the ones returned by
\code{s48\_unsafe\_extract\_byte\_vector\_2}, will likely become
invalid when a garbage collection occurs.  The interface provides a
facility to prevent a garbage collection from invalidating pointers to
byte vector's memory region.  It does this by copying byte vectors
that are used in external code from and to the Scheme heap.

These functions create byte vectors:

\begin{protos}
\cgcproto{s48\_ref\_t s48\_make\_byte\_vector\_2(s48\_call\_t, long)}
\cgcproto{s48\_ref\_t s48\_make\_unmovable\_byte\_vector\_2(s48\_call\_t, long)}
\cgcproto{s48\_ref\_t s48\_enter\_byte\_vector\_2(s48\_call\_t, const char *, long)}
\cgcproto{s48\_ref\_t s48\_enter\_unmovable\_byte\_vector\_2(s48\_call\_t, const char *, long)}
\end{protos}

\code{s48\_make\_byte\_vector\_2} creates a byte vector of given size,
\code{s48\_make\_unmovable\_byte\_vector\_2} creates a byte vector in
that is not moved by the garbage collector (only the Bibop garbage
collector supports this).  The functions
\code{s48\_enter\_byte\_vector\_2} and
\code{s48\_enter\_unmovable\_byte\_vector\_2} create and initialize
byte vectors.

The following functions copy byte vectors from and to the Scheme heap:

\begin{protos}
\cproto{void s48\_extract\_byte\_vector\_region\_2(s48\_call\_t, s48\_ref\_t, long, long, char*)}
\cproto{void s48\_enter\_byte\_vector\_region\_2(s48\_call\_t, s48\_ref\_t, long, long, char*)}
\cproto{void s48\_copy\_from\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t, char *)}
\cproto{void s48\_copy\_to\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t, char *)}
\end{protos}

\code{s48\_extract\_byte\_vector\_region\_2} copies a given section
from the given byte vector to its last argument,
\code{s48\_enter\_byte\_vector\_region\_2} copies the contents of its
last argument to its first argument to the given index.
\code{s48\_copy\_from\_byte\_vector\_2} copies the whole byte vector
to its last argument, \code{s48\_copy\_to\_byte\_vector\_2} copies the
contents of its last argument to the byte vector.

\begin{protos}
\cproto{char *s48\_extract\_byte\_vector\_unmanaged\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void \ s48\_release\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t, char*)}
\end{protos}

\code{s48\_extract\_byte\_vector\_unmanaged\_2} returns a local buffer
that is valid during the current external call and copies the contents
of the given byte vector to the returned buffer.  The returned byte
vector may be a copy of the Scheme byte vector, changes made to the
returned byte vector will not necessarily be reflected in Scheme until
\code{s48\_release\_byte\_vector\_2} is called.

The following functions to access byte vectors come with the most
support from the foreign-function interface.  Byte vectors that are
accessed via these functions are automatically managed by the
interface and are copied back to Scheme on return from the current
call:

\begin{protos}
\cproto{char *s48\_extract\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{char *s48\_extract\_byte\_vector\_readonly\_2(s48\_call\_t, s48\_ref\_t)}
\end{protos}

\code{s48\_extract\_byte\_vector\_2} extracts a byte vector from
Scheme by making a copy of the byte vectors contents and returning a
pointer to that copy.  Changes to the byte vector are automatically
copied back to the Scheme heap when the function returns, external
code raises an exception, or external code calls a Scheme function.
\code{s48\_extract\_byte\_vector\_readonly\_2} should be used for byte
vectors that are not modified by external code, since these byte
vectors are not copied back to Scheme.

\subsection{Memory overhead}
\label{sec:memory-overhead}

Each reference object consumes a certain amount of memory itself, in
addition to the memory taken by the referred Scheme object itself.
Even though local references are eventually freed on return of an
external call, there are some situations where it is desirable to free
local references explicitly, since waiting until the call returns may
be too long or never happen, which could keep unneeded objects live:

\begin{itemize}
\item External code may create a large number of local references in a
  single external call.  An example is the traversal of a list: Each
  call from external code to the functions that correspond to
  \texttt{car} and \texttt{cdr} returns a fresh local reference.  To
  avoid the consumption of storage for local references proportional
  to the length of the list, the traversal must free the
  no-longer-needed references as it goes.

For example, this is a straightforward definition of an
  external function that calculates the length of a list:

\begin{verbatim}
  s48_ref_t
  s48_length_2(s48_call_t call, s48_ref_t list)
  {
    long i = 0;
    while (!(s48_null_p_2(call, list)))
      {
        list = s48_cdr_2(call, list);
        ++i;
      }
    return s48_unsafe_enter_long_as_fixnum_2(call, i);
  }
\end{verbatim}

  \noindent{}In this implementation, each iteration step creates a new
  local reference object via \code{s48\_cdr\_2} that is actually only
  needed for the next iteration step.  As a result, this function
  creates new local references for every element of the list.  The
  local references are live during the entire function call.

  To avoid consuming storage proportional to the length of the list
  for all those local reference objects, the improved version cleans
  up the unneeded local reference on every iteration step:

\begin{verbatim}
  s48_ref_t
  s48_length_2(s48_call_t call, s48_ref_t list)
  {
    s48_ref_t l = s48_copy_local_ref(call, list);
    long i = 0;
    while (!(s48_null_p_2(call, l)))
      {
        s48_ref_t temp = l;
        l = s48_cdr_2(call, l);
        s48_free_local_ref(call, temp);
        ++i;
      }
    return s48_unsafe_enter_long_as_fixnum_2(call, i);
  }
\end{verbatim}

  \noindent{}Note that without the call to
  \code{s48\_copy\_local\_ref} the reference to the head of the list
  would be freed along with all the temporary references.  This would
  render the whole list unusable after the return from \code{s48\_length\_2}.

\item The external call does not return at all.  If the external
  function enters an infinite event dispatch loop, for example, it is
  crucial that the programmer releases local references manually that
  he created inside the loop so that they do not accumulate
  indefinitely and lead to a memory leak.

\item External code may hold a local reference to a large Scheme
  object.  After the external code is done working on this object, it
  performs some additional computation before returning to the caller.
  The local reference to the large object prevents the object from
  being garbage collected until the external function returns, even if
  the object is no longer in use for the remainder of the computation.
  It is more space-efficient if the programmer frees the local
  reference when the external function does not need it any longer and
  will not return for quite some time.

\item There are common situations where local references are created
  solely to be passed to another function and afterwards never used
  again.  In this case, the called function can free the local
  references of the arguments.

\item To improve memory usage while making subcalls from external
  calls, the foreign-function interface provides functionality to
  create a new (sub-)call object and clean the local references that
  are created during that subcall:

  \begin{protos}
  \cproto{s48\_call\_t s48\_make\_subcall(s48\_call\_t call)}
  \cproto{void s48\_free\_subcall(s48\_call\_t subcall)}
  \cproto{s48\_ref\_t s48\_finish\_subcall(s48\_call\_t call, s48\_call\_t subcall, s48\_ref\_t ref)}
  \end{protos}

  \code{s48\_make\_subcall} returns a new call object that represents a
  subcall of the current call and can be passed as the call argument
  to any subcalls of the current call.  Upon return of a subcall,
  \code{s48\_free\_subcall} frees the subcall and all the local
  references associated with it.  The function {s48\_finish\_subcall}
  also frees the subcall and all the local references associated with
  it, but copies its third argument to the current call, so that it
  survives the subcall.

\end{itemize}

\subsection{Keeping C data structures in the Scheme heap}
\label{sec:external-data}

C data structures can be kept in the Scheme heap by embedding them
 inside byte vectors.
The following macros can be used to create and access embedded C objects.

\begin{protos}
\cgcproto{s48\_ref\_t s48\_make\_value\_2(s48\_call\_t, type)}
\cgcproto{s48\_ref\_t s48\_make\_sized\_value\_2(s48\_call\_t, size)}
\cproto{type \ \ \ \ \ s48\_extract\_value\_2(s48\_call\_t, s48\_ref\_t, type)}
\cproto{long \ \ \ \ \ s48\_value\_size\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{type * \ \ \ s48\_extract\_value\_pointer\_2(s48\_call\_t, s48\_ref\_t, type)}
\cproto{void \ \ \ \ \ s48\_set\_value\_2(s48\_call\_t, s48\_ref\_t, type, value)}
\end{protos}

\noindent{}
\code{s48\_make\_value\_2} makes a byte vector large enough to hold an object
whose type is \cvar{type}.
\code{s48\_make\_sized\_value\_2} makes a byte vector large enough to hold an object
of \cvar{size} bytes.
\code{s48\_extract\_value\_2} returns the contents of a byte vector cast to
 \cvar{type}, \code{s48\_value\_size\_2} returns its size,
and \code{s48\_extract\_value\_pointer\_2} returns a pointer to the
contents of the byte vector.
The value returned by \code{s48\_extract\_value\_pointer\_2} is valid only until
the next garbage collection.
\code{s48\_set\_value\_2} stores \code{value} into the byte vector.

Pointers to C data structures can be stored in the Scheme heap:

\begin{protos}
\cgcproto{s48\_ref\_t s48\_enter\_pointer\_2(s48\_call\_t, void *)}
\cgcproto{void * \ \ \ s48\_extract\_pointer\_2(s48\_call\_t, s48\_ref\_t)}
\end{protos}

\noindent{}The function \code{s48\_enter\_pointer\_2} makes a byte
vector large enough to hold the pointer value and stores the pointer
value in the byte vector.  The function
\code{s48\_extract\_pointer\_2} extracts the pointer value from the
scheme heap.

\subsection{C code and heap images}
\label{sec:hibernation}

Scheme~48 uses dumped heap images to restore a previous system state.
The Scheme~48 heap is written into a file in a machine-independent and
 operating-system-independent format.
The procedures described above may be used to create objects in the
 Scheme heap that contain information specific to the current
 machine, operating system, or process.
A heap image containing such objects may not work correctly
 when resumed.

To address this problem, a record type may be given a `resumer'
 procedure.
On startup, the resumer procedure for a type is applied to each record of
 that type in the image being restarted.
This procedure can update the record in a manner appropriate to
 the machine, operating system, or process used to resume the
 image.

\begin{protos}
\protonoresult{define-record-resumer}{ record-type procedure}
\end{protos}

\noindent{}\code{Define-record-resumer} defines \cvar{procedure},
 which should accept one argument, to be the resumer for
 \var{record-type}.
The order in which resumer procedures are called is not specified.

The \cvar{procedure} argument to \code{define-record-resumer} may
 be \code{\#f}, in which case records of the given type are
 not written out in heap images.
When writing a heap image any reference to such a record is replaced by
 the value of the record's first field, and an exception is raised
 after the image is written.

\section{Using Scheme records in C code}

External modules can create records and access their slots
 positionally.

\begin{protos}
\cgcproto{s48\_ref\_t s48\_make\_record\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{int \ \ \ \ \ \ s48\_record\_p\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{s48\_ref\_t s48\_record\_type\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{s48\_ref\_t s48\_record\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_record\_set\_2(s48\_call\_t, s48\_ref\_t, long, s48\_ref\_t)} 
\end{protos}
%
The argument to \code{s48\_make\_record\_2} should be a shared binding
 whose value is a record type.
In C the fields of Scheme records are only accessible via offsets,
 with the first field having offset zero, the second offset one, and
 so forth.
If the order of the fields is changed in the Scheme definition of the
 record type the C code must be updated as well.

For example, given the following record-type definition
\begin{example}
(define-record-type thing :thing
  (make-thing a b)
  thing?
  (a thing-a)
  (b thing-b))
\end{example}
 the identifier \code{:thing} is bound to the record type and can
 be exported to C:
\begin{example}
(define-exported-binding "thing-record-type" :thing)
\end{example}
\code{Thing} records can then be made in C:
\begin{example}
static s48_ref_t
  thing_record_type_binding = NULL;

void initialize_things(void)
\{
  thing_record_type_binding =
     s48_get_imported_binding_2("thing-record-type");
\}

s48_ref_t make_thing(s48_call_t call, s48_ref_t a, s48_ref_t b)
\{
  s48_ref_t thing;
  thing = s48_make_record_2(call, thing_record_type_binding);
  s48_record_set_2(call, thing, 0, a);
  s48_record_set_2(call, thing, 1, b);
  return thing;
\}
\end{example}
Note that the interface takes care of protecting all local references 
 against the possibility of a garbage collection occurring during
 the call to \code{s48\_make\_record\_2()}; also note that the record
 type binding is a global reference that is live until explicitly
 freed.

\section{Raising exceptions from external code}
\label{sec:exceptions}

The following macros explicitly raise certain errors, immediately
 returning to Scheme~48.
Raising an exception performs all
 necessary clean-up actions to properly return to Scheme~48, including
 adjusting the stack of protected variables.

The following procedures are available for raising particular
 types of exceptions.
These never return.

\begin{protos}
\cproto{s48\_assertion\_violation\_2(s48\_call\_t, const char* who, const char* message, long count, ...)}
\cproto{s48\_error\_2(s48\_call\_t, const char* who, const char* message, long count, ...)}
\cproto{s48\_os\_error\_2(s48\_call\_t, const char* who, const char* message, long count, ...)}
\cproto{s48\_out\_of\_memory\_error\_2(s48\_call\_t, )}
\end{protos}

\noindent{}An assertion violation signaled via
\code{s48\_assertion\_violation\_2} typically means that an invalid
argument (or invalid number of arguments) has been passed.  An error
signaled via \code{s48\_error\_2} means that an environmental error
(like an I/O error) has occurred.  In both cases, \code{who} indicates
the location of the error, typically the name of the function it
occurred in.  It may be \code{NULL}, in which the system guesses a
name.  The \code{message} argument is an error message encoded in
UTF-8.  Additional arguments may be passed that become part of the
condition object that will be raised on the Scheme side: \code{count}
indicates their number, and the arguments (which must be of type
\code{s48\_ref\_t}) follow.

The \code{s48\_os\_error\_2} function is like \code{s48\_error\_2}, except
that the error message is inferred from an OS error code (as in
\code{strerror}).  The \code{s48\_out\_of\_memory\_error\_2} function
signals that the system has run out of memory.

The following macros raise assertion violations if their argument does
not have the required type.  \code{s48\_check\_boolean\_2} raises an
error if its argument is neither \code{\#t} or \code{\#f}.

\begin{protos}
\cproto{void s48\_check\_boolean\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_symbol\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_pair\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_string\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_integer\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_channel\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_record\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void s48\_check\_shared\_binding\_2(s48\_call\_t, s48\_ref\_t)}
\end{protos}

\section{External events}

External code can push the occurrence of external events into the main
Scheme~48 event loop and Scheme code can wait and act on external
events.

On the Scheme side, the external events functionality consists of the
following functions from the structure \code{primitives}:

\begin{protos}
\proto{new-external-event-uid}{ shared-binding-or-\#f}{ uid}
\protonoresult{unregister-external-event-uid!}{ uid}
\end{protos}

\noindent{}And the following functions from the structure
\code{external-events}:

\begin{protos}
\protonoresult{register-condvar-for-external-event!}{ uid condvar}
\protonoresult{wait-for-external-event}{ condvar}
\proto{new-external-event}{}{ uid condvar}
\end{protos}

\noindent{}The function \code{new-external-event-uid} returns a fresh
event identifier on every call.  When called with a shared binding
instead of \code{\#f}, \code{new-external-event-uid} returns a named
event identifier for permanent use.  The function
\code{unregister-external-event-uid} unregisters the given event
identifier.

External events use condition variables to synchronize the occurrence
of events, see section~\ref{sec:condition-variables} for more
information on condition variables.  The function
\code{register-condvar-for-external-event} registers a condition
variable with an event identifier.  For convenience, the function
\code{new-external-event} combines \code{new-external-event-uid} and
\code{register-condvar-for-external-event} and returns a fresh event
identifier and the corresponding condition variable.

The function \code{wait-for-external-event} blocks the caller (on the
condition variable) until the Scheme main event loop receives an event
notification (by \code{s48\_note\_external\_event}) of the event
identifier that is registered with the given condition variable (with
\code{register-condvar-for-external-event}).  There is no guarantee
that the caller of \code{wait-for-external-event} is unblocked on
every event notification, therefore the caller has to be prepared to
handle multiple external events that have occurred and external code
has to be prepared to store multiple external events.

The following prototype is the interface on the external side:

\begin{protos}
\cproto{void s48\_note\_external\_event(long)}
\end{protos}

\noindent{}External code has to collect external events and can use
\code{s48\_note\_external\_event} to signal the occurrence of an
external event to the main event loop.  The argument to
\code{s48\_note\_external\_event} is an event identifier that was
previously registered on the Scheme side.  Thus, external code has to
obtain the event identifier from the Scheme side, either by passing
the event identifier as an argument to the external function that
calls \code{s48\_note\_external\_event} or by exporting the Scheme
value to C (see section~\ref{sec:export-scheme-to-c}).

Since the main event loop does not guarantee that every call to
\code{s48\_note\_external\_event} causes the just occurred event to
get handled immediately, external code has to make sure that it can
collect multiple external events (i.e. keep them in an appropriate
data structure).  It is safe for external code to call
\code{s48\_note\_external\_event} on every collected external event,
though, even if older events have not been handled yet.

\subsection{Collecting external events in external code}

External code has to be able to collect multiple events that have
occurred.  Therefore, external code has to create the needed data
structures to store the information that is associated with the
occurred event.  Usually, external code collects the events in a
thread.  An separate thread does not have an call argument, though, so
it cannot create Scheme data structures.  It must use C data
structures to collect the events, for example it can create a linked
list of events.

Since the events are later handled on the Scheme side, the information
associated with the event needs to be visible on the Scheme side, too.
Therefore, external code exports a function to Scheme that returns all
current events as Scheme objects (the function that returns the events
knows about the current call and thus can create Scheme objects).
Scheme and external code might need to share Scheme record types that
represent the event information.  Typically, the function that returns
the events converts the C event list into a Scheme event list by
preserving the original order in which the events arrived.  Note that
the external list data structure that holds all events needs to be
mutex locked on each access to preserve thread-safe manipulation of
the data structure (the Scheme thread that processes events and the
external thread that collects events may access the data structures at
the same time).

\subsection{Handling external events in Scheme}

If the sole occurrence of an event does not suffice for the program,
the Scheme side has to pull the information that is associated with an
event from the C side.  Then, the Scheme side can handle the event
data.  For example, a typical event loop on the Scheme side that waits
on external events of an permanent event type that an long-running
external thread produces may look like this:

\begin{verbatim}
(define *external-event-uid* 
  (new-external-event-uid (lookup-imported-binding "my-event")))

(spawn-external-thread *external-event-uid*)

(let loop ()
  (let ((condvar (make-condvar)))
    (register-condvar-for-external-event! *external-event-uid* condvar)
    (wait-for-external-event condvar)
    (process-external-events! (get-external-events))
    (loop)))
\end{verbatim}

\noindent{}In the above example, the variable
\code{*external-event-uid*} is defined as a permanent event
identifier.  On every pass through the loop, a fresh condition
variable is registered with the event identifier, then
\code{wait-for-external-event} blocks on the condition variable until
external code signals the occurrence of a matching event.  Note that
\code{process-external-events!} and \code{get-external-events} need to
be defined by the user.  The user-written function
\code{get-external-events} returns all the events that the external
code has collected since the last time \code{get-external-events} was
called; the user-written function \code{process-external-events!}
handles the events on the Scheme side.

When the Scheme side only waits for one single event, there is no need
for an event loop and an permanent event identifier.  Then,
\code{new-external-event} is more convenient to use:

\begin{verbatim}
(call-with-values
  (lambda () (new-external-event))
  (lambda (uid condvar)
    (spawn-external-thread uid)
    (wait-for-external-event condvar)
    (unregister-external-event-uid! uid)
    ...))
\end{verbatim}

\noindent{}Here, \code{new-external-event} returns a fresh event
identifier and a fresh condition variable.  The event identifier is
passed to \code{spawn-external-thread} and the condition variable is
used to wait for the occurrence of the external event.

External code uses \code{s48\_note\_external\_event} to push the fact
that an external event occurred into the main event loop, then the
Scheme code needs to pull the actual event data from external code (in
this example with \code{get-external-events}).  The user-written
function \code{spawn-external-thread} runs the external code that
informs the Scheme side about the occurrence of external events.  The
event identifier is passed as an argument.  The external-event-related
parts of the implementation of \code{spawn-external-thread} in
external code could look like this:

\begin{verbatim}
s48_ref_t
spawn_external_thread(s48_call_t call, s48_ref_t sch_event_uid) {
  ...
  s48_note_external_event(s48_extract_long_2(call, sch_event_uid));
  ...
}
\end{verbatim}

\noindent{}The event identifier is extracted from its Scheme
representation and used to inform the Scheme side about an occurrence
of this specific event type.

\section{Unsafe functions and macros}

All of the C procedures and macros described above check that their
 arguments have the appropriate types and that indexes are in range.
The following procedures and macros are identical to those described
 above, except that they do not perform type and range checks.
They are provided for the purpose of writing more efficient code;
 their general use is not recommended.

\begin{protos}
\cproto{long \ \ \ \ \ s48\_unsafe\_extract\_char\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_unsafe\_enter\_char\_2(s48\_call\_t, long)}
\cproto{long \ \ \ \ \ s48\_unsafe\_extract\_integer\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{long \ \ \ \ \ s48\_unsafe\_extract\_double\_2(s48\_call\_t, s48\_ref\_t)}
\end{protos}
\begin{protos}
\cproto{long \ \ \ \ \ s48\_unsafe\_extract\_fixnum\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_unsafe\_enter\_fixnum\_2(s48\_call\_t, long)}
\end{protos}
\begin{protos}
\cproto{s48\_ref\_t s48\_unsafe\_car\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{s48\_ref\_t s48\_unsafe\_cdr\_2(s48\_call\_t, s48\_ref\_t)}
\cproto{void \ \ \ \ \ s48\_unsafe\_set\_car\_2(s48\_call\_t, s48\_ref\_t, s48\_ref\_t)}
\cproto{void \ \ \ \ \ s48\_unsafe\_set\_cdr\_2(s48\_call\_t, s48\_ref\_t, s48\_ref\_t)}
\end{protos}
\begin{protos}
\cproto{long \ \ \ \ \ s48\_unsafe\_vector\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{s48\_ref\_t s48\_unsafe\_vector\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_unsafe\_vector\_set\_2(s48\_call\_t, s48\_ref\_t, long, s48\_ref\_t)} 
\end{protos}
\begin{protos}
\cproto{long \ \ \ \ \ s48\_unsafe\_string\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{char \ \ \ \ \ s48\_unsafe\_string\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_unsafe\_string\_set\_2(s48\_call\_t, s48\_ref\_t, long, char)} 
\end{protos}
\begin{protos}
\cproto{s48\_ref\_t s48\_unsafe\_symbol\_to\_string\_2(s48\_call\_t, s48\_ref\_t)} 
\end{protos}
\begin{protos}
\cproto{char * \ \ \ s48\_unsafe\_extract\_byte\_vector\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{long \ \ \ \ \ s48\_unsafe\_byte\_vector\_length\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{char \ \ \ \ \ s48\_unsafe\_byte\_vector\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_unsafe\_byte\_vector\_set\_2(s48\_call\_t, s48\_ref\_t, long, int)} 
\end{protos}

Additionally to not performing type checks, the pointer returned by
\code{s48\_unsafe\_extract\_byte\_vector\_2} will likely become
invalid when a garbage collection occurs.  See
section\ref{sec:byte-vectors} on how the interface deals with byte
vectors in a proper way.

\begin{protos}
\cproto{s48\_ref\_t s48\_unsafe\_shared\_binding\_ref\_2(s48\_call\_t, s48\_ref\_t s\_b)}
\cproto{int\ \ \ \ \ \ \ s48\_unsafe\_shared\_binding\_p\_2(s48\_call\_t, x)}
\cproto{int\ \ \ \ \ \ \ s48\_unsafe\_shared\_binding\_is\_import\_p\_2(s48\_call\_t, s48\_ref\_t s\_b)}
\cproto{s48\_ref\_t s48\_unsafe\_shared\_binding\_name\_2(s48\_call\_t, s48\_ref\_t s\_b)}
\cproto{void\ \ \ \ \ \ s48\_unsafe\_shared\_binding\_set\_2(s48\_call\_t, s48\_ref\_t s\_b, s48\_ref\_t value)}
\end{protos}
\begin{protos}
\cproto{s48\_ref\_t s48\_unsafe\_record\_type\_2(s48\_call\_t, s48\_ref\_t)} 
\cproto{s48\_ref\_t s48\_unsafe\_record\_ref\_2(s48\_call\_t, s48\_ref\_t, long)} 
\cproto{void \ \ \ \ \ s48\_unsafe\_record\_set\_2(s48\_call\_t, s48\_ref\_t, long, s48\_ref\_t)} 
\end{protos}
\begin{protos}
\cproto{type \ \ \ \ \ s48\_unsafe\_extract\_value\_2(s48\_call\_t, s48\_ref\_t, type)}
\cproto{type * \ \ \ s48\_unsafe\_extract\_value\_pointer\_2(s48\_call\_t, s48\_ref\_t, type)}
\cproto{void \ \ \ \ \ s48\_unsafe\_set\_value\_2(s48\_call\_t, s48\_ref\_t, type, value)}
\end{protos}


\section{Converting external code to the new foreign-function interface}
\label{sec:gcprotect-conversion-recipe}

It is straightforward to convert external code from the old
foreign-function interface to the new foreign-function interface:

\begin{itemize}
\item Converting functions:
  \begin{itemize}
  \item Add \code{s48\_call call} as a first argument to every
    function prototype that returns or accepts a \code{s48\_value}.

  \item Replace every \code{s48\_value} type in the function prototype
    and the body with \code{s48\_ref\_t}.

  \item Add \code{call} as the first argument to every function call
    that returns or accepts a Scheme object.

  \item Remove all the \code{GCPROTECT}-related code (i.e.
    \code{GCPROTECT} and \code{UNPROTECT}).
  \end{itemize}

\item Converting global (static) variables:
  \begin{itemize}
  \item Replace \code{s48\_value} type of the global variable with
    \code{s48\_ref\_t}, initialize these variables with \code{NULL}.

  \item Set a real Scheme object in the initialization function of
    your code with one of these alternatives:
    \begin{itemize}
    \item Use \code{s48\_make\_global\_ref} to convert a
      \code{s48\_value} to a global reference.  For details and an
      example see section~\ref{sec:global-references}.

    \item Use \code{s48\_local\_to\_global\_ref} to convert a local
      reference object to a global one.

    \item If your global variable is supposed to hold a shared binding
      (e.g. an record type binding), you can use
      \code{s48\_get\_imported\_binding\_2} that returns a global
      reference.
    \end{itemize}
  
  \item Replace \code{S48\_GC\_PROTECT\_GLOBAL} with
    \code{s48\_local\_to\_global\_ref} to convert a local reference
    object to a global one.
  
  \item Use \code{s48\_free\_global\_ref} to cleanup global references
    when appropriate.
  \end{itemize}
\end{itemize}

\noindent{}If you add \verb|#define NO_OLD_FFI 1| just above
\verb|#include <scheme48.h>| in your source code file, it will hide all
the macros and prototype definitions of the old foreign-function
interface.  That way you can make sure that you are only using the new
interface and the C compiler will remind you if you don't.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "manual"
%%% End: 
