Obsolete.
This commit is contained in:
sperber
parent
2da600ffbb
commit
676cbbb8a8
|
|
@ -1,690 +0,0 @@
|
||||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
||||||
<HTML>
|
|
||||||
<!-- HTML file produced from file: external.tex --
|
|
||||||
-- using Hyperlatex v 2.3.1 (c) Otfried Cheong--
|
|
||||||
-- on Emacs 19.34.1, Tue Feb 23 18:21:44 1999 -->
|
|
||||||
<HEAD>
|
|
||||||
<TITLE>Mixing Scheme 48 and C</TITLE>
|
|
||||||
|
|
||||||
</HEAD><BODY>
|
|
||||||
|
|
||||||
|
|
||||||
<H1 ALIGN=CENTER>Using C code with Scheme 48</H1>
|
|
||||||
<H2 ALIGN=CENTER>Mike Sperber<BR><TT><FONT SIZE=-1>sperber@informatik.uni-tuebingen.de</FONT></TT><BR>Richard Kelsey<BR><TT><FONT SIZE=-1>kelsey@research.nj.nec.com</FONT></TT>
|
|
||||||
</H2>
|
|
||||||
<H3 ALIGN=CENTER>February 23, 1999</H3>
|
|
||||||
<H3 ALIGN=CENTER>Abstract</H3>
|
|
||||||
<BLOCKQUOTE>
|
|
||||||
This document describes an interface for calling C functions
|
|
||||||
from Scheme, calling Scheme functions from C, and allocating
|
|
||||||
storage in the Scheme heap.
|
|
||||||
These facilities are designed to link
|
|
||||||
existing C libraries into Scheme 48 in order to use them from Scheme.
|
|
||||||
To this end, 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 them is a straightforward task.
|
|
||||||
</BLOCKQUOTE>
|
|
||||||
<H1><A NAME="1">Available Facilities</A></H1>
|
|
||||||
|
|
||||||
<P>The following facilities are available for interfacing between
|
|
||||||
Scheme 48 and C:
|
|
||||||
<UL><LI>Scheme code can call C functions.
|
|
||||||
<LI>The external interface provides full introspection for all
|
|
||||||
Scheme objects. External code may inspect, modify, and allocate
|
|
||||||
Scheme objects arbitrarily.
|
|
||||||
<LI>External code may raise exceptions back to Scheme 48 to
|
|
||||||
signal errors.
|
|
||||||
<LI>External code may call back into Scheme. Scheme 48
|
|
||||||
correctly unrolls the process stack on non-local exits.
|
|
||||||
<LI>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.
|
|
||||||
</UL>
|
|
||||||
This document has three parts: the first describes how bindings are
|
|
||||||
moved from Scheme to C and vice versa, the second tells how to call
|
|
||||||
C functions from Scheme, and the third covers the C interface
|
|
||||||
to Scheme objects, including calling Scheme procedures, using the
|
|
||||||
Scheme heap, and so forth.
|
|
||||||
<H2><A NAME="2">Scheme structures</A></H2>
|
|
||||||
<P>The structure <CODE>external-calls</CODE> has
|
|
||||||
most of the Scheme functions described here.
|
|
||||||
The others are in
|
|
||||||
<CODE>dynamic-externals</CODE>, which has the functions for dynamic loading and
|
|
||||||
name lookup from
|
|
||||||
|
|
||||||
the section on <A HREF="#dynamic-externals">Dynamic Loading</A>,
|
|
||||||
and <CODE>shared-bindings</CODE>, which has the additional shared-binding functions
|
|
||||||
described in
|
|
||||||
|
|
||||||
the section on the <A HREF="#more-shared-bindings">complete shared-binding interface</A>.
|
|
||||||
<H2><A NAME="3">C naming conventions</A></H2>
|
|
||||||
<P>The names of all of Scheme 48's visible C bindings begin
|
|
||||||
with `<CODE>s48_</CODE>' (for procedures and variables) or
|
|
||||||
`<CODE>S48_</CODE>' (for macros).
|
|
||||||
Whenever a C name is derived from a Scheme identifier, we
|
|
||||||
replace `<CODE>-</CODE>' with `<CODE>_</CODE>' and convert letters to lowercase
|
|
||||||
for procedures and uppercase for macros.
|
|
||||||
A final `<CODE>?</CODE>' converted to `<CODE>_p</CODE>' (`<CODE>_P</CODE>' in C macro names).
|
|
||||||
A final `<CODE>!</CODE>' is dropped.
|
|
||||||
Thus the C macro for Scheme's <CODE>pair?</CODE> is <CODE>S48_PAIR_P</CODE> and
|
|
||||||
the one for <CODE>set-car!</CODE> is <CODE>S48_SET_CAR</CODE>.
|
|
||||||
Procedures and macros that do not check the types of their arguments
|
|
||||||
have `<CODE>unsafe</CODE>' in their names.
|
|
||||||
<P>All of the C functions and macros described have prototypes or definitions
|
|
||||||
in the file <CODE>c/scheme48.h</CODE>.
|
|
||||||
The C type for Scheme values is defined there to be <CODE>s48_value</CODE>.
|
|
||||||
<H1><A NAME="4">Shared bindings</A></H1>
|
|
||||||
|
|
||||||
<P>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.
|
|
||||||
<H2><A NAME="5">Exporting Scheme values to C</A></H2>
|
|
||||||
<UL><LI><CODE>(define-exported-binding<I> name value</I>) -> <I>shared-binding</I></CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>s48_value s48_get_imported_binding(char *name)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_SHARED_BINDING_REF(s48_value shared_binding)</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>Define-exported-binding</CODE> makes <CODE><I>value</I></CODE> available to C code
|
|
||||||
under as <CODE><I>name</I></CODE> which must be a <CODE><I>string</I></CODE>, creating a new shared
|
|
||||||
binding if necessary.
|
|
||||||
The C function <CODE>s48_get_imported_binding</CODE> returns the shared binding
|
|
||||||
defined for <CODE>name</CODE>, again creating it if necessary.
|
|
||||||
The C macro <CODE>S48_SHARED_BINDING_REF</CODE> dereferences a shared binding,
|
|
||||||
returning its current value.
|
|
||||||
<H2><A NAME="6">Exporting C values to Scheme</A></H2>
|
|
||||||
<UL><LI><CODE>void s48_define_exported_binding(char *name, s48_value value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>(lookup-imported-binding<I> string</I>) -> <I>shared-binding</I></CODE>
|
|
||||||
<LI><CODE>(shared-binding-ref<I> shared-binding</I>) -> <I>value</I></CODE>
|
|
||||||
</UL>
|
|
||||||
<P>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.
|
|
||||||
<P>The common case of exporting a C function to Scheme can be done using
|
|
||||||
the macro <CODE>S48_EXPORT_FUNCTION(<EM>name</EM>)</CODE>.
|
|
||||||
This expands into
|
|
||||||
<P><CODE>s48_define_exported_binding("<CODE><I>name</I></CODE>", s48_enter_pointer(<CODE><I>name</I></CODE>))</CODE>
|
|
||||||
<P>which boxes the function into a Scheme byte vector and then
|
|
||||||
exports it.
|
|
||||||
Note that <CODE>s48_enter_pointer</CODE> allocates space in the Scheme heap
|
|
||||||
and might trigger a
|
|
||||||
<A HREF="#gc">garbage collection</A>.
|
|
||||||
<UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>(import-definition <CODE><I>name</I></CODE>)</CODE></td> <td align=right>syntax</td></tr></table>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>(import-definition <CODE><I>name c-name</I></CODE>)</CODE></td> <td align=right>syntax</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
These macros simplify importing definitions from C to Scheme.
|
|
||||||
They expand into
|
|
||||||
<P><CODE>(define <CODE><I>name</I></CODE> (lookup-imported-binding <CODE><I>c-name</I></CODE>))</CODE>
|
|
||||||
<P>where <CODE><I>c-name</I></CODE> is as supplied for the second form.
|
|
||||||
For the first form <CODE><I>c-name</I></CODE> is derived from <CODE><I>name</I></CODE> by
|
|
||||||
replacing `<CODE>-</CODE>' with `<CODE>_</CODE>' and converting letters to lowercase.
|
|
||||||
For example, <CODE>(import-definition my-foo)</CODE> expands into
|
|
||||||
<P><CODE>(define my-foo (lookup-imported-binding "my_foo"))</CODE>
|
|
||||||
<H2><A NAME="more-shared-bindings">Complete shared binding interface</A></H2>
|
|
||||||
|
|
||||||
<P>There are a number of other Scheme functions related to shared bindings;
|
|
||||||
these are in the structure <CODE>shared-bindings</CODE>.
|
|
||||||
<UL><LI><CODE>(shared-binding?<I> x</I>) -> <I>boolean</I></CODE>
|
|
||||||
<LI><CODE>(shared-binding-name<I> shared-binding</I>) -> <I>string</I></CODE>
|
|
||||||
<LI><CODE>(shared-binding-is-import?<I> shared-binding</I>) -> <I>boolean</I></CODE>
|
|
||||||
<LI><CODE>(shared-binding-set!<I> shared-binding value</I>)</CODE>
|
|
||||||
<LI><CODE>(define-imported-binding<I> string value</I>)</CODE>
|
|
||||||
<LI><CODE>(lookup-exported-binding<I> string</I>)</CODE>
|
|
||||||
<LI><CODE>(undefine-imported-binding<I> string</I>)</CODE>
|
|
||||||
<LI><CODE>(undefine-exported-binding<I> string</I>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>Shared-binding?</CODE> is the predicate for shared-bindings.
|
|
||||||
<CODE>Shared-binding-name</CODE> returns the name of a binding.
|
|
||||||
<CODE>Shared-binding-is-import?</CODE> is true if the binding was defined from C.
|
|
||||||
<CODE>Shared-binding-set!</CODE> changes the value of a binding.
|
|
||||||
<CODE>Define-imported-binding</CODE> and <CODE>lookup-exported-binding</CODE> are
|
|
||||||
Scheme versions of <CODE>s48_define_exported_binding</CODE>
|
|
||||||
and <CODE>s48_lookup_imported_binding</CODE>.
|
|
||||||
The two <CODE>undefine-</CODE> procedures remove bindings from the two tables.
|
|
||||||
They do nothing if the name is not found in the table.
|
|
||||||
<P>The following C macros correspond to the Scheme functions above.
|
|
||||||
<UL><LI><CODE>int S48_SHARED_BINDING_P(x)</CODE>
|
|
||||||
<LI><CODE>int S48_SHARED_BINDING_IS_IMPORT_P(s48_value s_b)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_SHARED_BINDING_NAME(s48_value s_b)</CODE>
|
|
||||||
<LI><CODE>void S48_SHARED_BINDING_SET(s48_value s_b, s48_value value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<H1><A NAME="8">Calling C Functions from Scheme</A></H1>
|
|
||||||
|
|
||||||
<P>There are three different ways to call C functions from Scheme, depending on
|
|
||||||
how the C function was obtained.
|
|
||||||
<UL><LI><CODE>(call-imported-binding<I> binding arg<I><sub>0</sub></I> ...</I>) -> <I>value</I></CODE>
|
|
||||||
<LI><CODE>(call-external<I> external arg<I><sub>0</sub></I> ...</I>) -> <I>value</I></CODE>
|
|
||||||
<LI><CODE>(call-external-value<I> value name arg<I><sub>0</sub></I> ...</I>) -> <I>value</I></CODE>
|
|
||||||
</UL>
|
|
||||||
Each of these applies its first argument, a C function, to the rest of
|
|
||||||
the arguments.
|
|
||||||
For <CODE>call-imported-binding</CODE> the function argument must be an
|
|
||||||
imported binding.
|
|
||||||
For <CODE>call-external</CODE> the function argument must be an external
|
|
||||||
bound in the current process
|
|
||||||
(see
|
|
||||||
|
|
||||||
the section on <A HREF="#dynamic-externals">Dynamic Loading</A>).
|
|
||||||
For <CODE>call-external-value</CODE> <CODE><I>value</I></CODE> must be a byte vector
|
|
||||||
whose contents is a pointer to a C function and <CODE><I>name</I></CODE> should be
|
|
||||||
a string naming the function.
|
|
||||||
The <CODE><I>name</I></CODE> argument is used only for printing error messages.
|
|
||||||
<P>For all of these, the C function is passed the <CODE><I>arg<I><sub>i</sub></I></I></CODE> values
|
|
||||||
and the value returned is that returned by C procedure.
|
|
||||||
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).
|
|
||||||
<P>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).
|
|
||||||
<UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>(import-lambda-definition <CODE><I>name</I></CODE> (<CODE><I>formal</I></CODE> ...))</CODE></td> <td align=right>syntax</td></tr></table>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>(import-lambda-definition <CODE><I>name</I></CODE> (<CODE><I>formal</I></CODE> ...) <CODE><I>c-name</I></CODE>)</CODE></td> <td align=right>syntax</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
These macros simplify importing functions from C.
|
|
||||||
They define <CODE><I>name</I></CODE> to be a function with the given formals that
|
|
||||||
applies those formals to the corresponding C binding.
|
|
||||||
<CODE><I>C-name</I></CODE>, if supplied, should be a string.
|
|
||||||
These expand into
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define temp (lookup-imported-binding <CODE><I>c-name</I></CODE>))
|
|
||||||
(define <CODE><I>name</I></CODE>
|
|
||||||
(lambda (<CODE><I>formal</I></CODE> ...)
|
|
||||||
(external-apply temp <CODE><I>formal</I></CODE> ...)))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<P>
|
|
||||||
If <CODE><I>c-name</I></CODE> is not supplied, it is derived from <CODE><I>name</I></CODE> by converting
|
|
||||||
all letters to lowercase and replacing `<CODE>-</CODE>' with `<CODE>_</CODE>'.
|
|
||||||
<H1><A NAME="9">Adding external modules to the <CODE>Makefile</CODE></A></H1>
|
|
||||||
|
|
||||||
<P>Getting access to C bindings from Scheme requires that the C code be
|
|
||||||
compiled an linked in with the Scheme 48 virtual machine and that the
|
|
||||||
relevent shared-bindings be created.
|
|
||||||
The Scheme 48 makefile has rules for compiling and linking external code
|
|
||||||
and for specifying initialization functions that should be called on
|
|
||||||
startup.
|
|
||||||
There are three Makefile variables that control which external modules are
|
|
||||||
included in the executable for the virutal machine (<CODE>scheme48vm</CODE>).
|
|
||||||
<CODE>EXTERNAL_OBJECTS</CODE> lists the object files to be included in
|
|
||||||
<CODE>scheme48vm</CODE>,
|
|
||||||
<CODE>EXTERNAL_FLAGS</CODE> is a list of <CODE>ld</CODE> flags to be used when
|
|
||||||
creating <CODE>scheme48vm</CODE>, and
|
|
||||||
<CODE>EXTERNAL_INITIALIZERS</CODE> is a list of C procedures to be called
|
|
||||||
on startup.
|
|
||||||
The procedures listed in <CODE>EXTERNAL_INITIALIZERS</CODE> should take no
|
|
||||||
arguments and have a return type of <CODE>void</CODE>.
|
|
||||||
After changing the definitions of any of these variables you should
|
|
||||||
do <CODE>make scheme48vm</CODE> to rebuild the virtual machine.
|
|
||||||
<H1><A NAME="dynamic-externals">Dynamic Loading</A></H1>
|
|
||||||
|
|
||||||
<P>External code can be loaded into a running Scheme 48 process
|
|
||||||
and C object-file bindings can be dereferenced at runtime and
|
|
||||||
their values called
|
|
||||||
(although not all versions of Unix support all of this).
|
|
||||||
The required Scheme functions are in the structure <CODE>dynamic-externals</CODE>.
|
|
||||||
<UL><LI><CODE>(dynamic-load<I> string</I>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Dynamic-load</CODE> loads the named file into the current
|
|
||||||
process, raising an exception if the file cannot be found or if dynamic
|
|
||||||
loading is not supported by the operating system.
|
|
||||||
The file must have been compiled and linked appropriately.
|
|
||||||
For Linux, the following commands compile <CODE>foo.c</CODE> into a
|
|
||||||
file <CODE>foo.so</CODE> that can be loaded dynamically.
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
% gcc -c -o foo.o foo.c
|
|
||||||
% ld -shared -o foo.so foo.o
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<UL><LI><CODE>(get-external<I> string</I>) -> <I>external</I></CODE>
|
|
||||||
<LI><CODE>(external?<I> x</I>) -> <I>boolean</I></CODE>
|
|
||||||
<LI><CODE>(external-name<I> external</I>) -> <I>string</I></CODE>
|
|
||||||
<LI><CODE>(external-value<I> external</I>) -> <I>byte-vector</I></CODE>
|
|
||||||
</UL>
|
|
||||||
These functions give access to values bound in the current process, and
|
|
||||||
are used for retrieving values from dynamically-loaded files.
|
|
||||||
<CODE>Get-external</CODE> returns an <I>external</I> object that contains the
|
|
||||||
value of <CODE><I>name</I></CODE>, raising an exception if there is no such
|
|
||||||
value in the current process.
|
|
||||||
<CODE>External?</CODE> is the predicate for externals, and
|
|
||||||
<CODE>external-name</CODE> and <CODE>external-value</CODE> return the name and
|
|
||||||
value of an external.
|
|
||||||
The value is returned as byte vector of length four (on 32-bit
|
|
||||||
architectures).
|
|
||||||
The value is that which was extant when <CODE>get-external</CODE> was
|
|
||||||
called.
|
|
||||||
The following two functions can be used to update the values of
|
|
||||||
externals.
|
|
||||||
<UL><LI><CODE>(lookup-external<I> external</I>) -> <I>boolean</I></CODE>
|
|
||||||
<LI><CODE>(lookup-all-externals<I></I>) -> <I>boolean</I></CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Lookup-external</CODE> updates the value of <CODE><I>external</I></CODE> by looking its
|
|
||||||
name in the current process, returning <CODE>#t</CODE> if it is bound and <CODE>#f</CODE>
|
|
||||||
if it is not.
|
|
||||||
<CODE>Lookup-all-externals</CODE> calls <CODE>lookup-external</CODE> on all extant
|
|
||||||
externals, returning <CODE>#f</CODE> any are unbound.
|
|
||||||
<UL><LI><CODE>(call-external<I> external arg<I><sub>0</sub></I> ...</I>) -> <I>value</I></CODE>
|
|
||||||
</UL>
|
|
||||||
An external whose value is a C procedure can be called using
|
|
||||||
<CODE>call-external</CODE>.
|
|
||||||
See
|
|
||||||
|
|
||||||
the section on <A HREF="#8">calling C functions from Scheme</A>
|
|
||||||
for more information.
|
|
||||||
<P>In some versions of Unix retrieving a value from the current
|
|
||||||
process may require a non-trivial amount of computation.
|
|
||||||
We recommend that a dynamically-loaded file contain a single initialization
|
|
||||||
procedure that creates shared bindings for the values exported by the file.
|
|
||||||
<H1><A NAME="11">Compatibility</A></H1>
|
|
||||||
<P>Scheme 48's old <CODE>external-call</CODE> function is still available in the structure
|
|
||||||
<CODE>externals</CODE>, which now also includes <CODE>external-name</CODE> and
|
|
||||||
<CODE>external-value</CODE>.
|
|
||||||
The old <CODE>scheme48.h</CODE> file has been renamed <CODE>old-scheme48.h</CODE>.
|
|
||||||
<H1><A NAME="12">Accessing Scheme data from C</A></H1>
|
|
||||||
|
|
||||||
<P>The C header file <CODE>scheme48.h</CODE> provides
|
|
||||||
access to Scheme 48 data structures
|
|
||||||
(for compatibility, the old <CODE>scheme48.h</CODE> file is available
|
|
||||||
as <CODE>old-scheme48.h</CODE>).
|
|
||||||
The type <CODE>s48_value</CODE> is used for Scheme values.
|
|
||||||
When the type of a value is known, such as the integer returned
|
|
||||||
by <CODE>vector-length</CODE> or the boolean returned by <CODE>pair?</CODE>,
|
|
||||||
the corresponding C procedure returns a C value of the appropriate
|
|
||||||
type, and not a <CODE>s48_value</CODE>.
|
|
||||||
Predicates return <CODE>1</CODE> for true and <CODE>0</CODE> for false.
|
|
||||||
<H2><A NAME="13">Constants</A></H2>
|
|
||||||
|
|
||||||
<P>The following macros denote Scheme constants:
|
|
||||||
<DL><DT><B><CODE>S48_FALSE</CODE></B><DD> is <CODE>#f</CODE>.
|
|
||||||
<DT><B><CODE>S48_TRUE</CODE></B><DD> is <CODE>#t</CODE>.
|
|
||||||
<DT><B><CODE>S48_NULL</CODE></B><DD> is the empty list.
|
|
||||||
<DT><B><CODE>S48_UNSPECIFIC</CODE></B><DD> is a value used for functions which have no
|
|
||||||
meaningful return value
|
|
||||||
(in Scheme this value returned by the nullary procedure <CODE>unspecific</CODE>
|
|
||||||
in the structure <CODE>util</CODE>).
|
|
||||||
<DT><B><CODE>S48_EOF</CODE></B><DD> is the end-of-file object
|
|
||||||
(in Scheme this value is returned by the nullary procedure <CODE>eof-object</CODE>
|
|
||||||
in the structure <CODE>i/o-internal</CODE>).
|
|
||||||
</DL>
|
|
||||||
<H2><A NAME="14">Converting values</A></H2>
|
|
||||||
<P>The following functions convert values between Scheme and C
|
|
||||||
representations.
|
|
||||||
The `extract' ones convert from Scheme to C and the `enter's go the other
|
|
||||||
way.
|
|
||||||
<UL><LI><CODE>unsigned char s48_extract_char(s48_value)</CODE>
|
|
||||||
<LI><CODE>char * s48_extract_string(s48_value)</CODE>
|
|
||||||
<LI><CODE>long s48_extract_integer(s48_value)</CODE>
|
|
||||||
<LI><CODE>double s48_extract_double(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value s48_enter_char(unsigned char)</CODE>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_enter_string(char *)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_enter_integer(long)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_enter_double(double)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
<P>The value returned by <CODE>s48_extract_string</CODE> points to the actual
|
|
||||||
storage used by the string; it is valid only until the next
|
|
||||||
<A HREF="#gc">garbage collection</A>.
|
|
||||||
<P><CODE>s48_enter_integer()</CODE> 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
|
|
||||||
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.
|
|
||||||
<UL><LI><CODE>long s48_extract_fixnum(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value s48_enter_fixnum(long)</CODE>
|
|
||||||
<LI><CODE>long S48_MAX_FIXNUM_VALUE</CODE>
|
|
||||||
<LI><CODE>long S48_MIN_FIXNUM_VALUE</CODE>
|
|
||||||
</UL>
|
|
||||||
<P>An error is signalled if <CODE>s48_extract_fixnum</CODE>'s argument
|
|
||||||
is not a fixnum or if the argument to <CODE>s48_enter_fixnum</CODE> is less than
|
|
||||||
<CODE>S48_MIN_FIXNUM_VALUE</CODE> or greater than <CODE>S48_MAX_FIXNUM_VALUE</CODE>
|
|
||||||
(<I>-2<sup>29</sup></I> and <I>2<sup>29</sup>-1</I> in the current system).
|
|
||||||
<H2><A NAME="15">C versions of Scheme procedures</A></H2>
|
|
||||||
<P>The following macros and procedures are C versions of Scheme procedures.
|
|
||||||
The names were derived by replacing `<CODE>-</CODE>' with `<CODE>_</CODE>',
|
|
||||||
`<CODE>?</CODE>' with `<CODE>p</CODE>', and dropping `<CODE>!</CODE>.
|
|
||||||
<UL><LI><CODE>int S48_EQ_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>int S48_CHAR_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>int S48_INTEGER_P(s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>int S48_PAIR_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_CAR(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_CDR(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_SET_CAR(s48_value, s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_SET_CDR(s48_value, s48_value)</CODE>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_cons(s48_value, s48_value)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
<LI><CODE>long s48_length(s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>int S48_VECTOR_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>long S48_VECTOR_LENGTH(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_VECTOR_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_VECTOR_SET(s48_value, long, s48_value)</CODE>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_make_vector(long, s48_value)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>int S48_STRING_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>long S48_STRING_LENGTH(s48_value)</CODE>
|
|
||||||
<LI><CODE>char S48_STRING_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_STRING_SET(s48_value, long, char)</CODE>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_make_string(long, char)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>int S48_SYMBOL_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value s48_SYMBOL_TO_STRING(s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>int S48_BYTE_VECTOR_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>long S48_BYTE_VECTOR_LENGTH(s48_value)</CODE>
|
|
||||||
<LI><CODE>char S48_BYTE_VECTOR_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_BYTE_VECTOR_SET(s48_value, long, int)</CODE>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value s48_make_byte_vector(long, int)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
<H1><A NAME="16">Calling Scheme functions from C</A></H1>
|
|
||||||
|
|
||||||
<P>External code that has been called from Scheme can call back to Scheme
|
|
||||||
procedures using the following function.
|
|
||||||
<UL><LI><CODE>scheme_value s48_call_scheme(s48_value proc, long nargs, ...)</CODE>
|
|
||||||
</UL>
|
|
||||||
This calls the Scheme procedure <CODE>proc</CODE> on <CODE>nargs</CODE>
|
|
||||||
arguments, which are passed as additional arguments to <CODE>s48_call_scheme</CODE>.
|
|
||||||
There may be at most ten arguments.
|
|
||||||
The value returned by the Scheme procedure is returned by the C procedure.
|
|
||||||
Invoking any Scheme procedure may potentially cause a garbage collection.
|
|
||||||
<P>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()</CODE>).
|
|
||||||
Scheme continuations that capture a portion of the C stack have to follow the
|
|
||||||
same restriction.
|
|
||||||
For example, suppose Scheme procedure <CODE>s0</CODE> captures continuation <CODE>a</CODE>
|
|
||||||
and then calls C procedure <CODE>c0</CODE>, which in turn calls Scheme procedure
|
|
||||||
<CODE>s1</CODE>.
|
|
||||||
Procedure <CODE>s1</CODE> can safely call the continuation <CODE>a</CODE>, because that
|
|
||||||
is a downward use.
|
|
||||||
When <CODE>a</CODE> is called Scheme 48 will remove the portion of the C stack used
|
|
||||||
by the call to <CODE>c0</CODE>.
|
|
||||||
On the other hand, if <CODE>s1</CODE> captures a continuation, that continuation
|
|
||||||
cannot be used from <CODE>s0</CODE>, because by the time control returns to
|
|
||||||
<CODE>s0</CODE> the C stack used by <CODE>c0</CODE> 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.
|
|
||||||
<P>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</CODE> calls a C procedure which calls back
|
|
||||||
to Scheme, at which point control switches to thread <CODE>t1</CODE>, which also
|
|
||||||
calls C and then back to Scheme.
|
|
||||||
At this point both <CODE>t0</CODE> and <CODE>t1</CODE> have active calls to C on the
|
|
||||||
C stack, with <CODE>t1</CODE>'s C frame above <CODE>t0</CODE>'s.
|
|
||||||
If thread <CODE>t0</CODE> attempts to return from Scheme to C it will block,
|
|
||||||
as its frame is not accessable.
|
|
||||||
Once <CODE>t1</CODE> has returned to C and from there to Scheme, <CODE>t0</CODE> will
|
|
||||||
be able to resume.
|
|
||||||
The return to Scheme is required because context switches can only occur while
|
|
||||||
C code is running.
|
|
||||||
<CODE>T0</CODE> will also be able to resume if <CODE>t1</CODE> uses a continuation to
|
|
||||||
throw past its call to C.
|
|
||||||
<H1><A NAME="gc">Interacting with the Scheme Heap</A></H1>
|
|
||||||
|
|
||||||
|
|
||||||
<P>Scheme 48 uses a copying, precise garbage collector.
|
|
||||||
Any procedure that allocates objects within the Scheme 48 heap may trigger
|
|
||||||
a garbage collection.
|
|
||||||
Variables bound to values in the Scheme 48 heap need to be registered with
|
|
||||||
the garbage collector so that the value will be retained and so that the
|
|
||||||
variables will be updated if the garbage collector moves the object.
|
|
||||||
The garbage collector has no facility for updating pointers to the interiors
|
|
||||||
of objects, so such pointers, for example the ones returned by
|
|
||||||
<CODE>EXTRACT_STRING</CODE>, will likely become invalid when a garbage collection
|
|
||||||
occurs.
|
|
||||||
<H2><A NAME="18">Registering Objects with the GC</A></H2>
|
|
||||||
|
|
||||||
<P>A set of macros are used to manage the registration of local variables with the
|
|
||||||
garbage collector.
|
|
||||||
<UL><LI><CODE>S48_DECLARE_GC_PROTECT(<I>n</I>)</CODE>
|
|
||||||
<LI><CODE>void S48_GC_PROTECT_<I>n</I>(s48_value<I><sub>1</sub></I>, <I>...</I>, s48_value<I><sub>n</sub></I>)</CODE>
|
|
||||||
<LI><CODE>void S48_GC_UNPROTECT()</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>S48_DECLARE_GC_PROTECT(<I>n</I>)</CODE>, where <I>1 <= n <= 9</I>, allocates
|
|
||||||
storage for registering <I>n</I> variables.
|
|
||||||
At most one use of <CODE>S48_DECLARE_GC_PROTECT</CODE> may occur in a block.
|
|
||||||
<CODE>S48_GC_PROTECT_<I>n</I>(<I>v<sub>1</sub></I>, <I>...</I>, <I>v<sub>n</sub></I>)</CODE> registers the
|
|
||||||
<I>n</I> variables (l-values) with the garbage collector.
|
|
||||||
It must be within scope of a <CODE>S48_DECLARE_GC_PROTECT(<I>n</I>)</CODE>
|
|
||||||
and be before any code which can cause a GC.
|
|
||||||
<CODE>S48_GC_UNPROTECT</CODE> removes the block's protected variables from
|
|
||||||
the garbage collectors list.
|
|
||||||
It must be called at the end of the block after
|
|
||||||
any code which may cause a garbage collection.
|
|
||||||
Omitting any of the three may cause serious and
|
|
||||||
hard-to-debug problems.
|
|
||||||
Notably, the garbage collector may relocate an object and
|
|
||||||
invalidate <CODE>s48_value</CODE> variables which are not protected.
|
|
||||||
<P>A <CODE>gc-protection-mismatch</CODE> exception is raised if, when a C
|
|
||||||
procedure returns to Scheme, the calls
|
|
||||||
to <CODE>S48_GC_PROTECT()</CODE> have not been matched by an equal number of
|
|
||||||
calls to <CODE>S48_GC_UNPROTECT()</CODE>.
|
|
||||||
<P>Global variables may also be registered with the garbage collector.
|
|
||||||
<UL><LI><CODE>void S48_GC_PROTECT_GLOBAL(<CODE><I>value</I></CODE>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>S48_GC_PROTECT_GLOBAL</CODE> permanently registers the
|
|
||||||
variable <CODE><I>value</I></CODE> (an l-value) with the garbage collector.
|
|
||||||
There is no way to unregister the variable.
|
|
||||||
<H2><A NAME="19">Keeping C data structures in the Scheme heap</A></H2>
|
|
||||||
|
|
||||||
<P>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.
|
|
||||||
<UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value S48_MAKE_VALUE(type)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
<LI><CODE>type S48_EXTRACT_VALUE(s48_value, type)</CODE>
|
|
||||||
<LI><CODE>type * S48_EXTRACT_VALUE_POINTER(s48_value, type)</CODE>
|
|
||||||
<LI><CODE>void S48_SET_VALUE(s48_value, type, value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>S48_MAKE_VALUE</CODE> makes a byte vector large enough to hold an object
|
|
||||||
whose type is <CODE><I>type</I></CODE>.
|
|
||||||
<CODE>S48_EXTRACT_VALUE</CODE> returns the contents of a byte vector cast to
|
|
||||||
<CODE><I>type</I></CODE>, and <CODE>S48_EXTRACT_VALUE_POINTER</CODE> returns a pointer
|
|
||||||
to the contents of the byte vector.
|
|
||||||
The value returned by <CODE>S48_EXTRACT_VALUE_POINTER</CODE> is valid only until
|
|
||||||
the next <A HREF="#gc">garbage collection</A>.
|
|
||||||
<P><CODE>S48_SET_VALUE</CODE> stores <CODE>value</CODE> into the byte vector.
|
|
||||||
<H2><A NAME="20">C code and heap images</A></H2>
|
|
||||||
|
|
||||||
<P>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 on
|
|
||||||
when resumed.
|
|
||||||
<P>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.
|
|
||||||
<UL><LI><CODE>(define-record-resumer<I> record-type procedure</I>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>Define-record-resumer</CODE> defines <CODE><I>procedure</I></CODE>,
|
|
||||||
which should accept one argument, to be the resumer for
|
|
||||||
<I>record-type</I>.
|
|
||||||
The order in which resumer procedures are called is not specified.
|
|
||||||
<P>The <CODE><I>procedure</I></CODE> argument to <CODE>define-record-resumer</CODE> may
|
|
||||||
be <CODE>#f</CODE>, 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.
|
|
||||||
<H1><A NAME="21">Using Scheme records in C code</A></H1>
|
|
||||||
<P>External modules can create records and access their slots
|
|
||||||
positionally.
|
|
||||||
<UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>s48_value S48_MAKE_RECORD(s48_value)</CODE></td> <td align=right>(may GC)</td></tr></table>
|
|
||||||
<LI><CODE>int S48_RECORD_P(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_RECORD_TYPE(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_RECORD_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_RECORD_SET(s48_value, long, s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
The argument to <CODE>S48_MAKE_RECORD</CODE> 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.
|
|
||||||
<P>For example, given the following record-type definition
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-record-type thing :thing
|
|
||||||
(make-thing a b)
|
|
||||||
thing?
|
|
||||||
(a thing-a)
|
|
||||||
(b thing-b))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
the identifier <CODE>:thing</CODE> is bound to the record type and can
|
|
||||||
be exported to C:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-exported-binding "thing-record-type" :thing)
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<CODE>Thing</CODE> records can then be made in C:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
static scheme_value thing_record_type_binding = SCHFALSE;
|
|
||||||
|
|
||||||
void initialize_things(void)
|
|
||||||
{
|
|
||||||
S48_GC_PROTECT_GLOBAL(thing_record_type_binding);
|
|
||||||
thing_record_type_binding =
|
|
||||||
s48_get_imported_binding("thing-record-type");
|
|
||||||
}
|
|
||||||
|
|
||||||
scheme_value make_thing(scheme_value a, scheme_value b)
|
|
||||||
{
|
|
||||||
s48_value thing;
|
|
||||||
s48_DECLARE_GC_PROTECT(2);
|
|
||||||
|
|
||||||
S48_GC_PROTECT_2(a, b);
|
|
||||||
|
|
||||||
thing = s48_make_record(thing_record_type_binding);
|
|
||||||
S48_RECORD_SET(thing, 0, a);
|
|
||||||
S48_RECORD_SET(thing, 1, b);
|
|
||||||
|
|
||||||
S48_GC_UNPROTECT();
|
|
||||||
|
|
||||||
return thing;
|
|
||||||
}
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
Note that the variables <CODE>a</CODE> and <CODE>b</CODE> must be protected
|
|
||||||
against the possibility of a garbage collection occuring during
|
|
||||||
the call to <CODE>s48_make_record()</CODE>.
|
|
||||||
<H1><A NAME="22">Raising exceptions from external code</A></H1>
|
|
||||||
|
|
||||||
<P>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.
|
|
||||||
<UL><LI><CODE>s48_raise_scheme_exception(int type, int nargs, ...)</CODE>
|
|
||||||
</UL>
|
|
||||||
<P><CODE>s48_raise_scheme_exception</CODE> is the base procedure for
|
|
||||||
raising exceptions.
|
|
||||||
<CODE>type</CODE> is the type of exception, and should be one of the
|
|
||||||
<CODE>S48_EXCEPTION_</CODE>...constants defined in <CODE>scheme48arch.h</CODE>.
|
|
||||||
<CODE>nargs</CODE> is the number of additional values to be included in the
|
|
||||||
exception; these follow the <CODE>nargs</CODE> argument and should all have
|
|
||||||
type <CODE>s48_value</CODE>.
|
|
||||||
<CODE>s48_raise_scheme_exception</CODE> never returns.
|
|
||||||
<P>The following procedures are available for raising particular
|
|
||||||
types of exceptions.
|
|
||||||
Like <CODE>s48_raise_scheme_exception</CODE> these never return.
|
|
||||||
<UL><LI><CODE>s48_raise_argument_type_error(scheme_value)</CODE>
|
|
||||||
<LI><CODE>s48_raise_argument_number_error(int nargs, int min, int max)</CODE>
|
|
||||||
<LI><CODE>s48_raise_index_range_error(long value, long min, long max)</CODE>
|
|
||||||
<LI><CODE>s48_raise_closed_channel_error()</CODE>
|
|
||||||
<LI><CODE>s48_raise_os_error(int errno)</CODE>
|
|
||||||
<LI><CODE>s48_raise_out_of_memory_error()</CODE>
|
|
||||||
</UL>
|
|
||||||
<P>An argument type error indicates that the given value is of the wrong
|
|
||||||
type.
|
|
||||||
An argument number error is raised when the number of arguments, <CODE>nargs</CODE>,
|
|
||||||
should be, but isn't, between <CODE>min</CODE> and <CODE>max</CODE>, inclusive.
|
|
||||||
Similarly, and index range error is raised when <CODE>value</CODE> is not between
|
|
||||||
between <CODE>min</CODE> and <CODE>max</CODE>, inclusive.
|
|
||||||
<P>The following macros raise argument type errors if their argument does not
|
|
||||||
have the required type.
|
|
||||||
<UL><LI><CODE>void S48_CHECK_SYMBOL(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_PAIR(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_STRING(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_INTEGER(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_CHANNEL(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_BYTE_VECTOR(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_RECORD(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_CHECK_SHARED_BINDING(s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<H1><A NAME="23">Unsafe functions and macros</A></H1>
|
|
||||||
<P>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.
|
|
||||||
<UL><LI><CODE>char S48_UNSAFE_EXTRACT_CHAR(s48_value)</CODE>
|
|
||||||
<LI><CODE>char * S48_UNSAFE_EXTRACT_STRING(s48_value)</CODE>
|
|
||||||
<LI><CODE>long S48_UNSAFE_EXTRACT_INTEGER(s48_value)</CODE>
|
|
||||||
<LI><CODE>long S48_UNSAFE_EXTRACT_DOUBLE(s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>long S48_UNSAFE_EXTRACT_FIXNUM(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_UNSAFE_ENTER_FIXNUM(long)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>s48_value S48_UNSAFE_CAR(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_UNSAFE_CDR(s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_SET_CAR(s48_value, s48_value)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_SET_CDR(s48_value, s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>long S48_UNSAFE_VECTOR_LENGTH(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_UNSAFE_VECTOR_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_VECTOR_SET(s48_value, long, s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>long S48_UNSAFE_STRING_LENGTH(s48_value)</CODE>
|
|
||||||
<LI><CODE>char S48_UNSAFE_STRING_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_STRING_SET(s48_value, long, char)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>s48_value S48_UNSAFE_SYMBOL_TO_STRING(s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>long S48_UNSAFE_BYTE_VECTOR_LENGTH(s48_value)</CODE>
|
|
||||||
<LI><CODE>char S48_UNSAFE_BYTE_VECTOR_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_BYTE_VECTOR_SET(s48_value, long, int)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>s48_value S48_UNSAFE_SHARED_BINDING_REF(s48_value s_b)</CODE>
|
|
||||||
<LI><CODE>int S48_UNSAFE_SHARED_BINDING_P(x)</CODE>
|
|
||||||
<LI><CODE>int S48_UNSAFE_SHARED_BINDING_IS_IMPORT_P(s48_value s_b)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_UNSAFE_SHARED_BINDING_NAME(s48_value s_b)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_SHARED_BINDING_SET(s48_value s_b, s48_value value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>s48_value S48_UNSAFE_RECORD_TYPE(s48_value)</CODE>
|
|
||||||
<LI><CODE>s48_value S48_UNSAFE_RECORD_REF(s48_value, long)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_RECORD_SET(s48_value, long, s48_value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<UL><LI><CODE>type S48_UNSAFE_EXTRACT_VALUE(s48_value, type)</CODE>
|
|
||||||
<LI><CODE>type * S48_UNSAFE_EXTRACT_VALUE_POINTER(s48_value, type)</CODE>
|
|
||||||
<LI><CODE>void S48_UNSAFE_SET_VALUE(s48_value, type, value)</CODE>
|
|
||||||
</UL>
|
|
||||||
<HR ><ADDRESS><a href="http://www-pu.informatik.uni-tuebingen.de/users/sperber/">Mike
|
|
||||||
Sperber</a>, <a href="http://www.neci.nj.nec.com/homepages/kelsey/">Richard Kelsey</a></ADDRESS><BR>
|
|
||||||
</BODY></HTML>
|
|
||||||
|
|
@ -1,315 +0,0 @@
|
||||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
||||||
<HTML>
|
|
||||||
<!-- HTML file produced from file: utilities.tex --
|
|
||||||
-- using Hyperlatex v 2.3.1 (c) Otfried Cheong--
|
|
||||||
-- on Emacs 19.34.1, Tue Feb 23 18:25:11 1999 -->
|
|
||||||
<HEAD>
|
|
||||||
<TITLE>Untitled</TITLE>
|
|
||||||
|
|
||||||
</HEAD><BODY>
|
|
||||||
|
|
||||||
|
|
||||||
<H1 ALIGN=CENTER>Scheme 48 User's Guide</H1>
|
|
||||||
<H2 ALIGN=CENTER>Richard A. Kelsey</H2>
|
|
||||||
<H3 ALIGN=CENTER>February 23, 1999</H3>
|
|
||||||
<H1><A NAME="1">ASCII character encoding</A></H1>
|
|
||||||
<P>These are in the structure <CODE>ascii</CODE>.
|
|
||||||
<UL><LI><CODE>(char->ascii<VAR> char</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
<LI><CODE>(ascii->char<VAR> integer</VAR>) -> <VAR>char</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
These are identical to <CODE>char->integer</CODE> and <CODE>integer->char</CODE> except that
|
|
||||||
they use the ASCII encoding.
|
|
||||||
<UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>ascii-limit</CODE></td> <td align=right>integer</td></tr></table>
|
|
||||||
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE>ascii-whitespaces</CODE></td> <td align=right>list of integers</td></tr></table>
|
|
||||||
</UL>
|
|
||||||
<CODE>Ascii-limit</CODE> is one more than the largest value that <CODE>char->ascii</CODE>
|
|
||||||
may return.
|
|
||||||
<CODE>Ascii-whitespaces</CODE> is a list of the ASCII values of whitespace characters
|
|
||||||
(space, tab, line feed, form feed, and carriage return).
|
|
||||||
<H1><A NAME="2">Bitwise integer operations</A></H1>
|
|
||||||
<P>These functions use the two's-complement representation for integers.
|
|
||||||
There is no limit to the number of bits in an integer.
|
|
||||||
They are in the structures <CODE>bitwise</CODE> and <CODE>big-scheme</CODE>.
|
|
||||||
<UL><LI><CODE>(bitwise-and<VAR> integer integer</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
<LI><CODE>(bitwise-ior<VAR> integer integer</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
<LI><CODE>(bitwise-xor<VAR> integer integer</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
<LI><CODE>(bitwise-not<VAR> integer</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
These perform various logical operations on integers on a bit-by-bit
|
|
||||||
basis. `<CODE>ior</CODE>' is inclusive OR and `<CODE>xor</CODE>' is exclusive OR.
|
|
||||||
<UL><LI><CODE>(arithmetic-shift<VAR> integer bit-count</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
Shifts the integer by the given bit count, which must be an integer,
|
|
||||||
shifting left for positive counts and right for negative ones.
|
|
||||||
Shifting preserves the integer's sign.
|
|
||||||
<H1><A NAME="3">Arrays</A></H1>
|
|
||||||
<P>These are N-dimensional, zero-based arrays and
|
|
||||||
are in the structure <CODE>arrays</CODE>.
|
|
||||||
<P>The array interface is derived from one written by Alan Bawden.
|
|
||||||
<UL><LI><CODE>(make-array<VAR> value dimension<I><sub>0</sub></I> ...</VAR>) -> <VAR>array</VAR></CODE>
|
|
||||||
<LI><CODE>(array<VAR> dimensions element<I><sub>0</sub></I> ...</VAR>) -> <VAR>array</VAR></CODE>
|
|
||||||
<LI><CODE>(copy-array<VAR> array</VAR>) -> <VAR>array</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Make-array</CODE> makes a new array with the given dimensions, each of which
|
|
||||||
must be a non-negative integer.
|
|
||||||
Every element is initially set to <CODE><VAR>value</VAR></CODE>.
|
|
||||||
<CODE>Array</CODE> Returns a new array with the given dimensions and elements.
|
|
||||||
<CODE><VAR>Dimensions</VAR></CODE> must be a list of non-negative integers,
|
|
||||||
The number of elements should be the equal to the product of the
|
|
||||||
dimensions.
|
|
||||||
The elements are stored in row-major order.
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(make-array 'a 2 3) <CODE>-></CODE> {Array 2 3}
|
|
||||||
|
|
||||||
(array '(2 3) 'a 'b 'c 'd 'e 'f)
|
|
||||||
<CODE>-></CODE> {Array 2 3}
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<P><CODE>Copy-array</CODE> returns a copy of <CODE><VAR>array</VAR></CODE>.
|
|
||||||
The copy is identical to the <CODE><VAR>array</VAR></CODE> but does not share storage with it.
|
|
||||||
<UL><LI><CODE>(array?<VAR> value</VAR>) -> <VAR>boolean</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
Returns <CODE>#t</CODE> if <CODE><VAR>value</VAR></CODE> is an array.
|
|
||||||
<UL><LI><CODE>(array-ref<VAR> array index<I><sub>0</sub></I> ...</VAR>) -> <VAR>value</VAR></CODE>
|
|
||||||
<LI><CODE>(array-set!<VAR> array value index<I><sub>0</sub></I> ...</VAR>)</CODE>
|
|
||||||
<LI><CODE>(array->vector<VAR> array</VAR>) -> <VAR>vector</VAR></CODE>
|
|
||||||
<LI><CODE>(array-dimensions<VAR> array</VAR>) -> <VAR>list</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Array-ref</CODE> returns the specified array element and <CODE>array-set!</CODE>
|
|
||||||
replaces the element with <CODE><VAR>value</VAR></CODE>.
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(let ((a (array '(2 3) 'a 'b 'c 'd 'e 'f)))
|
|
||||||
(let ((x (array-ref a 0 1)))
|
|
||||||
(array-set! a 'g 0 1)
|
|
||||||
(list x (array-ref a 0 1))))
|
|
||||||
<CODE>-></CODE> '(b g)
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<P><CODE>Array->vector</CODE> returns a vector containing the elements of <CODE><VAR>array</VAR></CODE>
|
|
||||||
in row-major order.
|
|
||||||
<CODE>Array-dimensions</CODE> returns the dimensions of
|
|
||||||
the array as a list.
|
|
||||||
<UL><LI><CODE>(make-shared-array<VAR> array linear-map dimension<I><sub>0</sub></I> ...</VAR>) -> <VAR>array</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Make-shared-array</CODE> makes a new array that shares storage with <CODE><VAR>array</VAR></CODE>
|
|
||||||
and uses <CODE><VAR>linear-map</VAR></CODE> to map indicies to elements.
|
|
||||||
<CODE><VAR>Linear-map</VAR></CODE> must accept as many arguments as the number of
|
|
||||||
<CODE><VAR>dimension</VAR></CODE>s given and must return a list of non-negative integers
|
|
||||||
that are valid indicies into <CODE><VAR>array</VAR></CODE>.
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(array-ref (make-shared-array a f i0 i1 ...)
|
|
||||||
j0 j1 ...)
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
is equivalent to
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(apply array-ref a (f j0 j1 ...))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<P>As an example, the following function makes the transpose of a two-dimensional
|
|
||||||
array:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define (transpose array)
|
|
||||||
(let ((dimensions (array-dimensions array)))
|
|
||||||
(make-shared-array array
|
|
||||||
(lambda (x y)
|
|
||||||
(list y x))
|
|
||||||
(cadr dimensions)
|
|
||||||
(car dimensions))))
|
|
||||||
|
|
||||||
(array->vector
|
|
||||||
(transpose
|
|
||||||
(array '(2 3) 'a 'b 'c 'd 'e 'f)))
|
|
||||||
<CODE>-></CODE> '(a d b e c f)
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<H1><A NAME="4">Records</A></H1>
|
|
||||||
<P>New types can be constructed using the <CODE>define-record-type</CODE> macro
|
|
||||||
from the <CODE>define-record-types</CODE> structure
|
|
||||||
The general syntax is:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-record-type <CODE><VAR>tag</VAR></CODE> <CODE><VAR>type-name</VAR></CODE>
|
|
||||||
(<CODE><VAR>constructor-name</VAR></CODE> <CODE><VAR>field-tag</VAR></CODE> ...)
|
|
||||||
<CODE><VAR>predicate-name</VAR></CODE>
|
|
||||||
(<CODE><VAR>field-tag</VAR></CODE> <CODE><VAR>accessor-name</VAR></CODE> [<CODE><VAR>modifier-name</VAR></CODE>])
|
|
||||||
...)
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
This makes the following definitions:
|
|
||||||
<UL><LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
|
|
||||||
<tr> <td><CODE><CODE><VAR>type-name</VAR></CODE></CODE></td> <td align=right>type</td></tr></table>
|
|
||||||
<LI><CODE>(<CODE><VAR>constructor-name</VAR></CODE><VAR> field-init ...</VAR>) -> <VAR>type-name</VAR></CODE>
|
|
||||||
<LI><CODE>(<CODE><VAR>predicate-name</VAR></CODE><VAR> value</VAR>) -> <VAR>boolean</VAR></CODE>
|
|
||||||
<LI><CODE>(<CODE><VAR>accessor-name</VAR></CODE><VAR> type-name</VAR>) -> <VAR>value</VAR></CODE>
|
|
||||||
<LI><CODE>(<CODE><VAR>modifier-name</VAR></CODE><VAR> type-name value</VAR>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE><VAR>Type-name</VAR></CODE> is the record type itself, and can be used to
|
|
||||||
specify a print method (see below).
|
|
||||||
<CODE><VAR>Constructor-name</VAR></CODE> is a constructor that accepts values
|
|
||||||
for the fields whose tags are specified.
|
|
||||||
<CODE><VAR>Predicate-name</VAR></CODE> to a predicate that can returns <CODE>#t</CODE> for
|
|
||||||
elements of the type and <CODE>#f</CODE> for everything else.
|
|
||||||
The <CODE><VAR>accessor-name</VAR></CODE>s retrieve the values of fields,
|
|
||||||
and the <CODE><VAR>modifier-name</VAR></CODE>'s update them.
|
|
||||||
The <CODE><VAR>tag</VAR></CODE> is used in printing instances of the record type and
|
|
||||||
the field tags are used in the inspector and to match
|
|
||||||
constructor arguments with fields.
|
|
||||||
<UL><LI><CODE>(define-record-discloser<VAR> type discloser</VAR>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Define-record-discloser</CODE> determines how
|
|
||||||
records of type <CODE><VAR>type</VAR></CODE> are printed.
|
|
||||||
<CODE><VAR>Discloser</VAR></CODE> should be procedure which takes a single
|
|
||||||
record of type <CODE><VAR>type</VAR></CODE> and returns a list whose car is
|
|
||||||
a symbol.
|
|
||||||
The record will be printed as the value returned by <CODE><VAR>discloser</VAR></CODE>
|
|
||||||
with curly braces used instead of the usual parenthesis.
|
|
||||||
<P>For example
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-record-type pare :pare
|
|
||||||
(kons x y)
|
|
||||||
pare?
|
|
||||||
(x kar set-kar!)
|
|
||||||
(y kdr))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
defines <CODE>kons</CODE> to be a constructor, <CODE>kar</CODE> and <CODE>kdr</CODE> to be
|
|
||||||
accessors, <CODE>set-kar!</CODE> to be a modifier, and <CODE>pare?</CODE> to be a predicate
|
|
||||||
for a new type of object.
|
|
||||||
The type itself is named <CODE>:pare</CODE>.
|
|
||||||
<CODE>Pare</CODE> is a tag used in printing the new objects.
|
|
||||||
<P>By default, the new objects print as <CODE>#Pare</CODE>.
|
|
||||||
The print method can be modified using DEFINE-RECORD-DISCLOSER:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-record-discloser :pare
|
|
||||||
(lambda (p) `(pare ,(kar p) ,(kdr p))))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
will cause the result of <CODE>(kons 1 2)</CODE> to print as
|
|
||||||
<CODE>#{pare 1 2}</CODE>.
|
|
||||||
<H1><A NAME="5">Finite record types</A></H1>
|
|
||||||
<P>The structure <CODE>finite-types</CODE> has
|
|
||||||
two macros for defining `finite' record types.
|
|
||||||
These are record types for which there are a fixed number of instances,
|
|
||||||
which are created when the record type is defined.
|
|
||||||
The syntax for the defining a finite type is:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-finite-type <CODE><VAR>tag</VAR></CODE> <CODE><VAR>type-name</VAR></CODE>
|
|
||||||
(<CODE><VAR>field-tag</VAR></CODE> ...)
|
|
||||||
<CODE><VAR>predicate-name</VAR></CODE>
|
|
||||||
<CODE><VAR>vector-of-elements-name</VAR></CODE>
|
|
||||||
<CODE><VAR>name-accessor</VAR></CODE>
|
|
||||||
<CODE><VAR>index-accessor</VAR></CODE>
|
|
||||||
(<CODE><VAR>field-tag</VAR></CODE> <CODE><VAR>accessor-name</VAR></CODE> [<CODE><VAR>modifier-name</VAR></CODE>])
|
|
||||||
...
|
|
||||||
((<CODE><VAR>element-name</VAR></CODE> <CODE><VAR>field-value</VAR></CODE> ...)
|
|
||||||
...))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
This differs from <CODE>define-record-type</CODE> in the following ways:
|
|
||||||
<UL><LI>No name is specified for the constructor, but the field arguments
|
|
||||||
to the constructor are listed.
|
|
||||||
<LI>The <CODE><VAR>vector-of-elements-name</VAR></CODE> is added; it will be bound
|
|
||||||
to a vector containing all of the elements of the type.
|
|
||||||
These are constructed by applying the (unnamed) constructor to the
|
|
||||||
initial field values at the end of the form.
|
|
||||||
<LI>There are names for accessors for two required fields, name
|
|
||||||
and index.
|
|
||||||
These fields are not settable, and are not to be included
|
|
||||||
in the argument list for the constructor.
|
|
||||||
<LI>The form ends with the names and the initial field values for
|
|
||||||
the elements of the type.
|
|
||||||
The name must be first.
|
|
||||||
The remaining values must match the <CODE><VAR>field-tag</VAR></CODE>s in the constructor's
|
|
||||||
argument list.
|
|
||||||
<LI><CODE><VAR>Tag</VAR></CODE> is bound to a macro that maps <CODE><VAR>element-name</VAR></CODE>s to the
|
|
||||||
the corresponding element of the vector.
|
|
||||||
The name lookup is done at macro-expansion time.
|
|
||||||
</UL>
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-finite-type color :color
|
|
||||||
(red green blue)
|
|
||||||
color?
|
|
||||||
colors
|
|
||||||
color-name
|
|
||||||
color-index
|
|
||||||
(red color-red)
|
|
||||||
(green color-green)
|
|
||||||
(blue color-blue)
|
|
||||||
((white 255 255 255)
|
|
||||||
(black 0 0 0)
|
|
||||||
(yellow 255 255 0)
|
|
||||||
(maroon 176 48 96)))
|
|
||||||
|
|
||||||
(color-name (vector-ref colors 0)) <CODE>-></CODE> white
|
|
||||||
(color-name (color black)) <CODE>-></CODE> black
|
|
||||||
(color-index (color yellow)) <CODE>-></CODE> 2
|
|
||||||
(color-red (color maroon)) <CODE>-></CODE> 176
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<P>Enumerated types are finite types whose only fields are the name
|
|
||||||
and the index.
|
|
||||||
The syntax for defining an enumerated type is:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-enumerated-type <CODE><VAR>tag</VAR></CODE> <CODE><VAR>type-name</VAR></CODE>
|
|
||||||
<CODE><VAR>predicate-name</VAR></CODE>
|
|
||||||
<CODE><VAR>vector-of-elements-name</VAR></CODE>
|
|
||||||
<CODE><VAR>name-accessor</VAR></CODE>
|
|
||||||
<CODE><VAR>index-accessor</VAR></CODE>
|
|
||||||
(<CODE><VAR>element-name</VAR></CODE> ...))
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
In the absence of any additional fields, both the constructor argument
|
|
||||||
list and the initial field values are not required.
|
|
||||||
<P>The above example of a finite type can be pared down to the following
|
|
||||||
enumerated type:
|
|
||||||
<BLOCKQUOTE><PRE>
|
|
||||||
(define-enumerated-type color :color
|
|
||||||
color?
|
|
||||||
colors
|
|
||||||
color-name
|
|
||||||
color-index
|
|
||||||
(white black yellow maroon))
|
|
||||||
|
|
||||||
(color-name (vector-ref colors 0)) <CODE>-></CODE> white
|
|
||||||
(color-name (color black)) <CODE>-></CODE> black
|
|
||||||
(color-index (color yellow)) <CODE>-></CODE> 2
|
|
||||||
</PRE></BLOCKQUOTE>
|
|
||||||
<H1><A NAME="6">Hash tables</A></H1>
|
|
||||||
<P>These are generic hash tables, and are in the structure <CODE>tables</CODE>.
|
|
||||||
Strictly speaking they are more maps than tables, as every table has a
|
|
||||||
value for every possible key (for that type of table).
|
|
||||||
All but a finite number of those values are <CODE>#f</CODE>.
|
|
||||||
<UL><LI><CODE>(make-table<VAR></VAR>) -> <VAR>table</VAR></CODE>
|
|
||||||
<LI><CODE>(make-symbol-table<VAR></VAR>) -> <VAR>symbol-table</VAR></CODE>
|
|
||||||
<LI><CODE>(make-string-table<VAR></VAR>) -> <VAR>string-table</VAR></CODE>
|
|
||||||
<LI><CODE>(make-integer-table<VAR></VAR>) -> <VAR>integer-table</VAR></CODE>
|
|
||||||
<LI><CODE>(make-table-maker<VAR> compare-proc hash-proc</VAR>) -> <VAR>procedure</VAR></CODE>
|
|
||||||
<LI><CODE>(make-table-immutable!<VAR> table</VAR>)</CODE>
|
|
||||||
</UL>
|
|
||||||
The first four functions listed make various kinds of tables.
|
|
||||||
<CODE>Make-table</CODE> returns a table whose keys may be symbols, integer,
|
|
||||||
characters, booleans, or the empty list (these are also the values
|
|
||||||
that may be used in <CODE>case</CODE> expressions).
|
|
||||||
As with <CODE>case</CODE>, comparison is done using <CODE>eqv?</CODE>.
|
|
||||||
The comparison procedures used in symbol, string, and integer tables are
|
|
||||||
<CODE>eq?</CODE>, <CODE>string=?</CODE>, and <CODE>=</CODE>.
|
|
||||||
<P><CODE>Make-table-maker</CODE> takes two procedures as arguments and returns
|
|
||||||
a nullary table-making procedure.
|
|
||||||
<CODE><VAR>Compare-proc</VAR></CODE> should be a two-argument equality predicate.
|
|
||||||
<CODE><VAR>Hash-proc</VAR></CODE> should be a one argument procedure that takes a key
|
|
||||||
and returns a non-negative integer hash value.
|
|
||||||
If <CODE>(<CODE><VAR>compare-proc</VAR></CODE> <CODE><VAR>x</VAR></CODE> <CODE><VAR>y</VAR></CODE>)</CODE> returns true,
|
|
||||||
then <CODE>(= (<CODE><VAR>hash-proc</VAR></CODE> <CODE><VAR>x</VAR></CODE>) (<CODE><VAR>hash-proc</VAR></CODE> <CODE><VAR>y</VAR></CODE>))</CODE>
|
|
||||||
must also return true.
|
|
||||||
For example, <CODE>make-integer-table</CODE> could be defined
|
|
||||||
as <CODE>(make-table-maker = abs)</CODE>.
|
|
||||||
<P><CODE>Make-table-immutable!</CODE> prohibits future modification to its argument.
|
|
||||||
<UL><LI><CODE>(table?<VAR> value</VAR>) -> <VAR>boolean</VAR></CODE>
|
|
||||||
<LI><CODE>(table-ref<VAR> table key</VAR>) -> <VAR>value or <CODE>#f</CODE></VAR></CODE>
|
|
||||||
<LI><CODE>(table-set!<VAR> table key value</VAR>)</CODE>
|
|
||||||
<LI><CODE>(table-walk<VAR> procedure table</VAR>)</CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>Table?</CODE> is the predicate for tables.
|
|
||||||
<CODE>Table-ref</CODE> and <CODE>table-set!</CODE> access and modify the value of <CODE><VAR>key</VAR></CODE>
|
|
||||||
in <CODE><VAR>table</VAR></CODE>.
|
|
||||||
<CODE>Table-walk</CODE> applies <CODE><VAR>procedure</VAR></CODE>, which must accept two arguments,
|
|
||||||
to every associated key and non-<CODE>#f</CODE> value in <CODE>table</CODE>.
|
|
||||||
<UL><LI><CODE>(default-hash-function<VAR> value</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
<LI><CODE>(string-hash<VAR> string</VAR>) -> <VAR>integer</VAR></CODE>
|
|
||||||
</UL>
|
|
||||||
<CODE>default-hash-function</CODE> is the hash function used in the tables
|
|
||||||
returned by <CODE>make-table</CODE>, and <CODE>string-hash</CODE> it the one used
|
|
||||||
by <CODE>make-string-table</CODE>.
|
|
||||||
<HR >
|
|
||||||
</BODY></HTML>
|
|
||||||
Loading…
Reference in New Issue