| [Top] | [Contents] | [Index] | [ ? ] |
This manual documents Gambit-C. It covers release 4.0 beta 1.
1. Gambit-C: a portable version of Gambit A portable version of Gambit General Index
-- The Detailed Node Listing ---
Gambit-C: a portable version of Gambit
2. The Gambit Scheme interpreter The interpreter 3. The Gambit Scheme compiler The compiler 4. Runtime options for all programs 5. Handling of file names 6. Emacs interface Emacs interface for running Gambit 7. Extensions to Scheme 8. Scheme threads 9. Interface to C 10. Known limitations and deficiencies 11. Bugs fixed Bugs fixed from past versions 12. Copyright and distribution information
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Gambit programming system is a full implementation of the Scheme
language which conforms to the R4RS, R5RS and IEEE Scheme standards. It
consists of two programs: gsi, the Gambit Scheme interpreter,
and gsc, the Gambit Scheme compiler.
Gambit-C is a version of the Gambit programming system in which the compiler generates portable C code, making the whole Gambit-C system and the programs compiled with it easily portable to many computer architectures for which a C compiler is available. With appropriate declarations in the source code the executable programs generated by the compiler run roughly as fast as equivalent C programs.
For the most up to date information on Gambit and add-on packages please check the Gambit web page at `http://www.iro.umontreal.ca/~gambit' or send mail to `gambit@iro.umontreal.ca'.
Bug reports should be sent to `gambit@iro.umontreal.ca'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Unless the default is overridden when the Gambit-C system was built (with the command `configure --prefix=/some/directory'), all files are installed in `/usr/local/Gambit-C' under UNIX and `C:\Gambit-C' under Microsoft Windows. This is the Gambit installation directory.
The system's executables including the interpreter `gsi' and compiler `gsc' are stored in the `bin' subdirectory. It is convenient to put the `bin' directory in the shell's `PATH' environment variable so that these programs can be invoked simply by entering their name.
The runtime library is located in the `lib' subdirectory. When the system's runtime library is built as a shared-library (with the command `configure --enable-shared') all programs built with Gambit-C, including the interpreter and compiler, need to find this library when they are executed and consequently this directory must be in the path searched by the system for shared-libraries. This path is normally specified through an environment variable which is `LD_LIBRARY_PATH' on most versions of UNIX, `LIBPATH' on AIX, `SHLIB_PATH' on HPUX, `DYLD_LIBRARY_PATH' on Mac OS X, and `PATH' on Microsoft Windows. If the shell is of the `sh' family, the setting of the path can be made for a single execution by prefixing the program name with the environment variable assignment, as in:
% LD_LIBRARY_PATH=/usr/local/Gambit-C/lib gsi |
A similar problem exists with the Gambit header file `gambit.h', located in the `include' subdirectory. This header file is needed for compiling Scheme programs with the Gambit-C compiler. If the C compiler is being called explicitly, then it may be necessary to use a `-I<dir>' command line option to indicate where to find header files and a `-L<dir>' command line option to indicate where to find libraries. Access to both of these files can be simplified by creating a link to them in the appropriate system directories (special privileges may however be required):
ln -s /usr/local/Gambit-C/lib/libgambc.a /usr/lib ; name may vary ln -s /usr/local/Gambit-C/gambit.h /usr/include |
This is not done by the installation process. Alternatively these files can also be copied or linked in the directory where the C compiler is invoked (this requires no special privileges).
2. The Gambit Scheme interpreter The interpreter 3. The Gambit Scheme compiler The compiler 4. Runtime options for all programs 5. Handling of file names 7. Extensions to Scheme 8. Scheme threads 9. Interface to C 10. Known limitations and deficiencies 11. Bugs fixed Bugs fixed from past versions 12. Copyright and distribution information
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis:
gsi [-:runtimeoption,...] [-f] [-i] [[-e expressions] [file]]... |
The interpreter is executed in interactive mode when no file or `-e' option is given on the command line. When at least one file or `-e' option is present the interpreter is executed in batch mode. The `-i' option is ignored by the interpreter. The `-f' option avoids examining the interpreter's initialization file.
2.1 Interactive mode 2.2 Batch mode 2.3 Customization 2.4 Process exit status 2.5 Scheme scripts
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In this mode a read-eval-print loop (REPL) is started for interacting with the interpreter. In this loop the interpreter displays a prompt, reads a command and executes it. The commands can be Scheme expressions to evaluate (the typical case) or special commands. Commands can produce output such as the value or error message resulting from an evaluation.
The input and output of the interaction is done on the interaction channel. Normally the interaction channel is the standard input (`stdin') and standard output (`stdout') of the interpreter (for details see section 4. Runtime options for all programs). So unless I/O redirection is used, the interaction channel will correspond to the user's console, also known as the controlling terminal in the UNIX world. The standard error (`stderr') of the interpreter is not used for REPL interaction.
Expressions are evaluated in the global interaction environment.
The interpreter adds to this environment any definition entered using
the define and define-macro special forms. Once the
evaluation of an expression is completed, the value or values resulting
from the evaluation are output to the interaction channel by the
pretty printer. The special "void" object is not output. This object
is returned by most procedures and special forms which the Scheme
standard defines as returning an unspecified value (e.g. write,
set!, define).
When execution starts, the ports associated with `(current-input-port)', `(current-output-port)' and `(current-error-port)' all refer to the interaction channel.
The evaluation of an expression may stop before it is completed for the following reasons:
(step) was evaluated.
When an evaluation stops, a message is displayed indicating the reason and location where the evaluation was stopped. The location information includes, if known, the name of the procedure where the evaluation was stopped and the source code location in the format `stream@line.column', where stream is either a string naming a file or `(console)'.
A nested REPL is then initiated in the context of the point of execution where the evaluation was stopped. The nested REPL's continuation and evaluation environment are the same as the point where the evaluation was stopped. This allows the inspection of the evaluation context, which is particularly useful to determine the exact location and cause of an error.
The prompt of nested REPLs includes the nesting level. An end of file (usually ^D on UNIX and ^Z on MSDOS and Microsoft Windows) will cause the current REPL to be aborted and the enclosing REPL (one nesting level less) to be resumed.
At any time the user can examine the frames in the REPL's continuation,
which is useful to determine which chain of procedure calls lead to an
error. Expressions entered at a nested REPL are evaluated in the
environment of the continuation frame currently being examined if that
frame was created by interpreted Scheme code. If the frame was created
by compiled Scheme code then expressions get evaluated in the global
interaction environment. This feature may be used in interpreted code
to fetch the value of a variable in the current frame or to change its
value with set!. Note that some special forms (define in
particular) can only be evaluated in the global interaction environment.
In addition to expressions, the REPL accepts the following special "comma" commands:
,?
,q
,t
,d
,(c expr)
,c
,s
step-level-set!) and then stop,
causing a nested REPL to be entered. Just before the evaluation step is
performed, a line is displayed (in the same format as trace)
which indicates the expression that is being evaluated. If the
evaluation step produces a result, the result is also displayed on
another line. A nested REPL is then entered after displaying a message
which describes the next step of the computation. This command can
only be used to continue a computation that was stopped due to a user
interrupt, breakpoint or a single-step.
,l
,n
,+
,-
,y
,b
,i
,e
Here is a sample interaction with gsi:
% gsi Gambit Version 4.0 beta 1 > (define (f x) (let* ((y 10) (z (* x y))) (- x z))) > (define (g n) (if (> n 1) (+ 1 (g (/ n 2))) (f 'oops))) > (g 8) *** ERROR IN (stdin)@1.32 -- NUMBER expected (* 'oops 10) 1> ,i #<procedure f> = (lambda (x) (let ((y 10)) (let ((z (* x y))) (- x z)))) 1> ,b 0 f (stdin)@1:32 (* x y) 1 g (stdin)@2:32 (g (/ n 2)) 2 g (stdin)@2:32 (g (/ n 2)) 3 g (stdin)@2:32 (g (/ n 2)) 4 (interaction) (stdin)@3:1 (g 8) 5 ##initial-continuation 1> ,e y = 10 x = oops 1> ,+ 1 g (stdin)@2.32 (g (/ n 2)) 1-1> ,e n = 2 1-1> ,+ 2 g (stdin)@2.32 (g (/ n 2)) 1-2> ,e n = 4 1-2> ,+ 3 g (stdin)@2.32 (g (/ n 2)) 1-3> ,e n = 8 1-3> ,0 0 f (stdin)@1.32 (* x y) 1> (set! x 1) 1> ,e y = 10 x = 1 1> ,(c (* x y)) -6 > ,q |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In batch mode the command line arguments designate files to be loaded
and, in the case of `-e' options, expressions to be evaluated.
Note that `-e' options can be interspersed with the files on the
command line. The interpreter scans the command line arguments from
left to right, loading files with the load procedure and
evaluating expressions with the eval procedure in the global
interaction environment.
Files can have no extension, or the extension `.scm' or
`.six' or `.on' where n is a positive integer
that acts as a version number (the `.on' extension is used
for object files produced by gsc). When the file name has no
extension the load procedure first attempts to load the file
with no extension as a Scheme source file. If that file doesn't exist
it completes the file name with a `.on' extension with the
highest consecutive version number starting with 1, and loads that
file as an object file. If that file doesn't exist the file extension
`.scm' and `.six' will be tried in that order.
If the extension of the file loaded is `.scm' the content of the file will be parsed using the normal Scheme prefix syntax. If the extension of the file loaded is `.six' the content of the file will be parsed using the Scheme infix syntax extension (see 7. Extensions to Scheme).
When execution starts, the ports associated with `(current-input-port)', `(current-output-port)' and `(current-error-port)' refer respectively to the standard input (`stdin'), standard output (`stdout') and the standard error (`stderr') of the interpreter.
The interpreter exits after loading the files or as soon as an error occurs.
For example, under UNIX:
% cat m1.scm (display "hello") (newline) % cat m2.scm (display "world") (newline) % gsi -e "(display 1)" m1 -e "(display 2)" m2 -e "(display 3)" 1hello 2world 3 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are two ways to customize the interpreter. When the interpreter starts off it tries to execute a `(load "~~/gambcext")' (for an explanation of how file names are interpreted see 5. Handling of file names). An error is not signaled if the file does not exist. Interpreter extensions and patches that are meant to apply to all users and all modes should go in that file.
Extensions which are meant to apply to a single user or to a specific
directory are best placed in the initialization file, which is a
file containing Scheme code. In all modes, the interpreter first
tries to locate the initialization file by searching the following
locations: `gambcini' and `~/gambcini' (with no extension, a
`.scm' extension, and a `.six' extension in that order).
The first file that is found is examined as though the expression
(include initialization-file) had been entered at the
read-eval-print loop where initialization-file is the file that
was found. Note that by using an include the macros defined in
the initialization file will be visible from the read-eval-print loop
(this would not have been the case if load had been used). The
initialization file is not searched for or examined if the `-f'
option is specified.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Under UNIX, the status is zero when the interpreter exits normally and is nonzero when the interpreter exits due to an error.
For example, if the shell is sh:
% gsi nonexistent.scm *** ERROR IN ##main -- No such file or directory (load "nonexistent.scm") % echo $? 1 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gambit's load procedure treats specially files that begin with
the two characters `#!' or `@;'. Such files are called
script files. In addition to indicating that the file is a
script, the first line provides information about the source code
language to be used by the load procedure. After the two
characters `#!' or `@;' the system will search for the first
substring matching one of the following language specifying tokens:
scheme-r4rs
scheme-r5rs
scheme-ieee-1178-1990
scheme-srfi-0
scheme-six
If a language specifying token is not found, load will use the
same language as a nonscript file (i.e. it uses the file extension and
runtime system options to determine the language).
After processing the first line, load will read the rest of the file
and execute it. If this file is being loaded because it is an argument
on the interpreter's command line, the interpreter will
command-line procedure so that it returns a list
containing the expanded file name of the script file and the
arguments following the script file on the command line.
This is done before the script is executed.
main is called with the
command-line arguments. The way this is done depends on the format of
the script's first line. If there is a space after the two characters
`#!' or `@;' then main is called with the equivalent of
(main (cdr (command-line))) and main is expected to return
a process exit status code in the range 0 to 255. This conforms to SRFI
22. If there is no space after the two characters `#!' or
`@;' then main is called with the equivalent of (apply
main (cdr (command-line))) and the process exit status code is 0
(main's result is ignored). Note that the Gambit-C system
has a predefined main procedure which accepts any number of arguments
and returns 0, so it is perfectly valid for a script to not define
main and to do all its processing with top-level expressions.
main returns, the interpreter terminates. That is the
command-line arguments after a script file are not taken to be
other files to load.
Under UNIX, the Gambit-C installation process will have created the executable `gsi' and also the executables `scheme-r5rs', `scheme-srfi-0', etc as links to `gsi'. A Scheme script need only start with the name of the desired Scheme language variant prefixed with `#!', possibly a space, and the directory where the Gambit-C executables are stored. This script should be made executable by setting the execute permission bits (with a `chmod +x <script>'. Here is an example of a script which lists the files in the current directory:
#!/usr/local/Gambit-C/bin/scheme-srfi-0 (display "files:\n") (pp (directory-files (current-directory))) |
Here is another UNIX script, using the Scheme infix syntax extension, which takes a single integer argument and prints the numbers from 1 to that integer:
#!/usr/local/Gambit-C/bin/scheme-six
void main (obj n_str)
{
int n = \string->number(n_str);
for (int i=1; i<=n; i++)
pp(i);
}
|
Under UNIX, for maximal portability it is a good idea to start scripts indirectly through the `/usr/bin/env' program, so that the executable of the interpreter will be searched in the user's `PATH'. This is what SRFI 22 recommends. For example here is a script that mimics the UNIX `cat' utility for text files:
#! /usr/bin/env scheme-r5rs
(define (main arguments)
(for-each display-file (cdr arguments))
0)
(define (display-file filename)
(display
(call-with-input-file filename
(lambda (p)
(read-line p #f)))))
|
Under Microsoft Windows, the Gambit-C installation process will have created the executable `gsi.exe' and also the batch files `scheme-r5rs.bat', `scheme-srfi-0.bat', etc which simply invoke `gsi.exe'. A Scheme script need only start with the name of the desired Scheme language variant prefixed with `@;' and possibly a space. A UNIX script can be converted to a Microsoft Windows script simply by changing the first line and storing the script in a file whose name has a `.bat' or `.cmd' extension:
@;scheme-srfi-0 %~f0 %* (display "files:\n") (pp (directory-files (current-directory))) |
Note that Microsoft Windows always searches executables in the user's `PATH', so there is no need for an indirection through `/usr/bin/env'. However the first line must end with `%~f0 %*' to pass the expanded filename of the script and command line arguments to the interpreter.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis:
gsc [-:runtimeoption,...] [-f] [-i] [-e expressions]
[-prelude expressions] [-postlude expressions]
[-dynamic] [-cc-options options] [-ld-options options]
[-warnings] [-verbose] [-report] [-expansion]
[-gvm] [-debug] [-track-scheme]
[-o output] [-c] [-flat] [-l base] [file...]
|
3.1 Interactive mode 3.2 Customization 3.3 Batch mode 3.4 Link files
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When no command line argument is present other than options the compiler
behaves like the interpreter in interactive mode. The only difference
with the interpreter is that some additional predefined procedures are
available (notably compile-file).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Just like the interpreter, the compiler will examine the initialization file unless the `-f' option is specified.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In batch mode gsc takes a set of file names (either with
`.scm', `.six', `.c', or no extension) on the command
line and compiles each Scheme source file into a C file. File names
with no extension are taken to be Scheme source files and a `.scm'
extension is automatically appended to the file name. For each Scheme
source file `file.scm' and `file.six', the C file
`file.c' stripped of its directory will be produced (i.e. the
C file is created in the current working directory).
The C files produced by the compiler serve two purposes. They will be processed by a C compiler to generate object files, and they also contain information to be read by Gambit's linker to generate a link file. The link file is a C file that collects various linking information for a group of modules, such as the set of all symbols and global variables used by the modules. The linker is automatically invoked unless the `-c' or `-dynamic' options appear on the command line.
Compiler options must be specified before the first file name and after the `-:' runtime option (see section 4. Runtime options for all programs). If present, the `-f' and `-i' compiler options must come first. The available options are:
-f
-i
-e expressions
-prelude expressions
-postlude expressions
-cc-options options
-ld-options options
-warnings
-verbose
-report
-expansion
-gvm
-debug
-track-scheme
-o output
-c
-dynamic
-flat
-l base
The `-i' option forces the compiler to process the remaining command line arguments like the interpreter.
The `-e' option evaluates the specified expressions in the interaction environment.
The `-prelude' option adds the specified expressions to the top of the source code being compiled. The main use of this option is to supply declarations on the command line. For example the following invocation of the compiler will compile the file `bench.scm' in unsafe mode:
% gsc -prelude "(declare (not safe))" bench.scm |
The `-postlude' option adds the specified expressions to the bottom of the source code being compiled. The main use of this option is to supply the expression that will start the execution of the program. For example:
% gsc -postlude "(start-bench)" bench.scm |
The `-cc-options' option is only meaningful when the `-dynamic' option is also used. The `-cc-options' option adds the specified options to the command that invokes the C compiler. The main use of this option is to specify the include path, some symbols to define or undefine, the optimization level, or any C compiler option that is different from the default. For example:
% gsc -dynamic -cc-options "-U___SINGLE_HOST -O2 -I src/include" bench.scm |
The `-ld-options' option is only meaningful when the `-dynamic' option is also used. The `-ld-options' option adds the specified options to the command that invokes the C linker. The main use of this option is to specify additional object files or libraries that need to be linked, or any C linker option that is different from the default (such as the library search path and flags to select between static and dynamic linking). For example:
% gsc -dynamic -ld-options "-L /usr/X11R6/lib -lX11 -static" bench.scm |
The `-warnings' option displays on standard output all warnings that the compiler may have.
The `-verbose' option displays on standard output a trace of the compiler's activity.
The `-report' option displays on standard output a global variable usage report. Each global variable used in the program is listed with 4 flags that indicate if the global variable is defined, referenced, mutated and called.
The `-expansion' option displays on standard output the source code after expansion and inlining by the front end.
The `-gvm' option generates a listing of the intermediate code for the "Gambit Virtual Machine" (GVM) of each Scheme file on `file.gvm'.
The `-debug' option causes debugging information to be saved in the
code generated. With this option run time error messages indicate the
source code and its location, the backtraces are more precise, and
pp will display the source code of compiled procedures. The
debugging information is large (the size of the object file is typically
4 times bigger).
The `-track-scheme' options causes the generation of `#line' directives that refer back to the Scheme source code. This allows the use of a C debugger to debug Scheme code.
The `-o' option sets the name of the output file generated by the compiler. If a link file is being generated the name specified is that of the link file. Otherwise the name specified is that of the C file (this option is ignored if the compiler is generating more than one output file or is generating a dynamically loadable object file).
If the `-c' and `-dynamic' options do not appear on the command line, the Gambit linker is invoked to generate the link file from the set of C files specified on the command line or produced by the Gambit compiler. Unless the name is specified explicitly with the `-o' option, the link file is named `last_.c', where `last.c' is the last file in the set of C files. When the `-c' option is specified, the Scheme source files are compiled to C files. When the `-dynamic' option is specified, the Scheme source files are compiled to dynamically loadable object files (`.on' extension).
The `-flat' option is only meaningful if a link file is being generated (i.e. the `-c' and `-dynamic' options are absent). The `-flat' option directs the Gambit linker to generate a flat link file. By default, the linker generates an incremental link file (see the next section for a description of the two types of link files).
The `-l' option is only meaningful if an incremental link file is being generated (i.e. the `-c', `-dynamic' and `-flat' options are absent). The `-l' option specifies the link file (without the `.c' extension) of the base library to use for the incremental link. By default the link file of the Gambit runtime library is used (i.e. `~~/lib/_gambc.c').
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gambit can be used to create applications and libraries of Scheme modules. This section explains the steps required to do so and the role played by the link files.
In general, an application is composed of a set of Scheme modules and C modules. Some of the modules are part of the Gambit runtime library and the other modules are supplied by the user. When the application is started it must setup various global tables (including the symbol table and the global variable table) and then sequentially execute the Scheme modules (more or less as if they were being loaded one after another). The information required for this is contained in one or more link files generated by the Gambit linker from the C files produced by the Gambit compiler.
The order of execution of the Scheme modules corresponds to the order of the modules on the command line which produced the link file. The order is usually important because most modules define variables and procedures which are used by other modules (for this reason the program's main computation is normally started by the last module).
When a single link file is used to contain the linking information of all the Scheme modules it is called a flat link file. Thus an application built with a flat link file contains in its link file both information on the user modules and on the runtime library. This is fine if the application is to be statically linked but is wasteful in a shared-library context because the linking information of the runtime library can't be shared and will be duplicated in all applications (this linking information typically takes hundreds of Kbytes).
Flat link files are mainly useful to bundle multiple Scheme modules to
make a runtime library (such as the Gambit runtime library) or to make a
single file that can be loaded with the load procedure.
An incremental link file contains only the linking information that is not already contained in a second link file (the "base" link file). Assuming that a flat link file was produced when the runtime library was linked, an application can be built by linking the user modules with the runtime library's link file, producing an incremental link file. This allows the creation of a shared-library which contains the modules of the runtime library and its flat link file. The application is dynamically linked with this shared-library and only contains the user modules and the incremental link file. For small applications this approach greatly reduces the size of the application because the incremental link file is small. A "hello world" program built this way can be as small as 5 Kbytes. Note that it is perfectly fine to use an incremental link file for statically linked programs (there is very little loss compared to a single flat link file).
Incremental link files may be built from other incremental link files. This allows the creation of shared-libraries which extend the functionality of the Gambit runtime library.
3.4.1 Building an executable program 3.4.2 Building a loadable library 3.4.3 Building a shared-library 3.4.4 Other compilation options and flags
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The simplest way to create an executable program is to call up
gsc to compile each Scheme module into a C file and create an
incremental link file. The C files and the link file must then be
compiled with a C compiler and linked (at the object file level) with
the Gambit runtime library and possibly other libraries (such as the
math library and the dynamic loading library). Here is for example how
a program with three modules (one in C and two in Scheme) can be built:
% uname -a
Linux bailey 1.2.13 #2 Wed Aug 28 16:29:41 GMT 1996 i586
% cat m1.c
int power_of_2 (int x) { return 1<<x; }
% cat m2.scm
(c-declare "extern int power_of_2 ();")
(define pow2 (c-lambda (int) int "power_of_2"))
(define (twice x) (cons x x))
% cat m3.scm
(write (map twice (map pow2 '(1 2 3 4)))) (newline)
% gsc -c m2.scm # create m2.c (note: .scm is optional)
% gsc -c m3.scm # create m3.c (note: .scm is optional)
% gsc m2.c m3.c # create the incremental link file m3_.c
% gcc m1.c m2.c m3.c m3_.c -lgambc
% a.out
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
|
Alternatively, the three invocations of gsc can be replaced by a
single invocation:
% gsc m2 m3 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To bundle multiple modules into a single file that can be dynamically
loaded with the load procedure, a flat link file is needed.
When compiling the C files and link file generated, the flag
`-D___DYNAMIC' must be passed to the C compiler. The three
modules of the previous example can be bundled in this way:
% uname -a
Linux bailey 1.2.13 #2 Wed Aug 28 16:29:41 GMT 1996 i586
% gsc -flat -o foo.c m2 m3
m2:
m3:
*** WARNING -- "cons" is not defined,
*** referenced in: ("m2.c")
*** WARNING -- "map" is not defined,
*** referenced in: ("m3.c")
*** WARNING -- "newline" is not defined,
*** referenced in: ("m3.c")
*** WARNING -- "write" is not defined,
*** referenced in: ("m3.c")
% gcc -shared -fPIC -D___DYNAMIC m1.c m2.c m3.c foo.c -o foo.o1
% gsi
Gambit Version 4.0 beta 1
> (load "foo")
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
"/users/feeley/foo.o1"
> ,q
|
The warnings indicate that there are no definitions (defines or
set!s) of the variables cons, map, newline
and write in the set of modules being linked. Before
`foo.o1' is loaded, these variables will have to be bound; either
implicitly (by the runtime library) or explicitly.
Here is a more complex example, under Solaris, which shows how to build a loadable library `mymod.o1' composed of the files `m1.scm', `m2.scm' and `x.c' that links to system shared libraries (for X-windows):
% uname -a
SunOS ungava 5.6 Generic_105181-05 sun4m sparc SUNW,SPARCstation-20
% gsc -flat -o mymod.c m1 m2
m1:
m2:
*** WARNING -- "*" is not defined,
*** referenced in: ("m1.c")
*** WARNING -- "+" is not defined,
*** referenced in: ("m2.c")
*** WARNING -- "display" is not defined,
*** referenced in: ("m2.c" "m1.c")
*** WARNING -- "newline" is not defined,
*** referenced in: ("m2.c" "m1.c")
*** WARNING -- "write" is not defined,
*** referenced in: ("m2.c")
% gcc -fPIC -c -I../lib -D___DYNAMIC mymod.c m1.c m2.c x.c
% /usr/ccs/bin/ld -G -o mymod.o1 mymod.o m1.o m2.o x.o -lX11 -lsocket
% gsi mymod.o1
hello from m1
hello from m2
(f1 10) = 22
% cat m1.scm
(define (f1 x) (* 2 (f2 x)))
(display "hello from m1")
(newline)
(c-declare "#include \"x.h\"")
(define x-initialize (c-lambda (char-string) bool "x_initialize"))
(define x-display-name (c-lambda () char-string "x_display_name"))
(define x-bell (c-lambda (int) void "x_bell"))
% cat m2.scm
(define (f2 x) (+ x 1))
(display "hello from m2")
(newline)
(display "(f1 10) = ")
(write (f1 10))
(newline)
(x-initialize (x-display-name))
(x-bell 50) ; sound the bell at 50%
% cat x.c
#include <X11/Xlib.h>
static Display *display;
int x_initialize (char *display_name)
{
display = XOpenDisplay (display_name);
return display != NULL;
}
char *x_display_name (void)
{
return XDisplayName (NULL);
}
void x_bell (int volume)
{
XBell (display, volume);
XFlush (display);
}
% cat x.h
int x_initialize (char *display_name);
char *x_display_name (void);
void x_bell (int);
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A shared-library can be built using an incremental link file or a flat link file. An incremental link file is normally used when the Gambit runtime library (or some other library) is to be extended with new procedures. A flat link file is mainly useful when building a "primal" runtime library, which is a library (such as the Gambit runtime library) that does not extend another library. When compiling the C files and link file generated, the flags `-D___LIBRARY' and `-D___SHARED' must be passed to the C compiler. The flag `-D___PRIMAL' must also be passed to the C compiler when a primal library is being built.
A shared-library `mylib.so' containing the two first modules of the previous example can be built this way:
% uname -a Linux bailey 1.2.13 #2 Wed Aug 28 16:29:41 GMT 1996 i586 % gsc -o mylib.c m2 % gcc -shared -fPIC -D___LIBRARY -D___SHARED m1.c m2.c mylib.c -o mylib.so |
Note that this shared-library is built using an incremental link file
(it extends the Gambit runtime library with the procedures pow2
and twice). This shared-library can in turn be used to build
an executable program from the third module of the previous example:
% gsc -l mylib m3 % gcc m3.c m3_.c mylib.so -lgambc % LD_LIBRARY_PATH=.:/usr/local/lib a.out ((2 . 2) (4 . 4) (8 . 8) (16 . 16)) |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The performance of the code can be increased by passing the `-D___SINGLE_HOST' flag to the C compiler. This will merge all the procedures of a module into a single C procedure, which reduces the cost of intra-module procedure calls. In addition the `-O' option can be passed to the C compiler. For large modules, it will not be practical to specify both `-O' and `-D___SINGLE_HOST' for typical C compilers because the compile time will be high and the C compiler might even fail to compile the program for lack of memory.
Normally C compilers will not automatically search `/usr/local/Gambit-C/include' for header files so the flag `-I/usr/local/Gambit-C/include' should be passed to the C compiler. Similarly, C compilers/linkers will not automatically search `/usr/local/Gambit-C/lib' for libraries so the flag `-L/usr/local/Gambit-C/lib' should be passed to the C compiler/linker. For alternatives see @xref{Top}.
A variety of flags are needed by some C compilers when compiling a shared-library or a dynamically loadable library. Some of these flags are: `-shared', `-call_shared', `-rdynamic', `-fpic', `-fPIC', `-Kpic', `-KPIC', `-pic', `+z'. Check your compiler's documentation to see which flag you need.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Both gsi and gsc as well as executable programs compiled
and linked using gsc take a `-:' option which supplies
parameters to the runtime system. This option must appear first on
the command line. The colon is followed by a comma separated list of
options with no intervening spaces.
The available options are:
mheapsize
hheapsize
llivepercent
s
S
d[OPT...]
t[OPT...]
cencoding
=directory
+argument
The `m' option specifies the minimum size of the heap. The `m' is immediately followed by an integer indicating the number of kilobytes of memory. The heap will not shrink lower than this size. By default, the minimum size is 0.
The `h' option specifies the maximum size of the heap. The `h' is immediately followed by an integer indicating the number of kilobytes of memory. The heap will not grow larger than this size. By default, there is no limit (i.e. the heap will grow until the virtual memory is exhausted).
The `l' option specifies the percentage of the heap that will be occupied with live objects at the end of a garbage collection. The `l' is immediately followed by an integer between 1 and 100 inclusively indicating the desired percentage. The garbage collector will resize the heap to reach this percentage occupation. By default, the percentage is 50.
The `s' option selects standard Scheme mode. In this mode the reader is case insensitive and keywords are not recognized. The `S' option selects Gambit Scheme mode (the reader is case sensitive and recognizes keywords which end with a colon). By default Gambit Scheme mode is used.
The `d' option sets various debugging options. The letter `d' is followed by a sequence of letters indicating suboptions.
p
a
r
s
q
i
c
-
level
The default debugging options are equivalent to -:dpqi1 (i.e. an
uncaught exception in the primordial thread terminates the program after
displaying an error message). If the letter `d' is not followed by
suboptions, it is equivalent to -:dpri1 (i.e. a new REPL is
started only when an uncaught exception occurs in the primordial
thread).
The `t' option sets vaious terminal options. This is not fully implemented yet.
The `c' option selects the default character encoding for I/O. This is not fully implemented yet.
The `=' option overrides the setting of the Gambit installation directory.
The `+' option adds the text that follows to the command line before other arguments.
If the environment variable `GAMBCOPT' is defined, the runtime system will take its options from that environment variable. A `-:' option can be used to override some or all of the runtime system options. For example:
% GAMBCOPT=d0,=~/my-gambit2 % export GAMBCOPT % gsi -e '(pp (path-expand "~~")) (/ 1 0)' "/u/feeley/my-gambit2/" % echo $? 1 % gsi -:d1 -e '(pp (path-expand "~~")) (/ 1 0)' "/u/feeley/my-gambit2/" *** ERROR IN string@1.25 -- Divide by zero (/ 1 0) |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gambit uses a naming convention for files that is compatible with the one used by the underlying operating system but extended to allow referring to the home directory of the current user or some specific user and the Gambit installation directory.
A file is designated using a path. Each component of a path is separated by a `/' under UNIX, by a `/' or `\' under MSDOS and Microsoft Windows, and by a `:' under Classic Mac OS. A leading separator indicates an absolute path under UNIX, MSDOS and Microsoft Windows but indicates a relative path under Classic Mac OS. A path which does not contain a path separator is relative to the current working directory on all operating systems (including Classic Mac OS). A drive specifier such as `C:' may prefix a file name under MSDOS and Microsoft Windows.
Under Classic Mac OS the folder `Gambit-C' must exist in the `Preferences' folder and must not be an alias.
In this document and the rest of this section in particular, `/' has been used to represent the path separator.
A path which starts with the characters `~/' designates a file in the user's home directory. The user's home directory is contained in the `HOME' environment variable under UNIX, MSDOS and Microsoft Windows. Under Classic Mac OS this designates the folder which contains the application.
A file name which starts with the characters `~user/' designates a file in the home directory of the given user. Under UNIX this is found using the password file. There is no equivalent under MSDOS, Microsoft Windows, and Classic Mac OS.
A file name which starts with the characters `~~/' designates a file in the Gambit installation directory. This directory is normally `/usr/local/Gambit-C/' under UNIX, `C:\Gambit-C\' under MSDOS and Microsoft Windows, and under Classic Mac OS the `Gambit-C' folder. To override this binding under UNIX, MSDOS and Microsoft Windows, define the `GAMBCOPT' environment variable.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gambit comes with the Emacs package `gambit.el' which provides a nice environment for running Gambit from within the Emacs editor. This package filters the standard output of the Gambit process and when it intercepts a location information (in the format `stream@line.column' where stream is either `(stdin)' if the expression was obtained from standard input or a string naming a file) it opens a window to highlight the corresponding expression.
To use this package, make sure the file `gambit.el' is accessible from your load-path and that the following lines are in your `.emacs' file:
(autoload 'gambit-inferior-mode "gambit" "Hook Gambit mode into cmuscheme.") (autoload 'gambit-mode "gambit" "Hook Gambit mode into scheme.") (add-hook 'inferior-scheme-mode-hook (function gambit-inferior-mode)) (add-hook 'scheme-mode-hook (function gambit-mode)) (setq scheme-program-name "gsi -:t") |
Alternatively, if you don't mind always loading this package, you can simply add this line to your `.emacs' file:
(require 'gambit) |
You can then start an inferior Gambit process by typing `M-x run-scheme'. The commands provided in `cmuscheme' mode will be available in the Gambit interaction buffer (i.e. `*scheme*') and in buffers attached to Scheme source files. Here is a list of the most useful commands (for a complete list type `C-h m' in the Gambit interaction buffer):
C-x C-e
C-c C-z
C-c C-l
(load file).
C-c C-k
(compile-file file).
The file `gambit.el' provides these additional commands:
C-c c
C-c s
C-c l
C-c [
C-c ]
C-c _
These commands can be shortened to `M-c', `M-s', `M-l', `M-[', `M-]', and `M-_' respectively by adding this line to your `.emacs' file:
(setq gambit-repl-command-prefix "\e") |
This is more convenient to type than the two keystroke `C-c' based sequences but the purist may not like this because it does not follow normal Emacs conventions.
Here is what a typical `.emacs' file will look like:
(setq load-path
(cons "/usr/local/Gambit-C/share/emacs/site-lisp" ; location of gambit.el
load-path))
(setq scheme-program-name "/tmp/gsi -:t") ; if gsi not in executable path
(setq gambit-highlight-color "gray") ; if you don't like the default
(setq gambit-repl-command-prefix "\e") ; if you want M-c, M-s, etc
(require 'gambit)
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Gambit Scheme system conforms to the R4RS, R5RS and IEEE Scheme standards. Gambit supports a number of extensions to these standards by extending the behavior of standard special forms and procedures, and by adding special forms and procedures.
7.1 Standard special forms and procedures 7.2 Additional special forms and procedures 7.3 Unstable additions 7.4 Other extensions
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The extensions given in this section are all compatible with the Scheme standards. This means that the special forms and procedures behave as defined in the standards when they are used according to the standards.
These procedures take an optional argument which specifies special settings (character encoding, end-of-line encoding, buffering, etc).
*** This documentation is incomplete!
These procedures do nothing.
The read, write and display procedures take an
optional readtable argument which specifies the readtable to use.
If it is not specified, the readtable defaults to the current readtable.
These procedures support the following features.
keyword?).
#\newline
#\space
#\nul
#\bel
#\backspace
#\tab
#\linefeed
#\vt
#\page
#\return
#\rubout
#\n
#"
character and it must represent an exact integer, for example
#\#x20 is the space character, #\#d9 is the tab character,
and #\#e1.2e2 is the lower case character "x")
\n
\a
\b
\t
\v
\f
\r
\"
"
\\
\
\ooo
\xhh
#!" objects:
#!eof
#!void
#!optional
#!rest
#!key
+inf.
-inf.
+nan.
-0.
In addition to the above extensions to the Scheme syntax, the reader supports an infix syntax extension which is called SIX (Scheme Infix eXtension). The backslash character is a delimiter that marks the beginning of a single datum expressed in the infix syntax (the details are given below). One way to think about it is that the backslash character escapes the prefix syntax temporarily to use the infix syntax. For example a three element list could be written as `(X \\Y Z)', the elements X and Z are expressed using the normal prefix datum syntax and Y is expressed using the infix syntax. When the reader encounters an infix datum, it constructs a syntax tree for that particular datum. Each node of this tree is represented with a list whose first element is a symbol indicating the type of node. For example, `(six.identifier abc)' is the representation of the infix identifier `abc' and `(six.index (six.identifier abc) (six.identifier i))' is the representation of the infix datum `abc[i];'.
The infix grammar is shown below with the corresponding representation on the right hand side. *** The grammar is out of date!
| <infix datum> ::={} | |
| $1 | |
| <stat> ::={} | |
| $1 | |
| | | $1 |
| | | $1 |
| | | $1 |
| | | $1 |
| | | (six.compound)
|
| <if stat> ::={} | |
(six.if $3 $5)
| |
| | | (six.if $3 $5 $7)
|
| <while stat> ::={} | |
(six.while $3 $5)
| |
| <for stat> ::={} | |
(six.for $3 $5 $7 $9)
| |
| <oexpr> ::={} | |
| $1 | |
| | | |
| <expression stat> ::={} | |
(six.expression $1)
| |
| | | (six.clause $1)
|
| <expr> ::={} | |
| $1 | |
| <expr18> ::={} | |
(six.x:-y $1 $3)
| |
| | | $1 |
| <expr17> ::={} | |
(|six.x,y| $1 $3)
| |
| | | $1 |
| <expr16> ::={} | |
(six.x:=y $1 $3)
| |
| | | $1 |
| <expr15> ::={} | |
(six.x%=y $1 $3)
| |
| | | (six.x&=y $1 $3)
|
| | | (six.x*=y $1 $3)
|
| | | (six.x+=y $1 $3)
|
| | | (six.x-=y $1 $3)
|
| | | (six.x/=y $1 $3)
|
| | | (six.x<<=y $1 $3)
|
| | | (six.x=y $1 $3)
|
| | | (six.x>>=y $1 $3)
|
| | | (six.x^=y $1 $3)
|
| | | (|six.x\|=y| $1 $3)
|
| | | $1 |
| <expr14> ::={} | |
(six.x:y $1 $3)
| |
| | | $1 |
| <expr13> ::={} | |
(six.x?y:z $1 $3 $5)
| |
| | | $1 |
| <expr12> ::={} | |
(|six.x\|\|y| $1 $3)
| |
| | | $1 |
| <expr11> ::={} | |
(six.x&&y $1 $3)
| |
| | | $1 |
| <expr10> ::={} | |
(|six.x\|y| $1 $3)
| |
| | | $1 |
| <expr9> ::={} | |
(six.x^y $1 $3)
| |
| | | $1 |
| <expr8> ::={} | |
(six.x&y $1 $3)
| |
| | | $1 |
| <expr7> ::={} | |
(six.x!=y $1 $3)
| |
| | | (six.x==y $1 $3)
|
| | | $1 |
| <expr6> ::={} | |
(six.x<y $1 $3)
| |
| | | (six.x<=y $1 $3)
|
| | | (six.x>y $1 $3)
|
| | | (six.x>=y $1 $3)
|
| | | $1 |
| <expr5> ::={} | |
(six.x<<y $1 $3)
| |
| | | (six.x>>y $1 $3)
|
| | | $1 |
| <expr4> ::={} | |
(six.x+y $1 $3)
| |
| | | (six.x-y $1 $3)
|
| | | $1 |
| <expr3> ::={} | |
(six.x%y $1 $3)
| |
| | | (six.x*y $1 $3)
|
| | | (six.x/y $1 $3)
|
| | | $1 |
| <expr2> ::={} | |
| <expr2> | (six.&x $2)
|
| | <expr2> | (six.+x $2)
|
| | <expr2> | (six.-x $2)
|
| | <expr2> | (six.*x $2)
|
| | <expr2> | (six.!x $2)
|
| | | (six.cut)
|
| | <expr2> | (six.++x $2)
|
| | <expr2> | (six.--x $2)
|
| | <expr2> | (six.~x $2)
|
| | | $1 |
| <expr1> ::={} | |
(six.x++ $1)
| |
| | | (six.x-- $1)
|
| | | (six.call $1)
|
| | | (six.index $1)
|
| | | (six.arrow $1 $3)
|
| | | (six.dot $1 $3)
|
| | | $1 |
| <expr0> ::={} | |
(six.identifier $1)
| |
| | | (six.string $1)
|
| | | (six.char $1)
|
| | | (six.number $1)
|
| | <expr> | $2 |
| | <block> | $2 |
| | ... | (six.list $1)
|
| | | (six.prefix $2)
|
| | | (six.function $1 $3 $5)
|
| <block> ::={} | |
| <stat list> | (six.compound . $2)
|
| <stat list> ::={} | |
| <stat list> | ($1 . $2)
|
| | | |
| <declaration> ::={} | |
| <identifier> | (six.declaration $1 $2 $4)
|
| | <identifier> | (six.function-declaration $1 $2 $4 $6)
|
| <parameter list> ::={} | |
| $1 | |
| | | |
| <nonempty parameter list> ::={} | |
($1 . $2)
| |
| | | ($1)
|
| <parameter> ::={} | |
| <identifier> | ($1 $2)
|
| <type> ::={} | |
obj
| |
| | | int
|
| | | void
|
To make SIX useful for writing programs, most of the symbols representing the type of node are predefined macros which approximate the semantics of C. The semantics of SIX can be changed or extended by redefining these macros.
These procedures take any number of arguments including no argument.
This is useful to test if the elements of a list are sorted in a
particular order. For example, testing that the list of numbers
lst is sorted in nondecreasing order can be done with the call
(apply < lst).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
file must be a string naming an existing file containing Scheme
source code. The include special form splices the content of the
specified source file. This form can only appear where a define
form is acceptable.
For example:
(include "macros.scm") (define (f lst) (include "sort.scm") (map sqrt (sort lst))) |
Define name as a macro special form which expands into body.
This form can only appear where a define form is acceptable.
Macros are lexically scoped. The scope of a local macro definition
extends from the definition to the end of the body of the surrounding
binding construct. Macros defined at the top level of a Scheme module
are only visible in that module. To have access to the macro
definitions contained in a file, that file must be included using the
include special form. Macros which are visible from the REPL are
also visible during the compilation of Scheme source files.
For example:
(define-macro (push val var) `(set! ,var (cons ,val ,var))) (define-macro (unless test . body) `(if ,test #f (begin ,@body))) |
To examine the code into which a macro expands you can use the
compiler's `-expansion' option or the pp procedure.
For example:
> (define-macro (push val var) `(set! ,var (cons ,val ,var))) > (pp (lambda () (push 1 stack) (push 2 stack) (push 3 stack))) (lambda () (set! stack (cons 1 stack)) (set! stack (cons 2 stack)) (set! stack (cons 3 stack))) |
This form introduces declarations to be used by the compiler
(currently the interpreter ignores the declarations). This form can
only appear where a define form is acceptable. Declarations
are lexically scoped in the same way as macros. The following
declarations are accepted by the compiler:
(dialect)
(strategy)
([not] inline)
(inlining-limit n)
define or lambda) and the call site must
be declared as (inline), and the compiler must be able to find
the definition of the procedure referred to at the call site (if the
procedure is bound to a global variable, the definition site must have a
(block) declaration). Note that inlining usually causes much
less code expansion than specified by the inlining limit (an expansion
around 10% is common for n=300).
([not] lambda-lift)
([not] standard-bindings var...)
([not] extended-bindings var...)
([not] safe)
char=? may disregard the type of its arguments in
`safe' as well as `not safe' mode.
([not] interrupts-enabled)
(number-type primitive...)
The default declarations used by the compiler are equivalent to:
(declare (ieee-scheme) (separate) (inline) (inlining-limit 300) (lambda-lift) (not standard-bindings) (not extended-bindings) (safe) (interrupts-enabled) (generic) ) |
These declarations are compatible with the semantics of Scheme.
Typically used declarations that enhance performance, at the cost of
violating the Scheme semantics, are: (standard-bindings),
(block), (not safe) and (fixnum).
( formal-argument-list ) |
r4rs-lambda-formals
#!optional optional-formal-argument* | empty
( variable initializer )
#!rest rest-formal-argument | empty
#!key keyword-formal-argument* | empty
( variable initializer )
( variable* ) |
( variable+ . variable ) |
variable
. variable
These forms are extended versions of the lambda and define
special forms of standard Scheme. They allow the use of optional and
keyword formal arguments with the syntax and semantics of the DSSSL
standard.
When the procedure introduced by a lambda (or define) is
applied to a list of actual arguments, the formal and actual arguments
are processed as specified in the R4RS if the lambda-formals (or
define-formals) is a r4rs-lambda-formals (or
r4rs-define-formals), otherwise they are processed as specified in
the DSSSL language standard:
#f. The initializer is
evaluated in an environment in which all previous formal arguments have
been bound.
#!key was specified in the formal-argument-list, there
shall be an even number of remaining actual arguments. These are
interpreted as a series of pairs, where the first member of each pair is
a keyword specifying the argument name, and the second is the
corresponding value. It shall be an error if the first member of a pair
is not a keyword. It shall be an error if the argument name is not the
same as a variable in a keyword-formal-argument, unless there is a
rest-formal-argument. If the same argument name occurs more than
once in the list of actual arguments, then the first value is used. If
there is no actual argument for a particular
keyword-formal-argument, then the variable is bound to the result
of evaluating initializer if one was specified, and otherwise to
#f. The initializer is evaluated in an environment in
which all previous formal arguments have been bound.
It shall be an error for a variable to appear more than once in a formal-argument-list.
It is unspecified whether variables receive their value by binding or by
assignment. Currently the compiler and interpreter use different
methods, which can lead to different semantics if
call-with-current-continuation is used in an initializer.
Note that this is irrelevant for DSSSL programs because
call-with-current-continuation does not exist in DSSSL.
For example:
> ((lambda (#!rest x) x) 1 2 3) (1 2 3) > (define (f a #!optional b) (list a b)) > (define (g a #!optional (b a) #!key (c (* a b))) (list a b c)) > (define (h a #!rest b #!key c) (list a b c)) > (f 1) (1 #f) > (f 1 2) (1 2) > (g 3) (3 3 9) > (g 3 4) (3 4 12) > (g 3 4 c: 5) (3 4 5) > (g 3 4 c: 5 c: 6) (3 4 5) > (h 7) (7 () #f) > (h 7 c: 8) (7 (c: 8) 8) > (h 7 c: 8 z: 9) (7 (c: 8 z: 9) 8) |
These special forms are part of the "C-interface" which allows Scheme code to interact with C code. For a complete description of the C-interface see 9. Interface to C.
Record data types similar to Pascal records and C struct
types can be defined using the define-structure special form.
The identifier name specifies the name of the new data type. The
structure name is followed by k identifiers naming each field of
the record. The define-structure expands into a set of definitions
of the following procedures:
Record data types have a The printed representation os a record data
type includes the name of the type and the name and value of each field.
Record data types can not be read by the read procedure.
For example:
> (define-structure point x y color) > (define p (make-point 3 5 'red)) > p #<point 3 x: 3 y: 5 color: red> > (point-x p) 3 > (point-color p) red > (point-color-set! p 'black) > p #<point 3 x: 3 y: 5 color: black> |
trace starts tracing calls to the specified procedures. When a
traced procedure is called, a line containing the procedure and its
arguments is displayed (using the procedure call expression syntax).
The line is indented with a sequence of vertical bars which indicate the
nesting depth of the procedure's continuation. After the vertical bars
is a greater-than sign which indicates that the evaluation of the call
is starting.
When a traced procedure returns a result, it is displayed with the same indentation as the call but without the greater-than sign. This makes it easy to match calls and results (the result of a given call is the value at the same indentation as the greater-than sign). If a traced procedure P1 performs a tail call to a traced procedure P2, then P2 will use the same indentation as P1. This makes it easy to spot tail calls. The special handling for tail calls is needed to preserve the space complexity of the program (i.e. tail calls are implemented as required by Scheme even when they involve traced procedures).
untrace stops tracing calls to the specified procedures. With no
argument, trace returns the list of procedures currently being
traced. The void object is returned by trace if it is passed one
or more arguments. With no argument untrace stops all tracing
and returns the void object. A compiled procedure may be traced but
only if it is bound to a global variable.
For example:
> (define (fact n) (if (< n 2) 1 (* n (fact (- n 1))))) > (trace fact) > (fact 5) | > (fact 5) | | > (fact 4) | | | > (fact 3) | | | | > (fact 2) | | | | | > (fact 1) | | | | | 1 | | | | 2 | | | 6 | | 24 | 120 120 > (trace -) *** WARNING -- Rebinding global variable "-" to an interpreted procedure > (define (fact-iter n r) (if (< n 2) r (fact-iter (- n 1) (* n r)))) > (trace fact-iter) > (fact-iter 5 1) | > (fact-iter 5 1) | | > (- 5 1) | | 4 | > (fact-iter 4 5) | | > (- 4 1) | | 3 | > (fact-iter 3 20) | | > (- 3 1) | | 2 | > (fact-iter 2 60) | | > (- 2 1) | | 1 | > (fact-iter 1 120) | 120 120 > (trace) (#<procedure fact-iter> #<procedure -> #<procedure fact>) > (untrace) > (fact 5) 120 |
The procedure step enables single-stepping mode. After the call
to step the computation will stop just before the interpreter
executes the next evaluation step (as defined by
step-level-set!). A nested REPL is then started. Note that
because single-stepping is stopped by the REPL whenever the prompt is
displayed it is pointless to enter (step) by itself. On the
other hand entering (begin (step) expr) will evaluate
expr in single-stepping mode.
The procedure step-level-set! sets the stepping level which
determines the granularity of the evaluation steps when single-stepping
is enabled. The stepping level level must be an exact integer in
the range 0 to 7. At a level of 0, the interpreter ignores
single-stepping mode. At higher levels the interpreter stops the
computation just before it performs the following operations, depending
on the stepping level:
delay special form and operations at lower levels
lambda special form and operations at lower levels
define special form and operations at lower levels
set! special form and operations at lower levels
The default stepping level is 7.
For example:
> (define (fact n) (if (< n 2) 1 (* n (fact (- n 1))))) > (step-level-set! 1) > (begin (step) (fact 5)) *** STOPPED IN (stdin)@3.15 1> ,s | > (fact 5) *** STOPPED IN fact, (stdin)@1.22 1> ,s | | > (< n 2) | | #f *** STOPPED IN fact, (stdin)@1.43 1> ,s | | > (- n 1) | | 4 *** STOPPED IN fact, (stdin)@1.37 1> ,s | | > (fact (- n 1)) *** STOPPED IN fact, (stdin)@1.22 1> ,s | | | > (< n 2) | | | #f *** STOPPED IN fact, (stdin)@1.43 1> ,s | | | > (- n 1) | | | 3 *** STOPPED IN fact, (stdin)@1.37 1> ,l | | | > (fact (- n 1)) | | | 6 *** STOPPED IN fact, (stdin)@1.32 1> ,l | | > (* n (fact (- n 1))) | | 24 *** STOPPED IN fact, (stdin)@1.32 1> ,l | > (* n (fact (- n 1))) | 120 120 |
break places a breakpoint on each of the specified procedures.
When a procedure is called that has a breakpoint, the interpreter will
enable single-stepping mode (as if step had been called). This
typically causes the computation to stop soon inside the procedure if
the stepping level is high enough.
unbreak removes the breakpoints on the specified procedures.
With no argument, break returns the list of procedures currently
containing breakpoints. The void object is returned by break if
it is passed one or more arguments. With no argument unbreak
removes all the breakpoints and returns the void object. A breakpoint
can be placed on a compiled procedure but only if it is bound to a
global variable.
For example:
> (define (double x) (+ x x)) > (define (triple y) (- (double (double y)) y)) > (define (f z) (* (triple z) 10)) > (break double) > (break -) *** WARNING -- Rebinding global variable "-" to an interpreted procedure > (f 5) *** STOPPED IN double, (stdin)@1.21 1> ,b 0 double (stdin)@1:21 + 1 triple (stdin)@2:31 (double y) 2 f (stdin)@3:18 (triple z) 3 (interaction) (stdin)@6:1 (f 5) 4 ##initial-continuation 1> ,e x = 5 1> ,c *** STOPPED IN double, (stdin)@1.21 1> ,c *** STOPPED IN f, (stdin)@3.29 1> ,c 150 > (break) (#<procedure -> #<procedure double>) > (unbreak) > (f 5) 150 |
proper-tail-calls-set! sets a flag that controls how the
interpreter handles tail calls. When proper? is #f the
interpreter will treat tail calls like nontail calls, that is a new
continuation will be created for the call. This setting is useful for
debugging, because when a primitive signals an error the location
information will point to the call site of the primitive even if this
primitive was called with a tail call. The default setting of this flag
is #t, which means that a tail call will reuse the continuation
of the calling function.
The setting of this flag only affects code that is subsequently
processed by load or eval, or entered at the REPL.
display-environment-set! sets a flag that controls the automatic
display of the environment by the REPL. If display? is true, the
environment is displayed by the REPL before the prompt. The default
setting is not to display the environment.
path must be a string. file-exists? returns #t if a
file by that name exists, and returns #f otherwise.
force-output causes all data buffered on the output port
port to be written out. If port is not specified, the
current output port is used.
pretty-print and pp are similar to write except
that the result is nicely formatted. If obj is a procedure
created by the interpreter or a procedure created by code compiled with
the `-debug' option, pp will display its source code. The
argument readtable specifies the readtable to use. If it is not
specified, the readtable defaults to the current readtable.
These procedures implement string ports and they are compatible with
SRFI 6. String ports can be used like normal ports.
open-input-string returns an input string port which obtains
characters from the given string instead of a file. When the port is
closed with a call to close-input-port, a string containing the
characters that were not read is returned. open-output-string
returns an output string port which accumulates the characters written
to it. The procedure get-output-string retrieves the characters
sent to the output port since it was opened or since the last call to
get-output-string.
For example:
> (let ((i (open-input-string "alice #(1 2)")))
(let* ((a (read i)) (b (read i)) (c (read i)))
(list a b c)))
(alice #(1 2) #!eof)
> (let ((o (open-output-string)))
(write "cloud" o)
(write (* 3 3) o)
(pp (get-output-string o))
(pp (get-output-string o))
(write o o)
(pp (get-output-string o))
(close-output-port o))
"\"cloud\"9"
""
"# |
The procedure call-with-input-string is similar to
call-with-input-file except that the characters are obtained from
the string string. The procedure call-with-output-string
calls the procedure proc with a freshly created string port and
returns a string containing all characters output to that port.
For example:
> (call-with-input-string
"(1 2)"
(lambda (p) (read-char p) (read p)))
1
> (call-with-output-string
(lambda (p) (write p p)))
"# |
The procedure with-input-from-string is similar to
with-input-from-file except that the characters are obtained from
the string string. The procedure with-output-to-string
calls the thunk and returns a string containing all characters output to
the current output port.
For example:
> (with-input-from-string
"(1 2) hello"
(lambda () (read) (read)))
hello
> (with-output-to-string
(lambda () (write car)))
"# |
These procedures are respectively similar to
with-input-from-file and with-output-to-file. The
difference is that the first argument is a port instead of a file name.
*** This documentation is incomplete!
Returns the current readtable.
Readtables control the behavior of the reader (i.e. the read
procedure and the parser used by the load procedure and the
interpreter and compiler) and the printer (i.e. the procedures
write, display, pretty-print, and pp, and
the procedure used by the REPL to print results). Both the reader and
printer need to know the readtable so that they can preserve write/read
invariance. For example a symbol which contains upper case letters will
be printed with special escapes if the readtable indicates that the
reader is case insensitive.
These procedures configure readtables. The argument readtable specifies the readtable to configure.
For the procedure case-conversion?-set!, if conversion? is
#f, the reader will preserve the case of the symbols that are
read; if conversion? is the symbol upcase, the reader will
convert letters to upper case; otherwise the reader will convert to
lower case. The default is to preserve the case.
For the procedure keywords-allowed?-set!, if allowed? is
#f, the reader will not recognize keyword objects; if
allowed? is the symbol prefix, the reader will recognize
keyword objects that start with a colon (as in Common Lisp); otherwise
the reader will recognize keyword objects that end with a colon (as in
DSSSL). The default is to recognize keyword objects that end in a
colon.
For example:
> (case-conversion?-set! #f) > 'TeX TeX > (case-conversion?-set! #t) > 'TeX tex > (keywords-allowed?-set! #f) > (symbol? 'foo:) #t > (keywords-allowed?-set! #t) > (keyword? 'foo:) ; quote not really needed #t > (keywords-allowed?-set! 'prefix) > (keyword? ':foo) ; quote not really needed #t |
These procedures implement the keyword data type. Keywords are
similar to symbols but are self evaluating and distinct from the
symbol data type. A keyword is an identifier immediately followed by
a colon (or preceded by a colon if (set-keywords-allowed! 'prefix)
was called). The procedure keyword? returns #t if
obj is a keyword, and otherwise returns #f. The
procedure keyword->string returns the name of keyword as
a string, excluding the colon. The procedure string->keyword
returns the keyword whose name is string (the name does not
include the colon).
For example:
> (keyword? 'color) #f > (keyword? color:) #t > (keyword->string color:) "color" > (string->keyword "color") color: |
gc-report-set! controls the generation of reports during garbage
collections. If the argument is true, a brief report of memory usage is
generated after every garbage collection. It contains: the time taken
for this garbage collection, the amount of memory allocated in kilobytes
since the program was started, the size of the heap in kilobytes, the
heap memory in kilobytes occupied by live data, the proportion of the
heap occupied by live data, and the number of bytes occupied by movable
and nonmovable objects.
*** This documentation is incomplete!
These procedures implement the will data type. Will objects provide support for finalization. A will is an object that contains a reference to a testator object (the object attached to the will), and an action procedure which is a one parameter procedure which is called when the will is executed.
make-will creates a will object with the given testator
object and action procedure. will? tests if obj is a
will object. will-testator gets the testator object attached to
the will. will-execute! executes will.
An object is finalizable if all paths to the object from the roots (i.e. continuations of runnable threads, global variables, etc) pass through a will object. Note that by this definition an object that is not reachable at all from the roots is finalizable. Some objects, including symbols, small integers (fixnums), booleans and characters, are considered to be always reachable and are therefore never finalizable.
When the runtime system detects that a will's testator "T" is
finalizable the current computation is interrupted, the will's testator
is set to #f and the will's action procedure is called with "T"
as the sole argument. Currently only the garbage collector detects when
objects become finalizable but this may change in future versions of
Gambit (for example the compiler could perform an analysis to infer
finalizability at compile time). The garbage collector builds a list of
all wills whose testators are finalizable. Shortly after a garbage
collection, the action procedures of these wills will be called. The
link from the will to the action procedure is severed when the action
procedure is called.
Note that the testator object will not be reclaimed during the garbage collection that detected finalizability of the testator object. It is only when an object is not reachable from the roots (not even through will objects) that it is reclaimed by the garbage collector.
A remarkable feature of wills is that an action procedure can "resurrect" an object after it has become finalizable, by making it nonfinalizable. An action procedure could for example assign the testator object to a global variable.
For example:
> (define a (list 123))
> (set-cdr! a a) ; create a circular list
> (define b (vector a))
> (define c #f)
> (define w
(let ((obj a))
(make-will obj
(lambda (x) ; x will be eq? to obj
(display "executing action procedure")
(newline)
(set! c x)))))
> (will? w)
#t
> (car (will-testator w))
123
> (##gc)
> (set! a #f)
> (##gc)
> (set! b #f)
> (##gc)
executing action procedure
> (will-testator w)
#f
> (car c)
123
|
gensym returns a new uninterned symbol. Uninterned symbols
are guaranteed to be distinct from the symbols generated by the
procedures read and string->symbol. The symbol
prefix is the prefix used to generate the new symbol's name. If
it is not specified, the prefix defaults to `g'.
For example:
> (gensym) #:g0 > (gensym) #:g1 > (gensym 'star-trek-) #:star-trek-2 |
void returns the void object. The read-eval-print loop prints
nothing when the result is the void object.
eval's first argument is a datum representing an expression.
eval evaluates this expression in the global interaction
environment and returns the result. If present, the second argument is
ignored (it is provided for compatibility with R5RS).
For example:
> (eval '(+ 1 2)) 3 > ((eval 'car) '(1 2)) 1 > (eval '(define x 5)) > x 5 |
file must be a string naming an existing file containing Scheme source code. The extension can be omitted from file if the Scheme file has a `.scm' extension. This procedure compiles the source file into a file containing C code. By default, this file is named after file with the extension replaced with `.c'. However, if output is supplied the file is named `output'.
Compilation options are given as a list of symbols after the file name. Any combination of the following options can be used: `verbose', `report', `expansion', `gvm', and `debug'.
Note that this procedure is only available in gsc.
The arguments of compile-file are the same as the first two
arguments of compile-file-to-c. The compile-file
procedure compiles the source file into an object file by first
generating a C file and then compiling it with the C compiler. The
object file is named after file with the extension replaced with
`.on', where n is a positive integer that acts as a
version number. The next available version number is generated
automatically by compile-file. Object files can be loaded
dynamically by using the load procedure. The `.on'
extension can be specified (to select a particular version) or omitted
(to load the highest numbered version). Versions which are no longer
needed must be deleted manually and the remaining version(s) must be
renamed to start with extension `.o1'.
Note that this procedure is only available in gsc and that it
is only useful on operating systems that support dynamic loading.
The first argument must be a non empty list of strings naming Scheme modules to link (extensions must be omitted). The remaining optional arguments must be strings. An incremental link file is generated for the modules specified in module-list. By default the link file generated is named `last_.c', where last is the name of the last module. However, if output is supplied the link file is named `output'. The base link file is specified by the base parameter. By default the base link file is the Gambit runtime library link file `~~/_gambc.c'. However, if base is supplied the base link file is named `base.c'.
Note that this procedure is only available in gsc.
The following example shows how to build the executable program `hello' which contains the two Scheme modules `m1.scm' and `m2.scm'.
% uname -a
Linux bailey 1.2.13 #2 Wed Aug 28 16:29:41 GMT 1996 i586
% cat m1.scm
(display "hello") (newline)
% cat m2.scm
(display "world") (newline)
% gsc
Gambit Version 4.0 beta 1
> (compile-file-to-c "m1")
#t
> (compile-file-to-c "m2")
#t
> (link-incremental '("m1" "m2") "hello.c")
> ,q
% gcc m1.c m2.c hello.c -lgambc -o hello
% hello
hello
world
|
The first argument must be a non empty list of strings. The first string must be the name of a Scheme module or the name of a link file and the remaining strings must name Scheme modules (in all cases extensions must be omitted). The second argument must be a string, if it is supplied. A flat link file is generated for the modules specified in module-list. By default the link file generated is named `last_.c', where last is the name of the last module. However, if output is supplied the link file is named `output'.
Note that this procedure is only available in gsc.
The following example shows how to build the dynamically loadable Scheme library `lib.o1' which contains the two Scheme modules `m1.scm' and `m2.scm'.
% uname -a
Linux bailey 1.2.13 #2 Wed Aug 28 16:29:41 GMT 1996 i586
% cat m1.scm
(define (f x) (g (* x x)))
% cat m2.scm
(define (g y) (+ n y))
% gsc
Gambit Version 4.0 beta 1
> (compile-file-to-c "m1")
#t
> (compile-file-to-c "m2")
#t
> (link-flat '("m1" "m2") "lib.c")
*** WARNING -- "*" is not defined,
*** referenced in: ("m1.c")
*** WARNING -- "+" is not defined,
*** referenced in: ("m2.c")
*** WARNING -- "n" is not defined,
*** referenced in: ("m2.c")
> ,q
% gcc -shared -fPIC -D___DYNAMIC m1.c m2.c lib.c -o lib.o1
% gsc
Gambit Version 4.0 beta 1
> (load "lib")
*** WARNING -- Variable "n" used in module "m2" is undefined
"/users/feeley/lib.o1"
> (define n 10)
> (f 5)
35
> ,q
|
The warnings indicate that there are no definitions (defines or
set!s) of the variables *, + and n in the
modules contained in the library. Before the library is used, these
variables will have to be bound; either implicitly (by the runtime
library) or explicitly.
error signals an error and causes a nested REPL to be started.
The error message displayed is string followed by the remaining
arguments. The continuation of the REPL is the same as the one passed
to error. Thus, returning from the REPL with the `,c' or
`,(c expr)' command causes a return from the call to
error.
For example:
> (define (f x)
(let ((y (if (> x 0) (log x) (error "x must be positive"))))
(+ y 1)))
> (+ (f -4) 10)
*** ERROR IN (stdin)@2.34 -- x must be positive
1> ,(c 5)
16
|
exit causes the program to terminate with the status status
which must be an exact integer in the range 0 to 255. If it is not
specified, the status defaults to 0.
command-line returns a list of strings corresponding to the command
line arguments, including the program file name as the first element
of the list. When the interpreter executes a Scheme script, the list
returned by command-line contains the script's file name followed by
the remaining command line arguments.
getenv returns the value of the environment variable name
(a string) of the current process. A string is returned if the
environment variable is bound, otherwise default is returned if
it is specified, otherwise an exception is raised.
setenv changes the binding of the environment variable
name. If value is #f the binding is removed.
current-time returns a "time" object representing the current
point in real time. time->seconds converts the time object
time into an inexact real number representing the number of
seconds elapsed since the "epoch" (which is 00:00:00 Coordinated
Universal Time 01-01-1970). time->seconds converts the real
number x representing the number of seconds elapsed since the
"epoch" into a time object.
process-times returns a three element f64vector containing the
cpu time that has been used by the program and the real time that has
elapsed since it was started. The first element corresponds to "user"
time in seconds, the second element corresponds to "system" time in
seconds and the third element is the elapsed real time in seconds. On
operating systems that can't differentiate user and system time, the
system time is zero. On operating systems that can't measure cpu time,
the user time is equal to the elapsed real time and the system time is
zero.
cpu-time returns the cpu time in seconds that has been used by
the program (user time plus system time).
real-time returns the real time that has elapsed since the
program was started.
The resolution of the real time and cpu time clock is platform dependent. Typically the resolution of the cpu time clock is rather coarse (measured in "ticks" of 1/60th or 1/100th of a second). Time is computed internally using floating point numbers which means that there is a gradual loss of resolution as time moves away from the "epoch". Moreover, some operating systems report time in number of ticks using a 32 bit integer so the time returned by the above procedures may wraparound much before any significant loss of resolution occurs (for example 2.7 years if ticks are 1/50th of a second).
time evaluates expr and returns the result. As a side
effect it displays a message which indicates how long the evaluation
took (in real time and cpu time), how much time was spent in the garbage
collector, how much memory was allocated during the evaluation and how
many minor and major page faults occured (0 is reported if not running
under UNIX).
For example:
> (define (f x)
(let loop ((x x) (lst '()))
(if (= x 0)
lst
(loop (- x 1) (cons x lst)))))
> (length (time (f 100000)))
(time (f 100000))
266 ms real time
260 ms cpu time (260 user, 0 system)
8 collections accounting for 41 ms real time (30 user, 0 system)
6400136 bytes allocated
859 minor faults
no major faults
100000
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section contains additional special forms and procedures which are documented only in the interest of experimentation. They may be modified or removed in future releases of Gambit. The procedures in this section do not check the type of their arguments so they may cause the program to crash if called improperly.
The procedure ##gc forces a garbage collection of the heap.
Using the procedure ##add-gc-interrupt-job it is possible to
add a thunk that is called at the end of every garbage collection.
The procedure ##clear-gc-interrupt-jobs removes all the thunks
added with ##add-gc-interrupt-job.
The runtime system sets up a free running timer that raises an interrupt
at 10 Hz or faster. Using the procedure
##add-timer-interrupt-job it is possible to add a thunk that is
called every time a timer interrupt is received. The procedure
##clear-timer-interrupt-jobs removes all the thunks added with
##add-timer-interrupt-job. It is relatively easy to implement
threads by using these procedures in conjunction with
call-with-current-continuation.
The procedure shell-command calls up the shell to execute
command which must be a string. shell-command returns
the exit status of the shell in the form that the C system
command returns.
These procedures manipulate file paths.
current-directory returns (or sets) the current working
directory.
path-expand takes the path of a file or directory and returns an
absolute path of the file or directory. Relative paths are relative to
the current working directory. If the path is the empty string, the
current working directory is returned.
path-normalize takes a path of a file or directory and returns a
normalized path of the file or directory. A normalized path is a path
containing no redundant parts and which is coherent with the filesystem.
A normalized path of a directory will always end with a path separator
(i.e. `/', `\', or `:' depending on the operating
system).
The remaining procedures extract various parts of a path.
path-extension returns the file extension (including the period)
or the empty string if there is no extension.
path-strip-extension returns the path with the extension stripped
off. path-directory returns the file's directory (including the
last path separator) or the empty string if no directory is specified in
the path. path-strip-directory returns the path with the
directory stripped off. path-volume returns the file's volume
(including the last path separator) or the empty string if no volume is
specified in the path. path-strip-volume returns the path with
the volume stripped off.
*** This documentation is incomplete!
*** This documentation is incomplete!
Bytevectors are uniform vectors containing raw numbers (signed or unsigned exact integers or inexact reals). There are 10 types of bytevectors: `s8vector' (vector of exact integers in the range -2^7 to 2^7-1), `u8vector' (vector of exact integers in the range 0 to 2^8-1), `s16vector' (vector of exact integers in the range -2^15 to 2^15-1), `u16vector' (vector of exact integers in the range 0 to 2^16-1), `s32vector' (vector of exact integers in the range -2^31 to 2^31-1), `u32vector' (vector of exact integers in the range 0 to 2^32-1), `s64vector' (vector of exact integers in the range -2^63 to 2^63-1), `u64vector' (vector of exact integers in the range 0 to 2^64-1), `f32vector' (vector of 32 bit floating point numbers), and `f64vector' (vector of 64 bit floating point numbers). These procedures are the analog of the normal vector procedures for each of the bytevector types.
For example:
> (define v (u8vector 10 255 13)) > (u8vector-set! v 2 99) > v #u8(10 255 99) > (u8vector-ref v 1) 255 > (u8vector->list v) (10 255 99) |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gambit supports the Unicode character encoding standard
(ISO/IEC-10646-1). Scheme characters can be any of the characters in
the 16 bit subset of Unicode known as UCS-2. Scheme strings can
contain any character in UCS-2. Source code can also contain any
character in UCS-2. However, to read such source code properly
gsi and gsc must be told which character encoding to use
for reading the source code (i.e. UTF-8, UCS-2, or UCS-4). This can
be done by passing a character encoding parameter to load or by
specifying the runtime option `-:c' when gsi and
gsc are started.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Gambit supports the execution of multiple threads, and conforms to SRFI 18 and SRFI 21. Please refer to the SRFI 18 and SRFI 21 documents for further details. *** The text of those SRFI's will be included here eventually!
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Gambit Scheme system offers a mechanism for interfacing Scheme code and C code called the "C-interface". A Scheme program indicates which C functions it needs to have access to and which Scheme procedures can be called from C, and the C interface automatically constructs the corresponding Scheme procedures and C functions. The conversions needed to transform data from the Scheme representation to the C representation (and back), are generated automatically in accordance with the argument and result types of the C function or Scheme procedure.
The C-interface places some restrictions on the types of data that can be exchanged between C and Scheme. The mapping of data types between C and Scheme is discussed in the next section. The remaining sections of this chapter describe each special form of the C-interface.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Scheme and C do not provide the same set of built-in data types so it is important to understand which Scheme type is compatible with which C type and how values get mapped from one environment to the other. To improve compatibility a new type is added to Scheme, the `foreign' object type, and the following data types are added to C:
scheme-object
___SCMOBJ defined in `gambit.h')
bool
___BOOL defined in `gambit.h')
int8
___S8 defined in `gambit.h')
unsigned-int8
___U8 defined in `gambit.h')
int16
___S16 defined in `gambit.h')
unsigned-int16
___U16 defined in `gambit.h')
int32
___S32 defined in `gambit.h')
unsigned-int32
___U32 defined in `gambit.h')
int64
___S64 defined in `gambit.h')
unsigned-int64
___U64 defined in `gambit.h')
float32
___F32 defined in `gambit.h')
float64
___F64 defined in `gambit.h')
latin1
___LATIN1 defined in `gambit.h')
ucs2
___UCS2 defined in `gambit.h')
ucs4
___UCS4 defined in `gambit.h')
char-string
nonnull-char-string
nonnull-char-string-list
latin1-string
___LATIN1*)
nonnull-latin1-string
___LATIN1*)
nonnull-latin1-string-list
utf8-string
char, i.e. char*)
nonnull-utf8-string
char, i.e. char*)
nonnull-utf8-string-list
ucs2-string
___UCS2*)
nonnull-ucs2-string
___UCS2*)
nonnull-ucs2-string-list
ucs4-string
___UCS4*)
nonnull-ucs4-string
___UCS4*)
nonnull-ucs4-string-list
To specify a particular C type inside the c-lambda,
c-define and c-define-type forms, the following "Scheme
notation" is used:
Scheme notation
void
void
bool
bool
char
char (may be signed or unsigned depending on the C compiler)
signed-char
signed char
unsigned-char
unsigned char
latin1
latin1
ucs2
ucs2
ucs4
ucs4
short
short
unsigned-short
unsigned short
int
int
unsigned-int
unsigned int
long
long
unsigned-long
unsigned long
long-long
long long
unsigned-long-long
unsigned long long
float
float
double
double
int8
int8
unsigned-int8
unsigned-int8
int16
int16
unsigned-int16
unsigned-int16
int32
int32
unsigned-int32
unsigned-int32
int64
int64
unsigned-int64
unsigned-int64
float32
float32
float64
float64
(struct "c-struct-id" [tag [release-function]])
struct c-struct-id (where c-struct-id is the name of a
C structure; see below for the meaning of tag and release-function)
(union "c-union-id" [tag [release-function]])
union c-union-id (where c-union-id is the name of a
C union; see below for the meaning of tag and release-function)
(type "c-type-id" [tag [release-function]])
c-type-id (where c-type-id is an identifier naming a
C type; see below for the meaning of tag and release-function)
(pointer type [tag [release-function]])
T* (where T is the C equivalent of type
which must be the Scheme notation of a C type; see below for the meaning
of tag and release-function)
(nonnull-pointer type [tag [release-function]])
(pointer type [tag [release-function]])
except the NULL pointer is not allowed
(function (type1...) result-type)
(nonnull-function (type1...) result-type)
(function (type1...) result-type)
except the NULL pointer is not allowed
char-string
char-string
nonnull-char-string
nonnull-char-string
nonnull-char-string-list
nonnull-char-string-list
latin1-string
latin1-string
nonnull-latin1-string
nonnull-latin1-string
nonnull-latin1-string-list
nonnull-latin1-string-list
utf8-string
utf8-string
nonnull-utf8-string
nonnull-utf8-string
nonnull-utf8-string-list
nonnull-utf8-string-list
ucs2-string
ucs2-string
nonnull-ucs2-string
nonnull-ucs2-string
nonnull-ucs2-string-list
nonnull-ucs2-string-list
ucs4-string
ucs4-string
nonnull-ucs4-string
nonnull-ucs4-string
nonnull-ucs4-string-list
nonnull-ucs4-string-list
scheme-object
scheme-object
name
c-define-type)
"c-type-id"
(type "c-type-id"))
The struct, union, type, pointer and
nonnull-pointer types are "foreign types" and they are
represented on the Scheme side as "foreign objects". A foreign object
is internally represented as a pointer. This internal pointer is
identical to the C pointer being represented in the case of the
pointer and nonnull-pointer types.
In the case of the struct, union and type types,
the internal pointer points to a copy of the C data type being
represented. When an instance of one of these types is converted from C
to Scheme, a block of memory is allocated from the C heap and
initialized with the instance and then a foreign object is allocated
from the Scheme heap and initialized with the pointer to this copy.
This approach may appear overly complex, but it allows the conversion of
C++ classes that do not have a zero parameter constructor or an
assignment method (i.e. when compiling with a C++ compiler an instance
is copied using `new type (instance)', which calls the
copy-constructor of type if it is a class; type's assignment
operator is never used). Conversion from Scheme to C simply
dereferences the internal pointer (no allocation from the C heap is
performed). Deallocation of the copy on the C heap is under the control
of the release function attached to the foreign object (see below).
For type checking on the Scheme side, a tag can be specified
within a foreign type specification. The tag must be #f or
a symbol. When it is not specified the tag defaults to a symbol
whose name, as returned by symbol->string, is the C type
declaration for that type. For example the default tag for the type
`(pointer (pointer char))' is the symbol `char**'. Two
foreign types are compatible (i.e. can be converted from one to the
other) if they have identical tags or if at least one of the tags is
#f. For the safest code the #f tag should be used
sparingly, as it completely bypasses type checking. The external
representation of Scheme foreign objects (used by the write
procedure) contains the tag if it is not #f, and the hexadecimal
address denoted by the internal pointer, for example `#<char** 1
0x2AAC535C>'. Note that the hexadecimal address is in C notation, which
can be easily transferred to a C debugger with a "cut-and-paste".
A release-function can also be specified within a foreign type
specification. The release-function must be #f or a string
naming a C function with a single parameter of type `void*' (in
which the internal pointer is passed) and with a result of type
`___SCMOBJ' (for returning an error code). When the
release-function is not specified or is #f a default
function is constructed by the C-interface. This default function does
nothing in the case of the pointer and nonnull-pointer
types (deallocation is not the responsibility of the C-interface) and
returns the fixnum `___FIX(___NO_ERR)' to indicate no error. In
the case of the struct, union and type types, the
default function reclaims the copy on the C heap referenced by the
internal pointer (when using a C++ compiler this is done using
`delete (type*)internal-pointer', which calls the
destructor of type if it is a class) and returns
`___FIX(___NO_ERR)'. In many situations the default
release-function will perform the appropriate cleanup for the
foreign type. However, in certain cases special operations (such as
decrementing a reference count, removing the object from a table, etc)
must be performed. For such cases a user supplied
release-function is needed.
The release-function is invoked at most once for any foreign
object. After the release-function is invoked, the foreign object
is considered "released" and can no longer be used in a foreign type
conversion. When the garbage collector detects that a foreign object is
no longer reachable by the program, it will invoke the
release-function if the foreign object is not yet released. When
there is a need to release the foreign object promptly, the program can
explicitly call the Scheme procedure foreign-release! which
invokes the release-function if the foreign object is not yet
released, and does nothing otherwise.
The following table gives the C types to which each Scheme type can be converted:
#f
scheme-object; bool;
pointer;
function;
char-string;
latin1-string;
utf8-string;
ucs2-string;
ucs4-string
#t
scheme-object; bool
scheme-object; bool;
[[un]signed] char; latin1; ucs2;
ucs4
scheme-object; bool; [unsigned-]
int8/int16/int32/int64; [unsigned]
short/int/long
scheme-object; bool; float; double; float32; float64
scheme-object; bool;
char-string;
nonnull-char-string;
latin1-string;
nonnull-latin1-string;
utf8-string;
nonnull-utf8-string;
ucs2-string;
nonnull-ucs2-string;
ucs4-string;
nonnull-ucs4-string
scheme-object; bool; struct/union/type/pointer/nonnull-pointer with the appropriate tag
scheme-object; bool
scheme-object; bool
scheme-object; bool;
function;
nonnull-function
scheme-object; bool
The following table gives the Scheme types to which each C type will be converted:
[un]signed] char; latin1; ucs2; ucs4
unsigned-] int8/int16/int32/int64; [unsigned] short/int/long
float; double; float32; float64
char-string; latin1-string; utf8-string; ucs2-string; ucs4-string
#f if it is equal to `NULL'
nonnull-char-string; nonnull-latin1-string; nonnull-utf8-string; nonnull-ucs2-string; nonnull-ucs4-string
struct/union/type/pointer/nonnull-pointer
#f in the case of a pointer equal to `NULL'
function
#f if it is equal to `NULL'
nonnull-function
void
All Scheme types are compatible with the C types scheme-object
and bool. Conversion to and from the C type
scheme-object is the identity function on the object encoding.
This provides a low-level mechanism for accessing Scheme's object
representation from C (with the help of the macros in the
`gambit.h' header file). When a C bool type is expected,
an extended Scheme boolean can be passed (#f is converted to 0
and all other values are converted to 1).
The Scheme boolean #f can be passed to the C environment where a
char-string, latin1-string, utf8-string,
ucs2-string, ucs4-string, pointer or
function type is expected. In this case, #f is converted
to the `NULL' pointer. C bools are extended booleans so any
value different from 0 represents true. Thus, a C bool passed to
the Scheme environment is mapped as follows: 0 to #f and all
other values to #t.
A Scheme character passed to the C environment where any C character type is expected is converted to the corresponding character in the C environment. An error is signaled if the Scheme character does not fit in the C character. Any C character type passed to Scheme is converted to the corresponding Scheme character. An error is signaled if the C character does not fit in the Scheme character.
A Scheme exact integer passed to the C environment where a C integer
type (other than char) is expected is converted to the
corresponding integral value. An error is signaled if the value falls
outside of the range representable by that integral type. C integer
values passed to the Scheme environment are mapped to the same Scheme
exact integer. If the value is outside the fixnum range, a bignum is
created.
A Scheme inexact real passed to the C environment is converted to the
corresponding float, double, float32 or
float64 value. C float, double, float32 and
float64 values passed to the Scheme environment are mapped to the
closest Scheme inexact real.
Scheme's rational numbers and complex numbers are not compatible with any C numeric type.
A Scheme string passed to the C environment where any C string type is
expected is converted to a null terminated string using the appropriate
encoding. The C string is a fresh copy of the Scheme string. If the C
string was created for an argument of a c-lambda, the C string
will be reclaimed when the c-lambda returns. If the C string was
created for returning the result of a c-define to C, the caller
is responsible for reclaiming the C string with a call to the
___release_string function (see below for an example). Any C
string type passed to the Scheme environment causes the creation of a
fresh Scheme string containing a copy of the C string (unless the C
string is equal to NULL, in which case it is converted to
#f).
A foreign type passed to the Scheme environment causes the creation and
initialization of a Scheme foreign object with the appropriate tag
(except for the case of a pointer equal to NULL which is
converted to #f). A Scheme foreign object can be passed where a
foreign type is expected, on the condition that the tags are appropriate
(identical or one is #f) and the Scheme foreign object is not yet
released. The value #f is also acceptable for a pointer
type, and is converted to NULL.
Scheme procedures defined with the c-define special form can be
passed where the function and nonnull-function types are
expected. The value #f is also acceptable for a function
type, and is converted to NULL. No other Scheme procedures are
acceptable. Conversion from the function and
nonnull-function types to Scheme procedures is not currently
implemented.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
c-declare special form Synopsis:
(c-declare c-declaration) |
Initially, the C file produced by gsc contains only an
`#include' of `gambit.h'. This header file provides a
number of macro and procedure declarations to access the Scheme object
representation. The special form c-declare adds
c-declaration (which must be a string containing the C
declarations) to the C file. This string is copied to the C file on a
new line so it can start with preprocessor directives. All types of C
declarations are allowed (including type declarations, variable
declarations, function declarations, `#include' directives,
`#define's, and so on). These declarations are visible to
subsequent c-declares, c-initializes, and
c-lambdas, and c-defines in the same module. The most
common use of this special form is to declare the external functions
that are referenced in c-lambda special forms. Such functions
must either be declared explicitly or by including a header file which
contains the appropriate C declarations.
The c-declare special form does not return a value.
It can only appear at top level.
For example:
(c-declare " #include <stdio.h> extern char *getlogin (); #ifdef sparc char *host = \"sparc\"; /* note backslashes */ #else char *host = \"unknown\"; #endif FILE *tfile; ") |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
c-initialize special form Synopsis:
(c-initialize c-code) |
Just after the program is loaded and before control is passed to the
Scheme code, each C file is initialized by calling its associated
initialization function. The body of this function is normally empty
but it can be extended by using the c-initialize form. Each
occurence of the c-initialize form adds code to the body of the
initialization function in the order of appearance in the source file.
c-code must be a string containing the C code to execute. This
string is copied to the C file on a new line so it can start with
preprocessor directives.
The c-initialize special form does not return a value.
It can only appear at top level.
For example:
(c-initialize "tfile = tmpfile ();") |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
c-lambda special form Synopsis:
(c-lambda (type1...) result-type c-name-or-code) |
The c-lambda special form makes it possible to create a Scheme
procedure that will act as a representative of some C function or C code
sequence. The first subform is a list containing the type of each
argument. The type of the function's result is given next. Finally,
the last subform is a string that either contains the name of the C
function to call or some sequence of C code to execute. Variadic C
functions are not supported. The resulting Scheme procedure takes
exactly the number of arguments specified and delivers them in the same
order to the C function. When the Scheme procedure is called, the
arguments will be converted to their C representation and then the C
function will be called. The result returned by the C function will be
converted to its Scheme representation and this value will be returned
from the Scheme procedure call. An error will be signaled if some
conversion is not possible. The temporary memory allocated from the C
heap for the conversion of the arguments and result will be reclaimed
whether there is an error or not.
When c-name-or-code is not a valid C identifier, it is treated as
an arbitrary piece of C code. Within the C code the variables
`___arg1', `___arg2', etc. can be referenced to access the
converted arguments. Similarly, the result to be returned from the call
should be assigned to the variable `___result' except if the result
is of struct, union, type, pointer or
nonnull-pointer type in which case a pointer should be assigned
to the variable `___result_voidstar' which is of type `void*'.
If no result needs to be returned, the result-type should be
void and no assignment to the variable `___result' or
`___result_voidstar' should take place. Note that the C code
should not contain return statements as this is meaningless.
Control must always fall off the end of the C code. The C code is
copied to the C file on a new line so it can start with preprocessor
directives. Moreover the C code is always placed at the head of a
compound statement whose lifetime encloses the C to Scheme conversion of
the result. Consequently, temporary storage (strings in particular)
declared at the head of the C code can be returned by assigning them to
`___result' or `___result_voidstar'. In the
c-name-or-code, the macro `___AT_END' may be defined as the
piece of C code to execute before control is returned to Scheme but
after the result is converted to its Scheme representation. This is
mainly useful to deallocate temporary storage contained in the result.
When passed to the Scheme environment, the C void type is
converted to the void object.
For example:
(define fopen
(c-lambda (nonnull-char-string nonnull-char-string)
(pointer "FILE")
"fopen"))
(define fgetc
(c-lambda ((pointer "FILE"))
int
"fgetc"))
(let ((f (fopen "datafile" "r")))
(if f (write (fgetc f))))
(define char-code (c-lambda (char) int "___result = ___arg1;"))
(define host ((c-lambda () nonnull-char-string "___result = host;")))
(define stdin ((c-lambda () (pointer "FILE") "___result = stdin;")))
((c-lambda () void
"printf( \"hello\\n\" ); printf( \"world\\n\" );"))
(define pack-1-char
(c-lambda (char)
nonnull-char-string
"
___result = malloc (2);
if (___result != NULL) { ___result[0] = ___arg1; ___result[1] = 0; }
#define ___AT_END if (___result != NULL) free (___result);
"))
(define pack-2-chars
(c-lambda (char char)
nonnull-char-string
"
char s[3]; s[0] = ___arg1; s[1] = ___arg2; s[2] = 0; ___result = s;
"))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
c-define special form Synopsis:
(c-define (variable define-formals) (type1...) result-type c-name scope body) |
The c-define special form makes it possible to create a C
function that will act as a representative of some Scheme procedure. A
C function named c-name as well as a Scheme procedure bound to the
variable variable are defined. The parameters of the Scheme
procedure are define-formals and its body is at the end of the
form. The type of each argument of the C function, its result type and
c-name (which must be a string) are specified after the parameter
specification of the Scheme procedure. When the C function c-name
is called from C, its arguments are converted to their Scheme
representation and passed to the Scheme procedure. The result of the
Scheme procedure is then converted to its C representation and the C
function c-name returns it to its caller.
The scope of the C function can be changed with the scope
parameter, which must be a string. This string is placed immediately
before the declaration of the C function. So if scope is the
string "static", the scope of c-name is local to the module
it is in, whereas if scope is the empty string, c-name is
visible from other modules.
The c-define special form does not return a value.
It can only appear at top level.
For example:
(c-define (proc x #!optional (y x) #!rest z) (int int char float) int "f" "" (write (cons x (cons y z))) (newline) (+ x y)) (proc 1 2 #\x 1.5) => 3 and prints (1 2 #\x 1.5) (proc 1) => 2 and prints (1 1) ; if f is called from C with the call f (1, 2, 'x', 1.5) ; the value 3 is returned and (1 2 #\x 1.5) is printed. ; f has to be called with 4 arguments. |
The c-define special form is particularly useful when the
driving part of an application is written in C and Scheme procedures
are called directly from C. The Scheme part of the application is in
a sense a "server" that is providing services to the C part. The
Scheme procedures that are to be called from C need to be defined
using the c-define special form. Before it can be used, the
Scheme part must be initialized with a call to the function
`___setup'. Before the program terminates, it must call the
function `___cleanup' so that the Scheme part may do final
cleanup. A sample application is given in the file
`tests/server.scm'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
c-define-type special form Synopsis:
(c-define-type name type [c-to-scheme scheme-to-c [cleanup]]) |
This form associates the type identifier name to the C type
type. The name must not clash with predefined types
(e.g. char-string, latin1, etc.) or with types previously
defined with c-define-type in the same file. The
c-define-type special form does not return a value. It can only
appear at top level.
If only the two parameters name and type are supplied then after this definition, the use of name in a type specification is synonymous to type.
For example:
(c-define-type FILE "FILE") (c-define-type FILE* (pointer FILE)) (c-define-type time-struct-ptr (pointer (struct "tms"))) (define fopen (c-lambda (char-string char-string) FILE* "fopen")) (define fgetc (c-lambda (FILE*) int "fgetc")) |
Note that identifiers are not case sensitive in standard Scheme but it is good programming practice to use a name with the same case as in C.
If four or more parameters are supplied, then type must be a
string naming the C type, c-to-scheme and scheme-to-c must
be strings suffixing the C macros that convert data of that type between
C and Scheme. If cleanup is supplied it must be a boolean
indicating whether it is necessary to perform a cleanup operation (such
as freeing memory) when data of that type is converted from Scheme to C
(it defaults to #t). The cleanup information is used when the C
stack is unwound due to a continuation invocation (see
9.7 Continuations and the C-interface). Although it is safe to always specify #t,
it is more efficient in time and space to specify #f because the
unwinding mechanism can skip C-interface frames which only contain
conversions of data types requiring no cleanup. Two pairs of C macros
need to be defined for conversions performed by c-lambda forms
and two pairs for conversions performed by c-define forms:
___BEGIN_CFUN_scheme-to-c(___SCMOBJ, type, int) ___END_CFUN_scheme-to-c(___SCMOBJ, type, int) ___BEGIN_CFUN_c-to-scheme(type, ___SCMOBJ) ___END_CFUN_c-to-scheme(type, ___SCMOBJ) ___BEGIN_SFUN_c-to-scheme(type, ___SCMOBJ, int) ___END_SFUN_c-to-scheme(type, ___SCMOBJ, int) ___BEGIN_SFUN_scheme-to-c(___SCMOBJ, type) ___END_SFUN_scheme-to-c(___SCMOBJ, type) |
The macros prefixed with ___BEGIN perform the conversion and
those prefixed with ___END perform any cleanup necessary (such as
freeing memory temporarily allocated for the conversion). The macro
___END_CFUN_scheme-to-c must free the result of the
conversion if it is memory allocated, and
___END_SFUN_scheme-to-c must not (i.e. it is the
responsibility of the caller to free the result).
The first parameter of these macros is the C variable that contains the
value to be converted, and the second parameter is the C variable in
which to store the converted value. The third parameter, when present,
is the index (starting at 1) of the parameter of the c-lambda or
c-define form that is being converted (this is useful for
reporting precise error information when a conversion is impossible).
To allow for type checking, the first three ___BEGIN macros must
expand to an unterminated compound statement prefixed by an if,
conditional on the absence of type check error:
if ((___err = conversion_operation) == ___FIX(___NO_ERR)) {
|
The last ___BEGIN macro must expand to an unterminated compound
statement:
{ ___err = conversion_operation;
|
If type check errors are impossible then a ___BEGIN macro can
simply expand to an unterminated compound statement performing the
conversion:
{ conversion_operation;
|
The ___END macros must expand to a statement, or to nothing if no
cleanup is required, followed by a closing brace (to terminate the
compound statement started at the corresponding ___BEGIN macro).
The conversion_operation is typically a function call that returns
an error code value of type ___SCMOBJ (the error codes are defined in
`gambit.h', and the error code ___FIX(___UNKNOWN_ERR) is available
for generic errors). conversion_operation can also set the
variable ___errmsg of type ___SCMOBJ to a specific Scheme
string error message.
Below is a simple example showing how to interface to an `EBCDIC' character type. Memory allocation is not needed for conversion and type check errors are impossible when converting EBCDIC to Scheme characters, but they are possible when converting from Scheme characters to EBCDIC since Gambit supports Unicode characters.
(c-declare
"
typedef char EBCDIC; /* EBCDIC encoded characters */
void put_char (EBCDIC c) { ... } /* EBCDIC I/O functions */
EBCDIC get_char (void) { ... }
char EBCDIC_to_latin1[256] = { ... }; /* conversion tables */
char latin1_to_EBCDIC[256] = { ... };
___SCMOBJ SCMOBJ_to_EBCDIC (___SCMOBJ src, EBCDIC *dst)
{
int x = ___INT(src); /* convert from Scheme character to int */
if (x > 255) return ___UNKNOWN_ERR;
*dst = latin1_to_EBCDIC[x];
return ___FIX(___NO_ERR);
}
#define ___BEGIN_CFUN_SCMOBJ_to_EBCDIC(src,dst,i) \\
if ((___err = SCMOBJ_to_EBCDIC (src, &dst)) == ___FIX(___NO_ERR)) {
#define ___END_CFUN_SCMOBJ_to_EBCDIC(src,dst,i) }
#define ___BEGIN_CFUN_EBCDIC_to_SCMOBJ(src,dst) \\
{ dst = ___CHR(EBCDIC_to_latin1[src]);
#define ___END_CFUN_EBCDIC_to_SCMOBJ(src,dst) }
#define ___BEGIN_SFUN_EBCDIC_to_SCMOBJ(src,dst,i) \\
{ dst = ___CHR(EBCDIC_to_latin1[src]);
#define ___END_SFUN_EBCDIC_to_SCMOBJ(src,dst,i) }
#define ___BEGIN_SFUN_SCMOBJ_to_EBCDIC(src,dst) \\
{ ___err = SCMOBJ_to_EBCDIC (src, &dst);
#define ___END_SFUN_SCMOBJ_to_EBCDIC(src,dst) }
")
(c-define-type EBCDIC "EBCDIC" "EBCDIC_to_SCMOBJ" "SCMOBJ_to_EBCDIC" #f)
(define put-char (c-lambda (EBCDIC) void "put_char"))
(define get-char (c-lambda () EBCDIC "get_char"))
(c-define (write-EBCDIC c) (EBCDIC) void "write_EBCDIC" ""
(write-char c))
(c-define (read-EBCDIC) () EBCDIC "read_EBCDIC" ""
(read-char))
|
Below is a more complex example that requires memory allocation when
converting from C to Scheme. It is an interface to a 2D `point'
type which is represented in Scheme by a pair of integers. The
conversion of the x and y components is done by calls to
the conversion macros for the int type (defined in
`gambit.h'). Note that no cleanup is necessary when converting
from Scheme to C (i.e. the last parameter of the c-define-type is
#f).
(c-declare
"
typedef struct { int x, y; } point;
void line_to (point p) { ... }
point get_mouse (void) { ... }
point add_points (point p1, point p2) { ... }
___SCMOBJ SCMOBJ_to_POINT (___SCMOBJ src, point *dst, int arg_num)
{
___SCMOBJ ___err = ___FIX(___NO_ERR);
if (!___PAIRP(src))
___err = ___FIX(___UNKNOWN_ERR);
else
{
___SCMOBJ car = ___CAR(src);
___SCMOBJ cdr = ___CDR(src);
___BEGIN_CFUN_SCMOBJ_TO_INT(car,dst->x,arg_num)
___BEGIN_CFUN_SCMOBJ_TO_INT(cdr,dst->y,arg_num)
___END_CFUN_SCMOBJ_TO_INT(cdr,dst->y,arg_num)
___END_CFUN_SCMOBJ_TO_INT(car,dst->x,arg_num)
}
return ___err;
}
___SCMOBJ POINT_to_SCMOBJ (point src, ___SCMOBJ *dst, int arg_num)
{
___SCMOBJ ___err = ___FIX(___NO_ERR);
___SCMOBJ x_scmobj;
___SCMOBJ y_scmobj;
___BEGIN_SFUN_INT_TO_SCMOBJ(src.x,x_scmobj,arg_num)
___BEGIN_SFUN_INT_TO_SCMOBJ(src.y,y_scmobj,arg_num)
*dst = ___EXT(___make_pair) (x_scmobj, y_scmobj, ___STILL);
if (___FIXNUMP(*dst))
___err = *dst; /* return allocation error */
___END_SFUN_INT_TO_SCMOBJ(src.y,y_scmobj,arg_num)
___END_SFUN_INT_TO_SCMOBJ(src.x,x_scmobj,arg_num)
return ___err;
}
#define ___BEGIN_CFUN_SCMOBJ_to_POINT(src,dst,i) \\
if ((___err = SCMOBJ_to_POINT (src, &dst, i)) == ___FIX(___NO_ERR)) {
#define ___END_CFUN_SCMOBJ_to_POINT(src,dst,i) }
#define ___BEGIN_CFUN_POINT_to_SCMOBJ(src,dst) \\
if ((___err = POINT_to_SCMOBJ (src, &dst, ___RETURN_POS)) == ___FIX(___NO_ERR)) {
#define ___END_CFUN_POINT_to_SCMOBJ(src,dst) \\
___EXT(___release_scmobj) (dst); }
#define ___BEGIN_SFUN_POINT_to_SCMOBJ(src,dst,i) \\
if ((___err = POINT_to_SCMOBJ (src, &dst, i)) == ___FIX(___NO_ERR)) {
#define ___END_SFUN_POINT_to_SCMOBJ(src,dst,i) \\
___EXT(___release_scmobj) (dst); }
#define ___BEGIN_SFUN_SCMOBJ_to_POINT(src,dst) \\
{ ___err = SCMOBJ_to_POINT (src, &dst, ___RETURN_POS);
#define ___END_SFUN_SCMOBJ_to_POINT(src,dst) }
")
(c-define-type point "point" "POINT_to_SCMOBJ" "SCMOBJ_to_POINT" #f)
(define line-to (c-lambda (point) void "line_to"))
(define get-mouse (c-lambda () point "get_mouse"))
(define add-points (c-lambda (point point) point "add_points"))
(c-define (write-point p) (point) void "write_point" ""
(write p))
(c-define (read-point) () point "read_point" ""
(read))
|
An example that requires memory allocation when converting from C to Scheme and Scheme to C is shown below. It is an interface to a "null-terminated array of strings" type which is represented in Scheme by a list of strings. Note that some cleanup is necessary when converting from Scheme to C.
(c-declare
"
#include <stdlib.h>
#include <unistd.h>
extern char **environ;
char **get_environ (void) { return environ; }
void free_strings (char **strings)
{
char **ptr = strings;
while (*ptr != NULL)
{
___EXT(___release_string) (*ptr);
ptr++;
}
free (strings);
}
___SCMOBJ SCMOBJ_to_STRINGS (___SCMOBJ src, char ***dst, int arg_num)
{
/*
* Src is a list of Scheme strings. Dst will be a null terminated
* array of C strings.
*/
int i;
___SCMOBJ lst = src;
int len = 4; /* start with a small result array */
char **result = (char**) malloc (len * sizeof (char*));
if (result == NULL)
return ___FIX(___HEAP_OVERFLOW_ERR);
i = 0;
result[i] = NULL; /* always keep array null terminated */
while (___PAIRP(lst))
{
___SCMOBJ scm_str = ___CAR(lst);
char *c_str;
___SCMOBJ ___err;
if (i >= len-1) /* need to grow the result array? */
{
char **new_result;
int j;
len = len * 3 / 2;
new_result = (char**) malloc (len * sizeof (char*));
if (new_result == NULL)
{
free_strings (result);
return ___FIX(___HEAP_OVERFLOW_ERR);
}
for (j=i; j>=0; j--)
new_result[j] = result[j];
free (result);
result = new_result;
}
___err = ___EXT(___SCMOBJ_to_CHARSTRING) (scm_str, &c_str, arg_num);
if (___err != ___FIX(___NO_ERR))
{
free_strings (result);
return ___err;
}
result[i++] = c_str;
result[i] = NULL;
lst = ___CDR(lst);
}
if (!___NULLP(lst))
{
free_strings (result);
return ___FIX(___UNKNOWN_ERR);
}
/*
* Note that the caller is responsible for calling free_strings
* when it is done with the result.
*/
*dst = result;
return ___FIX(___NO_ERR);
}
___SCMOBJ STRINGS_to_SCMOBJ (char **src, ___SCMOBJ *dst, int arg_num)
{
___SCMOBJ ___err = ___FIX(___NO_ERR);
___SCMOBJ result = ___NUL; /* start with the empty list */
int i = 0;
while (src[i] != NULL)
i++;
/* build the list of strings starting at the tail */
while (--i >= 0)
{
___SCMOBJ scm_str;
___SCMOBJ new_result;
/*
* Invariant: result is either the empty list or a ___STILL pair
* with reference count equal to 1. This is important because
* it is possible that ___CHARSTRING_to_SCMOBJ and ___make_pair
* will invoke the garbage collector and we don't want the
* reference in result to become invalid (which would be the
* case if result was a ___MOVABLE pair or if it had a zero
* reference count).
*/
___err = ___EXT(___CHARSTRING_to_SCMOBJ) (src[i], &scm_str, arg_num);
if (___err != ___FIX(___NO_ERR))
{
___EXT(___release_scmobj) (result); /* allow GC to reclaim result */
return ___FIX(___UNKNOWN_ERR);
}
/*
* Note that scm_str will be a ___STILL object with reference
* count equal to 1, so there is no risk that it will be
* reclaimed or moved if ___make_pair invokes the garbage
* collector.
*/
new_result = ___EXT(___make_pair) (scm_str, result, ___STILL);
/*
* We can zero the reference count of scm_str and result (if
* not the empty list) because the pair now references these
* objects and the pair is reachable (it can't be reclaimed
* or moved by the garbage collector).
*/
___EXT(___release_scmobj) (scm_str);
___EXT(___release_scmobj) (result);
result = new_result;
if (___FIXNUMP(result))
return result; /* allocation failed */
}
/*
* Note that result is either the empty list or a ___STILL pair
* with a reference count equal to 1. There will be a call to
* ___release_scmobj later on (in ___END_CFUN_STRINGS_to_SCMOBJ
* or ___END_SFUN_STRINGS_to_SCMOBJ) that will allow the garbage
* collector to reclaim the whole list of strings when the Scheme
* world no longer references it.
*/
*dst = result;
return ___FIX(___NO_ERR);
}
#define ___BEGIN_CFUN_SCMOBJ_to_STRINGS(src,dst,i) \\
if ((___err = SCMOBJ_to_STRINGS (src, &dst, i)) == ___FIX(___NO_ERR)) {
#define ___END_CFUN_SCMOBJ_to_STRINGS(src,dst,i) \\
free_strings (dst); }
#define ___BEGIN_CFUN_STRINGS_to_SCMOBJ(src,dst) \\
if ((___err = STRINGS_to_SCMOBJ (src, &dst, ___RETURN_POS)) == ___FIX(___NO_ERR)) {
#define ___END_CFUN_STRINGS_to_SCMOBJ(src,dst) \\
___EXT(___release_scmobj) (dst); }
#define ___BEGIN_SFUN_STRINGS_to_SCMOBJ(src,dst,i) \\
if ((___err = STRINGS_to_SCMOBJ (src, &dst, i)) == ___FIX(___NO_ERR)) {
#define ___END_SFUN_STRINGS_to_SCMOBJ(src,dst,i) \\
___EXT(___release_scmobj) (dst); }
#define ___BEGIN_SFUN_SCMOBJ_to_STRINGS(src,dst) \\
{ ___err = SCMOBJ_to_STRINGS (src, &dst, ___RETURN_POS);
#define ___END_SFUN_SCMOBJ_to_STRINGS(src,dst) }
")
(c-define-type char** "char**" "STRINGS_to_SCMOBJ" "SCMOBJ_to_STRINGS")
(define execv (c-lambda (char-string char**) int "execv"))
(define get-environ (c-lambda () char** "get_environ"))
(c-define (write-strings x) (char**) void "write_strings" ""
(write x))
(c-define (read-strings) () char** "read_strings" ""
(read))
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The C-interface allows C to Scheme calls to be nested. This means that during a call from C to Scheme another call from C to Scheme can be performed. This case occurs in the following program:
(c-declare
"
int p (char *); /* forward declarations */
int q (void);
int a (char *x) { return 2 * p (x+1); }
int b (short y) { return y + q (); }
")
(define a (c-lambda (char-string) int "a"))
(define b (c-lambda (short) int "b"))
(c-define (p z) (char-string) int "p" ""
(+ (b 10) (string-length z)))
(c-define (q) () int "q" ""
123)
(write (a "hello"))
|
In this example, the main Scheme program calls the C function `a' which calls the Scheme procedure `p' which in turn calls the C function `b' which finally calls the Scheme procedure `q'.
Gambit-C maintains the Scheme continuation separately from the C stack, thus allowing the Scheme continuation to be unwound independently from the C stack. The C stack frame created for the C function `f' is only removed from the C stack when control returns from `f' or when control returns to a C function "above" `f'. Special care is required for programs which escape to Scheme (using first-class continuations) from a Scheme to C (to Scheme) call because the C stack frame will remain on the stack. The C stack may overflow if this happens in a loop with no intervening return to a C function. To avoid this problem make sure the C stack gets cleaned up by executing a normal return from a Scheme to C call.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
define) of the same procedure. Replace all
but the first define with assignments (set!).
define-structure) can be written with
write but can not be read by read.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
floor and ceiling procedures gave incorrect
results for negative arguments.
round procedure did not obey the round to even rule.
A value exactly in between two consecutive integers is now correctly
rounded to the closest even integer.
apply did not check that an implementation limit
on the number of arguments was not exceeded. This could corrupt the
heap if too many arguments were passed to apply.
and and or special forms was
very slow for deep nestings. This is now much faster. Note that
the code generated has not changed.
equal? was not performed properly when the arguments
were procedures. This could cause the program to crash.
display or write will be read back
by read as the same number.
display, write and number->string
are more precise and much faster than before (up to a factor of 50).
exact->inexact convert
exact rationals much more precisely than before, in particular when
the denominator is more than 1e308.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Gambit system (including the Gambit-C version) is Copyright (C) 1994-2002 by Marc Feeley, all rights reserved.
The Gambit system and programs developed with it may be used and
distributed only under the following conditions: they must include this
copyright and distribution notice and they must not be sold, transferred
or used to provide a tool or service (such as a web server) for which
there is a direct or indirect revenue. In other words if the software
developed with Gambit-C has commercial value a commercial license is
required. The system may be used at a school or university for teaching
and research even if tuition is charged by the school. For a commercial
license please contact gambit@iro.umontreal.ca.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| Jump to: | #
+
,
-
.
<
=
>
^
_
A B C D E F G H I K L M N O P R S T U V W |
|---|
| Jump to: | #
+
,
-
.
<
=
>
^
_
A B C D E F G H I K L M N O P R S T U V W |
|---|
| [Top] | [Contents] | [Index] | [ ? ] |
c-declare special form
c-initialize special form
c-lambda special form
c-define special form
c-define-type special form
| [Top] | [Contents] | [Index] | [ ? ] |
1. Gambit-C: a portable version of Gambit
2. The Gambit Scheme interpreter
3. The Gambit Scheme compiler
4. Runtime options for all programs
5. Handling of file names
6. Emacs interface
7. Extensions to Scheme
8. Scheme threads
9. Interface to C
10. Known limitations and deficiencies
11. Bugs fixed
12. Copyright and distribution information
General Index
| [Top] | [Contents] | [Index] | [ ? ] |
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
| [ < ] | Back | previous section in reading order | 1.2.2 |
| [ > ] | Forward | next section in reading order | 1.2.4 |
| [ << ] | FastBack | previous or up-and-previous section | 1.1 |
| [ Up ] | Up | up section | 1.2 |
| [ >> ] | FastForward | next or up-and-next section | 1.3 |
| [Top] | Top | cover (top) of document | |
| [Contents] | Contents | table of contents | |
| [Index] | Index | concept index | |
| [ ? ] | About | this page |