Gambit
This manual documents Gambit. It covers release v4.9.5.
1. The Gambit system
The Gambit programming system is a full implementation of the Scheme
language which conforms to the R4RS, R5RS, R7RS and IEEE Scheme standards. It
consists of two main programs: gsi
, the Gambit Scheme
interpreter, and gsc
, the Gambit Scheme compiler.
The Gambit Scheme compiler translates Scheme code to another target
language, currently C or JavaScript. The C target is the most mature
and it offers portability and fast execution. The JavaScript target
allows writing web apps in Scheme.
Most of the Gambit system, including the interpreter and compiler, is
written in Scheme and compiled to portable C code using the compiler.
The high portability of the generated C code allows the interpreter,
compiler and user programs to be easily compiled and executed on any
platform for which a C compiler is available. With appropriate
declarations in the source code the compiled Scheme programs run
roughly as fast as equivalent C programs.
For the most up to date information on Gambit and related resources
please visit the Gambit web page at https://gambitscheme.org.
Issues should be reported on the github source code repository
https://github.com/gambit/gambit.
1.1 Accessing the system files
Files related to Gambit, such as executables, libraries and header files,
are stored in multiple Gambit installation directories.
Gambit may be installed on a system according to two different
installation models.
In the first model there is a single directory where all the Gambit
installation directories are stored. This central installation
directory is typically /usr/local/Gambit
under UNIX,
/Library/Gambit
under macOS and C:/Program
Files/Gambit
under Microsoft Windows. This may have been
overridden when the system was built with the command ‘configure
--prefix=/my/Gambit’. If the system was built with the command
‘configure --enable-multiple-versions’ then the central
installation directory is prefix/version
, where
version
is the system version string
(e.g. v4.9.5
for Gambit v4.9.5). Moreover,
prefix/current
will be a symbolic link which points to
the central installation directory. In this model, the Gambit
installation directory named X is simply the subdirectory
X of the central installation directory.
In the second model some or all of the Gambit installation directories
are stored in installation specific directories. The location of
these directories is assigned when the system is built using the
command ‘configure --bindir=/my/bin --includedir=/my/include
--libdir=/my/lib’.
The advantage of the first model is that it is easy to have multiple
versions of Gambit coexist and to remove all the files of a given
version. However, the second model may be necessary to conform to the
package installation conventions of some operating systems.
Executable programs such as the interpreter gsi
and compiler
gsc
can be found in the bin
installation directory.
Adding this directory to the PATH
environment variable allows
these programs to be started by simply entering their name. This is
done automatically by the macOS and Microsoft Windows installers.
The runtime library is located in the lib
installation
directory. When the system’s runtime library is built as a
shared-library (with the command ‘configure --enable-shared’) all
programs built with Gambit, 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 macOS, and PATH
on Microsoft
Windows. If the shell is sh
, 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/lib gsi
|
A similar problem exists with the Gambit header file gambit.h
,
located in the include
installation directory. This header
file is needed for compiling Scheme programs with the Gambit
compiler. When the C compiler is being called explicitly 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/lib/libgambit.a /usr/lib # name may vary
$ ln -s /usr/local/Gambit/include/gambit.h /usr/include
|
Alternatively these files can be copied or linked in the directory
where the C compiler is invoked (this requires no special privileges).
Another approach is to set some environment variables which
are used to tell the C compiler where to find header files
and libraries. For example, the following settings can be
used for the gcc
C compiler:
| $ export LIBRARY_PATH=/usr/local/Gambit/lib
$ export CPATH=/usr/local/Gambit/include
|
Note that this may have been done by the installation process. In
particular, the macOS and Microsoft Windows prebuilt installers set
up the environment so that the gcc
compiler finds these files
automatically.
2. The Gambit Scheme interpreter
Synopsis:
| gsi [-:runtimeoption,…] [-i] [-f] [-h] [-help] [-v]
[[-] [-e expressions] [-install] [-uninstall] [-update]
[search-directory-or-module-or-file]]…
|
The interpreter is executed in batch mode when the command line
contains a module or file or a ‘-’, or ‘-e’ option. The
interpreter is executed in module management mode when the
command line contains the ‘-install’, ‘-uninstall’, or
‘-update’ option. Otherwise the interpreter is executed in
interactive mode. The ‘-i’ option is ignored by the
interpreter. The initialization file will be examined unless the
‘-f’ option is present (see section Customization). The
‘-h’ and ‘-help’ options print brief usage information on
standard output and exit. The ‘-v’ option prints the system
version string, system time stamp, operating system type, and
configure script options on standard output and exits. Runtime
options are explained in Runtime options.
2.1 Interactive mode
In interactive mode a read-eval-print loop (REPL) is started for the
user to interact with the interpreter. At each iteration of this loop
the interpreter displays a prompt, reads a command and executes it.
The commands can be expressions to evaluate (the typical case) or
special commands related to debugging, for example ‘,q’ to
terminate the process (for a complete list of commands see
Debugging or use the ‘,help’ command). Most commands produce
some 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. The interaction channel can be specified
through the runtime options but if none is specified the system uses a
reasonable default that depends on the system’s configuration.
Typically the program’s standard input and output are used as the
interaction channel. When using the runtime option ‘-:debug=c’,
the interaction channel is the user’s console, also known as the
controlling terminal in the UNIX world.
When the REPL starts, the ports associated with
‘(current-input-port)’, ‘(current-output-port)’ and
‘(current-error-port)’ all refer to the interaction channel.
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 are
defined as returning an unspecified value (e.g. write
,
set!
, define
).
Here is a sample interaction with gsi
:
| $ gsi
Gambit v4.9.5
> (define (fact n) (if (< n 2) 1 (* n (fact (- n 1)))))
> (map fact '(1 2 3 4 5 6))
(1 2 6 24 120 720)
> (values (fact 10) (fact 40))
3628800
815915283247897734345611269596115894272000000000
> ,q
|
What happens when errors occur is explained in Debugging.
2.2 Batch mode
In batch mode the command line arguments denote modules and files to
execute, REPL interactions to start (‘-’ option), and expressions
to be evaluated (‘-e’ option). Those options can be interspersed
with the search directories, modules, and files on the command line
and can occur multiple times.
In addition to these options the command line may contain 3 types of
non-options: search directories, modules, and files.
- Search directories
Search directories are locations in the file system that are searched
to resolve references to modules. Any command line argument that ends
with a path separator or a ‘.’ is treated as a search directory.
By default the module search order is initially ~~lib
(which contains
builtin modules) followed by ~~userlib
(which contains user
installed modules and is typically the directory
.gambit_userlib
in the user’s home directory). Search
directories on the command line are added to the front of the search
order, and thus take precedence over the default module search order.
- Modules
Modules are either unversioned or versioned (managed by
the git
version-control system). There are two flavors of
versioned modules: hosted modules have a git
repository
on a network accessible repository manager site such as
github.com
and gitlab.com
, and local modules have
a git
repository on the local file system. Module names have a
syntax similar to the paths used to identify files. They consist of one
or more non-empty parts separated by ‘/’. The last part may end
with a suffix of the form @version
. Only the
first part and version may contain ‘.’, otherwise only the
characters a-z, A-Z, 0-9, ‘-’, and ‘_’ are permitted. If
there are at least 3 parts and the first part contains at least one
‘.’ and no ‘_’, then it refers to a hosted module (1st part
= host, 2nd part = account, 3rd part = repository name). For example
github.com/gambit/hello@1.0
is a hosted module reference.
Otherwise it refers to a local versioned module or an unversioned
module, for example foobar
or A/B/C/D
.
- Files
Files are simple code containers located on the local file system.
They are also identified by a path. If a path is a valid
module or file, it is interpreted as a module. Note that a path
with a last component containing an extension, such as ‘.scm’,
and no @
, is always interpreted as a file.
The interpreter processes the command line arguments from left to
right. Search directories are added to the head of the module search
order. Files are executed using the load
procedure. Modules
are requested using the ##demand-module
special form (this form
is explained in Modules, but essentially it causes that module
to be searched in the module search order and executed once). The ‘-e’
option uses the eval
procedure to evaluate expressions in the
global interaction environment. After this processing the interpreter
exits.
The ports associated with ‘(current-input-port)’,
‘(current-output-port)’ and ‘(current-error-port)’ initially
refer respectively to the standard input (‘stdin’), standard
output (‘stdout’) and the standard error (‘stderr’) of the
interpreter. This is true even in REPLs started with the ‘-’
option. The usual interaction channel is still used to read
expressions and commands and to display results. This makes it
possible to use REPLs to debug programs which read the standard input
and write to the standard output, even when these have been
redirected.
Here is a sample use of the interpreter in batch mode, under UNIX:
| $ cat h.scm
(display "hello") (newline)
$ cat w.six
display("world"); newline();
$ gsi h.scm - w.six -e "(pretty-print 1)(pretty-print 2)"
hello
> (define (display x) (write (reverse (string->list x))))
> ,c
(#\d #\l #\r #\o #\w)
1
2
$ gsi . h w # add . to search order to load modules h and w
hello
world
|
2.3 Module management mode
Package management operations are executed using the command line
options ‘-install’, ‘-uninstall’, and ‘-update’
which respectively install, uninstall and update packages.
Package installation is explained in detail in Modules, but
here are a few examples:
| $ gsi -install github.com/gambit/hello
installing github.com/gambit/hello to /Users/feeley/.gambit_userlib/
$ gsi github.com/gambit/hello@1.0
hello world!
$ gsi -uninstall github.com/gambit/hello
uninstalling github.com/gambit/hello from /Users/feeley/.gambit_userlib/
|
2.4 Customization
There are two ways to customize the interpreter. When the interpreter
starts off it tries to execute a ‘(load "~~lib/gambext")’ (for an
explanation of how file names are interpreted see Host environment).
An error is not signaled when 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
working 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: ‘.gambini’ and ‘~/.gambini’ (with no
extension, a ‘.sld’ 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 when the ‘-f’
option is specified.
2.5 Process exit status
The status is zero when the interpreter exits normally and is nonzero
when the interpreter exits due to an error. Here is the meaning of
the exit statuses:
-
0
The execution of the primordial thread (i.e. the main thread) did not
encounter any error. It is however possible that other threads
terminated abnormally (by default threads other than the primordial
thread terminate silently when they raise an exception that is not
handled).
-
64
The runtime options or the environment variable ‘GAMBOPT’
contained a syntax error or were invalid.
-
70
This normally indicates that an exception was raised in the primordial
thread and the exception was not handled.
-
71
There was a problem initializing the runtime system, for example
insufficient memory to allocate critical tables.
For example, if the shell is sh
:
| $ gsi -e "(pretty-print (expt 2 100))"
1267650600228229401496703205376
$ echo $?
0
$ gsi -e "(pretty-print (expo 2 100))"
*** ERROR IN (string)@1.16 -- Unbound variable: expo
$ echo $?
70
$ gsi -:debug=0 -e "(pretty-print (expo 2 100))"
$ echo $?
70
$ gsi -:debug=0,unknown # try to use an unknown runtime option
$ echo $?
64
$ gsi -:debug=0 nonexistent.scm # try to load a file that does not exist
$ echo $?
70
$ gsi nonexistent.scm
*** ERROR IN ##load-module-or-file -- No such file or directory
(load "nonexistent.scm")
$ echo $?
70
|
Note the use of the runtime option ‘-:debug=0’ that prevents error
messages from being output.
2.6 Scheme scripts
The load
procedure treats specially files that begin with the
two characters ‘#!’ and ‘@;’. Such files are called
script files and the first line is called the script line.
In addition to indicating that the file is a script, the script line
provides information about the source code language to be used by the
load
procedure. After the two characters ‘#!’ and
‘@;’ the system will search for the first substring matching one
of the following language specifying tokens:
-
scheme-r4rs
-
R4RS language with prefix syntax, case-insensitivity, keyword syntax
not supported
-
scheme-r5rs
-
R5RS language with prefix syntax, case-insensitivity, keyword syntax
not supported
-
scheme-ieee-1178-1990
-
IEEE 1178-1990 language with prefix syntax, case-insensitivity, keyword
syntax not supported
-
scheme-srfi-0
-
R5RS language with prefix syntax and SRFI 0 support
(i.e. cond-expand
special form), case-insensitivity, keyword
syntax not supported
-
gsi-script
-
Full Gambit Scheme language with prefix syntax, case-sensitivity, keyword
syntax supported
-
gsc-script
-
Full Gambit Scheme language with prefix syntax, case-sensitivity, keyword
syntax supported
-
six-script
-
Full Gambit Scheme language with infix syntax, case-sensitivity, keyword
syntax supported
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 script line, load
will parse the rest of
the file (using the syntax of the language indicated) and then execute
it. When the file is being loaded because it is an argument on the
interpreter’s command line, the interpreter will:
-
Setup the
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. The expanded file name
of the script file can be used to determine the directory that
contains the script (i.e. (path-directory (car (command-line)))
).
-
After the script is loaded the procedure
main
is called with
the command line arguments. The way this is done depends on the
language specifying token. For scheme-r4rs
,
scheme-r5rs
, scheme-ieee-1178-1990
, and
scheme-srfi-0
, the main
procedure 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 the “Running Scheme Scripts on Unix SRFI” (SRFI
22). For gsi-script
and six-script
the main
procedure is called with the equivalent of (apply main (cdr
(command-line)))
and the process exit status code is 0 (main
’s
result is ignored). The Gambit 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 (examples are given in
the next section).
-
When
main
returns, the interpreter exits. The command line
arguments after a script file are consequently not processed (however
they do appear in the list returned by the command-line
procedure, after the script file’s expanded file name, so it is up to
the script to process them).
2.6.1 Scripts under UNIX and macOS
Under UNIX and macOS, the Gambit installation process creates the
executable ‘gsi’ and also the executables ‘six’,
‘gsi-script’, ‘six-script’, ‘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 ‘#!’ and the directory where the Gambit
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 on standard
output the files in the current directory:
| #!/usr/local/Gambit/bin/gsi-script
(for-each pretty-print (directory-files))
|
Here is another UNIX script, using the Scheme infix syntax extension,
which takes a single integer argument and prints on standard output the
numbers from 1 to that integer:
| #!/usr/local/Gambit/bin/six-script
function main(n_str)
{
scmobj n = \string->number(n_str);
for (scmobj i=1; i<=n; i++)
\pretty-print(i);
}
|
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 gsi-script
(define (display-file filename)
(display (call-with-input-file filename
(lambda (port)
(read-line port #f)))))
(for-each display-file (cdr (command-line)))
|
2.6.2 Scripts under Microsoft Windows
Under Microsoft Windows, the Gambit installation process creates the
executable ‘gsi.exe’ and ‘six.exe’ and also the batch files
‘gsi-script.bat’, ‘six-script.bat’, ‘scheme-r5rs.bat’,
‘scheme-srfi-0.bat’, etc which simply invoke ‘gsi.exe’ with
the same command line arguments. A Scheme script need only start with
the name of the desired Scheme language variant prefixed with
‘@;’. A UNIX script can be converted to a Microsoft Windows
script simply by changing the script line and storing the script in a
file whose name has a ‘.bat’ or ‘.cmd’ extension:
| @;gsi-script %~f0 %*
(display "files:\n")
(pretty-print (directory-files))
|
Note that Microsoft Windows always searches executables in the user’s
‘PATH’, so there is no need for an indirection such as the UNIX
‘/usr/bin/env’. However the script line must end with ‘%~f0
%*’ to pass the expanded filename of the script and command line
arguments to the interpreter.
2.6.3 Compiling scripts
A script file can be compiled using the Gambit Scheme compiler
(see section The Gambit Scheme compiler) into a standalone executable. The script line will
provide information to the compiler on which language to use. The
script line also provides information on which runtime options to use
when executing the compiled script. This is useful to set the default
runtime options of an executable program.
The compiled script will be executed similarly to an interpreted
script (i.e. the list of command line arguments returned by the
command-line
procedure and the invocation of the main
procedure).
For example:
| $ cat square.scm
#!/usr/local/Gambit/bin/gsi-script -:debug=0
(define (main arg)
(pretty-print (expt (string->number arg) 2)))
$ gsi square 30 # gsi will load square.scm
900
$ gsc -exe square # compile the script to a standalone program
$ ./square 30
900
$ ./square 1 2 3 # too many arguments to main
$ echo $?
70
$ ./square -:debug=1 1 2 3 # ask for error message
*** ERROR IN ##start-main -- Wrong number of arguments passed to procedure
(main "1" "2" "3")
|
3. The Gambit Scheme compiler
Synopsis:
| gsc [-:runtimeoption,…] [-i] [-f] [-h] [-help] [-v]
[-target target]
[-prelude expressions] [-postlude expressions]
[-dynamic] [-exe] [-obj]
[-nb-gvm-regs n] [-nb-arg-regs n] [-compactness level]
[-cc compiler] [-cc-options options]
[-ld-options-prelude options] [-ld-options options]
[-pkg-config pkg-config-args] [-pkg-config-path pkg-config-path]
[-warnings] [-verbose] [-report] [-expansion] [-gvm] [-cfg] [-dg]
[-debug] [-debug-location] [-debug-source]
[-debug-environments] [-track-scheme]
[-o output] [-c] [-keep-temp] [-link] [-flat] [-l base]
[-module-ref module-ref] [-linker-name linker-name]
[[-] [-e expressions] [-preload] [-nopreload]
[search-directory-or-module-or-file]]…
|
The ‘-h’ and ‘-help’ options print brief usage information
on standard output and exit. The ‘-v’ option prints the system
version string, system time stamp, operating system type, and
configure script options on standard output and exits.
The ‘-i’ option can be used to force gsc
to process the
command line like the interpreter. The only difference with the
interpreter is that the compilation related procedures listed in this
chapter are also available (i.e. compile-file
,
compile-file-to-target
, etc).
3.1 Interactive mode
When no command line argument is present other than options gsc
behaves like gsi
in interactive mode.
3.2 Customization
Like the interpreter, the compiler will examine the initialization
file unless the ‘-f’ option is specified. Runtime options are
explained in Runtime options.
3.3 Batch mode
In batch mode gsc
accepts on the command line 3 types of
non-options which are processed from left to right: search
directories, modules, and files. Search directories are
added to the list of module search order directories. Every command
line argument that is the name of a module that is found in the list
of module search order directories will cause that module to be
compiled. Similarly, file names (with either no extension, or a C
file extension, or some other extension) on the command line will
cause that file to be compiled. The compilation is done for the
target language specified with the -target
target option.
target is either js
, for JavaScript, or C
, which
is the default if no target language is specified.
The recognized C file extensions are ‘.c’, ‘.C’, ‘.cc’,
‘.cp’, ‘.cpp’, ‘.CPP’, ‘.cxx’, ‘.c++’,
‘.m’, ‘.M’, and ‘.mm’.
The extension can be omitted from a file name when the Scheme file has
a ‘.scm’, ‘.sld’ or ‘.six’ extension. When the
extension of the Scheme file is ‘.six’ the content of the file
will be parsed using the Scheme infix syntax extension (see
Scheme infix syntax extension). Otherwise, gsc
will parse
the Scheme file using the normal Scheme prefix syntax. Files with a C
file extension must have been previously produced by gsc
with
the C
target and the ‘-c’ option, and are used by the
C
target Gambit linker.
For each Scheme file the compiler creates a file of target code,
either ‘file.c’ or ‘file.js’ for the C
and js
targets respectively. The file’s name is the same as
the Scheme file, but the extension is changed to ‘.c’ or
‘.js’ as appropriate. By default the file is created in the
same directory as the Scheme file. This default can be overridden
with the compiler’s ‘-o’ option.
The files of target code produced by the compiler serve two purposes.
They will be processed by a C compiler or JavaScript VM, and they also
contain information to be read by Gambit’s linker to generate a
link file. The link file is a file of target code 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 only invoked when the ‘-link’ or ‘-exe’
options appear on the command line.
Compiler options must be specified before the first file name and
after the ‘-:’ runtime option (see section Runtime options). If
present, the ‘-i’, ‘-f’, and ‘-v’ compiler options
must come first. The available options are:
-
-i
Force interpreter mode.
-
-f
Do not examine the initialization file.
-
-h / -help
Print brief usage information on standard output and exit.
-
-v
Print the system version string, system time stamp, operating system
type, and configure script options on standard output and exit.
-
-target target
Select the target language.
-
-prelude expressions
Add expressions to the top of the source code being compiled.
-
-postlude expressions
Add expressions to the bottom of the source code being compiled.
-
-cc compiler
Select specific C compiler.
-
-cc-options options
Add options to the command that invokes the C compiler.
-
-ld-options-prelude options
Add options to the command that invokes the C linker.
-
-ld-options options
Add options to the command that invokes the C linker.
-
-pkg-config pkg-config-args
Use the pkg-config
program to determine options for the
C compiler and C linker.
-
-pkg-config-path pkg-config-path
Add a path to the PKG_CONFIG_PATH
environment variable.
-
-warnings
Display warnings.
-
-verbose
Display a trace of the compiler’s activity.
-
-report
Display a global variable usage report.
-
-expansion
Display the source code after expansion.
-
-gvm
Generate a listing of the GVM code.
-
-cfg
Generate a control flow graph of the GVM code.
-
-dg
Generate a dependency graph.
-
-debug
Include all debugging information in the code generated.
-
-debug-location
Include source code location debugging information in the code generated.
-
-debug-source
Include the source code debugging information in the code generated.
-
-debug-environments
Include environment debugging information in the code generated.
-
-track-scheme
Generate ‘#line’ directives referring back to the Scheme code.
-
-o output
Set name of output file or directory where output file(s) are written.
-
-dynamic
Compile Scheme source files to dynamically loadable object
files (this is the default).
-
-exe
Compile Scheme source files to an executable program (machine code or script).
-
-obj
Compile Scheme source files to object files by invoking the C compiler.
-
-keep-temp
Keep any intermediate files that are generated.
-
-c
Compile Scheme source files to target code without generating a link file.
-
-link
Compile Scheme source files to target code and generate a link file.
-
-flat
Generate a flat link file instead of the default incremental link file.
-
-l base
Specify the link file of the base library to use for the link.
-
-module-ref module-ref
Specify the reference of the generated module.
-
-linker-name linker-name
Specify the name of the low-level initialization function exported
by the module.
-
-preload
Turn on ‘preload’ linker bit.
-
-nopreload
Turn off ‘preload’ linker bit.
Start REPL interaction.
-
-e expressions
Evaluate expressions in the interaction environment.
-
-nb-gvm-regs n
Specify the number of available Gambit virtual machine registers.
-
-nb-arg-regs n
Specify the number of procedure call parameters passed in Gambit virtual
machine registers.
-
-compactness level
Specify the compactness of the generated code.
The ‘-i’ option forces the compiler to process the remaining
command line arguments like the interpreter.
The ‘-target’ option selects the target language of the compilation.
It is either js
for JavaScript, or C
for C (which is
the default).
The ‘-prelude’ option adds the specified expressions to the top
of the source code being compiled. It can appear multiple times. 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. It can appear multiple
times. 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’ option is only meaningful when the C
target is
selected. The ‘-cc’ option selects the specified C compiler for
compiling the generated C code. When this option is used, the default
C compiler options that were determined to be needed by the configure
script are nullified because they are very likely to be invalid for
the specified C compiler. Any options needed for this C compiler
should be specified explicitly using the ‘-cc-options’,
‘-ld-options-prelude’, and ‘-ld-options’ options. For
example:
| $ gsc -cc clang -cc-options "-O0 -bundle" bench.scm # clang on macOS
$ gsc -cc tcc -cc-options -shared bench.scm # tcc on linux
|
The ‘-cc-options’ option is only meaningful when the C
target is selected and a dynamically loadable object file is being
generated (neither the ‘-c’ or ‘-link’ options are used).
It can appear multiple times. 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 -cc-options "-U___SINGLE_HOST -O2 -I../include" bench.scm
|
The ‘-ld-options-prelude’ and ‘-ld-options’ options are only
meaningful when the C
target is selected and a dynamically
loadable object file is being generated (neither the ‘-c’ or
‘-link’ options are used). They can appear multiple times. The
‘-ld-options-prelude’ and ‘-ld-options’ options add the
specified options to the command that invokes the C linker (the
options in ld-options-prelude are passed to the C linker before
the input file and the options in ld-options are passed after).
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 -ld-options "-L/usr/X11R6/lib -lX11 -dynamic" app.scm
|
The ‘-pkg-config’ is only meaningful when the C
target is
selected. The ‘-pkg-config’ option will cause the
pkg-config
program to be invoked to determine the options to
add to the command that invokes the C compiler and C linker. It can
appear multiple times. The pkg-config
program is passed the
arguments in the string pkg-config-args in addition to either
--cflags
or --libs
. It is typical for
pkg-config-args to be the name of a system library, such as
"sqlite3"
, but other pkg-config
options can be
specified, such as "--static sqlite3"
. The
‘-pkg-config-path’ option adds a path to the
PKG_CONFIG_PATH
environment variable for use by the
pkg-config
program to find ‘.pc’ files. For example:
| $ gsc -pkg-config "x11" -pkg-config-path "/usr/share/pkgconfig" app.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 whether 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 ‘-cfg’ option generates a visual representation of the
control flow graph of the intermediate code for the “Gambit Virtual
Machine” (GVM) of each Scheme file on ‘file.cfg’.
The file is suitable for processing with the “dot” program.
For example, to generate the PDF file ‘file.cfg.pdf’
from ‘file.cfg’ the following command can be used:
The ‘-dg’ option generates a visual representation of the
dependency graph of each Scheme file on ‘file.dg’.
The file is suitable for processing with the “dot” program.
For example, to generate the PDF file ‘file.dg.pdf’
from ‘file.dg’ the following command can be used:
The ‘-debug’ option causes all kinds of debugging information to
be saved in the code generated. See the documentation of the
‘debug’ declaration for details.
The ‘-debug-location’ option causes source code location
debugging information to be saved in the code generated. See the
documentation of the ‘debug-location’ declaration for details.
The ‘-debug-source’ option causes source code debugging
information to be saved in the code generated. See the documentation
of the ‘debug-source’ declaration for details.
The ‘-debug-environments’ option causes environment debugging
information to be saved in the code generated. See the documentation
of the ‘debug-environments’ declaration for details.
The ‘-track-scheme’ option is only meaningful when the C
target is selected. The ‘-track-scheme’ option causes the
generation of ‘#line’ directives that refer back to the Scheme
source code. This allows the use of a C debugger or profiler to debug
Scheme code.
The ‘-o’ option sets the filename of the output file, or the
directory in which the output file(s) generated by the compiler are
written.
If the ‘-link’ or ‘-exe’ options appear on the command line,
the Gambit linker is invoked to generate the link file from the set of
files specified on the command line or produced by the Gambit
compiler. By default the link file is named after the last file on
the compiler’s command line. If the last file stripped of it’s
extension is ‘last’ then the link file is
‘last_.c’ for the C
target and ‘last_.js’
for the js
target. When the ‘-c’ option is specified, the
Scheme source files are compiled to target files without invoking the
linker, which is useful for separate compilation of modules. When the
‘-exe’ option is specified, the generated target files and link
file are combined to produce an executable program whose name defaults
to ‘last’ on Unix, and ‘last.exe’ or
‘last.bat’ on Windows depending on whether a machine code
executable or script is produced. When the C
target is
selected and the ‘-obj’ option is specified, the generated C
files are compiled using the C compiler to produce object files
(‘.o’ or ‘.obj’ extensions). If neither the ‘-link’,
‘-c’, ‘-exe’, or ‘-obj’ options appear on the command
line, the Scheme source files are compiled to dynamically loadable
object files (‘.on’ extension). The ‘-keep-temp’
option will prevent the deletion of any intermediate files that are
generated. Note that in this case the intermediate file
will be generated in the same directory as the Scheme source file even
if the ‘-o’ option is used.
The ‘-flat’ option is only meaningful when a link file is being
generated (i.e. the ‘-link’ or ‘-exe’ options also appear on
the command line). 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 when an incremental link file
is being generated (i.e. the ‘-link’ or ‘-exe’ options
appear on the command line and the ‘-flat’ option is absent).
The ‘-l’ option specifies the link file (without the ‘.c’ or
‘.js’ 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/_gambit’).
The ‘-preload’ and ‘-nopreload’ options are only meaningful
when a link file is being generated. The ‘-preload’ option turns
on the ‘preload’ linker bit for the modules that follow on the
command line. The following modules will be loaded unconditionally at
program startup and in command line order (this is the default for
compatibility with how legacy modules have been handled in the past).
The ‘-nopreload’ option turns off the ‘preload’ linker bit.
The following modules will be loaded only to satisfy the module
dependencies of the ##demand-module
form.
The ‘-’ option starts a REPL interaction.
The ‘-e’ option evaluates the specified expressions in the
interaction environment.
The ‘-nb-gvm-regs’ option specifies the number of Gambit virtual
machine registers that are available for the generated code. The
default number depends on configuration options and the target but it
is typically 5. All modules and the runtime library must be compiled
with the same setting. This option exists mainly for experimentation
by the developers. For example:
| $ gsc -nb-gvm-regs 10 -c bench.scm
|
The ‘-nb-arg-regs’ option specifies the number of procedure call
parameters passed in Gambit virtual machine registers. The default
number depends on configuration options and the target but it is
typically 3. All modules and the runtime library must be compiled
with the same setting. This option exists mainly for experimentation
by the developers. For example:
| $ gsc -nb-arg-regs 2 -c bench.scm
|
The ‘-compactness’ option selects the level of compactness of the
generated code. The default level depends on configuration options
and the target but it is typically 5. Levels from 0 to 5 cause the
generation of increasingly compact code with little or no impact on
execution speed. Lower values tend to make the generated code more
humanly readable. Above a level of 5 the compiler will trade
execution speed for saving code space. The detailed meaning of this
option depends on the target, some targets may ignore it and some
targets may require all modules and the runtime library to be compiled
with the same compactness level. For example:
| $ gsc -target js -compactness 0 -c bench.scm
|
3.4 Link files
Gambit can be used to create programs and libraries of Scheme
modules. This section explains the steps required to do so and the role
played by the link files.
In general, a program is composed of a set of Scheme modules and
modules in the target language. Some of the modules are part of the
Gambit runtime library and the other modules are supplied by the user.
When the program 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 though 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 target 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 a
program 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 program 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
programs (this linking information typically takes hundreds of kilobytes).
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, a program 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 program is dynamically linked with this shared-library and
only contains the user modules and the incremental link file. For
small programs this approach greatly reduces the size of the
program 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
The simplest way to create an executable program is to invoke
gsc
with the ‘-exe’ option. The compiler will
transparently perform all the steps necessary, including compiling
Scheme source files to target files, generating the link file, and
(when the C
target is selected) compiling the C files generated
to object files and creating the final executable file using the C
linker. The following example shows how to use the C
target to
build the executable program ‘hello.exe’ which contains the two
Scheme modules ‘h.scm’ and ‘w.six’.
| $ cat h.scm
(display "hello") (newline)
$ cat w.six
display("world"); newline();
$ gsc -o hello.exe -exe h.scm w.six
h.scm:
/Users/feeley/gambit/doc/h.c:
w.six:
/Users/feeley/gambit/doc/w.c:
/Users/feeley/gambit/doc/w_.c:
$ ./hello.exe
hello
world
|
The detailed steps which are performed can be viewed by setting the
‘GAMBUILD_VERBOSE’ environment variable to a nonnull value.
Alternatively, gsc
’s ‘-verbose’ option can be used (it
implicitly sets the ‘GAMBUILD_VERBOSE’ environment variable).
For example:
| $ export GAMBUILD_VERBOSE=yes
$ gsc -o hello.exe -exe h.scm w.six
h.scm:
/Users/feeley/gambit/doc/h.c:
gcc -O1 -Wno-unused -Wno-write-strings -Wdisabled-optimization
fwrapv -fno-strict-aliasing -fno-trapping-math -fno-math-errno
-fschedule-insns2 -foptimize-sibling-calls -fomit-frame-pointer -fPIC
-fno-common -mpc64 -D___SINGLE_HOST -I"/usr/local/Gambit/include"
-c -o 'h.o' 'h.c'
w.six:
/Users/feeley/gambit/doc/w.c:
gcc -O1 -Wno-unused -Wno-write-strings -Wdisabled-optimization
-fwrapv -fno-strict-aliasing -fno-trapping-math -fno-math-errno
-fschedule-insns2 -foptimize-sibling-calls -fomit-frame-pointer -fPIC
-fno-common -mpc64 -D___SINGLE_HOST -I"/usr/local/Gambit/include"
-c -o 'w.o' 'w.c'
/Users/feeley/gambit/doc/w_.c:
gcc -O1 -Wno-unused -Wno-write-strings -Wdisabled-optimization
-fwrapv -fno-strict-aliasing -fno-trapping-math -fno-math-errno
-fschedule-insns2 -foptimize-sibling-calls -fomit-frame-pointer -fPIC
-fno-common -mpc64 -D___SINGLE_HOST -I"/usr/local/Gambit/include"
-c -o 'w_.o' 'w_.c'
gcc -Wno-unused -Wno-write-strings -Wdisabled-optimization
-fwrapv -fno-strict-aliasing -fno-trapping-math -fno-math-errno
-fschedule-insns2 -foptimize-sibling-calls -fomit-frame-pointer -fPIC
-fno-common -mpc64 -D___SINGLE_HOST -I"/usr/local/Gambit/include"
-o 'hello.exe' 'w_.o' 'h.o' 'w.o' "/usr/local/Gambit/lib/libgambit.a"
|
Here is the same example using the js
target showing the creation
of a shell script invoking nodejs:
| $ export GAMBUILD_VERBOSE=yes
$ gsc -target js -o hello.exe -exe h.scm w.six
h.scm:
/Users/feeley/gambit/doc/h.js:
cat h.js > "h.o"
w.six:
/Users/feeley/gambit/doc/w.js:
cat w.js > "w.o"
/Users/feeley/gambit/doc/w_.js:
cat w_.js > "w_.o"
echo "#! /usr/bin/env node" > "hello.exe"
cat w_.o h.o w.o "/usr/local/Gambit/lib/_gambit.js" >> "hello.exe"
chmod +x "hello.exe"
|
Using a single invocation of gsc
with the ‘-exe’ option is
sometimes inappropriate when the build process is more complex, for
example when the program is composed of several separately compiled
modules. In such a case it is useful to decompose the build process
into smaller compilation steps. The ‘hello.exe’ executable
program could have been built with the C
target by separating
the generation of C files from the C compilation and linking:
| $ gsc -c h.scm
$ gsc -c w.six
$ gsc -o hello.exe -exe h.c w.c
|
When even finer control is desired the C
target’s build process
can be decomposed into smaller steps that invoke the C compiler and
linker explicitly. This is described in the rest of this section.
The gsc
compiler can be invoked to compile each Scheme module
into a C file and to 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. The content of the three source files (‘m1.c’,
‘m2.scm’ and ‘m3.scm’) is:
| /* File: "m1.c" */
int power_of_2 (int x) { return 1<<x; }
; File: "m2.scm"
(c-declare "extern int power_of_2 ();")
(define pow2 (c-lambda (int) int "power_of_2"))
(define (twice x) (cons x x))
; File: "m3.scm"
(write (map twice (map pow2 '(1 2 3 4)))) (newline)
|
The compilation of the two Scheme source files can be done with
three invocations of gsc
:
| $ gsc -c m2.scm # create m2.c (note: .scm is optional)
$ gsc -c m3.scm # create m3.c (note: .scm is optional)
$ gsc -link m2.c m3.c # create the incremental link file m3_.c
|
Alternatively, the three invocations of gsc
can be replaced by a
single invocation:
| $ gsc -link m2 m3
m2:
m3:
|
At this point there will be 4 C files: ‘m1.c’, ‘m2.c’,
‘m3.c’, and ‘m3_.c’. To produce an executable program these
files must be compiled with a C compiler and linked with the Gambit
runtime library. The C compiler options needed will depend on the C
compiler and the operating system (in particular it may be necessary
to add the options ‘-I/usr/local/Gambit/include
-L/usr/local/Gambit/lib’ to access the ‘gambit.h’ header file
and the Gambit runtime library).
Here is an example under macOS:
| $ uname -srmp
Darwin 20.6.0 x86_64 i386
$ gsc -obj m1.c m2.c m3.c m3_.c
m1.c:
m2.c:
m3.c:
m3_.c:
$ gcc m1.o m2.o m3.o m3_.o -lgambit
$ ./a.out
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
|
Here is an example under Linux:
| $ uname -srmp
Linux 5.10.0-9-amd64 x86_64 unknown
$ gsc -obj m1.c m2.c m3.c m3_.c
m1.c:
m2.c:
m3.c:
m3_.c:
$ gcc m1.o m2.o m3.o m3_.o -lgambit -lm -ldl -lutil
$ ./a.out
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
|
3.4.2 Building a loadable library
To bundle multiple modules into a single object file that can be
dynamically loaded with the load
procedure, a flat link file is
needed. The compiler’s ‘-o’ option must be used to name the C
file generated as follows. If the dynamically loadable object file is
to be named ‘myfile.on’ then the ‘-o’ option
must set the name of the link file generated to
‘myfile.on.c’ (note that the ‘.c’ extension
could also be ‘.cc’, ‘.cpp’ or whatever extension is
appropriate for C/C++ source files). The three modules of the
previous example can be bundled by generating a link file in this way:
| $ gsc -link -flat -o foo.o1.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")
|
The warnings indicate that there are no definitions (define
s 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.
When compiling the C files and link file generated, the flag
‘-D___DYNAMIC’ must be passed to the C compiler and the C
compiler and linker must be told to generate a dynamically loadable
shared library.
Here is an example under macOS:
| $ uname -srmp
Darwin 20.6.0 x86_64 i386
$ gsc -link -flat -o foo.o1.c m2 m3 > /dev/null
m2:
m3:
$ gsc -cc-options "-D___DYNAMIC" -obj m1.c m2.c m3.c foo.o1.c
m1.c:
m2.c:
m3.c:
foo.o1.c:
$ gcc -bundle m1.o m2.o m3.o foo.o1.o -o foo.o1
$ gsi foo.o1
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
|
Here is an example under Linux:
| $ uname -srmp
Linux 5.10.0-9-amd64 x86_64 unknown
$ gsc -link -flat -o foo.o1.c m2 m3 > /dev/null
m2:
m3:
$ gsc -cc-options "-D___DYNAMIC" -obj m1.c m2.c m3.c foo.o1.c
m1.c:
m2.c:
m3.c:
foo.o1.c:
$ gcc -shared m1.o m2.o m3.o foo.o1.o -o foo.o1
$ gsi foo.o1
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
|
Here is a more complex example, under Solaris, which shows how to build
a loadable library ‘mymod.o1’ composed of the files ‘m4.scm’,
‘m5.scm’ and ‘x.c’ that links to system shared libraries (for
X-windows):
| $ uname -srmp
SunOS ungava 5.6 Generic_105181-05 sun4m sparc SUNW,SPARCstation-20
$ gsc -link -flat -o mymod.o1.c m4 m5
m4:
m5:
*** WARNING -- "*" is not defined,
*** referenced in: ("m4.c")
*** WARNING -- "+" is not defined,
*** referenced in: ("m5.c")
*** WARNING -- "display" is not defined,
*** referenced in: ("m5.c" "m4.c")
*** WARNING -- "newline" is not defined,
*** referenced in: ("m5.c" "m4.c")
*** WARNING -- "write" is not defined,
*** referenced in: ("m5.c")
$ gsc -cc-options "-D___DYNAMIC" -obj m4.c m5.c x.c mymod.o1.c
m4.c:
m5.c:
x.c:
mymod.o1.c:
$ /usr/ccs/bin/ld -G -o mymod.o1 mymod.o1.o m4.o m5.o x.o -lX11 -lsocket
$ gsi mymod.o1
hello from m4
hello from m5
(f1 10) = 22
$ cat m4.scm
(define (f1 x) (* 2 (f2 x)))
(display "hello from m4")
(newline)
(c-declare #<<c-declare-end
#include "x.h"
c-declare-end
)
(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 m5.scm
(define (f2 x) (+ x 1))
(display "hello from m5")
(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);
|
3.4.3 Building a shared-library
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 -srmp
Linux 5.10.0-9-amd64 x86_64 unknown
$ gsc -link -o mylib.c m2
$ gsc -obj -cc-options "-D___SHARED" m1.c m2.c mylib.c
m1.c:
m2.c:
mylib.c:
$ gcc -shared m1.o m2.o mylib.o -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 -link -l mylib m3
$ gsc -obj m3.c m3_.c
m3.c:
m3_.c:
$ gcc m3.o m3_.o mylib.so -lgambit
$ LD_LIBRARY_PATH=.:/usr/local/lib ./a.out
((2 . 2) (4 . 4) (8 . 8) (16 . 16))
|
3.4.4 Other compilation options
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 ‘-O2’
option can be passed to the C compiler. For large modules, it will
not be practical to specify both ‘-O2’ 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.
It has been observed that lower levels of optimization (e.g. ‘-O1’)
often give faster compilation and also generate faster code. It is
a good idea to experiment.
Normally C compilers will not automatically search
‘/usr/local/Gambit/include’ for header files so the flag
‘-I/usr/local/Gambit/include’ should be passed to the C
compiler. Similarly, C compilers/linkers will not automatically
search ‘/usr/local/Gambit/lib’ for libraries so the flag
‘-L/usr/local/Gambit/lib’ should be passed to the C
compiler/linker. Alternatives are given in Accessing the system files.
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’, ‘-G’. Check your compiler’s documentation to see
which flag you need.
3.5 Procedures specific to compiler
The Gambit Scheme compiler features the following procedures that
are not available in the Gambit Scheme interpreter.
The file parameter must be a string. If expression is not
specified, file must name an existing file containing Scheme
source code. The extension can be omitted from file when the
Scheme file has a ‘.scm’, ‘.sld’ or ‘.six’ extension.
By default, this procedure compiles the source file into a file
containing C code. A different target language can be selected in the
options. The generated file is named after file with the
extension replaced with ‘.c’ or ‘.js’, as appropriate for
the target selected. The name of the generated file can also be
specified directly with the output parameter. If output
is a string naming a directory then the generated file is created in
that directory. Otherwise the name of the generated file is
output.
Compilation options are specified through the options parameter
which must be an association list. Any combination of the following
options can be used: ‘target’, ‘verbose’, ‘report’, ‘expansion’,
‘gvm’, ‘debug’, ‘module-ref’, and ‘linker-name’.
When expression is specified, the file parameter is not
open or read. Instead, expression is used as though it was the
content of the file. This makes it possible to compile source code
without having to create a file to contain the code. Note that
file is used in error messages and to determine the output file
name if output is not specified.
When the compilation is successful, compile-file-to-target
returns
the name of the file generated. When there is a compilation error,
#f
is returned.
| $ cat h.scm
(display "hello") (newline)
$ gsc
Gambit v4.9.5
> (compile-file-to-target "h")
"/Users/feeley/gambit/doc/h.c"
|
( compile-file file [options: options] [output: output] [base: base] [expression: expression] [cc-options: cc-options] [ld-options-prelude: ld-options-prelude] [ld-options: ld-options]) | procedure |
The file, options, output, and expression parameters have the
same meaning as for the compile-file-to-target
procedure, except that
file may be a Scheme source file or a
file possibly generated by the Gambit Scheme compiler (for example
with the compile-file-to-target
procedure). The
cc-options parameter is a string containing the options to pass
to the C compiler and the ld-options-prelude and
ld-options parameters are strings containing the options to pass
to the C linker (the options in ld-options-prelude are passed to
the C linker before the input file and the options in ld-options
are passed after).
The compile-file
procedure compiles the source file file
into an object file, which is either a file dynamically loadable using
the load
procedure, or a C linkable object file destined to be
linked with the C linker (for example to create a standalone
executable program). The presence of the
obj
option in options will cause the creation of a C
linkable object file and therefore the options
ld-options-prelude and ld-options are ignored, otherwise a
dynamically loadable file is created. In both cases, if file is
a Scheme source file, the compiler first compiles file to a C
file which is created in the same directory as file regardless
of the output parameter. Then the C file is compiled with the C
compiler.
When the compilation is successful, compile-file
returns the
name of the object file generated. When there is a compilation error,
#f
is returned.
The name of the object file can be specified with the output
parameter. If output is a string naming a directory then the
object file is created in that directory. Otherwise the name of the
object file is output.
In the case of a dynamically loadable object file, by default 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
.
When dynamically loaded object files are loaded using the load
procedure, the ‘.on’ extension can be specified (to select
a particular version) or omitted (to load the file with a
‘.on’ extension with the highest n consecutively from
1). When the ‘.on’ extension is not specified and older
versions are no longer needed, all versions must be deleted and the
compilation must be repeated (this is necessary because the file name,
including the extension, is used to name some of the exported symbols
of the object file).
Note that dynamically loadable object files can only be generated on
host operating systems that support dynamic loading.
| $ cat h.scm
(display "hello") (newline)
$ gsc
Gambit v4.9.5
> (compile-file "h")
"/Users/feeley/gambit/doc/h.o1"
> (load "h")
hello
"/Users/feeley/gambit/doc/h.o1"
> (compile-file-to-target "h" output: "h.o99.c")
"/Users/feeley/gambit/doc/h.o99.c"
> (compile-file "h.o99.c")
"/Users/feeley/gambit/doc/h.o99"
> (load "h.o99")
hello
"/Users/feeley/gambit/doc/h.o99"
> (compile-file-to-target "h")
"/Users/feeley/gambit/doc/h.c"
> (compile-file "h.c" options: '(obj))
"/Users/feeley/gambit/doc/h.o"
|
( link-incremental module-list [output: output] [linker-name: linker-name] [base: base] [warnings?: warnings?]) | procedure |
The first parameter must be a non empty list of strings naming Scheme
modules to link (the file extension may be omitted). An incremental
link file is generated for the modules specified in module-list.
By default the link file generated is named
‘last_.ext’, where last is the name of the last
module, without the file extension, and ext is the appropriate
extension for the target. The name of the generated link file can be
specified with the output parameter. If output is a
string naming a directory then the link file is created in that
directory. Otherwise the name of the link file is output.
The base link file is specified by the base parameter, which
must be a string. By default the base link file is the Gambit runtime
library link file ‘~~lib/_gambit’ (with extension appropriate for
the target). However, when base is supplied it is the name of
the base link file (the file extension may be omitted).
The warnings? parameter controls whether warnings are
generated for undefined references.
The following example shows how to build the executable program
‘hello’ which contains the two Scheme modules ‘h.scm’ and
‘w.six’.
| $ uname -srmp
Darwin 8.1.0 Power Macintosh powerpc
$ cat h.scm
(display "hello") (newline)
$ cat w.six
display("world"); newline();
$ gsc
Gambit v4.9.5
> (compile-file-to-target "h")
"/Users/feeley/gambit/doc/h.c"
> (compile-file-to-target "w")
"/Users/feeley/gambit/doc/w.c"
> (link-incremental '("h" "w") output: "hello.c")
"/Users/feeley/gambit/doc/hello_.c"
> ,q
$ gsc -obj h.c w.c hello.c
h.c:
w.c:
hello.c:
$ gcc h.o w.o hello.o -lgambit -o hello
$ ./hello
hello
world
|
( link-flat module-list [output: output] [linker-name: linker-name] [warnings?: warnings?]) | procedure |
The first parameter must be a non empty list of strings naming Scheme
modules to link (the file extension may be omitted). 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. A flat link file is
generated for the modules specified in module-list. By default
the link file generated is named ‘last_.ext’, where
last is the name of the last module, without the file extension,
and ext is the appropriate extension for the target. The name
of the generated link file can be specified with the output
parameter. If output is a string naming a directory then the
link file is created in that directory. Otherwise the name of the
link file is output. If a dynamically loadable object file is
produced from the link file ‘output’, then the name of the
dynamically loadable object file must be ‘output’ stripped
of its file extension.
The warnings? parameter controls whether warnings are
generated for undefined references.
The following example shows how to build the dynamically loadable object
file ‘lib.o1’ which contains the two Scheme modules
‘m6.scm’ and ‘m7.scm’.
| $ uname -srmp
Darwin 8.1.0 Power Macintosh powerpc
$ cat m6.scm
(define (f x) (g (* x x)))
$ cat m7.scm
(define (g y) (+ n y))
$ gsc
Gambit v4.9.5
> (compile-file-to-target "m6")
"/Users/feeley/gambit/doc/m6.c"
> (compile-file-to-target "m7")
"/Users/feeley/gambit/doc/m7.c"
> (link-flat '("m6" "m7") output: "lib.o1.c")
*** WARNING -- "*" is not defined,
*** referenced in: ("m6.c")
*** WARNING -- "+" is not defined,
*** referenced in: ("m7.c")
*** WARNING -- "n" is not defined,
*** referenced in: ("m7.c")
"/Users/feeley/gambit/doc/lib.o1.c"
> ,q
$ gcc -bundle -D___DYNAMIC m6.c m7.c lib.o1.c -o lib.o1
$ gsc
Gambit v4.9.5
> (load "lib")
*** WARNING -- Variable "n" used in module "m7" is undefined
"/Users/feeley/gambit/doc/lib.o1"
> (define n 10)
> (f 5)
35
> ,q
|
The warnings indicate that there are no definitions (define
s 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.
4. Runtime options
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:
-
min-heap=
SIZE or the shorthand m
SIZE
Set minimum heap size.
-
max-heap=
SIZE or the shorthand h
SIZE
Set maximum heap size.
-
live-ratio=
RATIO or the shorthand l
RATIO
Set the ratio of heap that is live after a garbage collection.
-
gambit
or the (deprecated) shorthand S
Select Gambit Scheme mode. This is the default mode.
-
r5rs
or the (deprecated) shorthand s
Select R5RS Scheme mode.
-
r7rs
Select R7RS Scheme mode.
-
debug
[=
[OPT...]] or the shorthand d
[OPT...]
Set debugging options.
-
~~
NAME=
DIRECTORY
Override the NAME installation directory.
-
add-arg=
ARGUMENT or the shorthand +
ARGUMENT
Add ARGUMENT to the command line before other arguments.
-
io-settings=
[IO...] or the shorthand i
[IO...]
Set general I/O settings.
-
file-settings=
[IO...] or the shorthand f
[IO...]
Set general file I/O settings.
-
stdio-settings=
[IO...] or the shorthand -
[IO...]
Set general stdio settings.
-
0
[IO...]
Set stdin settings.
-
1
[IO...]
Set stdout settings.
-
2
[IO...]
Set stderr settings.
-
terminal-settings=
[IO...] or the shorthand t
[IO...]
Set terminal I/O settings.
-
search=
[DIR]
Set or reset module search order.
-
whitelist=
[SOURCE]
Set or reset the whitelist of trusted sources for automatic
installation of hosted modules.
-
ask-install=
WHEN
Set automatic installation confirmation mode.
The min-heap=
SIZE and max-heap=
SIZE
options set limits on the size of the heap. The SIZE is an
integer that may be followed by G
(gigabytes), M
(megabytes), or K
or nothing (kilobytes). The heap will
not shrink lower than the minimum heap size which defaults to 0. The
heap will not grow larger than the maximum heap size if it is set (by
default the heap may grow until the virtual memory is exhausted).
The live-ratio=
RATIO option sets the percentage of
the heap that will be occupied with live objects after the heap is
resized at the end of a garbage collection. RATIO is an integer
between 1 and 100 inclusively indicating the desired percentage. The
garbage collector resizes the heap to reach this percentage occupation
(roughly), within the limits of the min-heap
and
max-heap
options. By default, the percentage is 50.
The gambit
, r5rs
and r7rs
options
configure the runtime system to conform to Gambit Scheme, R5RS Scheme
and R7RS Scheme respectively. The reader is case-insensitive in
r5rs
mode, and is case-sensitive in r7rs
and
gambit
modes. The reader supports keywords only in
gambit
mode, which is the default mode.
The debug=
OPT,... option sets various debugging options.
The equal sign is followed by a sequence of letters indicating suboptions.
-
p
-
Uncaught exceptions will be treated as “errors” in the primordial thread
only.
-
a
-
Uncaught exceptions will be treated as “errors” in all threads.
-
r
-
When an “error” occurs a new REPL will be started.
-
s
-
When an “error” occurs a new REPL will be started.
Moreover the program starts in single-stepping mode.
-
q
-
When an “error” occurs the program will terminate with a nonzero
exit status.
-
R
-
When a user interrupt occurs a new REPL will be started. User
interrupts are typically obtained by typing <^C>. Note that with
some system configurations <^C> abruptly terminates the process.
For example, under Microsoft Windows, <^C> works fine with the
standard console but with the MSYS terminal window it terminates the
process.
-
D
-
When a user interrupt occurs it will be deferred until the parameter
object current-user-interrupt-handler
is set or bound.
-
Q
-
When a user interrupt occurs the program will terminate with a nonzero
exit status.
- LEVEL
-
The verbosity level is set to LEVEL, a digit from 0 to 9.
At level 0 the runtime system will not display error messages
and warnings. At level 1 and above error messages and warnings are
displayed. At level 2 and above a backtrace is displayed.
At level 3 and above variable bindings are displayed in the backtrace.
At level 5 and above garbage collection reports are displayed during
program execution.
-
c
-
The REPL interaction channel will be the console.
-
-
-
The REPL interaction channel will be standard input and standard output.
-
+
-
The REPL interaction channel will be standard input and standard output
and standard error.
-
@
[HOST][:
PORT]
-
When a REPL is started by a thread a connection will be established
with the address HOST:PORT and that will be the REPL’s
interaction channel. The default HOST is 127.0.0.1 and the
default PORT is 44556.
-
$
[INTF][:
PORT]
-
The runtime system will open a socket to listen on port number
PORT for incoming connections on the network interface with
address INTF. The default INTF is 127.0.0.1 and the
default PORT is 44555.
The default debugging options are equivalent to debug=pqQ1-
(i.e. an uncaught exception in the primordial thread terminates the
program after displaying an error message). When the option
debug
is used without suboptions it is equivalent to
debug=prR1-
(i.e. a new REPL is started only when an uncaught
exception occurs in the primordial thread). When gsi
and
gsc
are running the main REPL, the debugging options are
changed to cause errors in the primordial thread and user interrupts
to start a nested REPL.
The ~~
NAME=
DIRECTORY option
overrides the setting of the NAME installation directory. If
NAME is empty, it will override the central installation
directory.
The add-arg=
ARGUMENT option adds the text that
follows to the command line before other arguments.
The option io-settings=
[IO...] sets the
default I/O settings of all types of ports. The option
file-settings=
[IO...] sets the default I/O
settings for ports associated to files. The option
stdio-settings=
[IO...] sets the default I/O
settings for ports associated to stdio (but finer control is possible
with 0
[IO...],
1
[IO...], and
2
[IO...] that set the I/O settings of stdin,
stdout, and stderr respectively). The option
terminal-settings=
[IO...] overrides the
default I/O settings for ports associated to terminals. The default
character encoding, end-of-line encoding and buffering can be set.
Moreover, for terminals the line-editing feature can be enabled or
disabled. Each IO is a one or two letter code as follows:
-
A
ASCII character encoding.
-
1
ISO-8859-1 character encoding.
-
2
UCS-2 character encoding.
-
4
UCS-4 character encoding.
-
6
UTF-16 character encoding.
-
8
UTF-8 character encoding.
-
U
UTF character encoding with fallback to UTF-8 on input if no BOM is present.
-
UA
UTF character encoding with fallback to ASCII on input if no BOM is present.
-
U1
UTF character encoding with fallback to ISO-8859-1 on input if no BOM is present.
-
U6
UTF character encoding with fallback to UTF-16 on input if no BOM is present.
-
U8
UTF character encoding with fallback to UTF-8 on input if no BOM is present.
-
L
If the LC_ALL
or LC_CTYPE
or LANG
environment
variables end with ‘.UTF-8’ or ‘.ISO-8859-1’ or
‘.LATIN-1’ (or a variation) set the character encoding
accordingly.
-
c
End-of-line is encoded as CR (carriage-return).
-
l
End-of-line is encoded as LF (linefeed)
-
cl
End-of-line is encoded as CR-LF.
-
u
Unbuffered I/O.
-
n
Line buffered I/O (‘n’ for “at newline”).
-
f
Fully buffered I/O.
-
r
Illegal character encoding is treated as an error (exception raised).
-
R
Silently replace illegal character encodings with Unicode character #xfffd
(replacement character).
-
e
Enable line-editing (applies to terminals only).
-
E
Disable line-editing (applies to terminals only).
The search=
[DIR] option adds DIR to the
head of the list of module search order directories, unless DIR
is empty, in which case it is set to the empty list. The initial
setting of the list of module search order directories is ~~lib
followed by ~~userlib
.
When a hosted module can’t be found in the directories on the list of
module search order directories it will be automatically installed if
it is from a source on the whitelist of trusted sources, which
initially contains only github.com/gambit
. The
whitelist=
[SOURCE] option adds SOURCE
to the whitelist, unless SOURCE is empty in which case the
whitelist will be set to the empty list (no source is trusted).
The ask-install=
WHEN option sets the automatic
installation mode confirmation mode to WHEN, which is one of
always
, repl
, and never
. When a hosted module
can’t be found in the directories on the list of module search order
directories and it is from a source not on the whitelist the runtime
system will ask for installation confirmation when WHEN is
always
, or when a REPL has already been started for the current
thread and WHEN is repl
. In the never
mode the
runtime system will not install the module automatically. The default
mode is repl
.
When a program’s execution starts, the runtime system obtains the
runtime options by processing in turn various sources of runtime options:
the defaults, the environment variable ‘GAMBOPT’, the script
line of the source code, and, unless the program is an interpreted
script, the first command line argument of the
program. Any runtime option can be overriden by a subsequent source
of runtime options. It is sometimes useful to prevent overriding
the runtime options of the script line. This can be achieved by
starting the script line runtime options with ‘-:,’. In
this case the environment variable ‘GAMBOPT’ is ignored,
and the first command line argument of the program is
not used for runtime options (it is treated like a normal
command line argument even if it starts with ‘-:’).
For example:
| $ export GAMBOPT=debug=0,~~=~/my-gambit2
$ gsi -e '(pretty-print (path-expand "~~")) (/ 1 0)'
"/Users/feeley/my-gambit2/"
$ echo $?
70
$ gsi -:debug=1 -e '(pretty-print (path-expand "~~")) (/ 1 0)'
"/Users/feeley/my-gambit2/"
*** ERROR IN (string)@1.35 -- Divide by zero
(/ 1 0)
|
5. Debugging
5.1 Debugging model
The evaluation of an expression may stop before it is completed for the
following reasons:
- An evaluation error has occured, such as attempting to
divide by zero.
- The user has interrupted the evaluation (usually by typing <^C>).
- A breakpoint has been reached or
(step)
was evaluated.
- Single-stepping mode is enabled.
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 a symbol within parentheses, such as
‘(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. For example when evaluating the expression
‘(let ((y (- 1 1))) (* (/ x y) 2))’, a “divide by zero” error is
reported and the nested REPL’s continuation is the one that takes the
result and multiplies it by two. The REPL’s lexical environment
includes the lexical variable ‘y’. This allows the inspection of
the evaluation context (i.e. the lexical and dynamic environments and
continuation), which is particularly useful to determine the exact
location and cause of an error.
The prompt of nested REPLs includes the nesting level; ‘1>’ is the
prompt at the first nesting level, ‘2>’ at the second nesting
level, and so on. An end of file (usually <^D>) will cause the
current REPL to be terminated 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. A backtrace that lists the chain of active
continuation frames in the REPL’s continuation can be obtained with
the ‘,b’ command. The frames are numbered from 0, that is frame
0 is the most recent frame of the continuation where execution
stopped, frame 1 is the parent frame of frame 0, and so on. It is
also possible to move the REPL to a specific parent continuation
(i.e. a specific frame of the continuation where execution stopped)
with the ‘,N’, ‘,N+’, ‘,N-’,
‘,+’, ‘,-’, ‘,++’, and ‘,--’ commands. When the
frame number of the frame being examined is not zero, it is shown in
the prompt after the nesting level, for example ‘1\5>’ is the
prompt when the REPL nesting level is 1 and the frame number is 5.
Expressions entered at a nested REPL are evaluated in the environment
(both lexical and dynamic) 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.
5.2 Debugging commands
In addition to expressions, the REPL accepts the following special
“comma” commands:
-
,? and ,help
-
Give a summary of the REPL commands.
-
,(h subject)
-
This command will show the section of the Gambit manual with the
definition of the procedure or special form subject, which must
be a symbol. For example ‘,(h time)’ will show the section
documenting the time
special form. Please see the help
procedure for additional information.
-
,h
-
This command will show the section of the Gambit manual with the
definition of the procedure which raised the exception for which this
REPL was started.
-
,q
-
Terminate the process with exit status 0. This is equivalent to
calling (exit 0)
.
-
,qt
-
Terminate the current thread (note that terminating the primordial
thread terminates the process).
-
,t
-
Return to the outermost REPL, also known as the “top-level REPL”.
-
,d
-
Leave the current REPL and resume the enclosing REPL. This command does
nothing in the top-level REPL.
-
,(c expr)
-
Leave the current REPL and continue the computation that initiated the
REPL with a specific value. This command can only be used to continue
a computation that signaled an error. The expression expr is
evaluated in the current context and the resulting value is returned
as the value of the expression which signaled the error. For example,
if the evaluation of the expression ‘(* (/ x y) 2)’ signaled an
error because ‘y’ is zero, then in the nested REPL a ‘,(c (+
4 y))’ will resume the computation of ‘(* (/ x y) 2)’ as though
the value of ‘(/ x y)’ was 4. This command must be used
carefully because the context where the error occured may rely on the
result being of a particular type. For instance a ‘,(c #f)’ in
the previous example will cause ‘*’ to signal a type error (this
problem is the most troublesome when debugging Scheme code that was
compiled with type checking turned off so be careful).
-
,c
-
Leave the current REPL and continue the computation that initiated the
REPL. This command can only be used to continue a computation that was
stopped due to a user interrupt, breakpoint or a single-step.
-
,s
-
Leave the current REPL and continue the computation that initiated the
REPL in single-stepping mode. The computation will perform an
evaluation step (as defined by 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
-
This command is similar to ‘,s’ except that it “leaps” over
procedure calls, that is procedure calls are treated like a single step.
Single-stepping mode will resume when the procedure call returns, or if
and when the execution of the called procedure encounters a breakpoint.
-
,N
-
Move to frame number N of the continuation. After changing the
current frame, a one-line summary of the frame is displayed as if the
‘,y’ command was entered.
-
,N+
-
Move forward by N frames in the chain of continuation frames
(i.e. towards older continuation frames). After changing the current
frame, a one-line summary of the frame is displayed as if the
‘,y’ command was entered.
-
,N-
-
Move backward by N frames in the chain of continuation frames
(i.e. towards more recent continuation frames). After changing the
current frame, a one-line summary of the frame is displayed as if the
‘,y’ command was entered.
-
,+
-
Equivalent to ‘,1+’.
-
,-
-
Equivalent to ‘,1-’.
-
,++
-
Equivalent to ‘,N+’ where N is the number of
continuation frames displayed at the head of a backtrace.
-
,--
-
Equivalent to ‘,N-’ where N is the number of
continuation frames displayed at the head of a backtrace.
-
,y
-
Display a one-line summary of the current frame. The information is
displayed in four fields. The first field is the frame number. The
second field is the procedure that created the frame or
‘(interaction)’ if the frame was created by an expression entered
at the REPL. The remaining fields describe the subproblem associated
with the frame, that is the expression whose value is being computed.
The third field is the location of the subproblem’s source code and
the fourth field is a reproduction of the source code, possibly
truncated to fit on the line. The last two fields may be missing if
that information is not available. In particular, the third field is
missing when the frame was created by a user call to the ‘eval’
procedure or by a compiled procedure not compiled with the declaration
‘debug-location’, and the last field is missing when the frame
was created by a compiled procedure not compiled with the declaration
‘debug-source’.
-
,b
-
Display a backtrace summarizing each frame in the chain of continuation
frames starting with the current frame. For each frame, the same
information as for the ‘,y’ command is displayed (except that
location information is displayed in the format
‘stream@line:column’). If there are more than 15
frames in the chain of continuation frames, some of the middle frames
will be omitted.
-
,be
-
Like the ‘,b’ command but also display the environment.
-
,bed
-
Like the ‘,be’ command but also display the dynamic environment.
-
,(b expr)
-
Display the backtrace of expr’s value, X, which is
obtained by evaluating expr in the current frame. X must
be a continuation or a thread. When X is a continuation, the
frames in that continuation are displayed. When X is a thread,
the backtrace of the current continuation of that thread is displayed.
-
,(be expr)
-
Like the ‘,(b expr)’ command but also display the
environment.
-
,(bed expr)
-
Like the ‘,(be expr)’ command but also display the dynamic
environment.
-
,i
-
Pretty print the procedure that created the current frame or
‘(interaction)’ if the frame was created by an expression entered
at the REPL. Compiled procedures will only be pretty printed when
they are compiled with the declaration ‘debug-source’.
-
,e
-
Display the environment which is accessible from the current frame.
The lexical environment is displayed, followed by the dynamic
environment if the parameter object
repl-display-dynamic-environment?
is not false. Global lexical
variables are not displayed. Moreover the frame must have been
created by interpreted code or code compiled with the declaration
‘debug-environments’. Due to space safety
considerations and compiler optimizations, some of the lexical
variable bindings may be missing. Lexical variable bindings are
displayed using the format ‘variable = expression’
(when variable is mutable) or ‘variable == expression’
(when variable is immutable, which may happen in compiled code
due to compiler optimization)
and dynamically-bound parameter bindings are displayed using the
format ‘(parameter) = expression’. Note that
expression can be a self-evaluating expression (number, string,
boolean, character, ...), a quoted expression, a lambda expression or
a global variable (the last two cases, which are only used when the
value of the variable or parameter is a procedure, simplifies the
debugging of higher-order procedures). A parameter can be a
quoted expression or a global variable. Lexical bindings are
displayed in inverse binding order (most deeply nested first) and
shadowed variables are included in the list.
-
,ed
-
Like the ‘,e’ command but the dynamic environment is always
displayed.
-
,(e expr)
-
Display the environment of expr’s value, X, which is
obtained by evaluating expr in the current frame. X must
be a continuation, a thread, a procedure, or a nonnegative integer.
When X is a continuation, the environment at that point in the
code is displayed. When X is a thread, the environment of the
current continuation of that thread is displayed. When X is a
procedure, the lexical environment where X was created is
combined with the current continuation and this combined environment
is displayed. When X is an integer, the environment at frame
number X of the continuation is displayed.
-
,(ed expr)
-
Like the ‘,(e expr)’ command but the dynamic environment is
always displayed.
-
,st
-
Display the state of the threads in the current thread’s thread group.
A thread can be: uninitialized, initialized, active, and
terminated (normally or abnormally). Active threads can be
running, sleeping and waiting on a synchronization object
(mutex, condition variable or port) possibly with a timeout.
-
,(st expr)
-
Display the state of a specific thread or thread group.
The value of expr must be a thread or thread group.
-
,(v expr)
-
Start a new REPL visiting expr’s value, X, which is
obtained by evaluating expr in the current frame. X must
be a continuation, a thread, a procedure, or a nonnegative integer.
When X is a continuation, the new REPL’s continuation is X
and evaluations are done in the environment at that point in the code.
When X is a thread, the thread is interrupted and the new REPL’s
continuation is the point where the thread was interrupted. When
X is a procedure, the lexical environment where X was
created is combined with the current continuation and evaluations are
done in this combined environment. When X is an integer, the
REPL is started in frame number X of the continuation.
5.3 Debugging example
Here is a sample interaction with gsi
:
| $ gsi
Gambit v4.9.5
> (define (invsqr x) (/ 1 (expt x 2)))
> (define (mymap fn lst)
(define (mm in)
(if (null? in)
'()
(cons (fn (car in)) (mm (cdr in)))))
(mm lst))
> (mymap invsqr '(5 2 hello 9 1))
*** ERROR IN invsqr, (console)@1.25 -- (Argument 1) NUMBER expected
(expt 'hello 2)
1> ,i
#<procedure #2 invsqr> =
(lambda (x) (/ 1 (expt x 2)))
1> ,e
x = 'hello
1> ,b
0 invsqr (console)@1:25 (expt x 2)
1 #<procedure #4> (console)@6:17 (fn (car in))
2 #<procedure #4> (console)@6:31 (mm (cdr in))
3 #<procedure #4> (console)@6:31 (mm (cdr in))
4 (interaction) (console)@8:1 (mymap invsqr '(5 2 hel...
1> ,+
1 #<procedure #4> (console)@6.17 (fn (car in))
1\1> (pp #4)
(lambda (in) (if (null? in) '() (cons (fn (car in)) (mm (cdr in)))))
1\1> ,e
in = '(hello 9 1)
mm = (lambda (in) (if (null? in) '() (cons (fn (car in)) (mm (cdr in)))))
fn = invsqr
lst = '(5 2 hello 9 1)
1\1> ,(e mm)
mm = (lambda (in) (if (null? in) '() (cons (fn (car in)) (mm (cdr in)))))
fn = invsqr
lst = '(5 2 hello 9 1)
1\1> fn
#<procedure #2 invsqr>
1\1> (pp fn)
(lambda (x) (/ 1 (expt x 2)))
1\1> ,+
2 #<procedure #4> (console)@6.31 (mm (cdr in))
1\2> ,e
in = '(2 hello 9 1)
mm = (lambda (in) (if (null? in) '() (cons (fn (car in)) (mm (cdr in)))))
fn = invsqr
lst = '(5 2 hello 9 1)
1\2> ,(c (list 3 4 5))
(1/25 1/4 3 4 5)
> ,q
|
5.4 Procedures related to debugging
( help [subject]) | procedure |
The help
procedure displays the section of the Gambit manual
with the definition of the procedure or special form subject,
which must be a procedure or symbol. For example the call (help
gensym)
will show the section documenting the gensym
procedure
and the call (help 'time)
will show the section documenting the
time
special form. When the subject is absent, the
documentation of the help
procedure is shown. The help
procedure returns the void object.
The parameter object help-browser
is bound to a string naming
the external program that is used by the help
procedure to view
the documentation. Initially it is bound to the empty string. In
normal circumstances when help-browser
is bound to an empty
string the help
procedure runs the script
~~bin/gambdoc.bat
which searches for a suitable web browser
to open the documentation in HTML format. Unless the system was built
with the command ‘configure --enable-help-browser=...’, the
text-only browser ‘lynx’ (see http://lynx.isc.org/) will
be used by default if it is available. We highly recommend that you
install this browser if you are interested in viewing the
documentation within the console in which the REPL is running. You
can exit ‘lynx’ conveniently by typing an end of file (usually
<^D>).
For example:
| > (help-browser "firefox") ; use firefox instead of lynx
> (help 'gensym)
> (help gensym) ; OK because gensym is a procedure
> (help 'time)
> (help time) ; not OK because time is a special form
*** ERROR IN (console)@5.7 -- Macro name can't be used as a variable: time
>
|
( apropos [substring [port]]) | procedure |
The apropos
procedure writes to the port port a report of
all the global variables whose name contains substring, a string
or symbol. If substring is not specified the report contains
all the global variables. If it is not specified, port defaults
to the interaction channel (i.e. the output will appear at the REPL).
The apropos
procedure returns the void object.
The global variables are grouped into namespaces. The empty
namespace, if it is relevant, is last. This reduces the likelihood it
will scroll off the screen if there are several global variables in
other namespaces, which are typically less interesting.
Note that with the apropos
procedure it is possible to reveal
the existence of procedures of the runtime system and modules that are
not intended to be called by user code. These procedures often avoid
type checking their arguments or must be called in a specific context,
so calling them incorrectly may crash the system. On the other hand
it also allows discovering the existence of certain functionalities
that may have gone unnoticed.
For example:
| > (apropos "cons")
"##" namespace:
10^-constants, cons, cons*, cons*-aux, console-port,
constant-expression-value, constant-expression?,
cprc-quasi-cons, deconstruct-call,
define-type-construct-constant, degen-quasi-cons,
gen-quasi-cons, quasi-cons, stdio/console-repl-channel,
void-constant?, xcons
empty namespace:
cons, cons*, console-port, xcons
> (import (srfi 69))
> (apropos "table?")
"##" namespace:
gc-hash-table?, mutable?, readtable?, table?
"srfi/69#" namespace:
hash-table?
empty namespace:
readtable?, table?
> (apropos "srfi/69#")
"srfi/69#" namespace:
||, alist->hash-table, hash, hash-by-identity,
hash-table->alist, hash-table-copy, hash-table-delete!,
hash-table-equivalence-function, hash-table-exists?,
hash-table-fold, hash-table-hash-function,
hash-table-keys, hash-table-merge!, hash-table-ref,
hash-table-ref/default, hash-table-set!, hash-table-size,
hash-table-update!, hash-table-update!/default,
hash-table-values, hash-table-walk, hash-table?,
make-hash-table, string-ci-hash, string-hash
|
The REPL keeps a history of the last few results printed by the
REPL. The call (repl-result-history-ref i)
returns the
ith previous result (the last for i=0, the next to last
for i=1, etc). By default the REPL result history remembers up
to 3 results. The maximal length of the history can be set to n
between 0 and 10 by a call to
(repl-result-history-max-length-set! n)
.
For convenience the reader defines an abbreviation for calling
repl-result-history-ref
. Tokens formed by a sequence of one or
more hash signs, such as ‘#
’, ‘##
’, etc, are
expanded by the reader into the list (repl-result-history-ref
i)
, where i is the number of hash signs minus 1. In
other words, ‘#
’ will return the last result printed by
the REPL, ‘##
’ will return the next to last, etc.
For example:
| > (map (lambda (x) (* x x)) '(1 2 3))
(1 4 9)
> (reverse #)
(9 4 1)
> (append # ##)
(9 4 1 1 4 9)
> 1
1
> 1
1
> (+ # ##)
2
> (+ # ##)
3
> (+ # ##)
5
> ####
*** ERROR IN (console)@9.1 -- (Argument 1) Out of range
(repl-result-history-ref 3)
1>
|
The trace
procedure 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).
The untrace
procedure stops tracing calls to the specified
procedures. When no argument is passed to the trace
procedure, the list of procedures currently being traced is returned.
The void object is returned by the trace
procedure when it is
passed one or more arguments. When no argument is passed to the
untrace
procedure 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 #2 fact-iter> #<procedure #3 -> #<procedure #4 fact>)
> (untrace)
> (fact 5)
120
|
The step
procedure 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:
-
procedure call
-
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
-
variable reference and operations at lower levels
-
constant reference 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 (console)@3.15
1> ,s
| > (fact 5)
*** STOPPED IN fact, (console)@1.22
1> ,s
| | > (< n 2)
| | #f
*** STOPPED IN fact, (console)@1.43
1> ,s
| | > (- n 1)
| | 4
*** STOPPED IN fact, (console)@1.37
1> ,s
| | > (fact (- n 1))
*** STOPPED IN fact, (console)@1.22
1> ,s
| | | > (< n 2)
| | | #f
*** STOPPED IN fact, (console)@1.43
1> ,s
| | | > (- n 1)
| | | 3
*** STOPPED IN fact, (console)@1.37
1> ,l
| | | > (fact (- n 1))
*** STOPPED IN fact, (console)@1.22
1> ,l
| | > (* n (fact (- n 1)))
| | 24
*** STOPPED IN fact, (console)@1.32
1> ,l
| > (* n (fact (- n 1)))
| 120
120
|
The break
procedure 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.
The unbreak
procedure 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, (console)@1.21
1> ,b
0 double (console)@1:21 +
1 triple (console)@2:31 (double y)
2 f (console)@3:18 (triple z)
3 (interaction) (console)@6:1 (f 5)
1> ,e
x = 5
1> ,c
*** STOPPED IN double, (console)@1.21
1> ,c
*** STOPPED IN f, (console)@3.29
1> ,c
150
> (break)
(#<procedure #3 -> #<procedure #4 double>)
> (unbreak)
> (f 5)
150
|
[Note: this procedure is DEPRECATED and will be removed
in a future version of Gambit. Use the ‘proper-tail-calls’
declaration instead.]
The parameter object generate-proper-tail-calls
is bound to a
boolean value controlling how the interpreter handles tail calls.
When it is bound to #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 initial value of this parameter object is #t
, which means
that a tail call will reuse the continuation of the calling function.
This parameter object only affects code that is subsequently processed
by load
or eval
, or entered at the REPL.
For example:
| > (generate-proper-tail-calls)
#t
> (let loop ((i 1)) (if (< i 10) (loop (* i 2)) oops))
*** ERROR IN #<procedure #2>, (console)@2.47 -- Unbound variable: oops
1> ,b
0 #<procedure #2> (console)@2:47 oops
1 (interaction) (console)@2:1 ((letrec ((loop (lambda...
1> ,t
> (generate-proper-tail-calls #f)
> (let loop ((i 1)) (if (< i 10) (loop (* i 2)) oops))
*** ERROR IN #<procedure #3>, (console)@6.47 -- Unbound variable: oops
1> ,b
0 #<procedure #3> (console)@6:47 oops
1 #<procedure #3> (console)@6:32 (loop (* i 2))
2 #<procedure #3> (console)@6:32 (loop (* i 2))
3 #<procedure #3> (console)@6:32 (loop (* i 2))
4 #<procedure #3> (console)@6:32 (loop (* i 2))
5 (interaction) (console)@6:1 ((letrec ((loop (lambda...
|
[Note: this procedure is DEPRECATED and will be removed
in a future version of Gambit. Use the parameter object
repl-display-environment?
instead.]
This procedure 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.
The parameter object repl-display-environment?
is bound to a
boolean value 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. This is particularly useful in
single-stepping mode. The default setting is not to display the
environment.
The parameter object display-dynamic-environment?
is bound to a
boolean value that controls wether the dynamic environment is
displayed when the environment is displayed. The default setting is
not to display the dynamic environment.
This procedure pretty-prints obj on the port port. If it
is not specified, port defaults to the current output-port.
For example:
| > (pretty-print
(let* ((x '(1 2 3 4)) (y (list x x x))) (list y y y)))
(((1 2 3 4) (1 2 3 4) (1 2 3 4))
((1 2 3 4) (1 2 3 4) (1 2 3 4))
((1 2 3 4) (1 2 3 4) (1 2 3 4)))
|
This procedure pretty-prints obj on the port port. When
obj is a procedure created by the interpreter or a procedure
created by code compiled with the declaration
‘debug-source’, the procedure’s source code is
displayed. If it is not specified, port defaults to the
interaction channel (i.e. the output will appear at the REPL).
For example:
| > (define (f g) (+ (time (g 100)) (time (g 1000))))
> (pp f)
(lambda (g)
(+ (##time (lambda () (g 100)) '(g 100))
(##time (lambda () (g 1000)) '(g 1000))))
|
This procedure 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
megabytes since the program was started, the size of the heap in
megabytes, the heap memory in megabytes occupied by live data, the
proportion of the heap occupied by live data, and the number of bytes
occupied by movable and nonmovable objects.
5.5 Console line-editing
The console implements a simple Scheme-friendly line-editing
user-interface that is enabled by default. It offers parentheses
balancing, a history of previous commands, symbol completion, and
several emacs-compatible keyboard commands. The user’s input is
displayed in a bold font and the output produced by the system is in a
plain font. The history of previous commands is saved in the file
‘~/.gambit_history’. It is restored when a REPL is started.
Symbol completion is triggered with the tab key. When the cursor is
after a sequence of characters that can form a symbol, typing the tab
key will search the symbol table for the first symbol (in alphabetical
order) that begins with that sequence and insert that symbol. Typing
the tab key in succession will cycle through all symbols with that
prefix. When all possible symbols have been shown or there are no
possible completions, the text reverts to the uncompleted symbol and
the bell is rung.
Here are the keyboard commands available (where the ‘M-
’
prefix means the escape key is typed and the ‘C-
’ prefix
means the control key is pressed):
-
C-d
Generate an end-of-file when the line is empty, otherwise delete
character at cursor.
-
delete or backspace
Delete character before cursor.
-
M-C-d
Delete word forward and keep a copy of this text on the clipboard.
-
M-delete
Delete word backward and keep a copy of this text on the clipboard.
-
M-backspace
Delete S-expression backward and keep a copy of this text on the clipboard.
-
C-a
Move cursor to beginning of line.
-
C-e
Move cursor to end of line.
-
C-b or left-arrow
Move cursor left one character.
-
M-b
Move cursor left one word.
-
M-C-b or M-
left-arrow
Move cursor left one S-expression.
-
C-f or right-arrow
Move cursor right one character.
-
M-f
Move cursor right one word.
-
M-C-f or M-
right-arrow
Move cursor right one S-expression.
-
C-p or M-p
or up-arrow
Move to previous line in history.
-
C-n or M-n
or down-arrow
Move to next line in history.
-
C-t
Transpose character at cursor with previous character.
-
M-t
Transpose word after cursor with previous word.
-
M-C-t
Transpose S-expression after cursor with previous S-expression.
-
C-l
Clear console and redraw line being edited.
-
C-nul
Set the mark to the cursor.
-
C-w
Delete the text between the cursor and the mark and keep a copy
of this text on the clipboard.
-
C-k
Delete the text from the cursor to the end of the line and keep a copy
of this text on the clipboard.
-
C-y
Paste the text that is on the clipboard.
-
F8
Same as typing ‘#||#,c;’ (REPL command to continue the computation).
-
F9
Same as typing ‘#||#,-;’ (REPL command to move to newer frame).
-
F10
Same as typing ‘#||#,+;’ (REPL command to move to older frame).
-
F11
Same as typing ‘#||#,s;’ (REPL command to step the computation).
-
F12
Same as typing ‘#||#,l;’ (REPL command to leap the computation).
On macOS, depending on your configuration, you may have to press
the fn
key to access the function key F12
and the
option
key to access the other function keys.
On Microsoft Windows the clipboard is the system clipboard. This
allows text to be copied and pasted between the program and other
applications. On other operating systems the clipboard is internal to
the program (it is not integrated with the operating system).
5.6 Emacs interface
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)’ when the expression was obtained from standard
input, ‘(console)’ when the expression was obtained from the
console, 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 -:debug=-")
|
Alternatively, if you don’t mind always loading this package,
you can simply add this line to your ‘.emacs’ file:
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
Evaluate the expression which is before the cursor (the expression will
be copied to the Gambit interaction buffer).
-
C-c C-z
Switch to Gambit interaction buffer.
-
C-c C-l
Load a file (file attached to current buffer is default) using
(load file)
.
-
C-c C-k
Compile a file (file attached to current buffer is default) using
(compile-file file)
.
The file ‘gambit.el’ provides these additional commands:
-
F8 or C-c c
Continue the computation (same as typing ‘#||#,c;’ to the REPL).
-
F9 or C-c ]
Move to newer frame (same as typing ‘#||#,-;’ to the REPL).
-
F10 or C-c [
Move to older frame (same as typing ‘#||#,+;’ to the REPL).
-
F11 or C-c s
Step the computation (same as typing ‘#||#,s;’ to the REPL).
-
F12 or C-c l
Leap the computation (same as typing ‘#||#,l;’ to the REPL).
-
C-c _
Removes the last window that was opened to highlight an expression.
The two keystroke version of these commands can be shortened to
‘M-c’, ‘M-[’, ‘M-]’, ‘M-s’, ‘M-l’, 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 ; add directory containing gambit.el
(cons "/usr/local/Gambit/share/emacs/site-lisp"
load-path))
(setq scheme-program-name "/tmp/gsi -:debug=-") ; 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)
|
5.7 GUIDE
The implementation and documentation for GUIDE, the Gambit Universal
IDE, are not yet complete.
6. Scheme extensions
6.1 Extensions to standard procedures
These procedures do nothing.
The procedure call-with-current-continuation
is bound to the
global variables call-with-current-continuation
and
call/cc
.
6.2 Extensions to standard special forms
( lambda lambda-formals body) | special form |
( define (variable define-formals) body) | special form |
-
lambda-formals =
(
formal-argument-list )
| r4rs-lambda-formals
-
define-formals = formal-argument-list | r4rs-define-formals
-
formal-argument-list = dsssl-formal-argument-list | rest-at-end-formal-argument-list
-
dsssl-formal-argument-list = reqs opts rest keys
-
rest-at-end-formal-argument-list = reqs opts keys rest | reqs opts keys
.
rest-formal-argument
-
reqs = required-formal-argument*
-
required-formal-argument = variable
-
opts =
#!optional
optional-formal-argument* | empty
-
optional-formal-argument = variable |
(
variable initializer )
-
rest =
#!rest
rest-formal-argument | empty
-
rest-formal-argument = variable
-
keys =
#!key
keyword-formal-argument* | empty
-
keyword-formal-argument = variable |
(
variable initializer )
-
initializer = expression
-
r4rs-lambda-formals =
(
variable* )
|
(
variable+ .
variable )
|
variable
-
r4rs-define-formals = variable* | variable*
.
variable
These forms are extended versions of the lambda
and define
special forms of standard Scheme. They allow the use of optional formal
arguments, either positional or named, and support 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).
If the formal-argument-list matches
dsssl-formal-argument-list or extended-formal-argument-list
they are processed as follows:
-
Variables in required-formal-arguments are bound to
successive actual arguments starting with the first actual argument. It
shall be an error if there are fewer actual arguments than
required-formal-arguments.
-
Next variables in optional-formal-arguments are bound to
remaining actual arguments. If there are fewer remaining actual
arguments than optional-formal-arguments, then the variables are
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.
-
If
#!key
does not appear in the formal-argument-list
and there is no rest-formal-argument then it shall be an error
if there are any remaining actual arguments.
-
If
#!key
does not appear in the formal-argument-list
and there is a rest-formal-argument then the
rest-formal-argument is bound to a list of all remaining actual
arguments.
-
If
#!key
appears in the formal-argument-list and there is
no rest-formal-argument then 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. 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.
-
If
#!key
appears in the formal-argument-list and there is
a rest-formal-argument before the #!key
then there
may be an even or odd number of remaining actual arguments and the
rest-formal-argument is bound to a list of all remaining actual
arguments. Then, these remaining actual arguments are scanned from
left to right in pairs, stopping at the first pair whose first element
is not a keyword. Each pair whose first element is a keyword matching
the name of a keyword-formal-argument gives the value (i.e. the
second element of the pair) of the corresponding 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.
-
If
#!key
appears in the formal-argument-list and there is
a rest-formal-argument after the #!key
then there may
be an even or odd number of remaining actual arguments. The remaining
actual arguments are scanned from left to right in pairs, stopping at
the first pair whose first element is not a keyword. Each pair shall
have as its first element a keyword matching the name of a
keyword-formal-argument; the second element gives the value of
the corresponding 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.
Finally, the rest-formal-argument is bound to the list of the
actual arguments that were not scanned (i.e. after the last
keyword/value pair).
In all cases it is an error for a variable to appear more than
once in a formal-argument-list.
Note that this specification is compatible with the DSSSL language
standard (i.e. a correct DSSSL program will have the same semantics
when run with Gambit).
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 (k (* a b))) (list a b k))
> (define (h1 a #!rest r #!key k) (list a k r))
> (define (h2 a #!key k #!rest r) (list a k r))
> (f 1)
(1 #f)
> (f 1 2)
(1 2)
> (g 3)
(3 3 9)
> (g 3 4)
(3 4 12)
> (g 3 4 k: 5)
(3 4 5)
> (g 3 4 k: 5 k: 6)
(3 4 5)
> (h1 7)
(7 #f ())
> (h1 7 k: 8 9)
(7 8 (k: 8 9))
> (h1 7 k: 8 z: 9)
(7 8 (k: 8 z: 9))
> (h2 7)
(7 #f ())
> (h2 7 k: 8 9)
(7 8 (9))
> (h2 7 k: 8 z: 9)
*** ERROR IN (console)@17.1 -- Unknown keyword argument passed to procedure
(h2 7 k: 8 z: 9)
|
6.3 Miscellaneous extensions
This procedure is the vector analog of the substring
procedure. It returns a newly allocated vector formed from the
elements of the vector vector beginning with index start
(inclusive) and ending with index end (exclusive).
For example:
| > (subvector '#(a b c d e f) 3 5)
#(d e)
|
This procedure is like the procedure subvector
except the
parameter start defaults to 0 and the parameter end
defaults to the length of the vector vector. Note that the
elements are not recursively copied.
For example:
| > (define v1 '#(a b c d e f))
> (define v2 (vector-copy v1))
> v2
#(a b c d e f)
> (eq? v1 v2)
#f
> (vector-copy v1 3)
#(d e f)
> (vector-copy v1 3 5)
#(d e)
|
( vector-copy! dest-vector dest-start vector [start [end]]) | procedure |
This procedure mutates the vector dest-vector. It copies the
elements of the vector vector beginning with index start
(inclusive) and ending with index end (exclusive) to the vector
dest-vector at index dest-start. The parameters
start and end default respectively to 0 and the length of
the vector vector. It is an error to copy more elements than
will fit in the tail of the vector dest-vector starting at index
dest-start. Note that the elements are not recursively copied.
For example:
| > (define v1 (vector 10 11 12 13 14 15))
> (define v2 (vector 20 21 22 23))
> (vector-copy! v1 1 v2)
> v1
#(10 20 21 22 23 15)
> (vector-copy! v1 1 v2 3)
> v1
#(10 23 21 22 23 15)
> (vector-copy! v1 1 v2 1 3)
> v1
#(10 21 22 22 23 15)
|
This procedure is the vector analog of the string-append
procedure. It returns a newly allocated vector whose elements
form the concatenation of the given vectors.
For example:
| > (define v '#(1 2 3))
> (vector-append v v v)
#(1 2 3 1 2 3 1 2 3)
|
This procedure returns a newly allocated vector whose elements form
the concatenation of all the vectors in the list lst. If the
optional vector separator argument is specified, it will be
added between all the elements of lst. Without the
separator argument the result is the same as (apply
vector-append lst)
.
For example:
| > (define v '#(1 2 3))
> (vector-concatenate (list v v v))
#(1 2 3 1 2 3 1 2 3)
> (vector-concatenate (list v v v) '#(88 99))
#(1 2 3 88 99 1 2 3 88 99 1 2 3)
|
This procedure is like vector-fill!
, but fills a selected part
of the given vector. It sets the elements of the vector vector,
beginning with index start (inclusive) and ending with index
end (exclusive) to fill. The value returned is
unspecified.
For example:
| > (define v (vector 'a 'b 'c 'd 'e 'f))
> (subvector-fill! v 3 5 'x)
> v
#(a b c x x f)
|
( subvector-move! src-vector src-start src-end dst-vector dst-start) | procedure |
This procedure replaces part of the contents of vector
dst-vector with part of the contents of vector
src-vector. It copies elements from src-vector, beginning
with index src-start (inclusive) and ending with index
src-end (exclusive) to dst-vector beginning with index
dst-start (inclusive). The value returned is unspecified.
For example:
| > (define v1 '#(1 2 3 4 5 6))
> (define v2 (vector 'a 'b 'c 'd 'e 'f))
> (subvector-move! v1 3 5 v2 1)
> v2
#(a 4 5 d e f)
|
This procedure shortens the vector vector so that its new size
is k. The value returned is unspecified.
For example:
| > (define v (vector 'a 'b 'c 'd 'e 'f))
> v
#(a b c d e f)
> (vector-shrink! v 3)
> v
#(a b c)
|
The procedure vector-cas!
performs an atomic compare-and-swap
operation on the element of vector vector at index k. If
the element’s value is eq?
to old-value then the element
is changed to new-value, otherwise the value does not change.
Regardless what happened, the element’s value prior to any change is
returned. It is thus possible to detect a change by an explicit
eq?
test of the result.
For example:
| > (define v (vector 'a))
> (eq? 'foo (vector-cas! v 0 'b 'foo))
#f
> v
#(a)
> (eq? 'a (vector-cas! v 0 'b 'a))
#t
> v
#(b)
|
The procedure vector-inc!
performs an atomic incrementation
on the element of vector vector at index k, which must be a
fixnum. The parameter step defaults to 1 and it is the fixnum value
that is added (with wraparound) to the element. The procedure returns
the value of the element prior to the incrementation.
For example:
| > (define v (vector 100))
> (vector-inc! v 0)
100
> (vector-inc! v 0)
101
> (vector-inc! v 0 5)
102
> v
#(107)
|
The procedure vector-set
returns a new copy of the vector
vector with the element at index k replaced with
obj.
For example:
| > (define v1 (vector 10 11 12 13))
> (define v2 (vector-set v1 2 99))
> v2
#(10 11 99 13)
> (eq? v1 v2)
#f
|
The procedure string-set
returns a new copy of the string
string with the character at index k replaced with
char.
For example:
| > (define s1 (string #\a #\b #\c #\d))
> (define s2 (string-set s1 2 #\.))
> s2
"ab.d"
> (eq? s1 s2)
#f
|
The procedures string-prefix-length
and
string-prefix-length-ci
return an exact nonnegative integer
indicating the length of the longest substring of the strings s1
and s2 at the start of those strings that are string=?
(for string-prefix-length
) or string-ci=?
(for
string-prefix-length-ci
). The optional exact nonnegative
integer parameters start1, end1, start2, and
end2 delimit the sections of the strings s1 and s2
that are considered. The parameters start1 and start2
default to 0, and the parameters end1 and end2 default to
the length of the strings s1 and s2 respectively.
For example:
| > (string-prefix-length "abracadabra" "abrac123")
5
> (string-prefix-length "abracadabra" "abrac123" 7)
4
> (string-prefix-length "abracadabra" "AbRaC123")
0
> (string-prefix-length-ci "abracadabra" "AbRaC123")
5
|
The procedures string-suffix-length
and
string-suffix-length-ci
return an exact nonnegative integer
indicating the length of the longest substring of the strings s1
and s2 at the end of those strings that are string=?
(for
string-suffix-length
) or string-ci=?
(for
string-suffix-length-ci
). The optional exact nonnegative
integer parameters start1, end1, start2, and
end2 delimit the sections of the strings s1 and s2
that are considered. The parameters start1 and start2
default to 0, and the parameters end1 and end2 default to
the length of the strings s1 and s2 respectively.
For example:
| > (string-suffix-length "abracadabra" "123dabra")
5
> (string-suffix-length "abracadabra" "123dAbRa" 1 4)
1
> (string-suffix-length-ci "abracadabra" "123dAbRa" 1 4)
3
|
The procedures string-prefix?
and string-prefix-ci?
return a boolean indicating whether the string s1 is a substring
at the start of string s2 when compared with string=?
(for string-prefix?
) or string-ci=?
(for
string-prefix-ci?
). The optional exact nonnegative integer
parameters start1, end1, start2, and end2
delimit the sections of the strings s1 and s2 that are
considered. The parameters start1 and start2 default to
0, and the parameters end1 and end2 default to the length
of the strings s1 and s2 respectively.
For example:
| > (string-prefix? "ab" "abracadabra")
#t
> (string-prefix? "ab" "Abracadabra")
#f
> (string-prefix? "ab" "Abracadabra" 0 2 7)
#t
> (string-prefix-ci? "ab" "ABracadabra")
#t
|
The procedures string-suffix?
and string-suffix-ci?
return a boolean indicating whether the string s1 is a substring
at the end of string s2 when compared with string=?
(for string-suffix?
) or string-ci=?
(for
string-suffix-ci?
). The optional exact nonnegative integer
parameters start1, end1, start2, and end2
delimit the sections of the strings s1 and s2 that are
considered. The parameters start1 and start2 default to
0, and the parameters end1 and end2 default to the length
of the strings s1 and s2 respectively.
For example:
| > (string-suffix? "ra" "abracadabra")
#t
> (string-suffix? "ra" "abracadabrA")
#f
> (string-suffix? "ra" "abracadabrA" 0 2 0 4)
#t
> (string-suffix-ci? "ra" "abracadabrA")
#t
|
The procedures string-contains
and string-contains-ci
look for the first substring of the string s1 (in a left to
right traversal) that is equal to the string s1 according to
string=?
(for string-contains
) or string-ci=?
(for string-contains-ci
). The result is #f
when the
string s2 is not found in s1, otherwise the result is an
exact nonnegative integer indicating the index in s1 where the
first occurrence of s2 is found. The optional exact nonnegative
integer parameters start1, end1, start2, and
end2 delimit the sections of the strings s1 and s2
that are considered. The parameters start1 and start2
default to 0, and the parameters end1 and end2 default to
the length of the strings s1 and s2 respectively.
For example:
| > (string-contains "abracadabra" "ra")
2
> (string-contains "abracadabra" "ra" 3)
9
> (string-contains "abracadabra" "Ra")
#f
> (string-contains-ci "abracadabra" "Ra")
2
|
This procedure returns a newly allocated string which is the
concatenation of all the strings in the list lst. If the
optional string separator argument is specified, it will be
added between all the elements of lst. Without the
separator argument the result is the same as (apply
string-append lst)
.
For example:
| > (define s "abc")
> (string-concatenate (list s s s))
"abcabcabc"
> (string-concatenate (list s s s) ",")
"abc,abc,abc"
|
This procedure is like string-fill!
, but fills a selected part
of the given string. It sets the elements of the string string,
beginning with index start (inclusive) and ending with index
end (exclusive) to fill. The value returned is
unspecified.
For example:
| > (define s (string #\a #\b #\c #\d #\e #\f))
> (substring-fill! s 3 5 #\x)
> s
"abcxxf"
|
( substring-move! src-string src-start src-end dst-string dst-start) | procedure |
This procedure replaces part of the contents of string
dst-string with part of the contents of string
src-string. It copies elements from src-string, beginning
with index src-start (inclusive) and ending with index
src-end (exclusive) to dst-string beginning with index
dst-start (inclusive). The value returned is unspecified.
For example:
| > (define s1 "123456")
> (define s2 (string #\a #\b #\c #\d #\e #\f))
> (substring-move! s1 3 5 s2 1)
> s2
"a45def"
|
This procedure shortens the string string so that its new size
is k. The value returned is unspecified.
For example:
| > (define s (string #\a #\b #\c #\d #\e #\f))
> s
"abcdef"
> (string-shrink! s 3)
> s
"abc"
|
These procedures implement the box data type. A box is a
cell containing a single mutable field. The lexical syntax
of a box containing the object obj is #&obj
(see section Box syntax).
The procedure box
returns a new box object whose content is
initialized to obj. The procedure box?
returns #t
if obj is a box, and otherwise returns #f
. The procedure
unbox
returns the content of the box box. The procedure
set-box!
changes the content of the box box to obj.
The procedure set-box!
returns an unspecified value.
For example:
| > (define b (box 0))
> b
#&0
> (define (inc!) (set-box! b (+ (unbox b) 1)))
> (inc!)
> b
#&1
> (unbox b)
1
|
These procedures implement the keyword data type. Keywords are
similar to symbols but are self evaluating and distinct from the
symbol data type. The lexical syntax of keywords is specified in
Keyword syntax.
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.
The procedure string->keyword
returns the keyword whose name is
string.
For example:
| > (keyword? 'color)
#f
> (keyword? color:)
#t
> (keyword->string color:)
"color"
> (string->keyword "color")
color:
|
This procedure 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
|
The procedure string->uninterned-symbol
returns a new uninterned
symbol whose name is name and hash is hash. The name must
be a string and the hash must be a nonnegative fixnum.
The procedure uninterned-symbol?
returns #t
when
obj is a symbol that is uninterned and #f
otherwise.
For example:
| > (uninterned-symbol? (gensym))
#t
> (string->uninterned-symbol "foo")
#:foo:
> (uninterned-symbol? (string->uninterned-symbol "foo"))
#t
> (uninterned-symbol? 'hello)
#f
> (uninterned-symbol? 123)
#f
|
The procedure string->uninterned-keyword
returns a new uninterned
keyword whose name is name and hash is hash. The name must
be a string and the hash must be a nonnegative fixnum.
The procedure uninterned-keyword?
returns #t
when
obj is a keyword that is uninterned and #f
otherwise.
For example:
| > (string->uninterned-keyword "foo")
#:foo:
> (uninterned-keyword? (string->uninterned-keyword "foo"))
#t
> (uninterned-keyword? hello:)
#f
> (uninterned-keyword? 123)
#f
|
This procedure returns obj.
This procedure returns the void object. The read-eval-print loop
prints nothing when the result is the void object.
( eval expr [env]) | procedure |
The first parameter is a datum representing an expression. The
eval
procedure evaluates this expression in the global
interaction environment and returns the result. If present, the
second parameter 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
|
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 either
directly using the include
special form or indirectly with the
import
special form. Macros which are visible from the REPL
are also visible during the compilation of Scheme source files.
For example:
| (define-macro (unless test . body)
`(if ,test #f (begin ,@body)))
(define-macro (push var #!optional val)
`(set! ,var (cons ,val ,var)))
|
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 var #!optional val)
`(set! ,var (cons ,val ,var)))
> (pp (lambda () (push stack 1) (push stack) (push stack 3)))
(lambda ()
(set! stack (cons 1 stack))
(set! stack (cons #f stack))
(set! stack (cons 3 stack)))
|
Define name as a macro special form whose expansion is specified
by expander. This form is available only when the runtime option
‘-:s’ is used. This option causes the loading of the
~~lib/syntax-case
support library, which is the Hieb and Dybvig
portable syntax-case
implementation which has been ported to
the Gambit interpreter and compiler. Note that this implementation of
syntax-case
does not support special forms that are specific to
Gambit.
For example:
| $ gsi -:s
Gambit v4.9.5
> (define-syntax unless
(syntax-rules ()
((unless test body ...)
(if test #f (begin body ...)))))
> (let ((test 111)) (unless (= 1 2) (list test test)))
(111 111)
> (pp (lambda () (let ((test 111)) (unless (= 1 2) (list test test)))))
(lambda () ((lambda (%%test14) (if (= 1 2) #f (list %%test14 %%test14))) 111))
> (unless #f (pp xxx))
*** ERROR IN (console)@7.16 -- Unbound variable: xxx
|
This procedure can only be executed during the phase of the Scheme
code’s processing (compilation) that corresponds to macro
expansion. Calls to this procedure are typically contained in macro
definitions but they can also be contained in procedures that are
called from a macro definition’s body directly or indirectly.
The result returned by the compilation-target
procedure
gives an indication of the target language of the compilation.
This can be used to write macros that depend on the type of compilation
and the target language.
When the result is the symbol T
the macro expansion is in the
context of compiling to the target language T
, e.g. C
,
js
, etc. When the result is a single element list (T)
the macro expansion is for the interpreter which itself was compiled
for the target language T
, e.g. (C)
, (js)
, etc.
For example:
| $ cat ct.scm
(define (level-0)
(string-append "0: " (object->string (compilation-target))))
(define-macro (test)
(define (level-1)
(string-append "1: " (object->string (compilation-target))))
(define-macro (level-2)
(string-append "2: " (object->string (compilation-target))))
`(list ,(level-1) ,(level-2)))
(pp (test))
(pp (level-0)) ;; run time exception
$ gsi ct.scm
("1: (C)" "2: (C)")
*** ERROR IN level-0, "ct.scm"@2.40 -- Not in compilation context
(compilation-target)
$ gsc -target js -exe ct.scm
$ ./ct
("1: js" "2: (C)")
*** ERROR IN level-0 -- Not in compilation context
(compilation-target)
|
Regardless of whether ‘ct.scm’ is being processed by the
interpreter or the compiler, the body of the level-0
procedure
is not in a compilation context and in the body of the level-2
macro the compilation target is (C)
indicating that the macro
expansion is being done for interpretation.
During the execution of the level-1
procedure, the
compilation target will correspond to what is processing
‘ct.scm’ (interpreter or compiler).
Note that the compilation target can also be tested by the
cond-expand
special form.
The cond-expand
expression type provides a way to statically
expand different expressions depending on the presence or absence of
a set of features. A ce-clause takes the following form:
| (feature-requirement expression …)
|
The last clause can be an “else clause,” which has the form
A feature-requirement takes one of the following forms:
-
feature-identifier
-
(library library-name)
-
(and feature-requirement …)
-
(or feature-requirement …)
-
(not feature-requirement)
-
(compilation-target target …)
The runtime system maintains a list of feature identifiers which are
present, as well as a list of libraries which can be imported. The
value of a feature-requirement is determined by replacing each
feature-identifier
and (library library-name)
on
the runtime system’s lists with #t
. Similarly, #t
replaces each (compilation-target target …)
for
which one of the target matches the expansion time value of
(compilation-target)
, with a target
of (_)
matching any single element list (i.e. the interpreter). All other
feature-identifier
, (library library-name)
, and
(compilation-target target …)
are replaced with
#f
. The resulting expression is then evaluated as a Scheme
boolean expression under the normal interpretation of and
,
or
, and not
.
A cond-expand
is then expanded by evaluating the
feature-requirements of successive ce-clauses in order
until one of them returns #t
. When a true clause is found, the
corresponding expressions are expanded to a begin
, and
the remaining clauses are ignored. If none of the
feature-requirements evaluate to #t
, then if there is an
else clause, its expressions are included. Otherwise, an
expansion time error is raised. Unlike cond
, cond-expand
does not depend on the value of any variables.
The feature identifier gambit
is always true when the
cond-expand
is expanded by the Gambit interpreter
or compiler.
For example:
| > (cond-expand (foobar 111) (gambit 222) (else 333))
222
> (cond-expand ((compilation-target js) 111) (else 222))
222
> (cond-expand ((compilation-target (_)) 111) (else 222))
111
|
The define-cond-expand-feature
form can be used to add the
feature identifiers feature-identifier … to the list of
features maintained by the runtime system. These features are usable
for the expansion of following cond-expand
forms in the same
file of source code, and the processing of other files and REPL
interactions.
For example:
| > (cond-expand (foobar 111) (gambit 222) (else 333))
222
> (define-cond-expand-feature foobar)
> (cond-expand (foobar 111) (gambit 222) (else 333))
111
|
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)
-
Use the given dialect’s semantics. dialect can be:
‘ieee-scheme’, ‘r4rs-scheme’, ‘r5rs-scheme’
or ‘gambit-scheme’.
-
(strategy)
-
Select block compilation or separate compilation. In block
compilation, the compiler assumes that global variables defined in the
current file that are not mutated in the file will never be mutated.
strategy can be: ‘block’ or ‘separate’.
-
([not] inline)
-
Allow (or disallow) inlining of user procedures.
-
([not] inline-primitives primitive…)
-
The given primitives should (or should not) be inlined
if possible (all primitives if none specified).
-
(inlining-limit n)
-
Select the degree to which the compiler inlines user procedures.
n is the upper-bound, in percent, on code expansion that will
result from inlining. Thus, a value of 300 indicates that the size of
the program will not grow by more than 300 percent (i.e. it will be at
most 4 times the size of the original). A value of 0 disables inlining.
The size of a program is the total number of subexpressions it contains
(i.e. the size of an expression is one plus the size of its immediate
subexpressions). The following conditions must hold for a procedure to
be inlined: inlining the procedure must not cause the size of the call
site to grow more than specified by the inlining limit, the site of
definition (the 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=370).
-
(allocation-limit n)
-
Indicate the maximum size of objects allocated with
make-vector
, make-string
, make-u8vector
, etc.
Knowing the maximum size allows the compiler to inline calls to these
allocators for small allocations. This is only supported by the C
target and only up to a size that is allowed for movable
objects (typically on the order of 1-2 KB). When n is an exact
nonnegative integer it is the upper-bound on the number of elements of
the allocated objects. When n is #t
a dynamic test of
the size is done. When n is #f
the allocation operation
is not inlined.
-
([not] lambda-lift)
-
Lambda-lift (or don’t lambda-lift) locally defined procedures.
-
([not] constant-fold)
-
Allow (or disallow) constant-folding of primitive procedures.
-
([not] standard-bindings var…)
-
The given global variables are known (or not known) to be equal to
the value defined for them in the dialect (all variables defined in
the standard if none specified).
-
([not] extended-bindings var…)
-
The given global variables are known (or not known) to be equal to the
value defined for them in the runtime system (all variables defined
in the runtime if none specified).
-
([not] run-time-bindings var…)
-
The given global variables will be tested at run time to see if they
are equal to the value defined for them in the runtime system (all
variables defined in the runtime if none specified).
-
([not] safe)
-
Generate (or don’t generate) code that will prevent fatal errors at
run time. Note that in ‘safe’ mode certain semantic errors will
not be checked as long as they can’t crash the system. For example
the primitive char=?
may disregard the type of its arguments in
‘safe’ as well as ‘not safe’ mode.
-
([not] interrupts-enabled)
-
Generate (or don’t generate) interrupt checks. Interrupt checks are
used to detect user interrupts and also to check for stack overflows.
Interrupt checking should not be turned off casually.
-
([not] poll-on-return)
-
Generate (or don’t generate) interrupt checks on procedure returns
(when interrupt checking is enabled). This declaration has no effect
on the behavior of interrupt checking on procedure calls, which is
needed to guarantee that stack overflows are handled properly.
-
([not] debug)
-
Enable (or disable) the generation of debugging information. The kind
of debugging information that is generated depends on the declarations
‘debug-location’, ‘debug-source’, and
‘debug-environments’. If any of the command line options
‘-debug’, ‘-debug-location’, ‘-debug-source’ and
‘-debug-environments’ are present, the ‘debug’ declaration
is initially enabled, otherwise it is initially disabled. When all
kinds of debugging information are generated there is a substantial
increase in the C compilation time and the size of the generated code.
When compiling a 3000 line Scheme file it was observed that the total
compilation time is 500% longer and the executable code is 150%
bigger.
-
([not] debug-location)
-
Select (or deselect) source code location debugging information. When
this declaration and the ‘debug’ declaration are in effect, run
time error messages indicate the location of the error in the source
code file. If any of the command line options ‘-debug-source’
and ‘-debug-environments’ are present and ‘-debug-location’
is absent, the ‘debug-location’ declaration is initially
disabled, otherwise it is initially enabled. When compiling a 3000
line Scheme file it was observed that the total compilation time is
200% longer and the executable code is 60% bigger.
-
([not] debug-source)
-
Select (or deselect) source code debugging information. When this
declaration and the ‘debug’ declaration are in effect, run time
error messages indicate the source code, the backtraces are more
precise, and the pp
procedure will display the source code of
compiled procedures. If any of the command line options
‘-debug-location’ and ‘-debug-environments’ are present and
‘-debug-source’ is absent, the ‘debug-source’ declaration is
initially disabled, otherwise it is initially enabled. When compiling
a 3000 line Scheme file it was observed that the total compilation
time is 90% longer and the executable code is 90% bigger.
-
([not] debug-environments)
-
Select (or deselect) environment debugging information. When this
declaration and the ‘debug’ declaration are in effect, the
debugger will have access to the environments of the continuations.
In other words the local variables defined in compiled procedures (and
not optimized away by the compiler) will be shown by the ‘,e’
REPL command. If any of the command line options
‘-debug-location’ and ‘-debug-source’ are present and
‘-debug-environments’ is absent, the ‘debug-environments’
declaration is initially disabled, otherwise it is initially enabled.
When compiling a 3000 line Scheme file it was observed that the total
compilation time is 70% longer and the executable code is 40% bigger.
-
([not] proper-tail-calls)
-
Generate (or don’t generate) proper tail calls. When proper tail
calls are turned off, tail calls are handled like non-tail calls, that
is a continuation frame will be created for all calls regardless of
their kind. This is useful for debugging because the caller of a
procedure will be visible in the backtrace produced by the REPL’s
‘,b’ command even when the call is a tail call. Be advised that
this does cause stack space to be consumed for tail calls which may
cause the stack to overflow when performing long iterations with tail
calls (whether they are expressed with a letrec
, named
let
, do
, or other form).
-
([not] generative-lambda)
-
Force (or don’t force) the creation of fresh closures when evaluating
lambda-expressions. A fresh closure is always created when a
lambda-expression has at least one free variable (that has not been
eliminated by dead-code elimination or other compiler optimization) or
when the generative-lambda declaration is turned on. When a
lambda-expression has no free variables and the generative-lambda
declaration is turned off, the value of the lambda-expression may be
the same procedure (in the sense of eq?
).
-
([not] optimize-dead-local-variables)
-
Remove (or preserve) the dead local variables in the environment.
Preserving the dead local variables is useful for debugging because
continuations will contain the dead variables. Thus, if the code is
also compiled with the declaration ‘debug-environments’
the ‘,e’, ‘,ed’, ‘,be’, and ‘,bed’ REPL
commands will display the dead variables. On the other hand,
preserving the dead local variables may change the space complexity of
the program (i.e. some of the data that would normally be reclaimed by
the garbage collector will not be). Note that due to other compiler
optimizations some dead local variables may be removed regardless of
this declaration.
-
([not] optimize-dead-definitions var…)
-
Remove (or preserve) the dead toplevel definitions of the given global
variables (all global variables if none specified). A toplevel
definition is dead if it is not referenced by toplevel expressions
of the program or toplevel definitions that aren’t dead (regardless
of the evaluation of its expression causing a side-effect). When a
module is separately compiled and some of its definitions are only
used by other modules, this declaration must be used with care to keep
definitions that are used by other modules, for example if foo
is referenced in another module the following declaration should be
used: ‘(declare (not optimize-dead-definitions foo))’.
-
(number-type primitive…)
-
Numeric arguments and result of the specified primitives are
known to be of the given type (all primitives if none specified).
number-type can be: ‘generic’, ‘fixnum’, or
‘flonum’.
-
(mostly-number-type primitive…)
-
Numeric arguments and result of the specified primitives are expected
to be most often of the given type (all primitives if none specified).
mostly-number-type can be: ‘mostly-generic’,
‘mostly-fixnum’, ‘mostly-fixnum-flonum’,
‘mostly-flonum’, or ‘mostly-flonum-fixnum’.
The default declarations used by the compiler are equivalent to:
| (declare
(gambit-scheme)
(separate)
(inline)
(inline-primitives)
(inlining-limit 370)
(allocation-limit #t)
(constant-fold)
(lambda-lift)
(not standard-bindings)
(not extended-bindings)
(run-time-bindings)
(safe)
(interrupts-enabled)
(not poll-on-return)
(not debug) ;; depends on debugging command line options
(debug-location) ;; depends on debugging command line options
(debug-source) ;; depends on debugging command line options
(debug-environments) ;; depends on debugging command line options
(proper-tail-calls)
(not generative-lambda)
(optimize-dead-local-variables)
(not optimize-dead-definitions)
(generic)
(mostly-fixnum-flonum)
)
|
These declarations are compatible with the semantics of R5RS Scheme
and includes a few procedures from R6RS (mainly fixnum specific and
flonum specific procedures). Typically used declarations that enhance
performance, at the cost of violating the R5RS Scheme semantics, are:
(standard-bindings)
, (block)
, (not safe)
and
(fixnum)
.
These procedures provide access to internal first-class continuations
which are represented using continuation objects distinct from procedures.
The procedure continuation?
returns #t
when obj is
a continuation object and #f
otherwise.
The procedure continuation-capture
is similar to the
call/cc
procedure but it represents the continuation with a
continuation object. The proc parameter must be a procedure
accepting a single argument. The procedure
continuation-capture
reifies its continuation and calls
proc with the corresponding continuation object as its sole
argument. Like for call/cc
, the implicit continuation of the
call to proc is the implicit continuation of the call to
continuation-capture
.
The procedure continuation-graft
performs a procedure call to
the procedure proc with arguments obj… and the
implicit continuation corresponding to the continuation object
cont. The current continuation of the call to procedure
continuation-graft
is ignored.
The procedure continuation-return
invokes the implicit
continuation corresponding to the continuation object cont with
the result(s) obj…. This procedure can be easily
defined in terms of continuation-graft
:
| (define (continuation-return cont . objs)
(continuation-graft cont apply values objs))
|
For example:
| > (define x #f)
> (define p (make-parameter 11))
> (pp (parameterize ((p 22))
(cons 33 (continuation-capture
(lambda (c) (set! x c) 44)))))
(33 . 44)
> x
#<continuation #2>
> (continuation-return x 55)
(33 . 55)
> (continuation-graft x (lambda () (expt 2 10)))
(33 . 1024)
> (continuation-graft x expt 2 10)
(33 . 1024)
> (continuation-graft x (lambda () (p)))
(33 . 22)
> (define (map-sqrt1 lst)
(call/cc
(lambda (k)
(map (lambda (x)
(if (< x 0)
(k 'error)
(sqrt x)))
lst))))
> (map-sqrt1 '(1 4 9))
(1 2 3)
> (map-sqrt1 '(1 -1 9))
error
> (define (map-sqrt2 lst)
(continuation-capture
(lambda (c)
(map (lambda (x)
(if (< x 0)
(continuation-return c 'error)
(sqrt x)))
lst))))
> (map-sqrt2 '(1 4 9))
(1 2 3)
> (map-sqrt2 '(1 -1 9))
error
|
The procedure display-continuation-backtrace
displays the
frames of the continuation corresponding to the continuation object
cont on the port port. If it is not specified, port
defaults to the current output-port. The frames are displayed in the
same format as the REPL’s ‘,b’ command.
The parameter display-env?, which defaults to #f
, controls
if the frames are displayed with its environment (the variables
accessible and their bindings).
The parameter all-frames?, which defaults to #f
, controls
which frames are displayed. Some frames of ancillary importance, such
as internal frames created by the interpreter, are not displayed when
all-frames? is #f
. Otherwise all frames are displayed.
The parameters max-head and max-tail, which default to 10
and 4 respectively, control how many frames are displayed at the head
and tail of the continuation.
The parameter depth, which defaults to 0, causes the frame numbers
to be offset by that value.
For example:
| > (define x #f)
> (define (fib n)
(if (< n 2)
(continuation-capture
(lambda (c) (set! x c) 1))
(+ (fib (- n 1))
(fib (- n 2)))))
> (fib 10)
89
> (display-continuation-backtrace x)
0 fib (console)@7:12 (fib (- n 2))
1 fib (console)@7:12 (fib (- n 2))
2 fib (console)@7:12 (fib (- n 2))
3 fib (console)@7:12 (fib (- n 2))
4 fib (console)@7:12 (fib (- n 2))
5 (interaction) (console)@8:1 (fib 10)
#f
> (display-continuation-backtrace x (current-output-port) #f #t)
0 fib (console)@7:12 (fib (- n 2))
1 fib (console)@6:9 (+ (fib (- n 1)) (fib (- ...
2 fib (console)@7:12 (fib (- n 2))
3 fib (console)@6:9 (+ (fib (- n 1)) (fib (- ...
4 fib (console)@7:12 (fib (- n 2))
5 fib (console)@6:9 (+ (fib (- n 1)) (fib (- ...
6 fib (console)@7:12 (fib (- n 2))
7 fib (console)@6:9 (+ (fib (- n 1)) (fib (- ...
8 fib (console)@7:12 (fib (- n 2))
9 fib (console)@6:9 (+ (fib (- n 1)) (fib (- ...
...
13 ##with-no-result-expected-toplevel
14 ##repl-debug
15 ##repl-debug-main
16 ##kernel-handlers
#f
> (display-continuation-backtrace x (current-output-port) #t #f)
0 fib (console)@7:12 (fib (- n 2))
n = 2
1 fib (console)@7:12 (fib (- n 2))
n = 4
2 fib (console)@7:12 (fib (- n 2))
n = 6
3 fib (console)@7:12 (fib (- n 2))
n = 8
4 fib (console)@7:12 (fib (- n 2))
n = 10
5 (interaction) (console)@8:1 (fib 10)
#f
> (display-continuation-backtrace x (current-output-port) #f #f 2 1 100)
100 fib (console)@7:12 (fib (- n 2))
101 fib (console)@7:12 (fib (- n 2))
...
105 (interaction) (console)@8:1 (fib 10)
#f
|
6.4 Undocumented extensions
The procedures in this section are not yet documented.
( top [timeout [thread-group [port]]]) | procedure |
( remq elem list) | procedure |
( list= elt= list …) | procedure |
( fold proc base list …) | procedure |
( iota count [start [step]]) | procedure |
( six.for stat1 expr2 expr3 stat2) | special form |
( six.if expr stat1 [stat2]) | special form |
( six.x @=y x y) | special form |
( six.x @y x y) | special form |
7. Modules
Gambit supports multiple modularization approaches and constructs:
legacy modules, primitive modules and R7RS compatible modules.
These are described in that order, which corresponds to increased
abstraction level. Unless there is a need for detailed control over
the modules, it is best to use the R7RS compatible module system for
the development of new code.
7.1 Legacy Modules
The legacy way of modularizing code, which was popular up to
R5RS, is still supported by Gambit. It consists of using the
load
procedure and the include
form. We discuss it
first to introduce some useful terms and explain the shortcomings
of this modularization approach.
The load
procedure’s path argument, a string, specifies
the location in the file system of a file to load. Loading a file
executes the code contained in the file, which is either source code
or compiled code (a dynamically loadable object file created by
the Gambit Scheme compiler, see the procedure compile-file
).
When path 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 will search for both a source file and
an object file. The object file’s path is obtained by adding to
path a ‘.on’ extension with the highest consecutive
version number starting with 1. The source file’s path is obtained by
adding to path the file extensions ‘.sld’, ‘.scm’ and
‘.six’ (the first found is the source file). If both a source
file and an object file exist, then the one with the latest
modification time is loaded. Otherwise the file that is found is
loaded. When path has an extension, the load
procedure
will only attempt to load the file with that specific extension.
After executing the code contained in the file, the load
procedure returns the path of the file that was loaded.
When a source code file is loaded its extension is used to determine
how it is parsed, unless the file’s first line is a special script
line (see Scheme scripts). When the extension is different from
‘.six’ the content of the file is parsed using the normal Scheme
prefix syntax. When the extension is ‘.six’ the content of the
file is parsed using the Scheme infix syntax extension (see
Scheme infix syntax extension).
Due to operating system limitations, loading a given ‘.on’
object file more than once in the same process is not supported. It
is possible however to recompile the source code file to create a new
‘.om’ object file with m > n and load that
object file.
For example:
| $ cat my-mod.scm
(define (double x) (* x 2))
(display "my-mod has finished loading!!!\n")
$ gsi
Gambit v4.9.5
> (load "my-mod")
my-mod has finished loading!!!
"/Users/feeley/gambit/doc/my-mod.scm"
> (double 21)
42
> (load "my-mod.scm")
my-mod has finished loading!!!
"/Users/feeley/gambit/doc/my-mod.scm"
> ,q
$ gsc my-mod
$ gsi
Gambit v4.9.5
> (load "my-mod")
my-mod has finished loading!!!
"/Users/feeley/gambit/doc/my-mod.o1"
> (double 21)
42
> (load "my-mod")
*** ERROR IN (console)@3.1 -- Can't load a given object file more than once
(load "my-mod")
1>
|
Note that any macro definition in the loaded file is local to the file
and is not visible from the REPL or other files that loaded this file.
The include
form can be used to access the macros defined in
another file.
The path argument must be a string specifying the location of an
existing file containing Scheme source code. Relative paths are
relative to the file that contains the include
form. The
include
special form splices the content of the specified
source file. This form can only appear where a define
form is
acceptable, i.e. at top level or in the body of a binding form.
For example:
| $ cat my-defs.scm
(define-macro (double x) `(* ,x 2))
(define (quad y) (double (double y)))
(display "howdy!\n")
$ cat my-includer.scm
(define (f x)
(include "my-defs.scm")
(+ 1 (quad x)))
$ gsi
Gambit v4.9.5
> (load "my-includer")
"/Users/feeley/udem-dlteam/gambit/my-includer.scm"
> (f 10)
howdy!
41
> (f 20)
howdy!
81
|
With legacy modularization, the code that implements the
module’s functionality is put in a source code file and this module is
accessed by other code by using a load
or include
of
that file. Here is an example of an angle0
module that is used
by an app0
main program:
| ;;;---------------------------------------- file: angle0/angle0.scm
(define factor (/ (atan 1) 45))
(define (deg->rad x) (* x factor))
(define (rad->deg x) (/ x factor))
;;;---------------------------------------- file: app0.scm
(load "angle0/angle0.scm") ;; or (include "angle0/angle0.scm")
(println "90 degrees is " (deg->rad 90) " radians")
;; run with: gsi app0.scm
|
This modularization approach has a number of issues:
-
It hinders code sharing among different programs and users because a
shared module’s location in the filesystem must be known to all
modules loading or including it. In the above example the path
"angle0/angle0.scm"
is relative so the load
procedure
will resolve the path incorrectly if the program executes
(current-directory "...")
before calling load
.
-
When a module is needed by more than one other module there will be
code duplication, redundant evaluation/compilation, and probably
incorrect execution if the module has side effects that should only
happen once (displaying a message, opening a database on the
filesystem, initializing the module’s state, etc). Moreover, when the
module has been compiled to an object file it can’t be loaded more
than once.
-
All the definitions of a module will be put in the global environment
(including top level macro definitions when using a top level
include
but not when using load
). This pollutes the
global environment with definitions that were not intended to be
exported by the module’s designer, such as the variable factor
in the above example that is only meant to be used by the
deg->rad
and rad->deg
procedures. Other modules may
also need a factor
variable internally, for instance to convert
distances from the metric to the english system. Nothing prevents such
accidental clashes.
7.2 Primitive Modules
7.2.1 ##demand-module
and ##supply-module
forms
The ##demand-module
form offers a way to avoid the issues of
multiple loading and filesystem localization of modules. The sole
parameter of this form is an (unevaluated) symbol that identifies the
module on which the module containing the ##demand-module
depends. When a module A
contains a (##demand-module
B)
, Gambit’s runtime system will ensure that module B
is
loaded before module A
is loaded. It also registers the module
in a cache when it is loaded so that it is loaded exactly once. In
other words the ##demand-module
form expresses the requirement
that the current module needs the functionality of another module. A
module can contain multiple uses of ##demand-module
and
possibly more than once for a given module. The
##demand-module
form can appear anywhere a define
can
appear. There is also a related ##supply-module
form that should
appear in the module to declare the module’s identity.
Gambit’s runtime system searches for modules in various directories,
by default in ~~lib
then in ~~userlib
(which maps to
~/.gambit_userlib
by default). These two directories are where
builtin modules and user installed modules are located respectively.
The source code for a module M
is searched, in each of the
module search order directories, first in M/M.ext
and
then in M.ext
, where .ext is one of the
acceptable Scheme source code file extensions (.sld
,
.scm
, .six
, etc). The list of module search order
directories can be extended with the -:search=
DIR runtime
option or by a command line argument to gsi
and gsc
that
ends with a path separator or a ‘.’.
With ##demand-module
and ##supply-module
the previous
example can be rewritten like this:
| ;;;---------------------------------------- file: angle1/angle1.scm
(##supply-module angle1) ;; declare that this is the module angle1
(define factor (/ (atan 1) 45))
(define (deg->rad x) (* x factor))
(define (rad->deg x) (/ x factor))
;;;---------------------------------------- file: app1.scm
(##demand-module angle1) ;; declare dependency on module angle1
(println "90 degrees is " (deg->rad 90) " radians")
;; run with either: gsi . app1.scm
;; or: gsi -:search=. app1.scm
;;
;; or install the angle1 module to avoid the . and -:search=.
|
7.2.2 ##namespace
and ##import
forms
( import module-ref) | special form |
The ##namespace
form offers a way to avoid name clashes by
specifying a mapping between identifiers. The mapping it specifies
has the same scope as a macro definition: it applies to the rest of a
source code file if it is at top level, or applies to the rest of the
body of a binding form if it is used in the body of a binding form.
The call (##namespace ("foo#" a b))
specifies that a reference
to a
becomes foo#a
and a reference to b
becomes
foo#b
. Here foo#
is the namespace. Finer control over
the mapping is possible by using aliases as in (##namespace
("foo#" (a bar) b))
which maps a
to foo#bar
and
b
to foo#b
. Multiple namespace specifications can
appear in the body of the ##namespace
form. When no
identifiers are specified, the mapping maps all identifiers not
containing #
to the namespace. For example in the scope of
(##namespace ("foo#"))
the reference x
maps to
foo#x
and the reference bar#x
remains unchanged.
Given that modules are identified by a unique symbol, the global names
defined by a module M
can be put in the namespace M#
to
avoid name clashes with other modules. The source code of module
M
and the modules depending on M
can explicitly prefix
the global names defined by M
with M#
or use a
##namespace
form to make this prefixing implicit. By
convention the namespace definition for the identifiers exported by
module M
is specified in the source code file M#.scm
in
the same directory as the M.scm
file.
Using this convention and the include
and ##namespace
forms, the previous example can be rewritten like this:
| ;;;---------------------------------------- file: angle2/angle2#.scm
(##namespace ("angle2#" deg->rad rad->deg))
;;;---------------------------------------- file: angle2/angle2.scm
(include "angle2#.scm")
(##namespace ("angle2#" factor))
(##supply-module angle2)
(define factor (/ (atan 1) 45))
(define (deg->rad x) (* x factor))
(define (rad->deg x) (/ x factor))
;;;---------------------------------------- file: app2.scm
(include "angle2/angle2#.scm")
(##demand-module angle2)
(println "90 degrees is " (deg->rad 90) " radians")
|
Note that the parameters of the two include
forms are
different, but this is correct because the paths are relative to the
file containing the include
form. However the module
localization problem has been reintroduced for the file
angle2/angle2#.scm
.
This problem can be solved using the ##import
form that
combines the semantics of the include
and
##demand-module
forms. The call (##import M)
will use
the module search order directories to locate the source code file of
module M
and will expand to an include
of the “hash”
file M#.ext
if it exists in the same directory, and a
(##demand-module M)
.
In addition, a builtin module gambit
exists that contains all
the global names exported by the runtime library. The gambit
module’s “hash” file gambit#.scm
contains a
##namespace
form that lists all the names exported by the
runtime library in an empty namespace:
| ;;;---------------------------------------- file: ~~lib/gambit#.scm
(##namespace ("" define if quote set! cons car cdr + - * / ;; etc
|
Using the gambit
module and the ##import
form, the
previous example can be rewritten like this:
| ;;;---------------------------------------- file: angle3/angle3#.scm
(##namespace ("angle3#" deg->rad rad->deg))
;;;---------------------------------------- file: angle3/angle3.scm
(##namespace ("angle3#")) ;; map all identifiers to angle3# namespace
(##import gambit) ;; except those defined by Gambit's RTS
(##supply-module angle3)
(define factor (/ (atan 1) 45))
(define (deg->rad x) (* x factor))
(define (rad->deg x) (/ x factor))
;;;---------------------------------------- file: app3.scm
(##import angle3)
(println "90 degrees is " (deg->rad 90) " radians")
|
In this example the (##import angle3)
takes care of the namespace
mapping and the loading of angle3.scm
because it is equivalent to:
| (begin
(##include "angle3/angle3#.scm")
(##demand-module angle3))
|
7.2.3 Macros
In addition to procedures, a module M
may export macros. The
file M#.scm
is the designated place to put exported macro
definitions. These macro definitions will essentially be copied at
the point where the ##import
of the module is done. Macros
that are needed strictly for the implementation of a module may be
defined in the file M.scm
and these macro definitions will not
be visible elsewhere. Note that the macros defined with
define-macro
are not hygienic, so the macro definition writer
should take care to explicitly indicate what identifiers resolve to
using fully qualified identifiers (i.e. containing a #
sign).
To explain these issues, lets extend our example module in the
following ways. First we want the module to export the macros
sind
and asind
that are like the sin
and
asin
procedures but use degrees instead of radians. Note that
it would be a better design for sind
and asind
to be
procedures, but we’ll implement them as macros for the sake of the
example. Second we want the procedures deg->rad
and rad->deg
to check that their argument is a real number using a check-real
macro.
In a setting where name clashes are not an issue these macros can be
defined as follows:
| (define-macro (sind x) `(sin (deg->rad ,x)))
(define-macro (asind x) `(rad->deg (asin ,x)))
(define-macro (check-real x y)
`(if (real? ,x) ,y (error "not real!")))
|
Name clashes will occur when the locations where these macros are
called are in the scope of new bindings for sin
,
deg->rad
, if
, error
, etc which are identifiers
used in the expanded code. A name clash can also happen for the name
define-macro
itself. To remove the possibility of name clashes
the ##namespace
form and fully qualified identifiers can be
used. All the Gambit special forms, such as let
, if
,
and define-macro
, have a fully qualified version (##let
,
##if
, and ##define-macro
). Gambit predefined procedures,
such as sin
, real?
, and error
, don’t necessarily
have a fully qualified version (some do and some don’t) but an empty
namespace definition in a ##let
form can be used to avoid the
clash, i.e. (##let () (##namespace ("") sin))
refers to the global
variable sin
whatever scope it is in. With these forms our
example can be written like this:
| ;;;---------------------------------------- file: angle4/angle4#.scm
(##namespace ("angle4#" deg->rad rad->deg))
(##define-macro (sind x) `((##let () (##namespace ("")) sin)
(angle4#deg->rad ,x)))
(##define-macro (asind x) `(angle4#rad->deg
((##let () (##namespace ("")) asin) ,x)))
;;;---------------------------------------- file: angle4/angle4.scm
(##namespace ("angle4#")) ;; map all identifiers to angle4# namespace
(##import gambit) ;; except those defined by Gambit's RTS
(##supply-module angle4)
(##define-macro (check-real x y)
`(##if ((##let () (##namespace ("")) real?) ,x)
,y
((##let () (##namespace ("")) error) "not real!")))
(define factor (/ (atan 1) 45))
(define (deg->rad x) (check-real x (* x factor)))
(define (rad->deg x) (check-real x (/ x factor)))
;;;---------------------------------------- file: app4.scm
(##import angle4)
(println "90 degrees is " (deg->rad 90) " radians")
(println "sind(90) is " (sind 90))
|
7.3 Primitive Procedures
Identifiers with a ##
prefix are not valid identifiers according
to RnRS. This means that code containing ##
prefixed identifiers
cannot be processed by and shared with other Scheme implementations.
They are hard to read by people that aren’t used to that extension.
Moreover the code lacks abstraction and safety because using
##car
rather than car
has a specific meaning: avoiding
type checks. Consequently it is hard to "turn on" safe execution of the
code when it needs to be debugged. Many parts of the runtime library are
expressed at a low level of abstraction (with ##
prefixed
identifiers) even when not required.
For those reasons ##
prefixed identifiers should be used
sparingly in new code, and existing code should gradually be rewritten
to avoid them. The primitive operations which are used to build
higher-level operations are all defined as procedures with a ##
prefix.
The file ~~lib/_gambit#.scm
contains the definition of the
primitive
macro whose purpose is to abstract from the ##
prefix. The call (primitive foo)
is equivalent to ##foo
and (primitive (foo a b))
is equivalent to (##foo a b)
.
The file ~~lib/_gambit#.scm
also contains the definition of the
standard
macro whose purpose is similar, but forces the use of
the empty namespace. The call (standard +)
is equivalent to
(##let () (##namespace ("" +)) +)
and (standard (+ a b))
is equivalent to ((##let () (##namespace ("" +)) +) a
b)
. Code that uses the primitive
and standard
macros can be ported to other Scheme implementations
by defining implementation specific primitive
and
standard
macros that implement the appropriate mapping for
that implementation.
The file ~~lib/_gambit#.scm
also contains definitions for the
define-procedure
and define-primitive
macros.
The primitive
and standard
macros work in tandem with the
define-procedure
and define-primitive
macros and the
~~lib/gambit/prim/prim#.scm
file and (gambit prim)
library. The file ~~lib/gambit/prim/prim#.scm
contains namespace
declarations that map operations exported by the runtime library without
a ##
prefix to their ##
prefixed names if this preserves
the meaning of the operation but possibly (and usually) with no type
checking. The (gambit prim)
library is similar but in the form of
a R7RS library. For example the following code:
| (include "~~lib/gambit/prim/prim#.scm")
(define (foo x) (square (car x)))
(println (foo (bar 0.5)))
(pp "hello")
|
is equivalent to this code:
| (##define (foo x) (##square (##car x)))
(##println (foo (bar 0.5)))
(##unimplemented#pp "hello")
|
The namespace declarations in ~~lib/gambit/prim/prim#.scm
have
caused a mapping of square
to ##square
, car
to
##car
and println
to ##println
because those primitives
perform the same operations (when the code has no errors). Note that
foo
and bar
have remained the same, because they are not
procedures exported by the runtime library, and pp
has been
mapped to ##unimplemented#pp
because pp
is a procedure
exported by the runtime library but ##pp
is not defined. Having
unimplemented
in the name helps catch situations where the
programmer expected a primitive operation to exist but this isn’t the
case.
The define-procedure
macro does two things. It supports type
annotations in the parameter list and it inserts a (include
"~~lib/gambit/prim/prim#.scm")
in the body so that primitive operations
can be used without the ##
prefix. Type checking and automatic
forcing of promise arguments are also added implicitly. The macro
define-primitive
is similar, but the procedure defined is
implicitly prefixed with ##
.
So all of these things work together to abstract away from the concept
of primitive operations. Primitives are implemented using procedures
with a ##
prefix, but other Scheme implementations could do it
differently.
Finally, there’s the (declare-safe-define-procedure <bool>)
macro
that can be used to enable/disable the mapping of names exported by the
runtime library to the corresponding primitives. This is useful to
enable type checks in the code. For example the following definition:
| (define-procedure (foo (x vector))
(vector-ref x 5))
|
which expands to
| (define (foo x)
(macro-check-vector x '(1 . x) (foo x)
(##vector-ref x 5)))
|
which expands to
| (define (foo x)
(if (##vector? x)
(##vector-ref x 5)
(##fail-check-vector '(1 . x) foo x)))
|
If the code is in the scope of a (declare-safe-define-procedure
#t)
then it is vector-ref
that is called instead of
##vector-ref
which will both check that x is a vector
(redundantly) and that the index is in range. However, the use of
##vector-ref
can be forced by writing the code with an explicit
use of the primitive
macro:
| (define-procedure (foo (x vector))
(primitive (vector-ref x 5)))
|
The expectation is that the primitive
special form will be
used sparingly. Searching the source code for the pattern "(primitive"
is a good way to find potentially unsafe code.
7.3.1 Type specifiers
Here is a list of the available type specifiers for a
define-procedure
parameter x and the associated constraint
on the value of x.
Note that there is no direct way for checking for a "list" or "list of
elements of type T". A procedure taking a list parameter will likely
iterate on the list’s pairs going from cdr to cdr until a non-pair is
found. Then a check for the empty list with
(macro-check-proper-list-null lst <arg-id> (<procedure-name>
<args>...) <body>)
will check that the parameter is a proper list
(i.e. that it ends with the empty list).
7.3.1.1 Basic types (other than numbers)
-
boolean
x is a boolean
-
char
x is a character
-
pair
x is a pair
-
procedure
x is a procedure
-
string
x is a string
-
symbol
x is a symbol
-
vector
x is a vector
7.3.1.2 Numbers
-
number
x is a number (possibly complex, rational, etc)
-
real
x is a real number (any number except complex)
-
fixnum
x is a fixnum and -2^(W-3) <= x <= 2^(W-3) - 1
-
(fixnum-range lo hi)
x is a fixnum and lo <= x < hi
-
(fixnum-range-incl lo hi)
x is a fixnum and lo <= x <= hi
-
index
x is a fixnum and 0 <= x
-
(index-range lo hi)
x is a fixnum and 0 <= lo <= x < hi
-
(index-range-incl lo hi)
x is a fixnum and 0 <= lo <= x <= hi
-
exact-signed-int8
x is an exact integer, -128 <= x <= 127
-
exact-signed-int16
x is an exact integer n, -32768 <= x <= 32767
-
exact-signed-int32
x is an exact integer n, -2^31 <= x <= 2^31 - 1
-
exact-signed-int64
x is an exact integer n, -2^63 <= x <= 2^63 - 1
-
exact-unsigned-int8
x is an exact integer n, 0 <= x <= 255
-
exact-unsigned-int16
x is an exact integer n, 0 <= x <= 65535
-
exact-unsigned-int32
x is an exact integer n, 0 <= x <= 2^32 - 1
-
exact-unsigned-int64
x is an exact integer n, 0 <= x <= 2^64 - 1
-
flonum
x is a flonum, exception mentions FLONUM
-
inexact-real
x is a flonum, exception mentions Inexact REAL
-
inexact-real-list
x is a flonum, exception mentions Inexact REAL LIST
7.3.1.3 Time types
-
time
x is a time object
-
absrel-time
x is a real or a time object
-
absrel-time-or-false
x is #f
or a real or a time object
7.3.1.4 Ports
-
port
x is a port (input, output, or input-output)
-
input-port
x is an input port
-
output-port
x is an output port
-
object-input-port
x is an object input port
-
object-output-port
x is an object output port
-
vector-input-port
x is a vector input port
-
vector-output-port
x is a vector output port
-
character-input-port
x is a character input port
-
character-output-port
x is a character output port
-
string-input-port
x is a string input port
-
string-output-port
x is a string output port
-
byte-port
x is a byte port (input, output, or input-output)
-
byte-input-port
x is a byte input port
-
byte-output-port
x is a byte output port
-
u8vector-input-port
x is a u8vector input port
u8vector-output-port x is a u8vector output port
-
device-input-port
x is a device intput port
-
device-output-port
x is a device output port
-
process-port
x is a process port
-
tcp-client-port
x is a tcp-client port
-
tcp-server-port
x is a tcp-server port
-
udp-port
x is a udp port
-
udp-input-port
x is a udp input port
-
udp-output-port
x is a udp output port
-
tty-port
x is a tty port
7.3.1.5 List and vector variants of above
-
list
no type checking (a non-null non-pair object is in fact a degenerate dotted list),
exception mentions LIST
-
proper-list
no type checking (code traversing the list must check for a proper-list),
exception mentions PROPER LIST
-
proper-list-null
x is the empty list, exception mentions PROPER LIST
-
proper-or-circular-list
no type checking (code traversing the list must check for a proper-list or circular-list),
exception mentions PROPER or CIRCULAR LIST
-
proper-or-circular-list-null
x is the empty list, exception mentions PROPER LIST
-
char-list
x is a character, exception mentions CHARACTER LIST
-
char-vector
x is a character, exception mentions CHARACTER VECTOR
-
pair-list
x is a pair, exception mentions PAIR LIST
-
exact-unsigned-int8-list-exact-unsigned-int8
x is an exact-unsigned-int8, exception mentions INTEGER LIST
-
exact-unsigned-int16-list-exact-unsigned-int16
x is an exact-unsigned-int16, exception mentions INTEGER LIST
-
exact-unsigned-int32-list-exact-unsigned-int32
x is an exact-unsigned-int32, exception mentions INTEGER LIST
-
exact-unsigned-int64-list-exact-unsigned-int64
x is an exact-unsigned-int64, exception mentions INTEGER LIST
-
exact-signed-int8-list-exact-signed-int8
x is an exact-signed-int8, exception mentions INTEGER LIST
-
exact-signed-int16-list-exact-signed-int16
x is an exact-signed-int16, exception mentions INTEGER LIST
-
exact-signed-int32-list-exact-signed-int32
x is an exact-signed-int32, exception mentions INTEGER LIST
-
exact-signed-int64-list-exact-signed-int64
x is an exact-signed-int64, exception mentions INTEGER LIST
7.3.1.6 Gambit types
-
error-exception
x is an error-exception object
-
box
x is a box
-
condvar
x is a condition variable
-
f32vector
x is a f32vector
-
f64vector
x is a f64vector
-
foreign
x is a foreign object
-
keyword
x is a keyword
-
mutex
x is a mutex
-
processor
x is a processor object
-
s16vector
x is a s16vector
-
s32vector
x is a s32vector
-
s64vector
x is a s64vector
-
s8vector
x is a s8vector
-
table
x is a table
-
tgroup
x is a thread group
-
thread
x is a thread
-
u16vector
x is a u16vector
-
u32vector
x is a u32vector
-
u64vector
x is a u64vector
-
u8vector
x is a u8vector
-
will
x is a will
-
continuation
x is a continuation object
-
random-source
x is a random-source object
-
readtable
x is a readtable
-
type
x is a structure type descriptor
-
mutable
x is a mutable object
7.3.1.7 Others
-
initialized-thread
-
not-initialized-thread
-
not-started-thread
-
not-started-thread-given-initialized
-
string-or-ip-address
-
string-or-nonnegative-fixnum
7.4 R7RS Compatible Modules
The R7RS Scheme standard specifies a modularization approach based on
the concept of library. A library is defined using the
define-library
form. This form is implemented as a macro that
expands into the constructs used by primitive modules, in particular a
##namespace
declaration with a namespace derived from the
library’s name so that all variables defined by the library are in
that namespace. With the define-library
form the angle3
module example given previously can be written like this:
| ;;;---------------------------------------- file: angle3.sld
(define-library (angle3)
(export deg->rad rad->deg)
(import (scheme base)
(scheme inexact))
(begin
(define factor (/ (atan 1) 45))
(define (deg->rad x) (* x factor))
(define (rad->deg x) (/ x factor))))
|
For this library the expansion of the define-library
form will
contain a ##namespace
declaration that causes the definition of
the global variables angle3#factor
, angle3#deg->rad
, and
angle3#rad->deg
. Meanwhile an (import (angle3))
in
another library will generate a ##namespace
declaration that
maps uses of deg->rad
and rad->deg
to the global
variables angle3#deg->rad
and angle3#rad->deg
respectively (note that the unexported global variable factor
is not included in the generated ##namespace
declaration).
For more complex libraries whose code is split into multiple files it
is convenient to put all the files in a dedicated subdirectory. This
is the preferred filesystem structure for a library but the runtime
system supports both styles. The previous module could be structured
like this instead:
| ;;;---------------------------------------- file: angle3/angle3.sld
(define-library (angle3)
(export deg->rad rad->deg)
(import (scheme base)
(scheme inexact))
(include "angle3.scm")) ;; path is relative to angle3.sld file
;;;---------------------------------------- file: angle3/angle3.scm
(define factor (/ (atan 1) 45))
(define (deg->rad x) (* x factor))
(define (rad->deg x) (/ x factor))
|
7.4.1 Identifying libraries
Each library is given a name so that it can be referred to in various
contexts, most notably in import
forms and the interpreter’s
and compiler’s command line. The R7RS defines a library name
as a list whose members are identifiers and exact non-negative
integers, for example (widget)
, (_hamt)
, (scheme
base)
, and (srfi 64)
.
The system maps these R7RS library names to module identifiers that
are symbols formed by concatenating the parts of the library name
separated with /
. The library name and module name
are interchangeable. Consequently, (import srfi/64)
and
(import _hamt)
are respectively equivalent to (import
(srfi 64))
and (import (_hamt))
. Using the module name to
identify libraries on the command line is convenient as it avoids
having to escape parentheses and spaces.
7.4.2 The define-library
form
In a library definition name specifies the name of the library
and declaration is one of:
| (export <export spec> ...)
(import <import set> ...)
(begin <command or definition> ...)
(include <filename> ...)
(include-ci <filename> ...)
(include-library-declarations <filename> ...)
(cond-expand <cond expand features> ...)
(namespace <namespace>)
(cc-options <options> ...)
(ld-options <options> ...)
(ld-options-prelude <options> ...)
(pkg-config <options> ...)
(pkg-config-path <path> ...)
|
7.4.3 (export <export spec> ...)
An export
declaration specifies a list of identifiers which
can be made visible to other libraries or programs.
An <export spec> takes one of the following forms:
| <identifier>
(rename <identifier>1 <identifier>2)
|
In an <export spec>, an <identifier> names a single
binding (variable or macro) defined within or imported into the library, where the
external name for the export is the same as the name of the binding
within the library. A rename
spec exports the binding
defined within or imported into the library and named by
<identifier>1 in each
(<identifier>1 <identifier>2)
pairing,
using <identifier>2 as the external name.
7.4.4 (import <import set> ...)
A library declares a dependency to another library with the
import
declaration. The (import <import set>
...)
form identifies the imported library or libraries.
Each <import set> names a set of bindings
from a library and possibly specifies local names for the
imported bindings. An <import set> takes one of the following forms:
| <library name>
(only <import set> <identifier> ...)
(except <import set> <identifier> ...)
(prefix <import set> <identifier>)
(rename <import set> (<identifier>1 <identifier>2) ...)
|
In the first form, all of the identifiers in the named library’s export
clauses are imported with the same names (or the exported names if
exported with rename
). The additional <import set>
forms modify this set as follows:
-
only
produces a subset of the given
<import set> including only the listed identifiers (after any
renaming). It is an error if any of the listed identifiers are
not found in the original set.
-
except
produces a subset of the given
<import set>, excluding the listed identifiers (after any
renaming). It is an error if any of the listed identifiers are not
found in the original set.
-
rename
modifies the given <import set>,
replacing each instance of <identifier>1 with
<identifier>2. It is an error if any of the listed
<identifier>1s are not found in the original set.
-
prefix
automatically renames all identifiers in
the given <import set>, prefixing each with the specified
<identifier>.
It is an error to import the same identifier more than once with
different bindings, or to redefine or mutate an imported binding with
a definition or with set!
, or to refer to an identifier before
it is imported.
As an extension to the R7RS syntax it is allowed for a <library
name> to contain a trailing @version
when the
library is hosted in a git
repository. The version must
match a tag of that repository and it indicates the specific library
version required. For example, (import (github.com/gambit hello
@1.0))
or equivalently (import github.com/gambit/hello@1.0)
.
Note that the version specifier is not separated with a /
in
the module name.
Another extension to the R7RS syntax when the library is hosted in a
git
repository is the use of dots before the name of the
library to indicate a relative reference within the repository. The
number of dots indicates the number of parent hops. For example, in
the library (github.com/gambit hello demo)
an (import
(.. hello))
will resolve to the (github.com/gambit hello)
library. A relative library reference should not contain an explicit
@version
because the version is implicitly the
same as the referring module.
7.4.5 (begin <command or definition> ...)
, (include <filename> ...)
, and (include-ci <filename> ...)
The begin
, include
, and include-ci
declarations are
used to specify the body of
the library. They have the same syntax and semantics as the corresponding
expression types.
This form of begin
is analogous to, but not the same as, the
two types of begin
expressions.
7.4.6 (include-library-declarations <filename> ...)
The include-library-declarations
declaration is similar to
include
except that the contents of the file are spliced directly into the
current library definition. This can be used, for example, to share the
same export
declaration among multiple libraries as a simple
form of library interface.
7.4.7 (cond-expand <cond expand features> ...)
The cond-expand
declaration has the same syntax and semantics as
the cond-expand
expression type, except that it expands to
spliced-in library declarations rather than expressions enclosed in begin
.
7.4.8 Extensions to the R7RS library declarations
The (namespace <namespace>)
declaration allows
overriding the namespace used for the library. This is mainly useful
for system libraries to prevent namespace prefixing using a
(namespace "")
declaration.
The remaining declarations are relevant to the C
target and
ignored otherwise. They provide information, in the form of strings,
to be passed to the compiler options of the same name when this library
is compiled:
-
(cc-options <options> ...)
-
(ld-options <options> ...)
-
(ld-options-prelude <options> ...)
-
(pkg-config <options> ...)
-
(pkg-config-path <path> ...)
For example, a library could force the C compiler to generate
machine code for i386 with:
| (define-library (foo)
(export bar)
(import (scheme base))
(cc-options "-march=i386") ;; request compilation for i386
(begin (define (bar) 42)))
|
7.5 Installing Modules
When a module is imported, the processing of the import
form
must locate and read the source code of the module at macro expansion
time to determine which names are exported and to what they are
mapped. The list of module search directories (~~lib
followed
by ~~userlib
by default) is searched to find the module’s
source code. At execution time the same search algorithm is used to
locate and load the module, either in source code form or compiled
form. The ~~lib
directory is where the system’s builtin
modules are put when Gambit is installed. The ~~userlib
directory is a convenient place where other modules can be installed
by the user because locating them does not require extending the list
of module search directories.
The list of module search directories can be modified using the
procedures module-search-order-reset!
and
module-search-order-add!
that respectively clear the list and
extend the list with the directory dir which must be a
string. The list can also be extended by using the
-:search=
DIR runtime option or by a command line argument
to gsi
and gsc
that ends with a path separator or a
‘.’ (see section ##demand-module
and ##supply-module
forms).
For example:
| $ cat foobar.sld
(define-library (foobar)
(import (scheme write))
(begin (display "foobar library has executed\n")))
$ gsi
Gambit v4.9.5
> (import (foobar))
*** ERROR IN (stdin)@1.9 -- Cannot find library (foobar)
> (module-search-order-add! ".")
> (import (foobar))
foobar library has executed
> ,q
$ gsi -:search=. foobar
foobar library has executed
$ gsi . foobar
foobar library has executed
|
When modules are installed it is done at the granularity of a
package, which is defined as a git
repository possibly
containing more than one module. For example, if the hosted module
github.com/gambit/hello/demo
needs to be installed it is all of
the code at github.com/gambit/hello
that is installed (this
includes the three modules github.com/gambit/hello
,
github.com/gambit/hello/demo
, and
github.com/gambit/hello/test
).
For convenience the runtime system will automatically install in the
~~userlib
directory any hosted module that is from a trusted
source. The whitelist of trusted sources, which initially contains
only github.com/gambit
, can be modified using the procedures
module-whitelist-reset!
and module-whitelist-add!
that
respectively clear the list and extend the list with the source
source which must be a string, symbol or list specifying a hosted module reference. The list can also be extended
with the -:whitelist=
SOURCE runtime option.
For example:
| $ gsi github.com/gambit/hello/demo # auto-install of github.com/gambit/hello package
People customarily greet each other when they meet.
In English you can say: hello Bob, nice to see you!
In French you can say: bonjour Bob, je suis enchanté!
Demo source code: /Users/feeley/.gambit_userlib/github.com/gambit/hello/@/demo.scm
$ gsi github.com/feeley/roman/demo # no auto-install because not on whitelist
*** ERROR IN ##main -- No such file or directory
(load "github.com/feeley/roman/demo")
$ gsi -:whitelist=github.com/feeley github.com/feeley/roman/demo
1 is I in roman numerals
2 is II in roman numerals
4 is IV in roman numerals
8 is VIII in roman numerals
16 is XVI in roman numerals
32 is XXXII in roman numerals
64 is LXIV in roman numerals
$ gsi github.com/feeley/roman/demo # OK because module is now installed
1 is I in roman numerals
2 is II in roman numerals
4 is IV in roman numerals
8 is VIII in roman numerals
16 is XVI in roman numerals
32 is XXXII in roman numerals
64 is LXIV in roman numerals
$ gsi github.com/feeley/roman/test # the test module was also installed
*** all tests passed out of a total of 19 tests
|
The use of the runtime option -:whitelist=
(with no SOURCE)
will disable the automatic installation of modules, even from
github.com/gambit
. For example:
| $ gsi -:whitelist= github.com/gambit/hello/demo
*** ERROR IN ##main -- No such file or directory
(load "github.com/gambit/hello/demo")
|
A manual management of packages is nevertheless possible with the
gsi
package management operations. These are invoked with the
command line options ‘-install’, ‘-uninstall’, and
‘-update’ which respectively install, uninstall and update
packages. The package management operations accept a list of
packages. Packages are installed in ~~userlib
which is mapped
to ~/.gambit_userlib
by default. An optional
‘-dir dir’ option can be used to install the package in
some other directory.
For example:
| $ gsi -install github.com/feeley/roman
installing github.com/feeley/roman to /Users/feeley/.gambit_userlib/
$ gsi github.com/feeley/roman/demo
1 is I in roman numerals
2 is II in roman numerals
4 is IV in roman numerals
8 is VIII in roman numerals
16 is XVI in roman numerals
32 is XXXII in roman numerals
64 is LXIV in roman numerals
$ gsi -uninstall github.com/feeley/roman
uninstalling github.com/feeley/roman from /Users/feeley/.gambit_userlib/
$ gsi -install -dir ~/mylibs github.com/feeley/roman
installing github.com/feeley/roman to /Users/feeley/mylibs
$ gsi ~/mylibs/ github.com/feeley/roman/demo
1 is I in roman numerals
2 is II in roman numerals
4 is IV in roman numerals
8 is VIII in roman numerals
16 is XVI in roman numerals
32 is XXXII in roman numerals
64 is LXIV in roman numerals
|
Local git
repositories can also be installed manually with the
package management operations using a path to the local repository.
This can be useful during the development phase before a library
becomes hosted.
For example:
| $ mkdir some
$ mkdir some/dir
$ mkdir some/dir/mylib
$ cd some/dir/mylib
$ cat > mylib.sld
(define-library (mylib)
(import (scheme write))
(begin (display "mylib library has executed\n")))
$ git init
Initialized empty Git repository in /Users/feeley/doc/some/dir/mylib/.git/
$ git add mylib.sld
$ git commit -m "first commit"
[master (root-commit) c3f6aff] first commit
1 file changed, 3 insertions(+)
create mode 100644 mylib.sld
$ cd ../../..
$ gsi some/dir/ mylib # execution of mylib without installation
mylib library has executed
$ gsi -install some/dir/mylib
installing some/dir/mylib to /Users/feeley/.gambit_userlib/
$ gsi mylib # execution of mylib after installation
mylib library has executed
|
7.6 Compiling Modules
When gsc
finds a command line argument that is the name of a
module found on the list of module search order directories (after an
automatic installation if that is appropriate) that module’s main
source code file will be compiled.
When a dynamic compilation is requested (which is the default
compilation mode and when the command line option -dynamic
is
used) the compiler will compile for the selected target the main
source code file to a target file and a dynamically loadable object
file with a ‘.o1’ extension. These files will be created in a
directory next to the module’s main source code file, with the same
name stripped of it’s extension and suffixed with the Gambit version
and the target name. This naming strategy aims to avoid loading the
compiled file in an inappropriate context. The module loading
algorithm knows it should check this directory to find a compiled
version of the module.
For example:
| $ mkdir lib1 lib2
$ cat > lib1/lib1.sld
(define-library (lib1)
(export fact)
(import (scheme base) (scheme write))
(begin
(define (fact n) (if (<= n 1) 1 (* n (fact (- n 1)))))
(display "lib1 loaded\n")))
$ cat > lib2/lib2.sld
(define-library (lib2)
(import (lib1) (scheme base) (scheme write))
(begin
(display
(cond-expand
((compilation-target C) "lib2 compiled to C\n")
((compilation-target (_)) "lib2 interpreted\n")
(else "lib2 compiled to other\n")))
(display (fact 10))
(newline)))
$ gsi . lib2 # loads lib1.sld and lib2.sld
lib1 loaded
lib2 interpreted
3628800
lib1
$ tree --charset=ascii --noreport lib1 lib2
`-- lib1.sld
lib2
`-- lib2.sld
$ gsc . lib1 lib2 # compile lib1.sld and lib2.sld using C target
$ gsi . lib2 # loads generated lib1.o1 and lib2.o1
lib1 loaded
lib2 compiled to C
3628800
$ gsc -target js . lib1 lib2 # also compile them for js target
$ tree --charset=ascii --noreport lib1 lib2
lib1
|-- lib1.sld
|-- lib1@gambit409003@C
| |-- lib1.c
| `-- lib1.o1
`-- lib1@gambit409003@js
|-- lib1.js
`-- lib1.o1
lib2
|-- lib2.sld
|-- lib2@gambit409003@C
| |-- lib2.c
| `-- lib2.o1
`-- lib2@gambit409003@js
|-- lib2.js
`-- lib2.o1
|
To create an executable program from a set of non-legacy modules
it is important to use the -nopreload
linking option when linking so
that the modules will be initialized in an order that is consistent
with the module dependencies. If the default -preload
linking option
is used some modules may be initialized out of order, leading to incorrect
execution.
Here is an example that extends the previous example:
| $ gsc -exe -nopreload . lib1/lib1.sld lib2/lib2.sld
$ lib2/lib2
lib1 loaded
lib2 compiled to C
3628800
$ gsc -target js -exe -nopreload . lib1/lib1.sld lib2/lib2.sld
$ lib2/lib2
lib1 loaded
lib2 compiled to other
3628800
|
8. Built-in data types
8.1 Numbers
8.1.1 Extensions to numeric procedures
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)
.
8.1.2 IEEE floating point arithmetic
To better conform to IEEE floating point arithmetic the standard
numeric tower is extended with these special inexact reals:
-
+inf.0
positive infinity
-
-inf.0
negative infinity
-
+nan.0
“not a number”
-
-0.
negative zero (‘0.’ is the positive zero)
The infinities and “not a number” are reals (i.e. (real?
+inf.0)
is #t
) but are not rational (i.e. (rational?
+inf.0)
is #f
).
Both zeros are numerically equal (i.e. (= -0. 0.)
is #t
)
but are not equivalent (i.e. (eqv? -0. 0.)
and (equal?
-0. 0.)
are #f
). All numerical comparisons with “not a
number”, including (= +nan.0 +nan.0)
, are #f
.
8.1.3 Integer square root and nth root
This procedure returns the integer part of the square root of the
nonnegative exact integer n.
For example:
This procedure returns the integer part of n1 raised to the
power 1/n2, where n1 is a nonnegative exact integer and
n2 is a positive exact integer.
For example:
| > (integer-nth-root 100 3)
4
|
8.1.4 Bitwise-operations on exact integers
The procedures defined in this section are compatible with the
withdrawn “Integer Bitwise-operation Library SRFI” (SRFI 33). Note
that some of the procedures specified in SRFI 33 are not provided.
Most procedures in this section are specified in terms of the binary
representation of exact integers. The two’s complement representation
is assumed where an integer is composed of an infinite number of bits.
The upper section of an integer (the most significant bits) are either
an infinite sequence of ones when the integer is negative, or they are
an infinite sequence of zeros when the integer is nonnegative.
This procedure returns n1 shifted to the left by n2 bits,
that is (floor (* n1 (expt 2 n2)))
. Both n1
and n2 must be exact integers.
For example:
| > (arithmetic-shift 1000 7) ; n1=...0000001111101000
128000
> (arithmetic-shift 1000 -6) ; n1=...0000001111101000
15
> (arithmetic-shift -23 -3) ; n1=...1111111111101001
-3
|
This procedure returns an exact integer whose bits combine the bits
from n2 and n3 depending on n1. The bit at index
i of the result depends only on the bits at index i in
n1, n2 and n3: it is equal to the bit in n2
when the bit in n1 is 0 and it is equal to the bit in n3
when the bit in n1 is 1. All arguments must be exact integers.
For example:
| > (bitwise-merge -4 -11 10) ; ...11111100 ...11110101 ...00001010
9
> (bitwise-merge 12 -11 10) ; ...00001100 ...11110101 ...00001010
-7
|
This procedure returns the bitwise “and” of the exact integers
n…. The value -1 is returned when there are no arguments.
For example:
| > (bitwise-and 6 12) ; ...00000110 ...00001100
4
> (bitwise-and 6 -4) ; ...00000110 ...11111100
4
> (bitwise-and -6 -4) ; ...11111010 ...11111100
-8
> (bitwise-and)
-1
|
This procedure returns the bitwise “and” of the bitwise complement
of the exact integer n1 and the exact integer n2.
For example:
| > (bitwise-andc1 11 26) ; ...00001011 ...00011010
16
> (bitwise-andc1 -12 26) ; ...11110100 ...00011010
10
|
This procedure returns the bitwise “and” of the exact integer
n1 and the bitwise complement of the exact integer n2.
For example:
| > (bitwise-andc2 11 26) ; ...00001011 ...00011010
1
> (bitwise-andc2 11 -27) ; ...00001011 ...11100101
10
|
This procedure returns the bitwise complement of the bitwise
“exclusive-or” of the exact integers n…. The value -1
is returned when there are no arguments.
For example:
| > (bitwise-eqv 6 12) ; ...00000110 ...00001100
-11
> (bitwise-eqv 6 -4) ; ...00000110 ...11111100
5
> (bitwise-eqv -6 -4) ; ...11111010 ...11111100
-7
> (bitwise-eqv)
-1
|
This procedure returns the bitwise “inclusive-or” of the exact
integers n…. The value 0 is returned when there are no
arguments.
For example:
| > (bitwise-ior 6 12) ; ...00000110 ...00001100
14
> (bitwise-ior 6 -4) ; ...00000110 ...11111100
-2
> (bitwise-ior -6 -4) ; ...11111010 ...11111100
-2
> (bitwise-ior)
0
|
This procedure returns the bitwise complement of the bitwise “and”
of the exact integer n1 and the exact integer n2.
For example:
| > (bitwise-nand 11 26) ; ...00001011 ...00011010
-11
> (bitwise-nand 11 -27) ; ...00001011 ...11100101
-2
|
This procedure returns the bitwise complement of the bitwise
“inclusive-or” of the exact integer n1 and the exact integer
n2.
For example:
| > (bitwise-nor 11 26) ; ...00001011 ...00011010
-28
> (bitwise-nor 11 -27) ; ...00001011 ...11100101
16
|
This procedure returns the bitwise complement of the exact integer
n.
For example:
| > (bitwise-not 3) ; ...00000011
-4
> (bitwise-not -1) ; ...11111111
0
|
This procedure returns the bitwise “inclusive-or” of the bitwise
complement of the exact integer n1 and the exact integer
n2.
For example:
| > (bitwise-orc1 11 26) ; ...00001011 ...00011010
-2
> (bitwise-orc1 -12 26) ; ...11110100 ...00011010
27
|
This procedure returns the bitwise “inclusive-or” of the exact
integer n1 and the bitwise complement of the exact integer
n2.
For example:
| > (bitwise-orc2 11 26) ; ...00001011 ...00011010
-17
> (bitwise-orc2 11 -27) ; ...00001011 ...11100101
27
|
This procedure returns the bitwise “exclusive-or” of the exact
integers n…. The value 0 is returned when there are no
arguments.
For example:
| > (bitwise-xor 6 12) ; ...00000110 ...00001100
10
> (bitwise-xor 6 -4) ; ...00000110 ...11111100
-6
> (bitwise-xor -6 -4) ; ...11111010 ...11111100
6
> (bitwise-xor)
0
|
This procedure returns the bit count of the exact integer n. If
n is nonnegative, the bit count is the number of 1 bits in the
two’s complement representation of n. If n is negative,
the bit count is the number of 0 bits in the two’s complement
representation of n.
For example:
| > (bit-count 0) ; ...00000000
0
> (bit-count 1) ; ...00000001
1
> (bit-count 2) ; ...00000010
1
> (bit-count 3) ; ...00000011
2
> (bit-count 4) ; ...00000100
1
> (bit-count -23) ; ...11101001
3
|
This procedure returns the bit length of the exact integer n.
If n is a positive integer the bit length is one more than the
index of the highest 1 bit (the least significant bit is at index 0).
If n is a negative integer the bit length is one more than the
index of the highest 0 bit. If n is zero, the bit length is 0.
For example:
| > (integer-length 0) ; ...00000000
0
> (integer-length 1) ; ...00000001
1
> (integer-length 2) ; ...00000010
2
> (integer-length 3) ; ...00000011
2
> (integer-length 4) ; ...00000100
3
> (integer-length -23) ; ...11101001
5
|
This procedure returns a boolean indicating if the bit at index
n1 of n2 is set (i.e. equal to 1) or not. Both n1
and n2 must be exact integers, and n1 must be
nonnegative.
For example:
| > (map (lambda (i) (bit-set? i -23)) ; ...11101001
'(7 6 5 4 3 2 1 0))
(#t #t #t #f #t #f #f #t)
|
This procedure returns a boolean indicating if the bitwise and
of n1 and n2 is different from zero or not. This procedure
is implemented more efficiently than the naive definition:
| (define (any-bits-set? n1 n2) (not (zero? (bitwise-and n1 n2))))
|
For example:
| > (any-bits-set? 5 10) ; ...00000101 ...00001010
#f
> (any-bits-set? -23 32) ; ...11101001 ...00100000
#t
|
This procedure returns a boolean indicating if the bitwise and
of n1 and n2 is equal to n1 or not. This procedure
is implemented more efficiently than the naive definition:
| (define (all-bits-set? n1 n2) (= n1 (bitwise-and n1 n2)))
|
For example:
| > (all-bits-set? 1 3) ; ...00000001 ...00000011
#t
> (all-bits-set? 7 3) ; ...00000111 ...00000011
#f
|
This procedure returns the bit index of the least significant bit of
n equal to 1 (which is also the number of 0 bits that are below
the least significant 1 bit). This procedure returns -1
when
n is zero.
For example:
| > (first-set-bit 24) ; ...00011000
3
> (first-set-bit 0) ; ...00000000
-1
|
These procedures operate on a bit-field which is n1 bits wide
starting at bit index n2. All arguments must be exact integers
and n1 and n2 must be nonnegative.
The procedure extract-bit-field
returns the bit-field of
n3 shifted to the right so that the least significant bit of the
bit-field is the least significant bit of the result.
The procedure test-bit-field?
returns #t
if any bit in
the bit-field of n3 is equal to 1, otherwise #f
is
returned.
The procedure clear-bit-field
returns n3 with all bits
in the bit-field replaced with 0.
The procedure replace-bit-field
returns n4 with the
bit-field replaced with the least-significant n1 bits of
n3.
The procedure copy-bit-field
returns n4 with the
bit-field replaced with the (same index and size) bit-field in
n3.
For example:
| > (extract-bit-field 5 2 -37) ; ...11011011
22
> (test-bit-field? 5 2 -37) ; ...11011011
#t
> (test-bit-field? 1 2 -37) ; ...11011011
#f
> (clear-bit-field 5 2 -37) ; ...11011011
-125
> (replace-bit-field 5 2 -6 -37) ; ...11111010 ...11011011
-21
> (copy-bit-field 5 2 -6 -37) ; ...11111010 ...11011011
-5
|
8.1.5 Fixnum specific operations
Fixnum-overflow-exception objects are raised by some of the fixnum
specific procedures when the result is larger than can fit in a
fixnum. The parameter exc must be a fixnum-overflow-exception
object.
The procedure fixnum-overflow-exception?
returns
#t
when obj is a fixnum-overflow-exception
object and #f
otherwise.
The procedure fixnum-overflow-exception-procedure
returns the procedure that raised exc.
The procedure fixnum-overflow-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (fixnum-overflow-exception? exc)
(list (fixnum-overflow-exception-procedure exc)
(fixnum-overflow-exception-arguments exc))
'not-fixnum-overflow-exception))
> (with-exception-catcher
handler
(lambda () (fx* 100000 100000)))
(#<procedure #2 fx*> (100000 100000))
|
8.1.6 Flonum specific operations
8.1.7 Pseudo random numbers
The procedures and variables defined in this section are compatible
with the “Sources of Random Bits SRFI” (SRFI 27). The
implementation is based on Pierre L’Ecuyer’s MRG32k3a pseudo random
number generator. At the heart of SRFI 27’s interface is the random
source type which encapsulates the state of a pseudo random number
generator. The state of a random source object changes every time a
pseudo random number is generated from this random source object.
The global variable default-random-source
is bound to the
random source object which is used by the random-integer
,
random-real
, random-u8vector
and random-f64vector
procedures.
This procedure returns a pseudo random exact integer in the range 0 to
n-1. The random source object in the global variable
default-random-source
is used to generate this number. The
parameter n must be a positive exact integer.
For example:
| > (random-integer 100)
24
> (random-integer 100)
2
> (random-integer 10000000000000000000000000000000000000000)
6143360270902284438072426748425263488507
|
This procedure returns a pseudo random inexact real between, but not
including, 0 and 1. The random source object in the global variable
default-random-source
is used to generate this number.
For example:
| > (random-real)
.24230672079133753
> (random-real)
.02317001922506932
|
This procedure returns a u8vector of length n containing pseudo
random exact integers in the range 0 to 255. The random source object
in the global variable default-random-source
is used to
generate these numbers. The parameter n must be a nonnegative
exact integer.
For example:
| > (random-u8vector 10)
#u8(200 53 29 202 3 85 208 187 73 219)
|
This procedure returns a f64vector of length n containing pseudo
random inexact reals between, but not including, 0 and 1. The random
source object in the global variable default-random-source
is
used to generate these numbers. The parameter n must be a nonnegative
exact integer.
For example:
| > (random-f64vector 3)
#f64(.7145854494613069 .47089632669147946 .5400124875182746)
|
This procedure returns a new random source object initialized to a
predetermined state (to initialize to a pseudo random state the
procedure random-source-randomize!
should be called).
For example:
| > (define rs (make-random-source))
> ((random-source-make-integers rs) 10000000)
8583952
|
This procedure returns #t
when obj is a random source
object and #f
otherwise.
For example:
| > (random-source? default-random-source)
#t
> (random-source? 123)
#f
|
The procedure random-source-state-ref
extracts the state of
the random source object random-source and returns a vector
containing the state.
The procedure random-source-state-set!
restores the state of
the random source object random-source to state which must
be a vector returned from a call to the procedure
random-source-state-ref
.
For example:
| > (define s (random-source-state-ref default-random-source))
> (random-integer 10000000000000000000000000000000000000000)
7583880188903074396261960585615270693321
> (random-source-state-set! default-random-source s)
> (random-integer 10000000000000000000000000000000000000000)
7583880188903074396261960585615270693321
|
These procedures change the state of the random source object
random-source. The procedure random-source-randomize!
sets the random source object to a state that depends on the current
time (which for typical uses can be considered to randomly initialize
the state). The procedure random-source-pseudo-randomize!
sets the random source object to a state that is determined only by
the current state and the nonnegative exact integers i and
j. For both procedures the value returned is unspecified.
For example:
| > (define s (random-source-state-ref default-random-source))
> (random-source-pseudo-randomize! default-random-source 5 99)
> (random-integer 10000000000000000000000000000000000000000)
9816755163910623041601722050112674079767
> (random-source-state-set! default-random-source s)
> (random-source-pseudo-randomize! default-random-source 5 99)
> (random-integer 10000000000000000000000000000000000000000)
9816755163910623041601722050112674079767
> (random-source-pseudo-randomize! default-random-source 5 99)
> (random-integer 10000000000000000000000000000000000000000)
9816755163910623041601722050112674079767
> (random-source-state-set! default-random-source s)
> (random-source-randomize! default-random-source)
> (random-integer 10000000000000000000000000000000000000000)
2271441220851914333384493143687768110622
> (random-source-state-set! default-random-source s)
> (random-source-randomize! default-random-source)
> (random-integer 10000000000000000000000000000000000000000)
6247966138948323029033944059178072366895
|
This procedure returns a procedure for generating pseudo random exact
integers using the random source object random-source. The
returned procedure accepts a single parameter n, a positive
exact integer, and returns a pseudo random exact integer in the range
0 to n-1.
For example:
| > (define rs (make-random-source))
> (define ri (random-source-make-integers rs))
> (ri 10000000)
8583952
> (ri 10000000)
2879793
|
This procedure returns a procedure for generating pseudo random
inexact reals using the random source object random-source. The
returned procedure accepts no parameters and returns a pseudo random
inexact real between, but not including, 0 and 1. The optional parameter
precision specifies an upper bound on the minimum amount by which two
generated pseudo-random numbers can be separated.
For example:
| > (define rs (make-random-source))
> (define rr (random-source-make-reals rs))
> (rr)
.857402537562821
> (rr)
.2876463473845367
|
This procedure returns a procedure for generating pseudo random
u8vectors using the random source object random-source. The
returned procedure accepts a single parameter n, a nonnegative
exact integer, and returns a u8vector of length n containing
pseudo random exact integers in the range 0 to 255.
For example:
| > (define rs (make-random-source))
> (define rv (random-source-make-u8vectors rs))
> (rv 10)
#u8(200 53 29 202 3 85 208 187 73 219)
> (rv 10)
#u8(113 8 182 120 138 103 53 192 40 176)
|
This procedure returns a procedure for generating pseudo random
f64vectors using the random source object random-source. The
returned procedure accepts a single parameter n, a nonnegative
exact integer, and returns an f64vector of length n containing
pseudo random inexact reals between, but not including, 0 and 1.
The optional parameter precision specifies an upper bound on the
minimum amount by which two generated pseudo-random numbers can be separated.
For example:
| > (define rs (make-random-source))
> (define rv (random-source-make-f64vectors rs))
> (rv 3)
#f64(.7342236104231586 .2876463473845367 .8574025375628211)
> (rv 3)
#f64(.013863292728449427 .33449296573515447 .8162050798467028)
|
8.1.8 Division
Division procedures in SRFI 141 that are not in R7RS.
8.2 Booleans
8.3 Pairs and lists
8.4 Symbols and keywords
8.5 Characters and strings
Gambit supports the Unicode character encoding standard. Scheme
characters can be any of the characters whose Unicode encoding is in
the range 0 to #x10ffff (inclusive) but not in the range #xd800 to
#xdfff. Source code can also contain any Unicode character, 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. ISO-8859-1, UTF-8, UTF-16, etc). This can be done by specifying
the runtime option ‘-:file-settings=...’ or ‘-:io-settings=...’
when gsi
and gsc
are started.
8.6 Extensions to character procedures
The procedure char->integer
returns the Unicode encoding of
the character char.
The procedure integer->char
returns the character whose
Unicode encoding is the exact integer n.
For example:
| > (char->integer #\!)
33
> (integer->char 65)
#\A
> (integer->char (char->integer #\u1234))
#\u1234
> (integer->char #xd800)
*** ERROR IN (console)@4.1 -- (Argument 1) Out of range
(integer->char 55296)
|
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 characters
lst
is sorted in nondecreasing order can be done with the call
(apply char<? lst)
.
8.7 Extensions to string procedures
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 strings
lst
is sorted in nondecreasing order can be done with the call
(apply string<? lst)
.
8.8 Vectors
8.9 Homogeneous numeric vectors
Homogeneous vectors are vectors containing raw numbers of the same
type (signed or unsigned exact integers or inexact reals). There are
10 types of homogeneous vectors:
‘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).
The lexical syntax of homogeneous vectors is specified in
Homogeneous vector syntax.
The procedures available for homogeneous vectors, listed below, are
the analog of the normal vector/string procedures for each of the
homogeneous vector types.
( s8vector-copy! dest-s8vector dest-start s8vector [start [end]]) | procedure |
( u8vector-copy! dest-u8vector dest-start u8vector [start [end]]) | procedure |
( s16vector-copy! dest-s16vector dest-start s16vector [start [end]]) | procedure |
( u16vector-copy! dest-u16vector dest-start u16vector [start [end]]) | procedure |
( s32vector-copy! dest-s32vector dest-start s32vector [start [end]]) | procedure |
( u32vector-copy! dest-u32vector dest-start u32vector [start [end]]) | procedure |
( s64vector-copy! dest-s64vector dest-start s64vector [start [end]]) | procedure |
( u64vector-copy! dest-u64vector dest-start u64vector [start [end]]) | procedure |
( f32vector-copy! dest-f32vector dest-start f32vector [start [end]]) | procedure |
( f64vector-copy! dest-f64vector dest-start f64vector [start [end]]) | procedure |
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)
> (u8vector-shrink! v 2)
> (v)
#u8(10 255)
|
The procedure object->u8vector
returns a u8vector that contains
the sequence of bytes that encodes the object obj. The
procedure u8vector->object
decodes the sequence of bytes
contained in the u8vector u8vector, which was produced by the
procedure object->u8vector
, and reconstructs an object
structurally equal to the original object. In other words the
procedures object->u8vector
and u8vector->object
respectively perform serialization and deserialization of Scheme
objects. Note that some objects are non-serializable (e.g. threads,
wills, some types of ports, and any object containing a
non-serializable object).
The optional encoder and decoder parameters are single
parameter procedures which default to the identity function. The
encoder procedure is called during serialization. As the
serializer walks through obj, it calls the encoder
procedure on each sub-object X that is encountered. The
encoder transforms the object X into an object Y
that will be serialized instead of X. Similarly the
decoder procedure is called during deserialization. When an
object Y is encountered, the decoder procedure is called
to transform it into the object X that is the result of
deserialization.
The encoder and decoder procedures are useful to customize
the serialized representation of objects. In particular, it can be
used to define the semantics of serializing objects, such as threads
and ports, that would otherwise not be serializable. The
decoder procedure is typically the inverse of the encoder
procedure, i.e. (decoder (encoder X))
=
X
.
For example:
| > (define (make-adder x) (lambda (y) (+ x y)))
> (define f (make-adder 10))
> (define a (object->u8vector f))
> (define b (u8vector->object a))
> (u8vector-length a)
1639
> (f 5)
15
> (b 5)
15
> (pp b)
(lambda (y) (+ x y))
|
8.10 Hashing and weak references
8.10.1 Hashing
All Scheme objects are uniquely identified with a serial number which
is a nonnegative exact integer. The object->serial-number
procedure
returns the serial number of object obj. This serial number is
only allocated the first time the object->serial-number
procedure is called on that object. Objects which do not have an
external textual representation that can be read by the read
procedure, use an external textual representation that includes a
serial number of the form #n
. Consequently, the
procedures write
, pretty-print
, etc will call the
object->serial-number
procedure to get the serial number, and
this may cause the serial number to be allocated.
The serial-number->object
procedure takes an exact integer
parameter n and returns the object whose serial number is
n. If no object currently exists with that serial number,
default is returned if it is specified, otherwise an
unbound-serial-number-exception object is raised. The reader defines
the following abbreviation for calling serial-number->object
:
the syntax #n
, where n is a sequence of decimal
digits and it is not followed by ‘=
’ or ‘#
’,
is equivalent to the list (serial-number->object n)
.
For example:
| > (define z (list (lambda (x) (* x x)) (lambda (y) (/ 1 y))))
> z
(#<procedure #2> #<procedure #3>)
> (#3 10)
1/10
> '(#3 10)
((serial-number->object 3) 10)
> car
#<procedure #4 car>
> (#4 z)
#<procedure #2>
|
Unbound-serial-number-exception objects are raised by the procedure
serial-number->object
when no object currently exists with that
serial number. The parameter exc must be an
unbound-serial-number-exception object.
The procedure unbound-serial-number-exception?
returns
#t
when obj is a unbound-serial-number-exception
object and #f
otherwise.
The procedure unbound-serial-number-exception-procedure
returns the procedure that raised exc.
The procedure unbound-serial-number-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (unbound-serial-number-exception? exc)
(list (unbound-serial-number-exception-procedure exc)
(unbound-serial-number-exception-arguments exc))
'not-unbound-serial-number-exception))
> (with-exception-catcher
handler
(lambda () (serial-number->object 1000)))
(#<procedure #2 serial-number->object> (1000))
|
The symbol-hash
procedure returns the hash number of the symbol
symbol. The hash number is a small exact integer (fixnum).
When symbol is an interned symbol the value returned is the same
as (string=?-hash (symbol->string symbol))
.
For example:
| > (symbol-hash 'car)
444471047
|
The keyword-hash
procedure returns the hash number of the
keyword keyword. The hash number is a small exact integer
(fixnum). When keyword is an interned keyword the value
returned is the same as (string=?-hash (keyword->string
keyword))
.
For example:
| > (keyword-hash car:)
444471047
|
The string=?-hash
procedure returns the hash number of the
string string. The hash number is a small exact integer
(fixnum). For any two strings s1 and s2, (string=?
s1 s2)
implies (= (string=?-hash s1)
(string=?-hash s2))
.
For example:
| > (string=?-hash "car")
444471047
|
The string-ci=?-hash
procedure returns the hash number of the
string string. The hash number is a small exact integer
(fixnum). For any two strings s1 and s2, (string-ci=?
s1 s2)
implies (= (string-ci=?-hash s1)
(string-ci=?-hash s2))
.
For example:
| > (string-ci=?-hash "CaR")
444471047
|
The eq?-hash
procedure returns the hash number of the object
obj. The hash number is a small exact integer (fixnum). For
any two objects o1 and o2, (eq? o1 o2)
implies (= (eq?-hash o1) (eq?-hash o2))
.
For example:
| > (eq?-hash #t)
536870910
|
The eqv?-hash
procedure returns the hash number of the object
obj. The hash number is a small exact integer (fixnum). For
any two objects o1 and o2, (eqv? o1 o2)
implies (= (eqv?-hash o1) (eqv?-hash o2))
.
For example:
| > (eqv?-hash 1.5)
496387656
|
The equal?-hash
procedure returns the hash number of the object
obj. The hash number is a small exact integer (fixnum). For
any two objects o1 and o2, (equal? o1 o2)
implies (= (equal?-hash o1) (equal?-hash o2))
.
For example:
| > (equal?-hash (list 1 2 3))
442438567
|
8.10.2 Weak references
The garbage collector is responsible for reclaiming objects that are
no longer needed by the program. This is done by analyzing the
reachability graph of all objects from the roots (i.e. the global
variables, the runnable threads, permanently allocated objects such as
procedures defined in a compiled file, nonexecutable wills, etc). If
a root or a reachable object X contains a reference to an object
Y then Y is reachable. As a general rule, unreachable
objects are reclaimed by the garbage collector.
There are two types of references: strong references and weak
references. Most objects, including pairs, vectors, records and
closures, contain strong references. An object X is
strongly reachable if there is a path from the roots to X
that traverses only strong references. Weak references only occur in
wills and tables. There are two types of weak references: will-weak
references and table-weak references. If all paths from the roots to
an object Y traverse at least one table-weak reference, then
Y will be reclaimed by the garbage collector. The will-weak
references are used for finalization and are explained in the next
section.
8.10.2.1 Wills
The following procedures implement the will data type. Will
objects provide support for finalization. A will is an object that
contains a will-weak reference to a testator object (the object
attached to the will), and a strong reference to an action
procedure which is a one parameter procedure which is called when the
will is executed.
The make-will
procedure creates a will object with the given
testator object and action procedure. The will?
procedure tests if obj is a will object. The
will-testator
procedure gets the testator object attached to
the will. The will-execute!
procedure executes
will.
A will becomes executable when its testator object is not
strongly reachable (i.e. the testator object is either
unreachable or only reachable using paths from the roots that traverse
at least one weak reference). Some objects, including symbols, small
exact integers (fixnums), booleans and characters, are considered to
be always strongly reachable.
When the runtime system detects that a will has become executable the
current computation is interrupted, the will’s testator is set to
#f
and the will’s action procedure is called with the will’s
testator as the sole argument. Currently only the garbage collector
detects when wills become executable but this may change in future
versions of Gambit (for example the compiler could perform an analysis
to infer will executability at compile time). The garbage collector
builds a list of all executable wills. 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 determined executability of the will. It is only when
an object is not reachable from the roots that it is reclaimed by the
garbage collector.
A remarkable feature of wills is that an action procedure can
“resurrect” an object. An action procedure could for example assign
the testator object to a global variable or create a new will with the
same testator object.
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
|
8.10.3 Tables
The following procedures implement the table data type. Tables
are heterogenous structures whose elements are indexed by keys which
are arbitrary objects. Tables are similar to association lists but
are abstract and the access time for large tables is typically smaller.
Each key contained in the table is bound to a value. The length of
the table is the number of key/value bindings it contains. New
key/value bindings can be added to a table, the value bound to a key
can be changed, and existing key/value bindings can be removed.
The references to the keys can either be all strong or all table-weak
and the references to the values can either be all strong or all
table-weak. The garbage collector removes key/value bindings from a
table when 1) the key is a table-weak reference and the key is
unreachable or only reachable using paths from the roots that traverse
at least one table-weak reference, or 2) the value is a table-weak
reference and the value is unreachable or only reachable using paths
from the roots that traverse at least one table-weak reference.
Key/value bindings that are removed by the garbage collector are
reclaimed immediately.
Although there are several possible ways of implementing tables, the
current implementation uses hashing with open-addressing. This is
space efficient and provides constant-time access. Hash tables are
automatically resized to maintain the load within specified bounds.
The load is the number of active entries (the length of the table)
divided by the total number of entries in the hash table.
Tables are parameterized with a key comparison procedure. By default
the equal?
procedure is used, but eq?
, eqv?
,
string=?
, string-ci=?
, or a user defined procedure can
also be used. To support arbitrary key comparison procedures, tables
are also parameterized with a hashing procedure accepting a key as its
single parameter and returning a fixnum result. The hashing procedure
hash must be consistent with the key comparison procedure
test, that is, for any two keys k1 and k2 in the
table, (test k1 k2)
implies (=
(hash k1) (hash k2))
. A default hashing
procedure consistent with the key comparison procedure is provided by
the system. The default hashing procedure generally gives good
performance when the key comparison procedure is eq?
,
eqv?
, equal?
, string=?
, and string-ci=?
.
However, for user defined key comparison procedures, the default
hashing procedure always returns 0. This degrades the performance of
the table to a linear search.
Tables can be compared for equality using the equal?
procedure.
Two tables X
and Y
are considered equal by
equal?
when they have the same weakness attributes, the same
key comparison procedure, the same hashing procedure, the same length,
and for all the keys k
in X
, (equal?
(table-ref X k) (table-ref Y k))
.
( make-table [size: size] [init: init] [weak-keys: weak-keys] [weak-values: weak-values] [test: test] [hash: hash] [min-load: min-load] [max-load: max-load]) | procedure |
The procedure make-table
returns a new table. The optional keyword
parameters specify various parameters of the table.
The size parameter is a nonnegative exact integer indicating
the expected length of the table. The system uses size to
choose an appropriate initial size of the hash table so that it does not
need to be resized too often.
The init parameter indicates a value that is associated to keys
that are not in the table. When init is not specified, no value
is associated to keys that are not in the table.
The weak-keys and weak-values parameters are extended
booleans indicating respectively whether the keys and values are
table-weak references (true) or strong references (false). By default
the keys and values are strong references.
The test parameter indicates the key comparison procedure. The
default key comparison procedure is equal?
. The key comparison
procedures eq?
, eqv?
, equal?
, string=?
,
and string-ci=?
are special because the system will use a
reasonably good hash procedure when none is specified.
The hash parameter indicates the hash procedure. This procedure
must accept a single key parameter, return a fixnum, and be consistent
with the key comparison procedure. When hash is not specified, a
default hash procedure is used. The default hash procedure is
reasonably good when the key comparison procedure is eq?
,
eqv?
, equal?
, string=?
, or string-ci=?
.
The min-load and max-load parameters are real numbers that
indicate the minimum and maximum load of the table respectively. The
table is resized when adding or deleting a key/value binding would
bring the table’s load outside of this range. The min-load
parameter must be no less than 0.05 and the max-load parameter
must be no greater than 0.95. Moreover the difference between
min-load and max-load must be at least 0.20. When
min-load is not specified, the value 0.45 is used. When
max-load is not specified, the value 0.90 is used.
For example:
| > (define t (make-table))
> (table? t)
#t
> (table-length t)
0
> (table-set! t (list 1 2) 3)
> (table-set! t (list 4 5) 6)
> (table-ref t (list 1 2))
3
> (table-length t)
2
|
The procedure table?
returns #t
when obj is a
table and #f
otherwise.
For example:
| > (table? (make-table))
#t
> (table? 123)
#f
|
The procedure table-length
returns the number of key/value
bindings contained in the table table.
For example:
| > (define t (make-table weak-keys: #t))
> (define x (list 1 2))
> (define y (list 3 4))
> (table-set! t x 111)
> (table-set! t y 222)
> (table-length t)
2
> (table-set! t x)
> (table-length t)
1
> (##gc)
> (table-length t)
1
> (set! y #f)
> (##gc)
> (table-length t)
0
|
The procedure table-ref
returns the value bound to the object
key in the table table. When key is not bound and
default is specified, default is returned. When
default is not specified but an init parameter was
specified when table was created, init is returned.
Otherwise an unbound-key-exception object is raised.
For example:
| > (define t1 (make-table init: 999))
> (table-set! t1 (list 1 2) 3)
> (table-ref t1 (list 1 2))
3
> (table-ref t1 (list 4 5))
999
> (table-ref t1 (list 4 5) #f)
#f
> (define t2 (make-table))
> (table-ref t2 (list 4 5))
*** ERROR IN (console)@7.1 -- Unbound key
(table-ref '#<table #2> '(4 5))
|
The procedure table-set!
binds the object key to
value in the table table. When value is not
specified, if table contains a binding for key then the
binding is removed from table. The procedure table-set!
returns an unspecified value.
For example:
| > (define t (make-table))
> (table-set! t (list 1 2) 3)
> (table-set! t (list 4 5) 6)
> (table-set! t (list 4 5))
> (table-set! t (list 7 8))
> (table-ref t (list 1 2))
3
> (table-ref t (list 4 5))
*** ERROR IN (console)@7.1 -- Unbound key
(table-ref '#<table #2> '(4 5))
|
The procedure table-search
searches the table table for a
key/value binding for which the two parameter procedure proc
returns a non false result. For each key/value binding visited by
table-search
the procedure proc is called with the key as
the first parameter and the value as the second parameter. The
procedure table-search
returns the first non false value
returned by proc, or #f
if proc returned #f
for all key/value bindings in table.
The order in which the key/value bindings are visited is unspecified
and may vary from one call of table-search
to the next. While
a call to table-search
is being performed on table, it is
an error to call any of the following procedures on table:
table-ref
, table-set!
, table-search
,
table-for-each
, table-copy
, table-merge
,
table-merge!
, and table->list
. It is also an error to
compare with equal?
(directly or indirectly with member
,
assoc
, table-ref
, etc.) an object that contains
table. All these procedures may cause table to be
reordered and resized. This restriction allows a more efficient
iteration over the key/value bindings.
For example:
| > (define square (make-table))
> (table-set! square 2 4)
> (table-set! square 3 9)
> (table-search (lambda (k v) (and (odd? k) v)) square)
9
|
The procedure table-for-each
calls the two parameter procedure
proc for each key/value binding in the table table. The
procedure proc is called with the key as the first parameter and
the value as the second parameter. The procedure table-for-each
returns an unspecified value.
The order in which the key/value bindings are visited is unspecified
and may vary from one call of table-for-each
to the next.
While a call to table-for-each
is being performed on
table, it is an error to call any of the following procedures on
table: table-ref
, table-set!
, table-search
,
table-for-each
, and table->list
. It is also an error to
compare with equal?
(directly or indirectly with member
,
assoc
, table-ref
, etc.) an object that contains
table. All these procedures may cause table to be
reordered and resized. This restriction allows a more efficient
iteration over the key/value bindings.
For example:
| > (define square (make-table))
> (table-set! square 2 4)
> (table-set! square 3 9)
> (table-for-each (lambda (k v) (write (list k v)) (newline)) square)
(2 4)
(3 9)
|
The procedure table->list
returns an association list
containing the key/value bindings in the table table. Each
key/value binding yields a pair whose car field is the key and whose
cdr field is the value bound to that key. The order of the bindings
in the list is unspecified.
For example:
| > (define square (make-table))
> (table-set! square 2 4)
> (table-set! square 3 9)
> (table->list square)
((3 . 9) (2 . 4))
|
( list->table list [size: size] [init: init] [weak-keys: weak-keys] [weak-values: weak-values] [test: test] [hash: hash] [min-load: min-load] [max-load: max-load]) | procedure |
The procedure list->table
returns a new table containing the
key/value bindings in the association list list. The optional
keyword parameters specify various parameters of the table and have
the same meaning as for the make-table
procedure.
Each element of list is a pair whose car field is a key and
whose cdr field is the value bound to that key. If a key appears more
than once in list (tested using the table’s key comparison
procedure) it is the first key/value binding in list that has
precedence.
For example:
| > (define t (list->table '((b . 2) (a . 1) (c . 3) (a . 4))))
> (table->list t)
((a . 1) (b . 2) (c . 3))
|
Unbound-key-exception objects are raised by the procedure
table-ref
when the key does not have a binding in the table.
The parameter exc must be an unbound-key-exception object.
The procedure unbound-key-exception?
returns
#t
when obj is a unbound-key-exception
object and #f
otherwise.
The procedure unbound-key-exception-procedure
returns the procedure that raised exc.
The procedure unbound-key-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define t (make-table))
> (define (handler exc)
(if (unbound-key-exception? exc)
(list (unbound-key-exception-procedure exc)
(unbound-key-exception-arguments exc))
'not-unbound-key-exception))
> (with-exception-catcher
handler
(lambda () (table-ref t '(1 2))))
(#<procedure #2 table-ref> (#<table #3> (1 2)))
|
The procedure table-copy
returns a new table containing the
same key/value bindings as table and the same table parameters
(i.e. hash procedure, key comparison procedure, key and value
weakness, etc).
For example:
| > (define t (list->table '((b . 2) (a . 1) (c . 3))))
> (define x (table-copy t))
> (table-set! t 'b 99)
> (table->list t)
((a . 1) (b . 99) (c . 3))
> (table->list x)
((a . 1) (b . 2) (c . 3))
|
( table-merge! table1 table2 [table2-takes-precedence?]) | procedure |
The procedure table-merge!
returns table1 after the
key/value bindings contained in table2 have been added to it.
When a key exists both in table1 and table2, then the
parameter table2-takes-precedence? indicates which binding will
be kept (the one in table1 if table2-takes-precedence? is
false, and the one in table2 otherwise). If
table2-takes-precedence? is not specified the binding in
table1 is kept.
For example:
| > (define t1 (list->table '((a . 1) (b . 2) (c . 3))))
> (define t2 (list->table '((a . 4) (b . 5) (z . 6))))
> (table->list (table-merge! t1 t2))
((a . 1) (b . 2) (c . 3) (z . 6))
> (define t1 (list->table '((a . 1) (b . 2) (c . 3))))
> (define t2 (list->table '((a . 4) (b . 5) (z . 6))))
> (table->list (table-merge! t1 t2 #t))
((a . 4) (b . 5) (c . 3) (z . 6))
|
( table-merge table1 table2 [table2-takes-precedence?]) | procedure |
The procedure table-merge
returns a copy of table1
(created with table-copy
) to which the key/value bindings
contained in table2 have been added using table-merge!
.
When a key exists both in table1 and table2, then the
parameter table2-takes-precedence? indicates which binding will
be kept (the one in table1 if table2-takes-precedence? is
false, and the one in table2 otherwise). If
table2-takes-precedence? is not specified the binding in
table1 is kept.
For example:
| > (define t1 (list->table '((a . 1) (b . 2) (c . 3))))
> (define t2 (list->table '((a . 4) (b . 5) (z . 6))))
> (table->list (table-merge t1 t2))
((a . 1) (b . 2) (c . 3) (z . 6))
> (table->list (table-merge t1 t2 #t))
((a . 4) (b . 5) (c . 3) (z . 6))
|
9. Records
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:
-
‘make-name’ – A k argument procedure which constructs
a new record from the value of its k fields.
-
‘name?’ – A procedure which tests if its single argument
is of the given record type.
-
‘name-field’ – For each field, a procedure taking
as its single argument a value of the given record type and returning
the content of the corresponding field of the record.
-
‘name-field-set!’ – For each field, a two
argument procedure taking as its first argument a value of the given
record type. The second argument gets assigned to the corresponding
field of the record and the void object is returned.
Record data types have a printed representation that 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 #2 x: 3 y: 5 color: red>
> (point-x p)
3
> (point-color p)
red
> (point-color-set! p 'black)
> p
#<point #2 x: 3 y: 5 color: black>
|
10. Threads
Gambit supports the execution of multiple Scheme threads. These
threads are managed entirely by Gambit’s runtime and are not related
to the host operating system’s threads. Gambit’s runtime does not
currently take advantage of multiprocessors (i.e. at most one thread is
running).
10.1 Introduction
Multithreading is a paradigm that is well suited for building complex
systems such as: servers, GUIs, and high-level operating systems.
Gambit’s thread system offers mechanisms for creating threads of
execution and for synchronizing them. The thread system also supports
features which are useful in a real-time context, such as priorities,
priority inheritance and timeouts.
The thread system provides the following data types:
-
Thread (a virtual processor which shares object space with all other
threads)
-
Mutex (a mutual exclusion device, also known as a lock and binary
semaphore)
-
Condition variable (a set of blocked threads)
10.2 Thread objects
A running thread is a thread that is currently executing. A
runnable thread is a thread that is ready to execute or running.
A thread is blocked if it is waiting for a mutex to become
unlocked, an I/O operation to become possible, the end of a “sleep”
period, etc. A new thread is a thread that has been allocated
but has not yet been initialized. An initialized thread is a
thread that can be made runnable. A new thread becomes runnable when
it is started by calling thread-start!
. A terminated
thread is a thread that can no longer become runnable (but
deadlocked threads are not considered terminated). The only
valid transitions between the thread states are from new to
initialized, from initialized to runnable, between runnable and
blocked, and from any state except new to terminated as indicated in
the following diagram:
| unblock
start <-------
NEW -------> INITIALIZED -------> RUNNABLE -------> BLOCKED
\ | block /
\ v /
+-----> TERMINATED <----+
|
Each thread has a base priority, which is a real number (where a
higher numerical value means a higher priority), a priority boost,
which is a nonnegative real number representing the priority increase
applied to a thread when it blocks, and a quantum, which is a
nonnegative real number representing a duration in seconds.
Each thread has a specific field which can be used in an
application specific way to associate data with the thread (some thread
systems call this “thread local storage”).
Each thread has a mailbox which is used for inter-thread
communication.
10.3 Mutex objects
A mutex can be in one of four states: locked (either owned
or not owned) and unlocked (either abandoned or
not abandoned).
An attempt to lock a mutex only succeeds if the mutex is in an unlocked
state, otherwise the current thread will wait. A mutex in the
locked/owned state has an associated owner thread, which by
convention is the thread that is responsible for unlocking the mutex
(this case is typical of critical sections implemented as “lock mutex,
perform operation, unlock mutex”). A mutex in the locked/not-owned
state is not linked to a particular thread.
A mutex becomes locked when a thread locks it using the
‘mutex-lock!’ primitive. A mutex becomes unlocked/abandoned when
the owner of a locked/owned mutex terminates. A mutex becomes
unlocked/not-abandoned when a thread unlocks it using the
‘mutex-unlock!’ primitive.
The mutex primitives do not implement recursive mutex semantics.
An attempt to lock a mutex that is locked implies that the current
thread waits even if the mutex is owned by the current thread (this can
lead to a deadlock if no other thread unlocks the mutex).
Each mutex has a specific field which can be used in an
application specific way to associate data with the mutex.
10.4 Condition variable objects
A condition variable represents a set of blocked threads. These blocked
threads are waiting for a certain condition to become true. When a
thread modifies some program state that might make the condition true,
the thread unblocks some number of threads (one or all depending on the
primitive used) so they can check if the condition is now true. This
allows complex forms of interthread synchronization to be expressed more
conveniently than with mutexes alone.
Each condition variable has a specific field which can be used in
an application specific way to associate data with the condition
variable.
10.5 Fairness
In various situations the scheduler must select one thread from a set of
threads (e.g. which thread to run when a running thread blocks or
expires its quantum, which thread to unblock when a mutex becomes
unlocked or a condition variable is signaled). The constraints on the
selection process determine the scheduler’s fairness. The
selection depends on the order in which threads become runnable or
blocked and on the priority attached to the threads.
The definition of fairness requires the notion of time ordering,
i.e. “event A occured before event B”. For the purpose of
establishing time ordering, the scheduler uses a clock with a discrete,
usually variable, resolution (a “tick”). Events occuring in a given
tick can be considered to be simultaneous (i.e. if event A occured
before event B in real time, then the scheduler will claim that
event A occured before event B unless both events fall
within the same tick, in which case the scheduler arbitrarily chooses a
time ordering).
Each thread T has three priorities which affect fairness; the
base priority, the boosted priority, and the effective
priority.
-
The base priority is the value contained in T’s base
priority field (which is set with the ‘thread-base-priority-set!’
primitive).
-
T’s boosted flag field contains a boolean that affects
T’s boosted priority. When the boosted flag field is false,
the boosted priority is equal to the base priority, otherwise the
boosted priority is equal to the base priority plus the value contained
in T’s priority boost field (which is set with the
‘thread-priority-boost-set!’ primitive). The boosted flag field is
set to false when a thread is created, when its quantum expires, and
when thread-yield! is called. The boosted flag field is set to
true when a thread blocks. By carefully choosing the base priority and
priority boost, relatively to the other threads, it is possible to set
up an interactive thread so that it has good I/O response time without
being a CPU hog when it performs long computations.
-
The effective priority is equal to the maximum of T’s
boosted priority and the effective priority of all the threads that are
blocked on a mutex owned by T. This priority inheritance
avoids priority inversion problems that would prevent a high priority
thread blocked at the entry of a critical section to progress because a
low priority thread inside the critical section is preempted for an
arbitrary long time by a medium priority thread.
Let P(T) be the effective priority of thread T and
let R(T) be the most recent time when one of the following
events occurred for thread T, thus making it runnable: T
was started by calling ‘thread-start!’, T called
‘thread-yield!’, T expired its quantum, or T became
unblocked. Let the relation NL(T1,T2), “T1
no later than T2”, be true if
P(T1)<P(T2) or
P(T1)=P(T2) and
R(T1)>R(T2), and false otherwise. The
scheduler will schedule the execution of threads in such a way that
whenever there is at least one runnable thread, 1) within a finite
time at least one thread will be running, and 2) there is never a pair
of runnable threads T1 and T2 for which
NL(T1,T2) is true and T1 is not running and
T2 is running.
A thread T expires its quantum when an amount of time equal to
T’s quantum has elapsed since T entered the running state
and T did not block, terminate or call ‘thread-yield!’.
At that point T exits the running state to allow other threads to
run. A thread’s quantum is thus an indication of the rate of progress
of the thread relative to the other threads of the same priority.
Moreover, the resolution of the timer measuring the running time may
cause a certain deviation from the quantum, so a thread’s quantum should
only be viewed as an approximation of the time it can run before
yielding to another thread.
Threads blocked on a given mutex or condition variable will unblock in
an order which is consistent with decreasing priority and increasing
blocking time (i.e. the highest priority thread unblocks first, and
among equal priority threads the one that blocked first unblocks first).
10.6 Memory coherency
Read and write operations on the store (such as reading and writing a
variable, an element of a vector or a string) are not atomic. It is
an error for a thread to write a location in the store while some
other thread reads or writes that same location. It is the
responsibility of the application to avoid write/read and write/write
races through appropriate uses of the synchronization primitives.
Concurrent reads and writes to ports are allowed. It is the
responsibility of the implementation to serialize accesses to a given
port using the appropriate synchronization primitives.
10.7 Timeouts
All synchronization primitives which take a timeout parameter accept
three types of values as a timeout, with the following meaning:
-
a time object represents an absolute point in time
-
an exact or inexact real number represents a relative time in
seconds from the moment the primitive was called
-
‘#f’ means that there is no timeout
When a timeout denotes the current time or a time in the past, the
synchronization primitive claims that the timeout has been reached
only after the other synchronization conditions have been checked.
Moreover the thread remains running (it does not enter the blocked
state). For example, (mutex-lock! m 0)
will lock mutex
m
and return ‘#t’ if m
is
currently unlocked, otherwise ‘#f’ is returned because the
timeout is reached.
10.8 Primordial thread
The execution of a program is initially under the control of a single
thread known as the primordial thread. The primordial thread has an
unspecified
base priority, priority boost, boosted flag, quantum,
name, specific field, dynamic environment, ‘dynamic-wind’
stack, and exception-handler. All threads are terminated when the
primordial thread terminates (normally or not).
10.9 Procedures
This procedure returns the current thread. For example:
| > (current-thread)
#<thread #1 primordial>
> (eq? (current-thread) (current-thread))
#t
|
This procedure returns #t
when obj is a thread object and
#f
otherwise.
For example:
| > (thread? (current-thread))
#t
> (thread? 'foo)
#f
|
( make-root-thread thunk [name [thread-group [input-port [output-port]]]]) | procedure |
The make-thread
procedure creates and returns an initialized
thread. This thread is not automatically made runnable (the procedure
thread-start!
must be used for this). A thread has the
following fields: base priority, priority boost, boosted flag,
quantum, name, specific, end-result, end-exception, and a list of
locked/owned mutexes it owns. The thread’s execution consists of a
call to thunk with the initial continuation. This
continuation causes the (then) current thread to store the result in
its end-result field, abandon all mutexes it owns, and finally
terminate. The ‘dynamic-wind’ stack of the initial continuation
is empty. The optional name is an arbitrary Scheme object which
identifies the thread (useful for debugging); it defaults to an
unspecified value. The specific field is set to an unspecified value.
The optional thread-group indicates which thread group this
thread belongs to; it defaults to the thread group of the current
thread. The base priority, priority boost, and quantum of the thread
are set to the same value as the current thread and the boosted flag
is set to false. The thread’s mailbox is initially empty. The thread
inherits the dynamic environment from the current thread. Moreover, in
this dynamic environment the exception-handler is bound to the
initial exception-handler which is a unary procedure which
causes the (then) current thread to store in its end-exception field
an uncaught-exception object whose “reason” is the argument of the
handler, abandon all mutexes it owns, and finally terminate.
The make-root-thread
procedure behaves like the
make-thread
procedure except the created thread does not
inherit the dynamic environment from the current thread and the base
priority is set to 0, the priority boost is set to 1.0e-6, and the
quantum is set to 0.02. The dynamic environment of the thread has the
global bindings of the parameter objects, except
current-input-port
which is bound to input-port,
current-output-port
which is bound to output-port, and
current-directory
which is bound to the initial current working
directory of the current process. If input-port is not
specified it defaults to a port corresponding to the standard input
(‘stdin’). If output-port is not specified it defaults to
a port corresponding to the standard output (‘stdout’).
For example:
| > (make-thread (lambda () (write 'hello)))
#<thread #2>
> (make-root-thread (lambda () (write 'world)) 'a-name)
#<thread #3 a-name>
|
The thread
procedure creates, starts and returns a new thread.
The call (thread thunk)
is equivalent to
(thread-start! (make-thread thunk))
.
For example:
| > (define a (thread (lambda () (expt 2 1005))))
> (define b (thread (lambda () (expt 2 1000))))
> (/ (thread-join! a) (thread-join! b))
32
|
This procedure returns the name of the thread. For example:
| > (thread-name (make-thread (lambda () #f) 'foo))
foo
|
The thread-specific
procedure returns the content of the
thread’s specific field.
The thread-specific-set!
procedure stores obj into the
thread’s specific field and returns an unspecified value.
For example:
| > (thread-specific-set! (current-thread) "hello")
> (thread-specific (current-thread))
"hello"
|
The procedure thread-base-priority
returns a real number which
corresponds to the base priority of the thread.
The procedure thread-base-priority-set!
changes the base
priority of the thread to priority and returns an
unspecified value. The priority must be a real number.
For example:
| > (thread-base-priority-set! (current-thread) 12.3)
> (thread-base-priority (current-thread))
12.3
|
The procedure thread-priority-boost
returns a real number which
corresponds to the priority boost of the thread.
The procedure thread-priority-boost-set!
changes the priority
boost of the thread to priority-boost and returns an
unspecified value. The priority-boost must be a nonnegative
real.
For example:
| > (thread-priority-boost-set! (current-thread) 2.5)
> (thread-priority-boost (current-thread))
2.5
|
The procedure thread-quantum
returns a real number which
corresponds to the quantum of the thread.
The procedure thread-quantum-set!
changes the quantum of the
thread to quantum and returns an unspecified value. The
quantum must be a nonnegative real. A value of zero selects the
smallest quantum supported by the implementation.
For example:
| > (thread-quantum-set! (current-thread) 1.5)
> (thread-quantum (current-thread))
1.5
> (thread-quantum-set! (current-thread) 0)
> (thread-quantum (current-thread))
0.
|
This procedure makes thread runnable and returns the
thread. The thread must be an initialized thread.
For example:
| > (let ((t (thread-start! (make-thread (lambda () (write 'a))))))
(write 'b)
(thread-join! t))
ab> or ba>
|
NOTE: It is useful to separate thread creation and thread activation
to avoid the race condition that would occur if the created thread
tries to examine a table in which the current thread stores the
created thread. See the last example of the thread-terminate!
procedure which contains mutually recursive threads.
This procedure causes the current thread to exit the running state as
if its quantum had expired and returns an unspecified value.
For example:
| ; a busy loop that avoids being too wasteful of the CPU
(let loop ()
(if (mutex-lock! m 0) ; try to lock m but don't block
(begin
(display "locked mutex m")
(mutex-unlock! m))
(begin
(do-something-else)
(thread-yield!) ; relinquish rest of quantum
(loop))))
|
This procedure causes the current thread to wait until the timeout is
reached and returns an unspecified value. This blocks the thread only
if timeout represents a point in the future. It is an error for
timeout to be ‘#f’.
For example:
| ; a clock with a gradual drift:
(let loop ((x 1))
(thread-sleep! 1)
(write x)
(loop (+ x 1)))
; a clock with no drift:
(let ((start (time->seconds (current-time)))
(let loop ((x 1))
(thread-sleep! (seconds->time (+ x start)))
(write x)
(loop (+ x 1))))
|
This procedure causes an abnormal termination of the thread. If
the thread is not already terminated, all mutexes owned by the
thread become unlocked/abandoned and a
terminated-thread-exception object is stored in the thread’s
end-exception field. If thread is the current thread,
thread-terminate!
does not return. Otherwise
thread-terminate!
returns an unspecified value; the termination
of the thread will occur at some point between the calling of
thread-terminate!
and a finite time in the future (an explicit
thread synchronization is needed to detect termination, see
thread-join!
).
For example:
| (define (amb thunk1 thunk2)
(let ((result #f)
(result-mutex (make-mutex))
(done-mutex (make-mutex)))
(letrec ((child1
(make-thread
(lambda ()
(let ((x (thunk1)))
(mutex-lock! result-mutex #f #f)
(set! result x)
(thread-terminate! child2)
(mutex-unlock! done-mutex)))))
(child2
(make-thread
(lambda ()
(let ((x (thunk2)))
(mutex-lock! result-mutex #f #f)
(set! result x)
(thread-terminate! child1)
(mutex-unlock! done-mutex))))))
(mutex-lock! done-mutex #f #f)
(thread-start! child1)
(thread-start! child2)
(mutex-lock! done-mutex #f #f)
result)))
|
NOTE: This operation must be used carefully because it terminates a
thread abruptly and it is impossible for that thread to perform any
kind of cleanup. This may be a problem if the thread is in the middle
of a critical section where some structure has been put in an
inconsistent state. However, another thread attempting to enter this
critical section will raise an abandoned-mutex-exception object
because the mutex is unlocked/abandoned. This helps avoid observing
an inconsistent state. Clean termination can be obtained by polling,
as shown in the example below.
For example:
| (define (spawn thunk)
(let ((t (make-thread thunk)))
(thread-specific-set! t #t)
(thread-start! t)
t))
(define (stop! thread)
(thread-specific-set! thread #f)
(thread-join! thread))
(define (keep-going?)
(thread-specific (current-thread)))
(define count!
(let ((m (make-mutex))
(i 0))
(lambda ()
(mutex-lock! m)
(let ((x (+ i 1)))
(set! i x)
(mutex-unlock! m)
x))))
(define (increment-forever!)
(let loop () (count!) (if (keep-going?) (loop))))
(let ((t1 (spawn increment-forever!))
(t2 (spawn increment-forever!)))
(thread-sleep! 1)
(stop! t1)
(stop! t2)
(count!)) ==> 377290
|
This procedure causes the current thread to wait until the
thread terminates (normally or not) or until the timeout is
reached if timeout is supplied. If the timeout is reached,
thread-join! returns timeout-val if it is supplied,
otherwise a join-timeout-exception object is raised. If the
thread terminated normally, the content of the end-result field
is returned, otherwise the content of the end-exception field is
raised.
For example:
| (let ((t (thread-start! (make-thread (lambda () (expt 2 100))))))
(do-something-else)
(thread-join! t)) ==> 1267650600228229401496703205376
(let ((t (thread-start! (make-thread (lambda () (raise 123))))))
(do-something-else)
(with-exception-handler
(lambda (exc)
(if (uncaught-exception? exc)
(* 10 (uncaught-exception-reason exc))
99999))
(lambda ()
(+ 1 (thread-join! t))))) ==> 1231
(define thread-alive?
(let ((unique (list 'unique)))
(lambda (thread)
; Note: this procedure raises an exception if
; the thread terminated abnormally.
(eq? (thread-join! thread 0 unique) unique))))
(define (wait-for-termination! thread)
(let ((eh (current-exception-handler)))
(with-exception-handler
(lambda (exc)
(if (not (or (terminated-thread-exception? exc)
(uncaught-exception? exc)))
(eh exc))) ; unexpected exceptions are handled by eh
(lambda ()
; The following call to thread-join! will wait until the
; thread terminates. If the thread terminated normally
; thread-join! will return normally. If the thread
; terminated abnormally then one of these two exception
; objects is raised by thread-join!:
; - terminated-thread-exception object
; - uncaught-exception object
(thread-join! thread)
#f)))) ; ignore result of thread-join!
|
Each thread has a mailbox which stores messages delivered to the
thread in the order delivered.
The procedure thread-send
adds the message msg at the end
of the mailbox of thread thread and returns an unspecified
value.
For example:
| > (thread-send (current-thread) 111)
> (thread-send (current-thread) 222)
> (thread-receive)
111
> (thread-receive)
222
|
To allow a thread to examine the messages in its mailbox without
removing them from the mailbox, each thread has a mailbox cursor
which normally points to the last message accessed in the mailbox.
When a mailbox cursor is rewound using the procedure
thread-mailbox-rewind
or
thread-mailbox-extract-and-rewind
or thread-receive
, the
cursor does not point to a message, but the next call to
thread-receive
and thread-mailbox-next
will set the
cursor to the oldest message in the mailbox.
The procedure thread-receive
advances the mailbox cursor of the
current thread to the next message, removes that message from the
mailbox, rewinds the mailbox cursor, and returns the message. When
timeout is not specified, the current thread will wait until a
message is available in the mailbox. When timeout is specified
and default is not specified, a
mailbox-receive-timeout-exception object is raised if the timeout is
reached before a message is available. When timeout is
specified and default is specified, default is returned if
the timeout is reached before a message is available.
The procedure thread-mailbox-next
behaves like
thread-receive
except that the message remains in the mailbox
and the mailbox cursor is not rewound.
The procedures thread-mailbox-rewind
or
thread-mailbox-extract-and-rewind
rewind the mailbox cursor of
the current thread so that the next call to thread-mailbox-next
and thread-receive
will access the oldest message in the
mailbox. Additionally the procedure
thread-mailbox-extract-and-rewind
will remove from the mailbox
the message most recently accessed by a call to
thread-mailbox-next
. When thread-mailbox-next
has not
been called since the last call to thread-receive
or
thread-mailbox-rewind
or
thread-mailbox-extract-and-rewind
, a call to
thread-mailbox-extract-and-rewind
only resets the mailbox
cursor (no message is removed).
For example:
| > (thread-send (current-thread) 111)
> (thread-receive 1 999)
111
> (thread-send (current-thread) 222)
> (thread-send (current-thread) 333)
> (thread-mailbox-next 1 999)
222
> (thread-mailbox-next 1 999)
333
> (thread-mailbox-next 1 999)
999
> (thread-mailbox-extract-and-rewind)
> (thread-receive 1 999)
222
> (thread-receive 1 999)
999
|
Mailbox-receive-timeout-exception objects are raised by the procedures
thread-receive
and thread-mailbox-next
when a timeout
expires before a message is available and no default value is
specified. The parameter exc must be a
mailbox-receive-timeout-exception object.
The procedure mailbox-receive-timeout-exception?
returns
#t
when obj is a mailbox-receive-timeout-exception
object and #f
otherwise.
The procedure mailbox-receive-timeout-exception-procedure
returns the procedure that raised exc.
The procedure mailbox-receive-timeout-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (mailbox-receive-timeout-exception? exc)
(list (mailbox-receive-timeout-exception-procedure exc)
(mailbox-receive-timeout-exception-arguments exc))
'not-mailbox-receive-timeout-exception))
> (with-exception-catcher
handler
(lambda () (thread-receive 1)))
(#<procedure #2 thread-receive> (1))
|
This procedure returns #t
when obj is a mutex object and
#f
otherwise.
For example:
| > (mutex? (make-mutex))
#t
> (mutex? 'foo)
#f
|
This procedure returns a new mutex in the unlocked/not-abandoned
state. The optional name is an arbitrary Scheme object which
identifies the mutex (useful for debugging); it defaults to an
unspecified value. The mutex’s specific field is set to an
unspecified value.
For example:
| > (make-mutex)
#<mutex #2>
> (make-mutex 'foo)
#<mutex #3 foo>
|
Returns the name of the mutex. For example:
| > (mutex-name (make-mutex 'foo))
foo
|
The mutex-specific
procedure returns the content of the
mutex’s specific field.
The mutex-specific-set!
procedure stores obj into the
mutex’s specific field and returns an unspecified value.
For example:
| > (define m (make-mutex))
> (mutex-specific-set! m "hello")
> (mutex-specific m)
"hello"
> (define (mutex-lock-recursively! mutex)
(if (eq? (mutex-state mutex) (current-thread))
(let ((n (mutex-specific mutex)))
(mutex-specific-set! mutex (+ n 1)))
(begin
(mutex-lock! mutex)
(mutex-specific-set! mutex 0))))
> (define (mutex-unlock-recursively! mutex)
(let ((n (mutex-specific mutex)))
(if (= n 0)
(mutex-unlock! mutex)
(mutex-specific-set! mutex (- n 1)))))
> (mutex-lock-recursively! m)
> (mutex-lock-recursively! m)
> (mutex-lock-recursively! m)
> (mutex-specific m)
2
|
Thos procedure returns information about the state of the mutex.
The possible results are:
- thread T:
the mutex is in the locked/owned state
and thread T is the owner of the mutex
- symbol
not-owned
:
the mutex is in the locked/not-owned state
- symbol
abandoned
:
the mutex is in the unlocked/abandoned
state
- symbol
not-abandoned
:
the mutex is in the unlocked/not-abandoned
state
For example:
| (mutex-state (make-mutex)) ==> not-abandoned
(define (thread-alive? thread)
(let ((mutex (make-mutex)))
(mutex-lock! mutex #f thread)
(let ((state (mutex-state mutex)))
(mutex-unlock! mutex) ; avoid space leak
(eq? state thread))))
|
This procedure locks mutex. If the mutex is currently
locked, the current thread waits until the mutex is unlocked, or
until the timeout is reached if timeout is supplied. If the
timeout is reached, mutex-lock!
returns ‘#f’. Otherwise,
the state of the mutex is changed as follows:
- if thread is ‘#f’ the
mutex becomes locked/not-owned,
- otherwise, let T be thread (or the
current thread if thread is not
supplied),
- if T is terminated the mutex
becomes unlocked/abandoned,
- otherwise mutex becomes locked/owned
with T as the owner.
After changing the state of the mutex, an
abandoned-mutex-exception object is raised if the mutex was
unlocked/abandoned before the state change, otherwise
mutex-lock!
returns ‘#t’. It is not an error if the
mutex is owned by the current thread (but the current thread
will have to wait).
For example:
| ; an implementation of a mailbox object of depth one; this
; implementation does not behave well in the presence of forced
; thread terminations using thread-terminate! (deadlock can occur
; if a thread is terminated in the middle of a put! or get! operation)
(define (make-empty-mailbox)
(let ((put-mutex (make-mutex)) ; allow put! operation
(get-mutex (make-mutex))
(cell #f))
(define (put! obj)
(mutex-lock! put-mutex #f #f) ; prevent put! operation
(set! cell obj)
(mutex-unlock! get-mutex)) ; allow get! operation
(define (get!)
(mutex-lock! get-mutex #f #f) ; wait until object in mailbox
(let ((result cell))
(set! cell #f) ; prevent space leaks
(mutex-unlock! put-mutex) ; allow put! operation
result))
(mutex-lock! get-mutex #f #f) ; prevent get! operation
(lambda (msg)
(case msg
((put!) put!)
((get!) get!)
(else (error "unknown message"))))))
(define (mailbox-put! m obj) ((m 'put!) obj))
(define (mailbox-get! m) ((m 'get!)))
; an alternate implementation of thread-sleep!
(define (sleep! timeout)
(let ((m (make-mutex)))
(mutex-lock! m #f #f)
(mutex-lock! m timeout #f)))
; a procedure that waits for one of two mutexes to unlock
(define (lock-one-of! mutex1 mutex2)
; this procedure assumes that neither mutex1 or mutex2
; are owned by the current thread
(let ((ct (current-thread))
(done-mutex (make-mutex)))
(mutex-lock! done-mutex #f #f)
(let ((t1 (thread-start!
(make-thread
(lambda ()
(mutex-lock! mutex1 #f ct)
(mutex-unlock! done-mutex)))))
(t2 (thread-start!
(make-thread
(lambda ()
(mutex-lock! mutex2 #f ct)
(mutex-unlock! done-mutex))))))
(mutex-lock! done-mutex #f #f)
(thread-terminate! t1)
(thread-terminate! t2)
(if (eq? (mutex-state mutex1) ct)
(begin
(if (eq? (mutex-state mutex2) ct)
(mutex-unlock! mutex2)) ; don't lock both
mutex1)
mutex2))))
|
This procedure unlocks the mutex by making it
unlocked/not-abandoned. It is not an error to unlock an unlocked
mutex and a mutex that is owned by any thread. If
condition-variable is supplied, the current thread is blocked
and added to the condition-variable before unlocking
mutex; the thread can unblock at any time but no later than when
an appropriate call to condition-variable-signal!
or
condition-variable-broadcast!
is performed (see below), and no
later than the timeout (if timeout is supplied). If there are
threads waiting to lock this mutex, the scheduler selects a
thread, the mutex becomes locked/owned or locked/not-owned, and the
thread is unblocked. mutex-unlock!
returns ‘#f’ when the
timeout is reached, otherwise it returns ‘#t’.
NOTE: The reason the thread can unblock at any time (when
condition-variable is supplied) is that the scheduler, when it
detects a serious problem such as a deadlock, must interrupt one of
the blocked threads (such as the primordial thread) so that it can
perform some appropriate action. After a thread blocked on a
condition-variable has handled such an interrupt it would be wrong for
the scheduler to return the thread to the blocked state, because any
calls to condition-variable-broadcast!
during the interrupt
will have gone unnoticed. It is necessary for the thread to remain
runnable and return from the call to mutex-unlock!
with a
result of ‘#t’.
NOTE: mutex-unlock!
is related to the “wait” operation on
condition variables available in other thread systems. The main
difference is that “wait” automatically locks mutex just
after the thread is unblocked. This operation is not performed by
mutex-unlock!
and so must be done by an explicit call to
mutex-lock!
. This has the advantages that a different timeout
and exception-handler can be specified on the mutex-lock!
and
mutex-unlock!
and the location of all the mutex operations is
clearly apparent.
For example:
| (let loop ()
(mutex-lock! m)
(if (condition-is-true?)
(begin
(do-something-when-condition-is-true)
(mutex-unlock! m))
(begin
(mutex-unlock! m cv)
(loop))))
|
This procedure returns #t
when obj is a
condition-variable object and #f
otherwise.
For example:
| > (condition-variable? (make-condition-variable))
#t
> (condition-variable? 'foo)
#f
|
This procedure returns a new empty condition variable. The optional
name is an arbitrary Scheme object which identifies the
condition variable (useful for debugging); it defaults to an
unspecified value. The condition variable’s specific field is set to
an unspecified value.
For example:
| > (make-condition-variable)
#<condition-variable #2>
|
This procedure returns the name of the condition-variable. For
example:
| > (condition-variable-name (make-condition-variable 'foo))
foo
|
The condition-variable-specific
procedure returns the content
of the condition-variable’s specific field.
The condition-variable-specific-set!
procedure stores obj
into the condition-variable’s specific field and returns
an unspecified value.
For example:
| > (define cv (make-condition-variable))
> (condition-variable-specific-set! cv "hello")
> (condition-variable-specific cv)
"hello"
|
This procedure unblocks a thread blocked on the
condition-variable (if there is at least one) and returns an
unspecified value.
For example:
| ; an implementation of a mailbox object of depth one; this
; implementation behaves gracefully when threads are forcibly
; terminated using thread-terminate! (an abandoned-mutex-exception
; object will be raised when a put! or get! operation is attempted
; after a thread is terminated in the middle of a put! or get!
; operation)
(define (make-empty-mailbox)
(let ((mutex (make-mutex))
(put-condvar (make-condition-variable))
(get-condvar (make-condition-variable))
(full? #f)
(cell #f))
(define (put! obj)
(mutex-lock! mutex)
(if full?
(begin
(mutex-unlock! mutex put-condvar)
(put! obj))
(begin
(set! cell obj)
(set! full? #t)
(condition-variable-signal! get-condvar)
(mutex-unlock! mutex))))
(define (get!)
(mutex-lock! mutex)
(if (not full?)
(begin
(mutex-unlock! mutex get-condvar)
(get!))
(let ((result cell))
(set! cell #f) ; avoid space leaks
(set! full? #f)
(condition-variable-signal! put-condvar)
(mutex-unlock! mutex)
result)))
(lambda (msg)
(case msg
((put!) put!)
((get!) get!)
(else (error "unknown message"))))))
(define (mailbox-put! m obj) ((m 'put!) obj))
(define (mailbox-get! m) ((m 'get!)))
|
This procedure unblocks all the thread blocked on the
condition-variable and returns an unspecified value.
For example:
| (define (make-semaphore n)
(vector n (make-mutex) (make-condition-variable)))
(define (semaphore-wait! sema)
(mutex-lock! (vector-ref sema 1))
(let ((n (vector-ref sema 0)))
(if (> n 0)
(begin
(vector-set! sema 0 (- n 1))
(mutex-unlock! (vector-ref sema 1)))
(begin
(mutex-unlock! (vector-ref sema 1) (vector-ref sema 2))
(semaphore-wait! sema))))
(define (semaphore-signal-by! sema increment)
(mutex-lock! (vector-ref sema 1))
(let ((n (+ (vector-ref sema 0) increment)))
(vector-set! sema 0 n)
(if (> n 0)
(condition-variable-broadcast! (vector-ref sema 2)))
(mutex-unlock! (vector-ref sema 1))))
|
11. Dynamic environment
The dynamic environment is the structure which allows the system
to find the value returned by the standard procedures
current-input-port
and current-output-port
. The
standard procedures with-input-from-file
and
with-output-to-file
extend the dynamic environment to produce a
new dynamic environment which is in effect for the dynamic extent of
the call to the thunk passed as their last argument. These procedures
are essentially special purpose dynamic binding operations on hidden
dynamic variables (one for current-input-port
and one for
current-output-port
). Gambit generalizes this dynamic binding
mechanism to allow the user to introduce new dynamic variables, called
parameter objects, and dynamically bind them. The parameter
objects implemented by Gambit are compatible with the specification of
the “Parameter objects SRFI” (SRFI 39).
One important issue is the relationship between the dynamic
environments of the parent and child threads when a thread is created.
Each thread has its own dynamic environment that is accessed when
looking up the value bound to a parameter object by that thread. When
a thread’s dynamic environment is extended it does not affect the
dynamic environment of other threads. When a thread is created it is
given a dynamic environment whose bindings are inherited from the
parent thread. In this inherited dynamic environment the parameter
objects are bound to the same cells as the parent’s dynamic
environment (in other words an assignment of a new value to a
parameter object is visible in the other thread).
Another important issue is the interaction between the
dynamic-wind
procedure and dynamic environments. When a thread
creates a continuation, the thread’s dynamic environment and the
‘dynamic-wind’ stack are saved within the continuation (an
alternate but equivalent point of view is that the ‘dynamic-wind’
stack is part of the dynamic environment). When this continuation is
invoked the required ‘dynamic-wind’ before and after thunks are
called and the saved dynamic environment is reinstated as the dynamic
environment of the current thread. During the call to each required
‘dynamic-wind’ before and after thunk, the dynamic environment
and the ‘dynamic-wind’ stack in effect when the corresponding
‘dynamic-wind’ was executed are reinstated. Note that this
specification precisely defines the semantics of calling
‘call-with-current-continuation’ or invoking a continuation
within a before or after thunk. The semantics are well defined even
when a continuation created by another thread is invoked. Below is an
example exercising the subtleties of this semantics.
| (with-output-to-file
"foo"
(lambda ()
(let ((k (call-with-current-continuation
(lambda (exit)
(with-output-to-file
"bar"
(lambda ()
(dynamic-wind
(lambda ()
(write '(b1))
(force-output))
(lambda ()
(let ((x (call-with-current-continuation
(lambda (cont) (exit cont)))))
(write '(t1))
(force-output)
x))
(lambda ()
(write '(a1))
(force-output)))))))))
(if k
(dynamic-wind
(lambda ()
(write '(b2))
(force-output))
(lambda ()
(with-output-to-file
"baz"
(lambda ()
(write '(t2))
(force-output)
; go back inside (with-output-to-file "bar" ...)
(k #f))))
(lambda ()
(write '(a2))
(force-output)))))))
|
The following actions will occur when this code is executed:
(b1)(a1)
is written to “bar”, (b2)
is then written to
“foo”, (t2)
is then written to “baz”, (a2)
is then
written to “foo”, and finally (b1)(t1)(a1)
is written to
“bar”.
The dynamic environment is composed of two parts: the local
dynamic environment and the global dynamic environment. There
is a single global dynamic environment, and it is used to lookup
parameter objects that can’t be found in the local dynamic
environment.
The make-parameter
procedure returns a new parameter
object. The set-filter argument is a one argument “set” conversion
procedure. The get-filter argument is a one argument “get” conversion
procedure. If they are not specified the conversion procedures
default to the identity function.
The global dynamic environment is updated to associate the parameter
object to a new cell. The initial content of the cell is the result
of applying the “set” conversion procedure to obj.
A parameter object is a procedure which accepts zero or one argument.
The cell bound to a particular parameter object in the dynamic
environment is accessed by calling the parameter object. When no
argument is passed, the value returned is the result
of applying the “get” conversion procedure to the content of the cell.
When one argument is passed the content of the cell is updated with the result
of applying the parameter object’s “set” conversion procedure to the
argument. Note that the conversion procedures can be used for
guaranteeing the type of the parameter object’s binding and/or to
perform some conversion of the value.
For example:
| > (define radix (make-parameter 10))
> (radix)
10
> (radix 2)
> (radix)
2
> (define prompt
(make-parameter
123
(lambda (x)
(if (string? x)
x
(object->string x)))))
> (prompt)
"123"
> (prompt "$")
> (prompt)
"$"
> (define p
(make-parameter
100
(lambda (val) ;; set filter
(pp (list val: val))
(list 0 val))
(lambda (state) ;; get filter
(pp (list state: state))
(set-car! state (+ 1 (car state)))
(+ (car state) (cadr state)))))
(val: 100)
> (p)
(state: (0 100))
101
> (p)
(state: (1 100))
102
> (p)
(state: (2 100))
103
> (p 555)
(val: 555)
> (p)
(state: (0 555))
556
> (p)
(state: (1 555))
557
> (define write-shared
(make-parameter
#f
(lambda (x)
(if (boolean? x)
x
(error "only booleans are accepted by write-shared")))))
> (write-shared 123)
*** ERROR IN ##make-parameter -- only booleans are accepted by write-shared
|
The parameterize
form, evaluates all procedure and
value expressions in an unspecified order. All the
procedure expressions must evaluate to procedures, either parameter
objects or procedures accepting zero and one argument. Then,
for each procedure p and in an unspecified order:
-
If p is a parameter object a new cell is created, initialized, and
bound to the parameter object in the local dynamic environment. The
value contained in the cell is the result of applying the parameter
object’s “set” conversion procedure to value. The resulting dynamic
environment is then used for processing the remaining bindings (or the
evaluation of body if there are no other bindings).
-
Otherwise p will be used according to the following protocol: we
say that the call
(p)
“gets p’s value” and that
the call (p x)
“sets p’s value to x”.
First, the parameterize
form gets p’s value and saves it in
a local variable. It then sets p’s value to value. It then
processes the remaining bindings (or evaluates body if there are
no other bindings). Then it sets p’s value to the saved value.
These steps are performed in a dynamic-wind
so that it is
possible to use continuations to jump into and out of the body
(i.e. the dynamic-wind
’s before thunk sets p’s value to
value and the after thunk sets p’s value to the saved value).
The result(s) of the parameterize
form are the result(s) of the
body.
Note that using procedures instead of parameter objects may lead to
unexpected results in multithreaded programs because the before and
after thunks of the dynamic-wind
are not called when control
switches between threads.
For example:
| > (define radix (make-parameter 2))
> (define prompt
(make-parameter
123
(lambda (x)
(if (string? x)
x
(object->string x)))))
> (radix)
2
> (parameterize ((radix 16)) (radix))
16
> (radix)
2
> (define (f n) (number->string n (radix)))
> (f 10)
"1010"
> (parameterize ((radix 8)) (f 10))
"12"
> (parameterize ((radix 8) (prompt (f 10))) (prompt))
"1010"
> (define p
(let ((x 1))
(lambda args
(if (null? args) x (set! x (car args))))))
> (let* ((a (p))
(b (parameterize ((p 2)) (list (p))))
(c (p)))
(list a b c))
(1 (2) 1)
|
12. Exceptions
12.1 Exception-handling
Gambit’s exception-handling model is inspired from the withdrawn
“Exception Handling SRFI” (SRFI 12), the “Multithreading support
SRFI” (SRFI 18), and the “Exception Handling for Programs SRFI”
(SRFI 34). The two fundamental operations are the dynamic binding of
an exception handler (i.e. the procedure
with-exception-handler
) and the invocation of the exception
handler (i.e. the procedure raise
).
All predefined procedures which check for errors (including type
errors, memory allocation errors, host operating-system errors, etc)
report these errors using the exception-handling system (i.e. they
“raise” an exception that can be handled in a user-defined exception
handler). When an exception is raised and the exception is not
handled by a user-defined exception handler, the predefined exception
handler will display an error message (if the primordial thread raised
the exception) or the thread will silently terminate with no error
message (if it is not the primordial thread that raised the
exception). This default behavior can be changed through the
‘-:debug=...’ runtime option (see section Runtime options).
Predefined procedures normally raise exceptions by performing a
tail-call to the exception handler (the exceptions are “complex”
procedures such as eval
, compile-file
, read
,
write
, etc). This means that the continuation of the exception
handler and of the REPL that may be started due to this is normally
the continuation of the predefined procedure that raised the
exception. By exiting the REPL with the ,(c expression)
command it is thus possible to resume the program as though the call
to the predefined procedure returned the value of expression.
For example:
| > (define (f x) (+ (car x) 1))
> (f 2) ; typo... we meant to say (f '(2))
*** ERROR IN f, (console)@1.18 -- (Argument 1) PAIR expected
(car 2)
1> ,(c 2)
3
|
The parameter object current-exception-handler
is bound to the
current exception-handler. Calling this procedure with no argument
returns the current exception-handler and calling this procedure with
one argument sets the current exception-handler to
new-exception-handler.
For example:
| > (current-exception-handler)
#<procedure #2 primordial-exception-handler>
> (current-exception-handler (lambda (exc) (pp exc) 999))
> (/ 1 0)
#<divide-by-zero-exception #3>
999
|
Returns the result(s) of calling thunk with no arguments. The
handler, which must be a procedure, is installed as the current
exception-handler in the dynamic environment in effect during the call
to thunk. Note that the dynamic environment in effect during
the call to handler has handler as the exception-handler.
Consequently, an exception raised during the call to handler may
lead to an infinite loop.
For example:
| > (with-exception-handler
(lambda (e) (write e) 5)
(lambda () (+ 1 (* 2 3) 4)))
11
> (with-exception-handler
(lambda (e) (write e) 5)
(lambda () (+ 1 (* 'foo 3) 4)))
#<type-exception #2>10
> (with-exception-handler
(lambda (e) (write e 9))
(lambda () (+ 1 (* 'foo 3) 4)))
infinite loop
|
Returns the result(s) of calling thunk with no arguments. A new
exception-handler is installed as the current exception-handler in the
dynamic environment in effect during the call to thunk. This
new exception-handler will call the handler, which must be a
procedure, with the exception object as an argument and with the same
continuation as the call to with-exception-catcher
. This
implies that the dynamic environment in effect during the call to
handler is the same as the one in effect at the call to
with-exception-catcher
. Consequently, an exception raised
during the call to handler will not lead to an infinite loop.
For example:
| > (with-exception-catcher
(lambda (e) (write e) 5)
(lambda () (+ 1 (* 2 3) 4)))
11
> (with-exception-catcher
(lambda (e) (write e) 5)
(lambda () (+ 1 (* 'foo 3) 4)))
#<type-exception #2>5
> (with-exception-catcher
(lambda (e) (write e 9))
(lambda () (+ 1 (* 'foo 3) 4)))
*** ERROR IN (console)@7.1 -- (Argument 2) OUTPUT PORT expected
(write '#<type-exception #3> 9)
|
This procedure tail-calls the current exception-handler with obj
as the sole argument. If the exception-handler returns, the
continuation of the call to raise
is invoked.
For example:
| > (with-exception-handler
(lambda (exc)
(pp exc)
100)
(lambda ()
(+ 1 (raise "hello"))))
"hello"
101
|
The procedure abort
calls the current exception-handler with
obj as the sole argument. If the exception-handler returns, the
procedure abort
will be tail-called with a
noncontinuable-exception object, whose reason field is obj, as
sole argument.
Noncontinuable-exception objects are raised by the abort
procedure when the exception-handler returns. The parameter exc
must be a noncontinuable-exception object.
The procedure noncontinuable-exception?
returns
#t
when obj is a noncontinuable-exception
object and #f
otherwise.
The procedure noncontinuable-exception-reason
returns the
argument of the call to abort
that raised exc.
For example:
| > (call-with-current-continuation
(lambda (k)
(with-exception-handler
(lambda (exc)
(pp exc)
(if (noncontinuable-exception? exc)
(k (list (noncontinuable-exception-reason exc)))
100))
(lambda ()
(+ 1 (abort "hello"))))))
"hello"
#<noncontinuable-exception #2>
("hello")
|
12.2 Exception objects related to memory management
Heap-overflow-exception objects are raised when the allocation of an
object would cause the heap to use more memory space than is available.
The procedure heap-overflow-exception?
returns
#t
when obj is a heap-overflow-exception
object and #f
otherwise.
For example:
| > (define (handler exc)
(if (heap-overflow-exception? exc)
exc
'not-heap-overflow-exception))
> (with-exception-catcher
handler
(lambda ()
(define (f x) (f (cons 1 x)))
(f '())))
#<heap-overflow-exception #2>
|
Stack-overflow-exception objects are raised when the allocation of a
continuation frame would cause the heap to use more memory space than
is available.
The procedure stack-overflow-exception?
returns
#t
when obj is a stack-overflow-exception
object and #f
otherwise.
For example:
| > (define (handler exc)
(if (stack-overflow-exception? exc)
exc
'not-stack-overflow-exception))
> (with-exception-catcher
handler
(lambda ()
(define (f) (+ 1 (f)))
(f)))
#<stack-overflow-exception #2>
|
12.3 Exception objects related to the host environment
Os-exception objects are raised by procedures which access the host
operating-system’s services when the requested operation fails. The
parameter exc must be a os-exception object.
The procedure os-exception?
returns
#t
when obj is a os-exception
object and #f
otherwise.
The procedure os-exception-procedure
returns the procedure that raised exc.
The procedure os-exception-arguments
returns the list of arguments of the procedure that raised exc.
The procedure os-exception-code
returns an exact integer error
code that can be converted to a string by the err-code->string
procedure. Note that the error code is operating-system dependent.
The procedure os-exception-message
returns
#f
or a string giving details of the exception in a
human-readable form.
For example:
| > (define (handler exc)
(if (os-exception? exc)
(list (os-exception-procedure exc)
(os-exception-arguments exc)
(err-code->string (os-exception-code exc))
(os-exception-message exc))
'not-os-exception))
> (with-exception-catcher
handler
(lambda () (host-info "x.y.z")))
(#<procedure #2 host-info> ("x.y.z") "Unknown host" #f)
|
No-such-file-or-directory-exception objects are raised by procedures
which access the filesystem (such as open-input-file
and
directory-files
) when the path specified can’t be found on the
filesystem. The parameter exc must be a
no-such-file-or-directory-exception object.
The procedure no-such-file-or-directory-exception?
returns
#t
when obj is a no-such-file-or-directory-exception
object and #f
otherwise.
The procedure no-such-file-or-directory-exception-procedure
returns the procedure that raised exc.
The procedure no-such-file-or-directory-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (no-such-file-or-directory-exception? exc)
(list (no-such-file-or-directory-exception-procedure exc)
(no-such-file-or-directory-exception-arguments exc))
'not-no-such-file-or-directory-exception))
> (with-exception-catcher
handler
(lambda () (with-input-from-file "nofile" read)))
(#<procedure #2 with-input-from-file> ("nofile" #<procedure #3 read>))
|
File-exists-exception objects are raised by procedures
which access the filesystem (such as open-output-file
and
create-directory
) when the path specified is an existing
file on the filesystem. The parameter exc must be a
file-exists-exception object.
The procedure file-exists-exception?
returns
#t
when obj is a file-exists-exception
object and #f
otherwise.
The procedure file-exists-exception-procedure
returns the procedure that raised exc.
The procedure file-exists-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (file-exists-exception? exc)
(list (file-exists-exception-procedure exc)
(file-exists-exception-arguments exc))
'not-file-exists-exception))
> (with-exception-catcher
handler
(lambda () (with-output-to-file '(path: "foo" create: #t) newline)))
> (with-exception-catcher
handler
(lambda () (with-output-to-file '(path: "foo" create: #t) newline)))
(#<procedure #2 with-output-to-file>
((path: "foo" create: #t) #<procedure #3 newline>))
|
Permission-denied-exception objects are raised by procedures
which access the filesystem (such as open-file
and
open-directory
) when the access to the specified path is not
allowed, or search permission is denied for a directory in the path prefix,
or write access to the parent directory isn’t allowed for a file that
doesn’t exist yet on the filesystem. The parameter exc must be a
permission-denied-exception object.
The procedure permission-denied-exception?
returns
#t
when obj is a permission-denied-exception
object and #f
otherwise.
The procedure permission-denied-exception-procedure
returns the procedure that raised exc.
The procedure permission-denied-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (permission-denied-exception? exc)
(list (permission-denied-exception-procedure exc)
(permission-denied-exception-arguments exc))
'not-permission-denied-exception))
> (with-exception-catcher
handler
(lambda () (with-input-from-file "empty" read)))
#!eof
> (with-exception-catcher
handler
(lambda () (with-input-from-file "noperm" read)))
(#<procedure #2 with-input-from-file> ("noperm" #<procedure #3 read>))
|
Unbound-os-environment-variable-exception objects are raised when an
unbound operating-system environment variable is accessed by the
procedures getenv
and setenv
. The parameter exc
must be an unbound-os-environment-variable-exception object.
The procedure unbound-os-environment-variable-exception?
returns
#t
when obj is an unbound-os-environment-variable-exception
object and #f
otherwise.
The procedure unbound-os-environment-variable-exception-procedure
returns the procedure that raised exc.
The procedure unbound-os-environment-variable-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (unbound-os-environment-variable-exception? exc)
(list (unbound-os-environment-variable-exception-procedure exc)
(unbound-os-environment-variable-exception-arguments exc))
'not-unbound-os-environment-variable-exception))
> (with-exception-catcher
handler
(lambda () (getenv "DOES_NOT_EXIST")))
(#<procedure #2 getenv> ("DOES_NOT_EXIST"))
|
12.4 Exception objects related to threads
Scheduler-exception objects are raised by the scheduler when some
operation requested from the host operating system failed
(e.g. checking the status of the devices in order to wake up threads
waiting to perform I/O on these devices). The parameter exc
must be a scheduler-exception object.
The procedure scheduler-exception?
returns
#t
when obj is a scheduler-exception
object and #f
otherwise.
The procedure scheduler-exception-reason
returns the
os-exception object that describes the failure detected by the
scheduler.
Deadlock-exception objects are raised when the scheduler discovers
that all threads are blocked and can make no further progress. In
that case the scheduler unblocks the primordial-thread and forces it
to raise a deadlock-exception object.
The procedure deadlock-exception?
returns #t
when
obj is a deadlock-exception object and #f
otherwise.
For example:
| > (define (handler exc)
(if (deadlock-exception? exc)
exc
'not-deadlock-exception))
> (with-exception-catcher
handler
(lambda () (read (open-vector))))
#<deadlock-exception #2>
|
Abandoned-mutex-exception objects are raised when the current thread
locks a mutex that was owned by a thread which terminated (see
mutex-lock!
).
The procedure abandoned-mutex-exception?
returns
#t
when obj is a abandoned-mutex-exception
object and #f
otherwise.
For example:
| > (define (handler exc)
(if (abandoned-mutex-exception? exc)
exc
'not-abandoned-mutex-exception))
> (with-exception-catcher
handler
(lambda ()
(let ((m (make-mutex)))
(thread-join!
(thread-start!
(make-thread
(lambda () (mutex-lock! m)))))
(mutex-lock! m))))
#<abandoned-mutex-exception #2>
|
Join-timeout-exception objects are raised when a call to the
thread-join!
procedure reaches its timeout before the target
thread terminates and a timeout-value parameter is not specified. The
parameter exc must be a join-timeout-exception object.
The procedure join-timeout-exception?
returns
#t
when obj is a join-timeout-exception
object and #f
otherwise.
The procedure join-timeout-exception-procedure
returns the procedure that raised exc.
The procedure join-timeout-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (join-timeout-exception? exc)
(list (join-timeout-exception-procedure exc)
(join-timeout-exception-arguments exc))
'not-join-timeout-exception))
> (with-exception-catcher
handler
(lambda ()
(thread-join!
(thread-start!
(make-thread
(lambda () (thread-sleep! 10))))
5)))
(#<procedure #2 thread-join!> (#<thread #3> 5))
|
Started-thread-exception objects are raised when the target thread of
a call to the procedure thread-start!
is already started. The
parameter exc must be a started-thread-exception object.
The procedure started-thread-exception?
returns
#t
when obj is a started-thread-exception
object and #f
otherwise.
The procedure started-thread-exception-procedure
returns the procedure that raised exc.
The procedure started-thread-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (started-thread-exception? exc)
(list (started-thread-exception-procedure exc)
(started-thread-exception-arguments exc))
'not-started-thread-exception))
> (with-exception-catcher
handler
(lambda ()
(let ((t (make-thread (lambda () (expt 2 1000)))))
(thread-start! t)
(thread-start! t))))
(#<procedure #2 thread-start!> (#<thread #3>))
|
Terminated-thread-exception objects are raised when the
thread-join!
procedure is called and the target thread has
terminated as a result of a call to the thread-terminate!
procedure. The parameter exc must be a
terminated-thread-exception object.
The procedure terminated-thread-exception?
returns
#t
when obj is a terminated-thread-exception
object and #f
otherwise.
The procedure terminated-thread-exception-procedure
returns the procedure that raised exc.
The procedure terminated-thread-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (terminated-thread-exception? exc)
(list (terminated-thread-exception-procedure exc)
(terminated-thread-exception-arguments exc))
'not-terminated-thread-exception))
> (with-exception-catcher
handler
(lambda ()
(thread-join!
(thread-start!
(make-thread
(lambda () (thread-terminate! (current-thread))))))))
(#<procedure #2 thread-join!> (#<thread #3>))
|
Uncaught-exception objects are raised when an object is raised in a
thread and that thread does not handle it (i.e. the thread terminated
because it did not catch an exception it raised). The parameter
exc must be an uncaught-exception object.
The procedure uncaught-exception?
returns
#t
when obj is an uncaught-exception
object and #f
otherwise.
The procedure uncaught-exception-procedure
returns the procedure that raised exc.
The procedure uncaught-exception-arguments
returns the list of arguments of the procedure that raised exc.
The procedure uncaught-exception-reason
returns the object that
was raised by the thread and not handled by that thread.
For example:
| > (define (handler exc)
(if (uncaught-exception? exc)
(list (uncaught-exception-procedure exc)
(uncaught-exception-arguments exc)
(uncaught-exception-reason exc))
'not-uncaught-exception))
> (with-exception-catcher
handler
(lambda ()
(thread-join!
(thread-start!
(make-thread
(lambda () (open-input-file "data" 99)))))))
(#<procedure #2 thread-join!>
(#<thread #3>)
#<wrong-number-of-arguments-exception #4>)
|
12.5 Exception objects related to C-interface
Cfun-conversion-exception objects are raised by the C-interface when
converting between the Scheme representation and the C representation
of a value during a call from Scheme to C. The parameter exc
must be a cfun-conversion-exception object.
The procedure cfun-conversion-exception?
returns #t
when
obj is a cfun-conversion-exception object and #f
otherwise.
The procedure cfun-conversion-exception-procedure
returns the
procedure that raised exc.
The procedure cfun-conversion-exception-arguments
returns the
list of arguments of the procedure that raised exc.
The procedure cfun-conversion-exception-code
returns an exact
integer error code that can be converted to a string by the
err-code->string
procedure.
The procedure cfun-conversion-exception-message
returns
#f
or a string giving details of the exception in a
human-readable form.
For example:
| $ cat test1.scm
(define weird
(c-lambda (char-string) nonnull-char-string
"___return(___arg1);"))
$ gsc test1.scm
$ gsi
Gambit v4.9.5
> (load "test1")
"/Users/feeley/gambit/doc/test1.o1"
> (weird "hello")
"hello"
> (define (handler exc)
(if (cfun-conversion-exception? exc)
(list (cfun-conversion-exception-procedure exc)
(cfun-conversion-exception-arguments exc)
(err-code->string (cfun-conversion-exception-code exc))
(cfun-conversion-exception-message exc))
'not-cfun-conversion-exception))
> (with-exception-catcher
handler
(lambda () (weird 'not-a-string)))
(#<procedure #2 weird>
(not-a-string)
"(Argument 1) Can't convert to C char-string"
#f)
> (with-exception-catcher
handler
(lambda () (weird #f)))
(#<procedure #2 weird>
(#f)
"Can't convert result from C nonnull-char-string"
#f)
|
Sfun-conversion-exception objects are raised by the C-interface when
converting between the Scheme representation and the C representation
of a value during a call from C to Scheme. The parameter exc
must be a sfun-conversion-exception object.
The procedure sfun-conversion-exception?
returns #t
when
obj is a sfun-conversion-exception object and #f
otherwise.
The procedure sfun-conversion-exception-procedure
returns the
procedure that raised exc.
The procedure sfun-conversion-exception-arguments
returns the
list of arguments of the procedure that raised exc.
The procedure sfun-conversion-exception-code
returns an exact
integer error code that can be converted to a string by the
err-code->string
procedure.
The procedure sfun-conversion-exception-message
returns
#f
or a string giving details of the exception in a
human-readable form.
For example:
| $ cat test2.scm
(c-define (f str) (nonnull-char-string) int "f" ""
(string->number str))
(define t1 (c-lambda () int "___return(f (\"123\"));"))
(define t2 (c-lambda () int "___return(f (0));"))
(define t3 (c-lambda () int "___return(f (\"1.5\"));"))
$ gsc test2.scm
$ gsi
Gambit v4.9.5
> (load "test2")
"/u/feeley/test2.o1"
> (t1)
123
> (define (handler exc)
(if (sfun-conversion-exception? exc)
(list (sfun-conversion-exception-procedure exc)
(sfun-conversion-exception-arguments exc)
(err-code->string (sfun-conversion-exception-code exc))
(sfun-conversion-exception-message exc))
'not-sfun-conversion-exception))
> (with-exception-catcher handler t2)
(#<procedure #2 f>
()
"(Argument 1) Can't convert from C nonnull-char-string"
#f)
> (with-exception-catcher handler t3)
(#<procedure #2 f> () "Can't convert result to C int" #f)
|
Multiple-c-return-exception objects are raised by the C-interface when
a C to Scheme procedure call returns and that call’s stack frame is no
longer on the C stack because the call has already returned, or has
been removed from the C stack by a longjump
.
The procedure multiple-c-return-exception?
returns #t
when obj is a multiple-c-return-exception object and #f
otherwise.
For example:
| $ cat test3.scm
(c-define (f str) (char-string) scheme-object "f" ""
(pp (list 'entry 'str= str))
(let ((k (call-with-current-continuation (lambda (k) k))))
(pp (list 'exit 'k= k))
k))
(define scheme-to-c-to-scheme-and-back
(c-lambda (char-string) scheme-object
"___return(f (___arg1));"))
$ gsc test3.scm
$ gsi
Gambit v4.9.5
> (load "test3")
"/Users/feeley/gambit/doc/test3.o1"
> (define (handler exc)
(if (multiple-c-return-exception? exc)
exc
'not-multiple-c-return-exception))
> (with-exception-catcher
handler
(lambda ()
(let ((c (scheme-to-c-to-scheme-and-back "hello")))
(pp c)
(c 999))))
(entry str= "hello")
(exit k= #<procedure #2>)
#<procedure #2>
(exit k= 999)
#<multiple-c-return-exception #3>
|
Wrong-processor-c-return-exception objects are raised by the runtime
system when a C to Scheme procedure call returns and that call’s stack frame
was created by another processor.
The procedure wrong-processor-c-return-exception?
returns #t
when obj is a wrong-processor-c-return-exception object and #f
otherwise.
12.6 Exception objects related to the reader
Datum-parsing-exception objects are raised by the reader (i.e. the
read
procedure) when the input does not conform to the grammar
for datum. The parameter exc must be a datum-parsing-exception
object.
The procedure datum-parsing-exception?
returns #t
when
obj is a datum-parsing-exception object and #f
otherwise.
The procedure datum-parsing-exception-kind
returns a symbol
denoting the kind of parsing error that was encountered by the
reader when it raised exc. Here is a table of the possible
return values:
datum-or-eof-expected | Datum or EOF expected |
datum-expected | Datum expected |
improperly-placed-dot | Improperly placed dot |
incomplete-form-eof-reached | Incomplete form, EOF reached |
incomplete-form | Incomplete form |
character-out-of-range | Character out of range |
invalid-character-name | Invalid ’#\’ name |
illegal-character | Illegal character |
s8-expected | Signed 8 bit exact integer expected |
u8-expected | Unsigned 8 bit exact integer expected |
s16-expected | Signed 16 bit exact integer expected |
u16-expected | Unsigned 16 bit exact integer expected |
s32-expected | Signed 32 bit exact integer expected |
u32-expected | Unsigned 32 bit exact integer expected |
s64-expected | Signed 64 bit exact integer expected |
u64-expected | Unsigned 64 bit exact integer expected |
inexact-real-expected | Inexact real expected |
invalid-hex-escape | Invalid hexadecimal escape |
invalid-escaped-character | Invalid escaped character |
open-paren-expected | ’(’ expected |
invalid-token | Invalid token |
invalid-sharp-bang-name | Invalid ’#!’ name |
duplicate-label-definition | Duplicate definition for label |
missing-label-definition | Missing definition for label |
illegal-label-definition | Illegal definition of label |
invalid-infix-syntax-character | Invalid infix syntax character |
invalid-infix-syntax-number | Invalid infix syntax number |
invalid-infix-syntax | Invalid infix syntax |
The procedure datum-parsing-exception-parameters
returns a list
of the parameters associated with the parsing error that was
encountered by the reader when it raised exc.
For example:
| > (define (handler exc)
(if (datum-parsing-exception? exc)
(list (datum-parsing-exception-kind exc)
(datum-parsing-exception-parameters exc))
'not-datum-parsing-exception))
> (with-exception-catcher
handler
(lambda ()
(with-input-from-string "(s #\\pace)" read)))
(invalid-character-name ("pace"))
|
12.7 Exception objects related to evaluation and compilation
Expression-parsing-exception objects are raised by the evaluator and
compiler (i.e. the procedures eval
, compile-file
, etc)
when the input does not conform to the grammar for expression. The
parameter exc must be a expression-parsing-exception object.
The procedure expression-parsing-exception?
returns #t
when
obj is a expression-parsing-exception object and #f
otherwise.
The procedure expression-parsing-exception-kind
returns a
symbol denoting the kind of parsing error that was encountered by the
evaluator or compiler when it raised exc. Here is a table of
the possible return values:
id-expected | Identifier expected |
ill-formed-namespace | Ill-formed namespace |
ill-formed-namespace-prefix | Ill-formed namespace prefix |
namespace-prefix-must-be-string | Namespace prefix must be a string |
macro-used-as-variable | Macro name can’t be used as a variable |
variable-is-immutable | Variable is immutable |
ill-formed-macro-transformer | Macro transformer must be a lambda expression |
reserved-used-as-variable | Reserved identifier can’t be used as a variable |
ill-formed-special-form | Ill-formed special form |
cannot-open-file | Can’t open file |
filename-expected | Filename expected |
ill-placed-define | Ill-placed ’define’ |
ill-placed-**include | Ill-placed ’##include’ |
ill-placed-**define-macro | Ill-placed ’##define-macro’ |
ill-placed-**declare | Ill-placed ’##declare’ |
ill-placed-**namespace | Ill-placed ’##namespace’ |
ill-formed-expression | Ill-formed expression |
unsupported-special-form | Interpreter does not support |
ill-placed-unquote | Ill-placed ’unquote’ |
ill-placed-unquote-splicing | Ill-placed ’unquote-splicing’ |
parameter-must-be-id | Parameter must be an identifier |
parameter-must-be-id-or-default | Parameter must be an identifier or default binding |
duplicate-parameter | Duplicate parameter in parameter list |
ill-placed-dotted-rest-parameter | Ill-placed dotted rest parameter |
parameter-expected-after-rest | #!rest must be followed by a parameter |
ill-formed-default | Ill-formed default binding |
ill-placed-optional | Ill-placed #!optional |
ill-placed-rest | Ill-placed #!rest |
ill-placed-key | Ill-placed #!key |
key-expected-after-rest | #!key expected after rest parameter |
ill-placed-default | Ill-placed default binding |
duplicate-variable-definition | Duplicate definition of a variable |
empty-body | Body must contain at least one expression |
variable-must-be-id | Defined variable must be an identifier |
else-clause-not-last | Else clause must be last |
ill-formed-selector-list | Ill-formed selector list |
duplicate-variable-binding | Duplicate variable in bindings |
ill-formed-binding-list | Ill-formed binding list |
ill-formed-call | Ill-formed procedure call |
ill-formed-cond-expand | Ill-formed ’cond-expand’ |
unfulfilled-cond-expand | Unfulfilled ’cond-expand’ |
The procedure expression-parsing-exception-parameters
returns a list
of the parameters associated with the parsing error that was
encountered by the evaluator or compiler when it raised exc.
For example:
| > (define (handler exc)
(if (expression-parsing-exception? exc)
(list (expression-parsing-exception-kind exc)
(expression-parsing-exception-parameters exc))
'not-expression-parsing-exception))
> (with-exception-catcher
handler
(lambda ()
(eval '(+ do 1))))
(reserved-used-as-variable (do))
|
Unbound-global-exception objects are raised when an unbound global
variable is accessed. The parameter exc must be an
unbound-global-exception object.
The procedure unbound-global-exception?
returns
#t
when obj is an unbound-global-exception
object and #f
otherwise.
The procedure unbound-global-exception-variable
returns a
symbol identifying the unbound global variable.
For example:
| > (define (handler exc)
(if (unbound-global-exception? exc)
(list 'variable= (unbound-global-exception-variable exc))
'not-unbound-global-exception))
> (with-exception-catcher
handler
(lambda () foo))
(variable= foo)
|
Not-in-compilation-context-exception objects are raised by the
procedure compilation-target
when it is executed outside of a
compilation context. The parameter exc must be a
not-in-compilation-context-exception object.
The procedure not-in-compilation-context-exception?
returns
#t
when obj is a not-in-compilation-context-exception
object and #f
otherwise.
The procedure not-in-compilation-context-exception-procedure
returns the procedure that raised exc.
The procedure not-in-compilation-context-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (not-in-compilation-context-exception? exc)
(list (not-in-compilation-context-exception-procedure exc)
(not-in-compilation-context-exception-arguments exc))
'not-not-in-compilation-context-exception))
> (with-exception-catcher
handler
(lambda () (compilation-target)))
(#<procedure #2 compilation-target> ())
|
12.8 Exception objects related to type checking
Type-exception objects are raised when a primitive procedure is called
with an argument of incorrect type (i.e. when a run time type-check
fails). The parameter exc must be a type-exception object.
The procedure type-exception?
returns
#t
when obj is a type-exception
object and #f
otherwise.
The procedure type-exception-procedure
returns the procedure that raised exc.
The procedure type-exception-arguments
returns the list of arguments of the procedure that raised exc.
The procedure type-exception-arg-id
returns the identity of the
argument whose type is incorrect, which can be an exact integer position
(1 for the first argument) or a pair whose car
is the position
and the cdr
is the parameter name as a symbol.
The procedure type-exception-type-id
returns an identifier of
the type expected. The type-id can be a symbol, such as number
and string-or-nonnegative-fixnum
, or a record type descriptor.
For example:
| > (define (handler exc)
(if (type-exception? exc)
(list (type-exception-procedure exc)
(type-exception-arguments exc)
(type-exception-arg-id exc)
(type-exception-type-id exc))
'not-type-exception))
> (with-exception-catcher
handler
(lambda () (vector-ref '#(a b c) 'foo)))
(#<procedure #2 vector-ref> (#(a b c) foo) 2 exact-integer)
> (with-exception-catcher
handler
(lambda () (time->seconds 'foo)))
(#<procedure #3 time->seconds> (foo) 1 #<type #4 time>)
|
Range-exception objects are raised when a numeric parameter is not in
the allowed range. The parameter exc must be a range-exception
object.
The procedure range-exception?
returns #t
when obj
is a range-exception object and #f
otherwise.
The procedure range-exception-procedure
returns the procedure that raised exc.
The procedure range-exception-arguments
returns the list of arguments of the procedure that raised exc.
The procedure range-exception-arg-id
returns the identity of the
argument which is not in the allowed range, which can be an exact integer position
(1 for the first argument) or a pair whose car
is the position
and the cdr
is the parameter name as a symbol.
For example:
| > (define (handler exc)
(if (range-exception? exc)
(list (range-exception-procedure exc)
(range-exception-arguments exc)
(range-exception-arg-id exc))
'not-range-exception))
> (with-exception-catcher
handler
(lambda () (string-ref "abcde" 10)))
(#<procedure #2 string-ref> ("abcde" 10) 2)
|
Divide-by-zero-exception objects are raised when a division by zero is
attempted. The parameter exc must be a divide-by-zero-exception
object.
The procedure divide-by-zero-exception?
returns
#t
when obj is a divide-by-zero-exception
object and #f
otherwise.
The procedure divide-by-zero-exception-procedure
returns the procedure that raised exc.
The procedure divide-by-zero-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (divide-by-zero-exception? exc)
(list (divide-by-zero-exception-procedure exc)
(divide-by-zero-exception-arguments exc))
'not-divide-by-zero-exception))
> (with-exception-catcher
handler
(lambda () (/ 5 0 7)))
(#<procedure #2 /> (5 0 7))
|
Length-mismatch-exception objects are raised by some procedures when
they are called with two or more list arguments and the lists are not
of the same length. The parameter exc must be a
length-mismatch-exception object.
The procedure length-mismatch-exception?
returns
#t
when obj is an length-mismatch-exception
object and #f
otherwise.
The procedure length-mismatch-exception-procedure
returns the procedure that raised exc.
The procedure length-mismatch-exception-arguments
returns the list of arguments of the procedure that raised exc.
The procedure length-mismatch-exception-arg-id
returns the identity of the
argument whose length is the shortest, which can be an exact integer position
(1 for the first argument) or a pair whose car
is the position
and the cdr
is the parameter name as a symbol.
12.9 Exception objects related to procedure call
Wrong-number-of-arguments-exception objects are raised when a
procedure is called with the wrong number of arguments. The parameter
exc must be a wrong-number-of-arguments-exception object.
The procedure wrong-number-of-arguments-exception?
returns
#t
when obj is a wrong-number-of-arguments-exception
object and #f
otherwise.
The procedure wrong-number-of-arguments-exception-procedure
returns the procedure that raised exc.
The procedure wrong-number-of-arguments-exception-arguments
returns the list of arguments of the procedure that raised exc.
For example:
| > (define (handler exc)
(if (wrong-number-of-arguments-exception? exc)
(list (wrong-number-of-arguments-exception-procedure exc)
(wrong-number-of-arguments-exception-arguments exc))
'not-wrong-number-of-arguments-exception))
> (with-exception-catcher
handler
(lambda () (open-input-file "data" 99)))
(#<procedure #2 open-input-file> ("data" 99))
|