summaryrefslogtreecommitdiffstats
path: root/scm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'scm.texi')
-rw-r--r--scm.texi482
1 files changed, 354 insertions, 128 deletions
diff --git a/scm.texi b/scm.texi
index 5d93f63..199ebd9 100644
--- a/scm.texi
+++ b/scm.texi
@@ -4,16 +4,16 @@
@settitle SCM
@setchapternewpage on
@c Choices for setchapternewpage are {on,off,odd}.
-@paragraphindent 2
+@paragraphindent 0
@defcodeindex ft
@syncodeindex ft tp
-@c @dircategory Scheme
-@c @direntry
-@c * SCM: (scm). A Scheme interpreter.
-@c @end direntry
-
@c %**end of header
+@dircategory The Algorithmic Language Scheme
+@direntry
+* SCM: (scm). A Scheme interpreter.
+@end direntry
+
@iftex
@finalout
@c DL: lose the egregious vertical whitespace, esp. around examples
@@ -24,13 +24,13 @@
@titlepage
@title SCM
@subtitle Scheme Implementation
-@subtitle Version 5b3
-@subtitle May 1997
+@subtitle Version 5c3
+@subtitle April 1998
@author by Aubrey Jaffer
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -53,10 +53,11 @@ by the author.
@ifinfo
This manual documents the SCM Scheme implementation. The most recent
information about SCM can be found on SCM's @dfn{WWW} home page:
-@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html
+@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html}
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation
+
+Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -87,9 +88,7 @@ by the author.
* The Language:: Reference.
* Packages:: Optional Capabilities.
* The Implementation:: How it works.
-* Procedure and Macro Index::
-* Variable Index::
-* Type Index::
+* Index::
@end menu
@node Overview, Installing SCM, Top, Top
@@ -103,15 +102,7 @@ machine independent platform for [JACAL], a symbolic algebra system.
@noindent
The most recent information about SCM can be found on SCM's @dfn{WWW}
home page:
-@ifset html
-<A HREF="http://www-swiss.ai.mit.edu/~jaffer/SCM.html">
-@end ifset
-
-@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html
-
-@ifset html
-</A>
-@end ifset
+@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html}
@end iftex
@menu
@@ -439,40 +430,40 @@ low priority. SLIB is available from the same sites as SCM:
@ifclear html
@itemize @bullet
@item
-ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz
+swissnet.ai.mit.edu:/pub/scm/slib2c3.tar.gz
@item
-prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz
+prep.ai.mit.edu:/pub/gnu/jacal/slib2c3.tar.gz
@item
-ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz
+ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz
@item
-ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c0.tar.gz
+ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c3.tar.gz
@end itemize
@end ifclear
@ifset html
-<A HREF="file://ftp-swiss.ai.mit.edu/pub/scm/slib2c0.tar.gz">
-ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz
+<A HREF="file://swissnet.ai.mit.edu/pub/scm/slib2c3.tar.gz">
+swissnet.ai.mit.edu:/pub/scm/slib2c3.tar.gz
</A>
-<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2c0.tar.gz">
-prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz
+<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2c3.tar.gz">
+prep.ai.mit.edu:/pub/gnu/jacal/slib2c3.tar.gz
</A>
-<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2c0.tar.gz">
-ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz
+<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2c3.tar.gz">
+ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz
</A>
-<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c0.tar.gz">
-ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c0.tar.gz
+<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c3.tar.gz">
+ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c3.tar.gz
</A>
@end ifset
@noindent
-Unpack SLIB (@samp{tar xzf slib2c0.tar.gz} or @samp{unzip -ao
-slib2c0.zip}) in an appropriate directory for your system; both
+Unpack SLIB (@samp{tar xzf slib2c3.tar.gz} or @samp{unzip -ao
+slib2c3.zip}) in an appropriate directory for your system; both
@code{tar} and @code{unzip} will create the directory @file{slib}.
@noindent
Then create a file @file{require.scm} in the SCM
@dfn{implementation-vicinity} (this is the same directory as where the
-file @file{Init.scm} is installed). @file{require.scm} should have the
+file @file{Init5c3.scm} is installed). @file{require.scm} should have the
contents:
@example
@@ -551,7 +542,7 @@ bash$ ./build.scm
@print{}
#!/bin/sh
rm -f scmflags.h
-echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
+echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
@@ -572,7 +563,7 @@ bash$ ./build.scm -p vms
$DELETE scmflags.h
$CREATE scmflags.h
$DECK
-#define IMPLINIT "/home/jaffer/scm/Init.scm"
+#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"
#define BIGNUMS
#define FLOATS
#define ARRAYS
@@ -675,7 +666,7 @@ specifies that that @var{flag} will be put on linker command-lines.
@deffn {Build Option} -s @var{pathname}
@deffnx {Build Option} ---scheme-initial=@var{pathname}
specifies that @var{pathname} should be the default location of the SCM
-initialization file @file{Init.scm}. SCM tries several likely locations
+initialization file @file{Init5c3.scm}. SCM tries several likely locations
before resorting to @var{pathname} (@pxref{File-System Habitat}).
If not specified, the current directory (where build is building) is
used.
@@ -912,7 +903,7 @@ bash$ build -c foo.c -i init_foo
@print{}
#!/bin/sh
rm -f scmflags.h
-echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
+echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h
echo '#define COMPILED_INITS init_foo();'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
@@ -931,7 +922,7 @@ bash$ build -t dll -c foo.c
@print{}
#!/bin/sh
rm -f scmflags.h
-echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
+echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
@@ -1090,6 +1081,7 @@ the compilation command lines or add a @code{#define @var{flag}} line to
------- ----------
ARM_ULIB Huw Rogers free unix library for acorn archimedes
AZTEC_C Aztec_C 5.2a
+__CYGWIN32__ cygwin32(?)
_DCC Dice C on AMIGA
__GNUC__ Gnu CC (and DJGPP)
__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0
@@ -1097,9 +1089,12 @@ __HIGHC__ MetaWare High C
__IBMC__ C-Set++ on OS/2 2.1
_MSC_VER MS VisualC++ 4.2
MWC Mark Williams C on COHERENT
+__MWERKS__ Metrowerks Compiler; Macintosh and WIN32 (?)
+_POSIX_SOURCE ??
_QC Microsoft QuickC
__STDC__ ANSI C compliant
__TURBOC__ Turbo C and Borland C
+__USE_POSIX ??
__WATCOMC__ Watcom C on MS-DOS
__ZTC__ Zortech C
@@ -1111,6 +1106,7 @@ GNUDOS DJGPP (obsolete in version 1.08)
__GO32__ DJGPP (future?)
hpux HP-UX
linux Linux
+macintosh Macintosh (THINK_C and __MWERKS__ define)
MCH_AMIGA Aztec_c 5.2a on AMIGA
MSDOS Microsoft C 5.10 and 6.00A
__MSDOS__ Turbo C, Borland C, and DJGPP
@@ -1214,14 +1210,14 @@ Don't try to run as subproccess
@item remove @dots{} in scmfig.h and recompile scm
@itemx add @dots{} in scmfig.h and recompile scm
Do it and recompile files.
-@item ERROR: @file{Init.scm} not found
+@item ERROR: @file{Init5c3.scm} not found
Assign correct IMPLINIT in makefile or @file{scmfig.h} or define
environment variable @code{SCM_INIT_PATH} to be the full pathname of
-@file{Init.scm} (@pxref{Installing SCM}).
+@file{Init5c3.scm} (@pxref{Installing SCM}).
@item WARNING: require.scm not found
define environment variable @code{SCHEME_LIBRARY_PATH} to be the full
pathname of the scheme library [SLIB] or change @code{library-vicinity} in
-@file{Init.scm} to point to library or remove. @xref{Installation, , , slib,
+@file{Init5c3.scm} to point to library or remove. @xref{Installation, , , slib,
SLIB}.
Make sure the value of @code{(library-vicinity)} has a trailing file
@@ -1291,7 +1287,7 @@ smaller than @code{HEAP_SEG_SIZE}).
@item ERROR: Rogue pointer in Heap.
See above under machine crashes.
@item Newlines don't appear correctly in output files.
-Check file mode (define OPEN_@dots{} in @file{Init.scm}
+Check file mode (define OPEN_@dots{} in @file{Init5c3.scm}
@item Spaces or control characters appear in symbol names
Check character defines in @file{scmfig.h}.
@item Negative numbers turn positive.
@@ -1371,7 +1367,7 @@ variable @var{SCM_INIT_PATH}.
If @var{SCM_INIT_PATH} is not defined or if the file it names is not
present, @code{scm} tries to find the directory containing the
executable file. If it is able to locate the executable, @code{scm}
-looks for the initialization file (usually @file{Init.scm}) in
+looks for the initialization file (usually @file{Init5c3.scm}) in
platform-dependent directories relative to this directory.
@xref{File-System Habitat} for a blow-by-blow description.
@@ -1382,13 +1378,13 @@ compile parameter @var{IMPLINIT} (defined in the makefile or
@noindent
Unless the option @code{-no-init-file} or @code{--no-init-file} occurs
-in the command line, @file{Init.scm} checks to see if there is file
+in the command line, @file{Init5c3.scm} checks to see if there is file
@file{ScmInit.scm} in the path specified by the environment variable
@var{HOME} (or in the current directory if @var{HOME} is undefined). If
it finds such a file it is loaded.
@noindent
-@file{Init.scm} then looks for command input from one of three sources:
+@file{Init5c3.scm} then looks for command input from one of three sources:
From an option on the command line, from a file named on the command
line, or from standard input.
@@ -1558,7 +1554,7 @@ Like above but @code{rev4-optional-procedures} are also loaded.
@defvr {Environment Variable} SCM_INIT_PATH
is the pathname where @code{scm} will look for its initialization
-code. The default is the file @file{Init.scm} in the source directory.
+code. The default is the file @file{Init5c3.scm} in the source directory.
@end defvr
@defvr {Environment Variable} SCHEME_LIBRARY_PATH
@@ -1566,7 +1562,7 @@ is the [SLIB] Scheme library directory.
@end defvr
@defvr {Environment Variable} HOME
-is the directory where @file{Init.scm} will look for the user
+is the directory where @file{Init5c3.scm} will look for the user
initialization file @file{ScmInit.scm}.
@end defvr
@@ -1655,18 +1651,7 @@ Editing of Scheme code is supported by emacs. Buffers holding files
ending in .scm are automatically put into scheme-mode. EMACS for MS-DOS
and MS-Windows systems is available (free) from:
-@ifclear html
-@itemize @bullet
-@item
-http://simtel.coast.net/SimTel/gnu/demacs.html
-@end itemize
-@end ifclear
-
-@ifset html
-<A HREF="http://simtel.coast.net/SimTel/gnu/demacs.html">
-http://simtel.coast.net/SimTel/gnu/demacs.html
-</A>
-@end ifset
+@center @url{http://simtel.coast.net/SimTel/gnu/demacs.html}
If your Emacs can run a process in a buffer you can use the Emacs
command @samp{M-x run-scheme} with SCM. Otherwise, use the emacs
@@ -1800,7 +1785,7 @@ offers source code debugging from
GNU Emacs. PSD runs slowly, so start by instrumenting only a few
functions at a time.
@lisp
-ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
+swissnet.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz
ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz
ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz
@@ -1899,14 +1884,14 @@ signal warnings and errors.
@defun warn arg1 arg2 arg3 @dots{}
Alias for @ref{System, slib:warn, , slib, SLIB}. Outputs an error
message containing the arguments. @code{warn} is defined in
-@file{Init.scm}.
+@file{Init5c3.scm}.
@end defun
@defun error arg1 arg2 arg3 @dots{}
Alias for @ref{System, slib:error, , slib, SLIB}. Outputs an error
message containing the arguments, aborts evaluation of the current form
and resumes the top level read-eval-print loop. @code{Error} is defined
-in @file{Init.scm}.
+in @file{Init5c3.scm}.
@end defun
@noindent
@@ -1927,7 +1912,7 @@ systems.
@defun stack-trace
Prints information describing the stack of partially evaluated
expressions. @code{stack-trace} returns @code{#t} if any lines were
-printed and @code{#f} otherwise. See @file{Init.scm} for an example of
+printed and @code{#f} otherwise. See @file{Init5c3.scm} for an example of
the use of @code{stack-trace}.
@end defun
@@ -1958,7 +1943,7 @@ top-level have @r{#@@} prepended.
@noindent
For instance, @code{open-input-file} is defined as follows in
-@file{Init.scm}:
+@file{Init5c3.scm}:
@example
(define (open-input-file str)
@@ -2016,7 +2001,7 @@ interactive, or should quit after the command line is processed.
@var{*interactive*} is controlled directly by the command-line options
@samp{-b}, @samp{-i}, and @samp{-s} (@pxref{Invoking SCM}). If none of
these options are specified, the rules to determine interactivity are
-more complicated; see @file{Init.scm} for details.
+more complicated; see @file{Init5c3.scm} for details.
@end defvar
@defun abort
@@ -2072,7 +2057,7 @@ also gives the hexadecimal heap segment and stack bounds.
@end defun
@defvr Constant *scm-version*
-Contains the version string (e.g. @file{5b3}) of SCM.
+Contains the version string (e.g. @file{5c3}) of SCM.
@end defvr
@subsection Executable path
@@ -2088,6 +2073,7 @@ by calling @code{execpath} with the pathname.
Returns the path (string) which SCM uses to find the executable file
whose invocation the currently running session is, or #f if the path is
not set.
+
@defunx execpath #f
@defunx execpath newpath
Sets the path to @code{#f} or @var{newpath}, respectively. The old path
@@ -2701,9 +2687,15 @@ These procedures generalize and extend the standard capabilities in
@ref{Ports, , ,r4rs, Revised(4) Scheme}.
@defun open-file string modes
+@defunx try-open-file string modes
Returns a port capable of receiving or delivering characters as
specified by the @var{modes} string. If a file cannot be opened
@code{#f} is returned.
+
+Internal functions opening files @dfn{callback} to the SCM function
+@code{open-file}. You can extend @code{open-file} by redefining it.
+@code{try-open-file} is the primitive procedure; Do not redefine
+@code{try-open-file}!
@end defun
@defvr Constant open_read
@@ -2784,6 +2776,10 @@ interactive port that has no ready characters.
@c end rationale
@end deffn
+@defun isatty? port
+Returns @code{#t} if @var{port} is input or output to a serial non-file device.
+@end defun
+
@node Soft Ports, Syntax Extensions, Files and Ports, The Language
@section Soft Ports
@@ -2915,7 +2911,64 @@ If @var{identifier} is unbound in the top level environment, then
@var{initial-value} as if the @code{defvar} form were instead the form
@code{(define identifier initial-value)} . If @var{identifier} already
has a value, then @var{initial-value} is @emph{not} evaluated and
-@var{identifier}'s value is not changed.
+@var{identifier}'s value is not changed. @code{defconst} is valid only
+when used at top-level.
+@end defspec
+
+@defspec defconst identifier value
+If @var{identifier} is unbound in the top level environment, then
+@var{identifier} is @code{define}d to the result of evaluating the form
+@var{value} as if the @code{defconst} form were instead the form
+@code{(define identifier value)} . If @var{identifier} already has a
+value, then @var{value} is @emph{not} evaluated, @var{identifier}'s
+value is not changed, and an error is signaled. @code{defconst} is
+valid only when used at top-level.
+@end defspec
+
+@defspec casev key clause1 clause2 @dots{}
+@code{casev} is an extension of standard Scheme @code{case}: Each
+@var{clause} of a @code{casev} statement must have as first element a
+list containing elements which are:
+
+@itemize @bullet
+@item
+literal datums, or
+@item
+a comma followed by the name of a symbolic constant, or
+@item
+a comma followed by an at-sign (@@) followed by the name of a symbolic
+constant whose value is a list.
+@end itemize
+
+A @code{casev} statement is equivalent to a @code{case} statement in
+which these symbolic constants preceded by commas have been replaced by
+the values of the constants, and all symbolic constants preceded by
+comma-at-signs have been replaced by the elements of the list values of
+the constants. This use of comma, (or, equivalently, @code{unquote}) is
+similar to that of @code{quasiquote} except that the unquoted
+expressions must be @dfn{symbolic constants}.
+
+Symbolic constants are defined using @code{defconst}, their values are
+substituted in the head of each @code{casev} clause during macro
+expansion. @code{defconst} constants should be defined before use.
+@code{casev} can be substituted for any correct use of @code{case}.
+
+@format
+@t{(defconst unit '1)
+(defconst semivowels '(w y))
+(casev (* 2 3)
+ ((2 3 5 7) 'prime)
+ ((,unit 4 6 8 9) 'composite)) ==> composite
+(casev (car '(c d))
+ ((a) 'a)
+ ((b) 'b)) ==> @emph{unspecified}
+(casev (car '(c d))
+ ((a e i o u) 'vowel)
+ ((,@@semivowels) 'semivowel)
+ (else 'consonant)) ==> consonant
+}
+@end format
+
@end defspec
@noindent
@@ -2966,9 +3019,13 @@ from @var{proc} which has been passed to
(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example
+@end defun
-An @dfn{environment} is a list of @dfn{environment frames}. There are 2
-types of environment frames:
+@defun environment->tree env
+An @dfn{environment} is an opaque object representing lexical bindings.
+@code{environment->tree} returns a representation of the environment
+@var{env} as a list of environment frames. There are 2 types of
+environment frames:
@table @code
@item ((lambda (variable1 @dots{}) @dots{}) value1 @dots{})
@@ -2989,8 +3046,19 @@ result in an environment frame for each variable:
@end defun
@defspec @@apply procedure argument-list
-Returns the result of applying procedure to argument-list. (apply
-procedure argument-list) will produce the same result.
+Returns the result of applying @var{procedure} to @var{argument-list}.
+@code{@@apply} differs from @code{apply} when the identifiers bound by
+the closure being applied are @code{set!}; setting affects
+@var{argument-list}.
+
+@example
+(define lst (list 'a 'b 'c))
+(@@apply (lambda (v1 v2 v3) (set! v1 (cons v2 v3))) lst)
+lst @result{} ((b . c) b c)
+@end example
+
+Thus a mutable environment can be treated as both a list and local
+bindings.
@end defspec
@defspec @@call-with-current-continuation procedure)
@@ -3022,7 +3090,7 @@ use the predicate @code{symbol?}.
A synthetic identifier includes two data: a parent, which is an
identifier, and an environment, which is either @code{#f} or a lexical
-environment which has been passed to a macro expander
+environment which has been passed to a @dfn{macro expander}
(a procedure passed as an argument to @code{procedure->macro},
@code{procedure->memoizing-macro}, or @code{procedure->syntax}).
@@ -3149,10 +3217,10 @@ redefinition, for example:
* Dump:: Create Fast-Booting Executables
* Numeric:: Numeric Language Extensions
* Arrays:: As in APL
-* I/O-Extensions:: 'i/o-extensions
-* Posix Extensions:: 'posix
-* Regular Expression Pattern Matching:: 'regex
-* Line Editing:: 'edit-line
+* I/O-Extensions:: i/o-extensions
+* Posix Extensions:: posix
+* Regular Expression Pattern Matching:: regex
+* Line Editing:: edit-line
* Curses:: Screen Control
* Sockets:: Cruise the Net
@end menu
@@ -3183,7 +3251,7 @@ scm -e'(link-named-scm"cute""cube")'
(lambda (fp)
(for-each
(lambda (string) (write-line string fp))
- '("#define IMPLINIT \"/home/jaffer/scm/Init.scm\""
+ '("#define IMPLINIT \"/home/jaffer/scm/Init5c3.scm\""
"#define COMPILED_INITS init_cube();"
"#define BIGNUMS"
"#define FLOATS"
@@ -3520,7 +3588,7 @@ is not real.
@menu
* Conventional Arrays::
-* Array Mapping::
+* Array Mapping:: array-for-each
* Uniform Array::
* Bit Vectors::
@end menu
@@ -3829,8 +3897,7 @@ Returns @code{#t} if the @var{obj} is an array of type corresponding to
@defun make-uniform-array prototype bound1 bound2 @dots{}
Creates and returns a uniform array of type corresponding to
-@var{prototype} that has as many dimensions as there are @var{bound}s
-and fills it with @var{prototype}.
+@var{prototype} that has as many dimensions as there are @var{bound}s.
@end defun
@defun array-prototype array
@@ -3890,6 +3957,34 @@ omitted, in which case it defaults to the value returned by
@code{(current-output-port)}.
@end defun
+@defun logaref array index1 index2 @dots{}
+If an @var{index} is provided for each dimension of @var{array} returns
+the @var{index1}, @var{index2}, @dots{}'th element of @var{array}. If
+one more @var{index} is provided, then the last index specifies bit
+position of the twos-complement representation of the array element
+indexed by the other @var{index}s returning @code{#t} if the bit is 1,
+and @code{#f} if 0. It is an error if this element is not an exact
+integer.
+
+@example
+(logaref '#(#b1101 #b0010) 0) @result{} #b1101
+(logaref '#(#b1101 #b0010) 0 1) @result{} #f
+(logaref '#2((#b1101 #b0010)) 0 0) @result{} #b1101
+@end example
+@end defun
+
+@defun logaset! array val index1 index2 @dots{}
+If an @var{index} is provided for each dimension of @var{array} sets the
+@var{index1}, @var{index2}, @dots{}'th element of @var{array} to
+@var{val}. If one more @var{index} is provided, then the last index
+specifies bit position of the twos-complement representation of an exact
+integer array element, setting the bit to 1 if @var{bool} is @code{#t}
+and to 0 if @var{bool} is @code{#f} if 0. In this case it is an error
+if the array element is not an exact integer or if @var{val} is not
+boolean.
+@end defun
+
+
@node Bit Vectors, , Uniform Array, Arrays
@subsection Bit Vectors
@@ -3947,10 +4042,6 @@ Returns
If @code{'i/o-extensions} is provided (by linking in @file{ioext.o}),
@ref{Line I/O, , , slib, SLIB}, and the following functions are defined:
-@defun isatty? port
-Returns @code{#t} if @var{port} is input or output to a serial non-file device.
-@end defun
-
@defun stat <port-or-string>
Returns a vector of integers describing the argument. The argument
can be either a string or an open input port. If the argument is an
@@ -5242,7 +5333,7 @@ Returns the host address number (integer) for host @var{string} or
@defun inet:address->string address
Converts an internet (integer) address to a string in numbers and dots
-notation. This is an inverse function to inet:address.
+notation.
@end defun
@defun inet:network address
@@ -5461,7 +5552,7 @@ or you can use a client written in scheme:
@end example
-@node The Implementation, Procedure and Macro Index, Packages, Top
+@node The Implementation, Index, Packages, Top
@chapter The Implementation
@menu
@@ -5705,8 +5796,14 @@ Returns non-zero if @var{x} is a @code{tc3_cons} or isn't, respectively.
@deftp Cell tc3_closure
applicable object returned by (lambda (args) @dots{}).
-@code{tc3_closure}s have a pointer to other the body of the procedure in
-the @code{CAR} and a pointer to the environment in the @code{CDR}.
+@code{tc3_closure}s have a pointer to the body of the procedure in the
+@code{CAR} and a pointer to the environment in the @code{CDR}. Bits 1
+and 2 (zero-based) in the @code{CDR} indicate a lower bound on the
+number of required arguments to the closure, which is used to avoid
+allocating rest argument lists in the environment cache. This encoding
+precludes an immediate value for the @code{CDR}: In the case of
+an empty environment all bits above 2 in the @code{CDR} are zero.
+
@defmac CLOSUREP x
Returns non-zero if @var{x} is a @code{tc3_closure}.
@@ -5717,6 +5814,11 @@ Returns non-zero if @var{x} is a @code{tc3_closure}.
Returns the code body or environment of closure @var{x}, respectively.
@end defmac
+@defmac ARGC x
+Returns the a lower bound on the number of required arguments to closure
+@var{x}, it cannot exceed 3.
+@end defmac
+
@end deftp
@node Header Cells, Subr Cells, Cells, Data Types
@@ -6077,7 +6179,7 @@ gloc PPPPPPPPPPPPPPPPPPPPPPPPPPPPP001}
1s and 0s here indicate type. G missing means sys (not GC'd)
SIMPLE:}
@t{cons ..........SCM car..............0 ...........SCM cdr.............G
-closure ..........SCM code...........011 ...........SCM env.............G
+closure ..........SCM code...........011 ...........SCM env...........CCG
HEADERs:
ssymbol .........long length....G0000101 ..........char *chars...........
msymbol .........long length....G0000111 ..........char *chars...........
@@ -6139,6 +6241,7 @@ array ...short rank..cxxxxxxxxG1111111 ............*array..............}
@menu
* Garbage Collection:: Automatically reclaims unused storage
+* Memory Management for Environments::
* Signals::
* C Macros::
* Changing Scm::
@@ -6152,7 +6255,7 @@ array ...short rank..cxxxxxxxxG1111111 ............*array..............}
* Evaluation:: Why SCM is fast
@end menu
-@node Garbage Collection, Signals, Operations, Operations
+@node Garbage Collection, Memory Management for Environments, Operations, Operations
@subsection Garbage Collection
The garbage collector is in the latter half of @file{sys.c}. The
@@ -6237,7 +6340,116 @@ object is freed. If the type header of smob is collected, the smob's
@code{free} procedure is called to free its storage.
@end deftypefun
-@node Signals, C Macros, Garbage Collection, Operations
+@node Memory Management for Environments, Signals, Garbage Collection, Operations
+@subsection Memory Management for Environments
+
+@itemize @bullet
+@item
+@dfn{Ecache} was designed and implemented by Radey Shouman.
+
+@item
+This documentation of ecache was written by Tom Lord.
+@end itemize
+
+The memory management component of SCM contains special features which
+optimize the allocation and garbage collection of environments.
+
+The optimizations are based on certain facts and assumptions:
+
+The SCM evaluator creates many environments with short lifetimes and
+these account of a @emph{large portion} of the total number of objects
+allocated.
+
+The general purpose allocator allocates objects from a freelist, and
+collects using a mark/sweep algorithm. Research into garbage
+collection suggests that such an allocator is sub-optimal for object
+populations containing a large portion of short-lived members and that
+allocation strategies involving a copying collector are more
+appropriate.
+
+It is a property of SCM, reflected throughout the source code, that a
+simple copying collector can not be used as the general purpose memory
+manager: much code assumes that the run-time stack can be treated as a
+garbage collection root set using @dfn{conservative garbage collection}
+techniques, which are incompatible with objects that change location.
+
+Nevertheless, it is possible to use a mostly-separate
+copying-collector, just for environments. Roughly speaking, cons
+pairs making up environments are initially allocated from a small heap
+that is collected by a precise copying collector. These objects must
+be handled specially for the collector to work. The (presumably)
+small number of these objects that survive one collection of the
+copying heap are copied to the general purpose heap, where they will
+later be collected by the mark/sweep collector. The remaining pairs
+are more rapidly collected than they would otherwise be and all of
+this collection is accomplished without having to mark or sweep any
+other segment of the heap.
+
+Allocating cons pairs for environments from this special heap is a
+heuristic that approximates the (unachievable) goal:
+
+@quotation
+allocate all short-lived objects from the copying-heap, at no extra cost
+in allocation time.
+@end quotation
+
+
+@subsubheading Implementation Details
+
+A separate heap (@code{ecache_v}) is maintained for the copying
+collector. Pairs are allocated from this heap in a stack-like fashion.
+Objects in this heap may be protected from garbage collection by:
+
+@enumerate
+@item
+Pushing a reference to the object on a stack specially maintained for
+that purpose. This stack (@code{scm_estk}) is used in place of the C
+run-time stack by the SCM evaluator to hold local variables which refer
+to the copying heap.
+
+@item
+Saving a reference to every object in the mark/sweep heap which directly
+references the copying heap in a root set that is specially maintained
+for that purpose (@code{scm_egc_roots}). If no object in the mark/sweep
+heap directly references an object from the copying heap, that object
+can be preserved by storing a direct reference to it in the
+copying-collector root set.
+@item
+Keeping no other references to these objects, except references between
+the objects themselves, during copying collection.
+@end enumerate
+
+When the copying heap or root-set becomes full, the copying collector is
+invoked. All protected objects are copied to the mark-sweep heap. All
+references to those objects are updated. The copying collector root-set
+and heap are emptied.
+
+References to pairs allocated specificly for environments are
+inaccessible to the Scheme procedures evaluated by SCM. These pairs
+are manipulated by only a small number of code fragments in the
+interpreter. To support copying collection, those code fragments
+(mostly in @file{eval.c}) have been modified to protect environments from
+garbage collection using the three rules listed above.
+
+During a mark-sweep collection, the copying collector heap is marked
+and swept almost like any ordinary segment of the general purpose
+heap. The only difference is that pairs from the copying heap that
+become free during a sweep phase are not added to the freelist.
+
+The environment cache is disabled by adding @code{#define NO_ENV_CACHE}
+to @file{eval.c}; all environment cells are then allocated from the
+regular heap.
+
+@subsubheading Relation to Other Work
+
+This work seems to build upon a considerable amount of previous work
+into garbage collection techniques about which a considerable amount
+of literature is available.
+
+
+
+
+@node Signals, C Macros, Memory Management for Environments, Operations
@subsection Signals
@defun init_signals
@@ -6263,9 +6475,10 @@ macros @code{DEFER_INTS} and @code{ALLOW_INTS}.
@defmac DEFER_INTS
sets the global variable @code{ints_disabled} to 1. If an interrupt
-occurs during a time when @code{ints_disabled} is 1 one of the global
-variables @code{sig_deferred} or @code{alrm_deferred} is set to 1 and
-the handler returns.
+occurs during a time when @code{ints_disabled} is 1, then
+@code{deferred_proc} is set to non-zero, one of the global variables
+@code{SIGINT_deferred} or @code{SIGALRM_deferred} is set to 1, and the
+handler returns.
@defmacx ALLOW_INTS
Checks the deferred variables and if set the appropriate handler is
@@ -6348,7 +6561,8 @@ SCM_dummy1 = (SCM) &@i{foo};
@noindent
@code{SCM_dummy} variables are not currently defined. Passing the
address of the local @code{SCM} variable to @emph{any} procedure also
-protects it.
+protects it. The procedure @code{scm_protect_temp} is provided for
+this purpose.
@noindent
Also, if you maintain a static pointer to some (non-immediate)
@@ -6436,7 +6650,7 @@ will append a symbol @code{'@i{foo}} to the (list) value of
put any scheme code which needs to be run as part of your package into
@file{I@i{foo}.scm}.
@item
-put an @code{if} into @file{Init.scm} which loads @file{I@i{foo}.scm} if
+put an @code{if} into @file{Init5c3.scm} which loads @file{I@i{foo}.scm} if
your package is included:
@example
@@ -6695,7 +6909,7 @@ The source code for these routines are found in @file{rope.c}.
@deftypefun int scm_ldfile (char *@var{file})
Loads the Scheme source file @var{file}. Returns 0 if successful, non-0
if not. This function is used to load SCM's initialization file
-@file{Init.scm}.
+@file{Init5c3.scm}.
@end deftypefun
@deftypefun int scm_ldprog (char *@var{file})
@@ -6979,24 +7193,6 @@ the size down, certain @code{EVALCAR} calls which don't need to be fast
(because they rarely occur or because they are part of expensive
operations) are instead calls to the C function @code{evalcar}.
-There was some discussion a year ago about a "Forth" style Scheme
-interpreter. This is the only improvement I know of which would beat
-SCM in speed.
-
-@quotation
-Provided there is still type code space available in SCM, if we devote
-some of the IMCAR codes to "inlined" operations, we should get a
-significant performance boost. What is eliminated is the having to look
-up a @code{GLOC} or @code{ILOC} and then dispatch on the subr type. The
-IMCAR operation would be dispatched to directly. Another way to view
-this is that we make available special form versions of @code{CAR},
-@code{CDR}, etc. Since the actual operation code is localized in the
-interpreter, it is much easier than uncompilation and then recompilation
-to handle @code{(trace car)}; For instance a switch gets set which tells
-the interpreter to instead always look up the values of the associated
-symbols.
-@end quotation
-
@defvar symhash
Top level symbol values are stored in the @code{symhash} table.
@code{symhash} is an array of lists of @code{ISYM}s and pairs of symbols
@@ -7011,6 +7207,18 @@ far in to go for the value. When this immediate object is subsequently
encountered, the value can be retrieved quickly.
@end deftp
+@code{ILOC}s work up to a maximum depth of 4096 frames or 4096
+identifiers in a frame. Radey Shouman added @dfn{FARLOC}
+@tindex FARLOC
+to handle cases exceeding these limits. A @code{FARLOC} consists of a
+pair whose CAR is the immediate type @code{IM_FARLOC_CAR} or
+@code{IM_FARLOC_CDR}, and whose CDR is a pair of INUMs specifying the
+frame and distance with a larger range than @code{ILOC}s span.
+
+Adding @code{#define TEST_FARLOC} to @file{eval.c} causes @code{FARLOC}s
+to be generated for all local identifiers; this is useful only for
+testing memoization.
+
@deftp Immediate GLOC
Pointers to symbols not defined in local environments are changed to one
plus the value cell address in symhash. This incremented pointer is
@@ -7145,7 +7353,7 @@ subdirectory. For example, the executable might be
@subsection Executable Pathname
@noindent
-For purposes of finding @file{Init.scm}, dumping an executable, and
+For purposes of finding @file{Init5c3.scm}, dumping an executable, and
dynamic linking, a SCM session needs the pathname of its executable
image.
@@ -7230,6 +7438,8 @@ Returns the number of argument strings in @var{argv}.
@itemize @bullet
@item
+Allow users to set limits for @code{malloc()} storage.
+@item
Prefix and make more uniform all C function, variable, and constant
names. Provide a file full of #define's to provide backward
compatability.
@@ -7248,10 +7458,6 @@ Currently, @code{dump}ing an executable does not preserve ports. When
loading a @code{dump}ed executable, disk files could be reopened to the
same file and position as they had when the executable was dumped.
@item
-Compaction could be done to @code{malloc}ed objects by freeing and
-reallocing all the malloc objects encountered in a scan of the heap.
-Whether compactions would actually occur is system depenedent.
-@item
Copying all of the stack is wasteful of storage. Any time a
call-with-current-continuation is called the stack could be re-rooted
with a frame which calls the contin just created. This in combination
@@ -7274,6 +7480,25 @@ This is trickier than it first looks because the must_malloc() routine
is also used for allocating heap segments, which do not have the
@code{LENGTH} field restriction. Putting the 24 bit test into
@code{must_malloc()} should be tested for speed impact.
+
+@item
+In the quest for speed, there has been some discussion about a "Forth"
+style Scheme interpreter.
+
+@quotation
+Provided there is still type code space available in SCM, if we devote
+some of the IMCAR codes to "inlined" operations, we should get a
+significant performance boost. What is eliminated is the having to look
+up a @code{GLOC} or @code{ILOC} and then dispatch on the subr type. The
+IMCAR operation would be dispatched to directly. Another way to view
+this is that we make available special form versions of @code{CAR},
+@code{CDR}, etc. Since the actual operation code is localized in the
+interpreter, it is much easier than uncompilation and then recompilation
+to handle @code{(trace car)}; For instance a switch gets set which tells
+the interpreter to instead always look up the values of the associated
+symbols.
+@end quotation
+
@end itemize
@menu
@@ -7534,21 +7759,22 @@ copying various files over to MS-DOS/WINDOWS.
@end itemize
-@node Procedure and Macro Index, Variable Index, The Implementation, Top
+@node Index, , The Implementation, Top
+@c @node Procedure and Macro Index, Variable Index, The Implementation, Top
@unnumbered Procedure and Macro Index
This is an alphabetical list of all the procedures and macros in SCM.
@printindex fn
-@node Variable Index, Type Index, Procedure and Macro Index, Top
+@c @node Variable Index, Type Index, Procedure and Macro Index, Top
@unnumbered Variable Index
This is an alphabetical list of all the global variables in SCM.
@printindex vr
-@node Type Index, , Variable Index, Top
+@c @node Type Index, , Variable Index, Top
@unnumbered Type Index
This is an alphabetical list of data types and feature names in SCM.