.\" $Revision: 1.25 $ .\" .ds Vs 3.0 .\" .so ../util/tmac.scheme .\" .\" Courier bold; used for system output in transcripts. .ie \n(.U .fp 6 B .el .fp 6 CB .\" .\" Code start. .de Cs .nr sF \\n(.f .ft 5 .ps -1 .vs -1 .ie \n(.U .RS .el .in 1c .nf .if !\n(.U .sp .3c .. .\" Code end. .de Ce .fi .ie \n(.U .RE .el .in .vs .ps .ft \\n(sF .. .\" Newline in code. .de Cl .sp .6 .. .\" Same as .Cl .de El .Cl .. .\" Example start/end. As floating keeps (used for figures .\" in this document) and regular keeps cannot be mixed, the .\" functionality must be simulated here. This sucks... .de Es .Cs .if !\n(.U .di EE .. .de Ee .Ce .if !\n(.U \{\ .di .if \\n(dn-\\n(.t .sp 1000 .nf .EE .fi .sp .5 .\} .. .\" .K1 header-text .\" Major heading with TOC entry. .de K1 .NH \\$1 .XS \\*(SN \\$1 .XE .. .\" .K2 header-text .\" Level-2 heading with TOC entry. .de K2 .NH 2 \\$1 .XS \\n(PN 2n \\*(SN \\$1 .XE .. .\" .K3 header-text .\" Level-3 heading with TOC entry. .de K3 .NH 3 \\$1 .XS \\n(PN 4n \\*(SN \\$1 .XE .. .\" .AP appendix-text .\" Appendix with TOC entry. .de AP .ie \\n(.U .NH .el .SH \\$1 .XS \\$1 .XE .. .\" .Rf name value .\" Reference anchor. Each occurrence of `name' anywhere in .\" the document will be replaced by `value'. .de Rf .if !\n(.U .tm s/@(\\$1)/\\$2/g .. .\" .\" Counter for Figures (auto-pre-increment). .nr fS 0 1 .\" .\" Figure start. .de Fs .br .ie \\n(.$ .KS .el .KF .sp 1.2 \u\l'\\n(.lu_'\d .nr sF \\n(.f .ft 5 .ps -1 .vs -1 .nf .. .\" .Fc caption-text .\" Figure caption. Used at end of Figure, before .Fe. .de Fc .sp .2 .fi .ps .vs .ft \\n(sF .ce 999 \s-1\f3Figure \\n+(fS:\fP \c \\$1\s0 .if \\n(.$=2 \s-1\&\\$2\s0 .ce 0 .. .\" .Fe name .\" Figure end. Defines a reference anchor `name' with the .\" number of the Figure as value. .de Fe .Rf \\$1 \\n(fS .LP \l'\\n(.lu_' .sp .KE .. .\" Relative indent start. .de Rs .if !\\n(.U .RS .. .\" Relative indent end. .de Re .if !\\n(.U .RE .. .\" .TL Building Extensible Applications with Elk \*- .sp .3 C/C++ Programmer's Manual .AU Oliver Laumann .AB Elk (\f2Extension Language Kit\fP) is a Scheme implementation designed as an embeddable, reusable extension language subsystem for integration into existing and future applications written in C or C++. The programmer's interface to Elk provides for a close interworking of the C/C++ parts of Elk-based, \f2hybrid\fP applications with extensible Scheme code. This manual describes the facilities of the C/C++ programmer's interface that can be used by authors of extensible applications and Scheme extensions. Topics range from the architecture of Elk-based applications and the definition of application-specific Scheme types and primitives to more advanced subjects such as weak data structures and interacting with the garbage collector. Many examples throughout the text illustrate the facilities and techniques discussed in this manual. .AE .\" --------------------------------------------------------------------------- .K1 "Additional Documentation" .PP The official specification of the Scheme programming language is the @[.``R\*(^4RS''] (William Clinger and Jonathan Rees (editors), \f2Revised\*(^4 Report on the Algorithmic Language Scheme\fP, 1991). A slightly modified version of an earlier revision of this report was adopted as an IEEE an ANSI standard in 1990 (IEEE\|Std\|1178-1990, \f2IEEE Standard for the Scheme Programming Language\fP, 1991). .PP The dialect of Scheme implemented by Elk (a superset of the official language) is described in the \f2Reference Manual for the Elk Extension Language Interpreter\fP that is included in the Elk distribution as troff source and preformatted PostScript files. Reference manuals for the various predefined Elk extensions (such as the UNIX and X11 extensions) are also part of the distribution; see the file ``doc/README'' for an overview of the available documentation. .PP This manual supersedes the document \f2Interfacing Scheme to the ``Real World''\fP that was included in earlier versions of Elk. .PP An article about Elk has appeared in USENIX Computing Systems in 1994 (Oliver Laumann and Carsten Bormann, Elk: The Extension Language Kit, \f2USENIX Computing Systems\fP, vol.\& 7, no.\& 4, pp.\& 419\-449). .PP A recent example of an application that uses Elk as its extension language implementation is freely available in source and binary form as \f2http://www.informatik.uni-bremen.de/~net/unroff\fP. @[.\f2unroff\fP] is a programmable, extensible troff translator with Scheme-based back-ends for the Hypertext Markup Language. The source code shown in Appendix B has been directly taken from the \f2unroff\fP source; authors of Elk-based applications are encourage to reuse this and other parts of the \f2unroff\fP source for their own projects. .\" --------------------------------------------------------------------------- .K1 "Introduction" .PP This manual can be roughly divided into two parts. The first part (chapters\ @(ch-arch) to\ @(ch-static)) describes the architectural aspects of Elk-based applications and Elk extensions. Facilities and tools for building extensible applications with Elk are introduced here. Readers who are already familiar with the concepts explained in this part of the document may want to skip it and begin reading at chapter\ @(ch-notes) or later. The second part (covering chapters\ @(ch-notes) to\ @(ch-advanced)) specifies the C functions and types available to application programmers and describes techniques for building data structures that can be interfaced to Scheme in an efficient way. Appendix C briefly summarizes all the functions, macros, types, and variables exported by the Elk kernel to the C/C++ programmer. .PP Here is a short overview of the remaining chapters of this manual. Chapter\ @(ch-arch) discusses the architecture of extensible applications based on Elk and their relation to Elk extensions. Chapter\ @(ch-linking) provides an overview of the two basic methods for integrating an application (or extensions) with Elk: dynamic loading and static linking. Chapter\ @(ch-dynl) describes use of dynamic loading in more detail; topics include automatic extension initialization and C++ static constructors embedded in dynamically loaded modules. Chapter\ @(ch-static) describes several forms of linking user-supplied code with Elk statically and how these affect the structure of an application's \f2main()\fP function. .PP The remaining chapters are a complete specification of the functions and types of the C/C++ programmer's interface to Elk. Chapter\ @(ch-notes) provides introductory notes and advice for programmers of C/C++ code interfacing to Elk (use of include files, predefined preprocessor symbols, etc.). Chapter\ @(ch-anatomy) describes the anatomy of Scheme objects from the C/C++ programmer's point of view. Chapter\ @(ch-defprim) explains how applications and extensions can define new Scheme primitives. Chapter\ @(ch-types) presents the standard, built-in Scheme types implemented by Elk (numbers, pairs, vectors, etc.) and functions for creating and accessing Scheme objects of these types from within C/C++ code. The facilities for defining new, first-class Scheme data types are described in chapter\ @(ch-deftype). Finally, chapter\ @(ch-advanced) deals with a number of more advanced topics, such as functions for interacting with the garbage collector, automatic finalization of inaccessible objects, definition of user-supplied reader functions, error handling, etc. .PP A note on the naming conventions followed by the C identifiers used throughout this document: the names of all functions, macros, types, and variables exported by Elk have their components separated by underscores and capitalized (as in \f2Register_Object()\fP, for example). In contrast, the names defined by examples shown in this manual only use lower case letters, so that they can be distinguished easily from predefined functions exported by Elk. .\" --------------------------------------------------------------------------- .K1 "The Architecture of Extensible Applications" @[.=application architecture]@[.=extensible application] .Rf ch-arch \*(SN .PP Extensible applications built with Elk are @[.=hybrid application] \f2hybrid\fP in that they consist of code written in a mixture of languages\*-code written in the application's @[.\f2implementation language\fP] (C or C++) and code written in the @[.\f2extension language\fP] (Scheme). An application of this kind is usually composed of two layers, a low-level C/C++ layer that provides the basic, performance-critical functionality of the application, and on top of that a higher-level layer which is written in Scheme and interpreted at runtime. .PP The Scheme-language portion of an Elk-based application may range from just a few dozen lines of Scheme code (if a simple form of customization is sufficient) to fifty percent of the application or more (if a high degree of extensibility is required). As Scheme code is interpreted at runtime by an interpreter embedded in the application, users can customize and modify the application's Scheme layer or add and test their own Scheme procedures; recompilation, access to the C/C++ source, or knowledge of the implementation language are not required. Therefore, an application can achieve highest extensibility by restricting its low-level part to just a small core of time-critical C/C++ code. .PP To enable extensions to ``work on'' an application's internal data structures and state, the application core exports a set of new, application-specific Scheme data types and primitives operating on them to the Scheme layer. These types and primitives can be thought of as a ``wrapper'' around some of the C/C++ types and functions used by the application's core. For example, the core of an Elk-based newsreader program would export first-class Scheme types representing \f2newsgroups\fP, \f2subscriptions\fP, and \f2news articles\fP; these types would encapsulate the corresponding low-level C ``structs'' or C++ classes. In addition, it would export a number of Scheme primitives to operate on these types\*-to create members of them (e.\|g.\& by reading a news article from disk), to present them to the user through the application's user-interface, etc. Each of these primitives would recur on one or more corresponding C or C++ functions implementing the functionality in an efficient way. .PP Another job of the low-level C/C++ layer of an application is to hide platform-specific or system-specific details by providing suitable abstractions, so that the Scheme part can be kept portable and simple. For example, in case of the newsreader program, extension writers should not have to care about whether the news articles are stored in a local file system or retrieved from a network server, or about the idiosyncrasies of the system's networking facilities. Most of these system-specific details can be better dealt with in a language oriented towards systems programming, such as C, than in Scheme. .PP To decide whether to make a function part of the low-level part of an application or to write it in the extension language, you may ask yourself the following questions: .IP \(bu \f2Is the function performance-critical?\&\fP .RS .LP If the answer to this question is \f2yes\fP, put the function into the C/C++ core. For example, in case of the newsreader application, a primitive to search all articles in a given newsgroup for a pattern is certainly performance-critical and would therefore be written in the implementation language, while a function to ask the user to select an item from a list of newsgroups is not time-critical and could be written Scheme. .RE .IP \(bu \f2Does the function have to deal with platform-specific details?\&\fP .RS .LP For example, a function that needs to allocate and open a UNIX pseudo-tty or to establish a network connection needs to care about numerous system-specific details and different kinds of operating system facilities and will therefore be written in C/C++ rather than in Scheme. .RE .IP \(bu \f2In which language can the function be expressed more ``naturally''?\&\fP .RS .LP A function that parses and tokenizes a string can be expressed more naturally (that is, in a significantly more concise and efficient way) in a language such as C than in Scheme. On the other hand, functions to construct trees of news articles, to traverse them, and to apply a function to each node are obvious candidates for writing them in a Lisp-like language (Scheme). .RE .IP \(bu \f2Are customizability and extensibility important?\&\fP .RS .LP If it is likely that the application's users will want to customize or augment a function or even replace it with their own versions, write it in the extension language. If, for some reason, this is impossible or not practicable, at least provide suitable @[.``hooks''] that enable users to influence the function's operation from within Scheme code. .RE .\" --------------------------------------------------------------------------- .K2 "Scheme Extensions" @[.=Scheme extensions] .PP In addition to the Scheme interpreter component, Elk consists of a number of \f2Scheme extensions\fP. These extensions are not specific to any kind application and are therefore reusable. They provide the ``glue'' between Scheme and a number of external libraries, in particular the X11 libraries and the UNIX C library (exceptions are the @[.record extension] and the @[.bitstring extension] which provide a functionality of their own). The purpose of these extensions is to make the functionality of the external libraries (for example, the UNIX system calls) available to Scheme as Scheme data types and primitives operating on them. .PP While the Scheme extensions are useful for writing freestanding Scheme programs (e.\|g.\& for @[.rapid prototyping] of X11-based Scheme programs), their main job is to help building applications that need to interface to external libraries on the extension language level. The @[.X11 extension]s, for instance, are intended to be used by applications with a graphical user interface based on the X window system. By linking the X11 extensions (in addition to the Scheme interpreter) with an Elk-based application, the application's user interface can be written entirely in Scheme and will therefore be inherently customizable and extensible. As the Scheme extensions are reusable and can be shared between applications, extension language code can be written in a portable manner. .\" --------------------------------------------------------------------------- .K2 "Applications versus Extensions" .PP As far as the C/C++ programmer's interface to Elk (that is, the subject of this manual) is concerned, there is not really a technical difference between Scheme \f2extensions\fP on the one hand (such as the X11 extensions), and Elk-based, extensible \f2applications\fP on the other hand. Both are composed of an efficient, low-level C/C++ core and, above that, a higher-level layer written in Scheme. In both cases, the C/C++ layer exports a set of Scheme types and primitives to the Scheme layer (that is, to the Scheme \f2programmer\fP) and thus needs to interact with the Scheme interpreter. Because of this analogy, the rest of the manual will mostly drop the distinction between applications and extensions and concentrate on the interface between C/C++ and Elk. .PP The only noteworthy difference between applications and extensions is that the former tend to have their own @[.\f2main()\fP] function that gains control on startup, while Scheme extensions do not have a \f2main()\fP entry point\*-they are usually loaded into the interpreter (or application) during runtime. This distinction will become important in the next chapter, when the different ways of joining Elk and C/C++ code will be discussed. .\" --------------------------------------------------------------------------- .K1 "Linking Applications and Extensions with Elk" .Rf ch-linking \*(SN .PP There are two different mechanisms for integrating compiled C/C++ code (extensions or an application) with Elk: @[.\f2static linking\fP] and @[.\f2dynamic loading\fP]. The object files that make up an Elk-based application are usually linked statically with the Scheme interpreter in the normal way to produce an executable program. Compiled extensions, on the other hand, are usually dynamically loaded into the running Scheme interpreter as they are needed. These conventions reflect the normal case; Scheme extensions may as well be linked statically with the interpreter .IP \(bu to produce a ``specialized'' instance of the interpreter (for example, when developing X11-based Scheme code, an extended version of the interpreter may be produced by linking it statically with the X11 extensions); .IP \(bu if a particular extension is required by an application from the beginning (an application with an X-based user-interface would be linked with the X11 extensions statically, as loading on-demand would not be useful in this case); .IP \(bu on the (few) platforms where dynamic loading is not supported or where dynamic loading has a large performance overhead. .PP Likewise, dynamic loading is not only useful for on-demand loading of reusable Scheme extensions; \f2applications\fP can benefit from this facility as well. To reduce the size of the final executable, parts of an application may loaded dynamically rather than linked statically if they are used infrequently or if only a few of them are used at a time. Dynamic loading enables the author of an extensible application to decompose it into an arbitrary number of individual parts as an alternative to combining them statically into a large, monolithic executable. An extensible newsreader program, for example, may include a separate spelling check module that is dynamically loaded the first time it is needed (i.\|e.\& when a newly written news article is to be spell-checked). .PP The capability to dynamically load compiled C/C++ code into a running application enables users to write @[.\f2hybrid extension]s\fP which consist of a low-level C/C++ part and a high-level part written in Scheme. As a result, extensions can execute much faster (extensions to the Emacs editor, for example, must be entirely written in Emacs-Lisp and can therefore become slow if sufficiently complex); and extensions can deal more easily with low-level, platform-specific details. .\" --------------------------------------------------------------------------- .K1 "Dynamic Loading" .Rf ch-dynl \*(SN @[.=dynamic loading] .PP Object files (compiled C/C++ code) are loaded by means of the standard @[.\f2load\fP primitive] of Scheme, just like ordinary Scheme files. All you need to do is to compile your C or C++ source file, apply the @[.\f2makedl\fP script] that comes with the Elk distribution to the resulting object file, and load it into the interpreter or application. \f2makedl\fP prepares object files for dynamic loading (which is a no-op on most platforms) and combines several object files into one to speed up loading; arguments are the output file and one or more input files or additional libraries (input and output file may be identical): .Es \f6%\fP cc \-c \-I/usr/elk/include file.c \f6%\fP /usr/elk/lib/makedl file.o file.o \f6%\fP scheme \f6>\fP (load 'file.o) \f6>\fP .Ee (This examples assumes that Elk has been installed under ``/usr/elk'' on your site. Additional arguments may be required for the call to \f2cc\fP.) .PP Elk does not attempt to discriminate object code and Scheme code based on the files' contents; the names of object files are required to end in ``.o'', the standard suffix for object modules in UNIX. Scheme files, on the other hand, end in ``.scm'' by convention. This convention is not enforced by Elk\*-everything that is not an object file is considered to be a Scheme file. A list of object files may be passed to the \f2load\fP primitive which may save time on platforms where a call to the system linker is involved. .PP Loading object files directly as shown above is uncommon. Instead, the Scheme part of a @[.hybrid extension] usually loads its corresponding object file (and all the other files that are required) automatically, so that one can write, for example, .Es (require 'unix) .Ee to load the @[.UNIX extension]. This expression causes the file \f2unix.scm\fP to be loaded, which then loads the object file \f2unix.o\fP\*-the UNIX extension's low-level part\*-automatically on startup. Additional \f2load-libraries\fP (as explained in the next section) may be set by the Scheme file immediately before loading the extension's object file. .PP When an object file is loaded, @[.unresolved reference]s are resolved against the symbols exported by the running interpreter or by the combination of an application and the interpreter (the \f2base program\fP). This is an essential feature, as dynamically loaded extensions must be able to reference the elementary Scheme primitives defined by the interpreter core and all the other functions that are available to the extension/application programmer. In addition, references are resolved against the symbols exported by all previously loaded object files. The term @[.\f2incremental loading\fP] is used for this style of dynamic loading, as it allows building complex applications from small components incrementally. .\" --------------------------------------------------------------------------- .K2 "Load Libraries" .PP Dynamically loadable object files usually have unresolved references into one or more libraries, most likely at least into the standard @[.C library]. Therefore, when loading an object file, references are resolved not only against the base program and previously loaded object files, but also against a number of user-supplied @[.\f2load libraries\fP]. The @[.X11 extension]s of Elk, for instance, need to be linked against the respective libraries of the @[.X window system], such as \f2libX11\fP and \f2libXt\fP. These load libraries can be assigned to the Scheme variable \f2load-libraries\fP which is bound in the top-level environment of Elk. Typically, \f2load-libraries\fP is dynamically assigned a set of library names by means of @[.\f2fluid-let\fP] immediately before calling \f2load\fP. For example, the @[.Xlib extension] (\f2xlib.scm\fP) contains code such as .Es (fluid-let ((load-libraries (string-append "\-L/usr/X11/lib \-lX11 " load-libraries))) (load 'xlib.o)) .Ee to load the accompanying object file (\f2xlib.o\fP), linking it against the system's X library in addition to whatever libraries were already in use at that point. The default value of \f2load-libraries\fP is ``\-lc'' (i.\|e.\& the C library), as extensions are likely to use functions from this library in addition to those C library functions that have already been linked into the base program or have been pulled in by previously loaded object files. By using \f2string-append\fP in the example above, the specified libraries are added to the default value of \f2load-libraries\fP rather than overwriting it. The exact syntax of the load libraries is platform specific. For instance, ``\-L/usr/X11/lib'' as used above is recognized by the system linker of most UNIX variants as an option indicating in which directory the libraries reside on the system, but different options or additional libraries are required on certain platforms (as specified by the platform's ``config/site'' file in the Elk distribution). .\" --------------------------------------------------------------------------- .K2 "Extension Initializers and Finalizers" .PP When loading an object file, Elk scans the file's symbol table for the names of @[.extension initialization function]s or @[.\f2extension initializer\fP]s. These extension initializers are the initial entry points to the newly loaded extension; their names must have the prefix @[.``elk_init_''] (earlier the prefix ``init_'' was used; it was changed in Elk \*(Vs to avoid name conflicts). Each extension initializer found in the object file is invoked to pass control to the extension. The job of the extension initializers is to register the Scheme types and primitives defined by the extension with the interpreter and to perform any dynamic initializations. .PP As each extension may have an arbitrary number of initialization functions rather than one single function with a fixed name, extension writers can divide their extensions into a number of independent modules, each of which provides its own initialization function. The compiled modules can then be combined into one dynamically loadable object file without having to lump all initializations into a central initialization function. .PP In the same manner, extension can define an arbitrary number of @[.\f2extension finalization function]s\fP which are called on termination of the Scheme interpreter or application. The names of finalization functions begin with @[.``elk_finit_'']. Extension finalization functions are typically used for clean-up operations such as removing temporary files. .PP The extension initializers (as well as the finalizers) are called in an unspecified order. .\" --------------------------------------------------------------------------- .K2 "C++ Static Constructors and Destructors" .PP In addition to calling extension initialization functions, the \f2load\fP primitives invokes all @[.C++ static constructor]s that are present in the dynamically loaded object file in case it contains compiled C++ code. Likewise, @[.C++ static destructor]s are called automatically on termination. The constructors and destructors are called in an unspecified order, but all constructors (destructors) are called before calling any extension initializers (finalizers). Elk recognizes the function name prefixes of static constructor and destructor functions used by all major UNIX @[.C++ compiler]s; new prefixes can be added if required. .\" --------------------------------------------------------------------------- .K1 "Static Linking" @[.=static linking] .Rf ch-static \*(SN .PP Linking user-supplied code with Elk statically can be used as an alternative to dynamic loading on platforms that do not support it, for applications with their own @[.\f2main()\fP], and to avoid the overhead of loading frequently used Elk extensions. Dynamic loading and static linking may be used in combination\*- additional object files can be loaded in a running executable formed by linking the Scheme interpreter with extensions or with an application (or parts thereof). .PP When making the Scheme interpreter component of Elk, these executables and object files get installed (relative to your \f2install_dir\fP which usually is ``/usr/elk'' or ``/usr/local/elk''): .Rs .IP \f2bin/scheme\fP The freestanding, plain Scheme interpreter. .IP \f2lib/standalone.o\fP @[.=standalone.o] The Scheme interpreter as a relocatable object file which can be linked with user-supplied object files to form an executable. This object file contains a \f2main()\fP function; thus the Scheme interpreter starts up in the normal way when the executable is invoked. .IP \f2lib/module.o\fP @[.=module.o] Like \f2standalone.o\fP, except that the object file does not export its own \f2main()\fP function. Therefore, the object files linked with it have to supply a \f2main()\fP. .Re .PP The object file \f2standalone.o\fP is typically linked with a number of Elk extensions (e.\|g.\& the X11 extensions), while \f2module.o\fP is used by Elk-based applications which contribute their own \f2main()\fP and need to be ``in control'' on startup. .\" --------------------------------------------------------------------------- .K2 "Linking the Scheme Interpreter with Extensions" .PP A shell script @[.\f2linkscheme\fP] (installed as ``lib/linkscheme'') simplifies combining the Scheme interpreter with a number of\*-user-supplied or predefined\*-extensions statically. This script is called with the name of the output file (the resulting executable) and any number of object files and libraries. It basically links the object files and libraries with ``standalone.o'' and supplies any additional libraries that may be required by the interpreter. In general, this can be done just as well by calling the linker or compiler directly, but \f2linkscheme\fP also takes care of additional processing that needs to be performed on at least one platform (currently AIX). .PP To create an instance of Elk including the Xlib, Xt, and Xaw extensions, \f2linkscheme\fP would be used as follows (again assuming you have installed the software under ``/usr/elk''): .Es \f6%\fP cd /usr/elk \f6%\fP lib/linkscheme x11scheme runtime/obj/xt.o runtime/obj/xaw/*.o \e \-lXaw \-lXmu \-lXt \-lSM \-lICE \-lX11 \-lXext .Ee .PP The exact form of the libraries depends on your platform and X11 version; for example, additional options may be required if X11 is not installed in a standard location at your site. \f2xlib.o\fP is the @[.Xlib extension], \f2xt.o\fP is the X toolkit intrinsics (Xt) extension, and the subdirectory \f2xaw\fP holds the object files for all the @[.Athena widgets]. The executable \f2x11scheme\fP can now be used to run arbitrary X11 applications using the Athena widgets without requiring any runtime loading of object files belonging to the @[.X11 extension]s: .Es \f6%\fP x11scheme \f6>\fP (load '../examples/xaw/dialog.scm) [Autoloading xwidgets.scm] [Autoloading xt.scm] [Autoloading siteinfo.scm] \&... .Ee .PP In the same way, \f2linkscheme\fP can be used to link the Scheme interpreter with any new, user-supplied extensions, with parts of an Elk-based application, or with any combination thereof. .\" --------------------------------------------------------------------------- .K3 "Automatic Extension Initialization" .Rf ch-autoinit \*(SN .PP When linking Elk with extensions, it is \f2not\fP necessary to add calls to the @[.extension initializer]s to the Scheme interpreter's \f2main()\fP function and recompile the interpreter; all extensions are initialized automatically on startup. To accomplish this kind of automatic initialization, Elk scans its own symbol table on startup, invoking any @[.``elk_init_''] functions and @[.C++ static constructor]s, in the same way the symbol table of object files is scanned when they are dynamically loaded. @[.Extension finalizer]s and @[.C++ static destructor]s are saved for calling on exit. Automatic extension initialization only works if .Rs .IP \(bu the executable file has a symbol table (i.\|e.\& you must not strip it) .IP \(bu the executable file can be opened for reading .IP \(bu the interpreter can locate its executable file by scanning the shell's directory search path. .Re .PP The performance overhead caused by the initial scanning of the symbol is small; the program's symbol table can be read or mapped into memory efficiently (it it has not been automatically mapped into the address space by the operating system in the first place). .\" --------------------------------------------------------------------------- .K2 "Linking the Scheme Interpreter with an Application" .PP Elk-based applications that have their own \f2main()\fP are linked with the Scheme interpreter installed as \f2module.o\fP which, unlike \f2standalone.o\fP, does not export a \f2main()\fP function. No special \f2linkscheme\fP script is required to link with \f2module.o\fP; application writers usually will add ``/usr/elk/lib/module.o'' (or whatever the correct path is) to the list of object files in their Makefile. To simplify linking with Elk, a trivial script @[.\f2ldflags\fP] (which lives in ``lib'' along with \f2linkscheme\fP) is supplied that just echoes any additional libraries required by the Scheme interpreter. Application developers may use \f2ldflags\fP in their Makefiles. .PP As \f2module.o\fP does not have a \f2main()\fP entry point, an application using it must initialize the interpreter from within its own \f2main()\fP. This is done by calling .@[.\f2Elk_Init()\fP]: .Es void Elk_Init(int argc, char **argv, int init_flag, char *filename); .Ee .PP \f2Elk_Init()\fP is only defined by \f2module.o\fP and is essentially a ``wrapper'' around the Scheme interpreter's \f2main()\fP. \f2argc\fP and \f2argv\fP are the arguments to be passed to the Scheme interpreter's \f2main()\fP. These may or may not be the calling program's original arguments; however, @[.\f2argv[0\]\fP] must be that from the calling program in any case (because its address is used by Elk to determine the program's stack base). If \f2init_flag\fP is nonzero, the interpreter scans its symbol table to invoke @[.extension initializer]s as described in @(ch-autoinit). @[.C++ static constructor]s, however, are never invoked by \f2module.o\fP (regarless of \f2init_flag\fP), because they are already taken care of by the runtime startup in this case. If \f2filename\fP is nonzero, it is the name of Scheme file to be loaded by \f2Elk_Init()\fP. .\" --------------------------------------------------------------------------- .K3 "An Example ``main()'' Function" .PP Figure @(main) shows a realistic (yet somewhat simplified) example \f2main()\fP function of an application using Elk. .Fs char *directory; .El int main(int ac, char **av) { char **eav; int eac = 1, c; .El Set_App_Name(av[0]); eav = safe_malloc((ac+2+1) * sizeof(char *)); /* ac + -p xxx + 0 */ eav[0] = av[0]; while ((c = getopt(ac, av, "gh:o")) != EOF) switch (c) { case 'o': \f2process option...\fP case 'g': eav[eac++] = "-g"; break; case 'h': eav[eac++] = "-h"; eav[eac++] = optarg; break; case '?': usage(); return 1; } if ((directory = getenv("APP_DIR")) == 0) directory = DEFAULT_DIR; eav[eac++] = "-p"; eav[eac] = safe_malloc(strlen(directory) + 11); sprintf(eav[eac++], ".:%s/elk/scm", directory); eav[eac] = 0; Elk_Init(eac, eav, 0, 0); .El \f2initialize application's modules...\fP .El boot_code(); .El \f2application's main loop (if written in C)\fP ... .Fc "Example \f2main()\fP of an Elk-based application (simplified)" .Fe main .PP The code shown in the example must construct a new argument vector to be passed to \f2Elk_Init()\fP, because the application has command line options of its own (just \f2\-o\fP in the example). Two Elk-options (\f2\-g\fP and \f2\-h\fP) are handed to \f2Elk_Init()\fP if present, so that a mixture of Elk-specific and application-specific options can be given (see the manual page for the Scheme interpreter for the meaning of Elk's options). (\f2safe_malloc()\fP is assumed to be a wrapper around \f2malloc()\fP with proper error-checking.) @[.\f2Set_App_Name()\fP] is provided by Elk and is called with a name to be displayed in front of fatal error messages by the interpreter. .PP When all the options have been parsed, an additional option \f2\-p\fP is synthesized to provide a minimal initial @[.\f2load-path\fP] for Elk. This load-path consists of the current directory and a subdirectory of the directory under which the application expects its files that are needed during runtime. An environment variable can be used to set this directory. Defining a load-path like this has the benefit that a minimal, self-contained Elk runtime environment (e.\|g.\& a toplevel and the debugger) can be shipped with binary distributions of the application so that users are not required to have Elk installed at their sites. .PP When Elk has been initialized by calling \f2Elk_Init()\fP, the application may initialize all its other modules and finally load an initial Scheme file that ``boots'' the Scheme part of the application (which may involve loading further Scheme files). This initial Scheme file may be quite simple and just define a few functions used later, or it main contain the application's entire ``driving logic'' or interactive user-interface. This is accomplished by a function \f2boot_code()\fP which may as simple as this: .Es void boot_code(void) { char *fn = safe_malloc(strlen(directory) + 30); .El sprintf(fn, "%s/scm/app.scm", directory); Set_Error_Tag("initial load"); Load_File(fn); free(fn); } .Ee .PP @[.\f2Load_File()\fP] is defined by Elk and loads a Scheme file whose name is supplied as a C string. @[.\f2Set_Error_Tag()\fP] may be used by extensions and applications to define the symbol that is passed as the first argument to the standard @[.error handler] when a Scheme error is signaled (see section @(ch-error)). .\" --------------------------------------------------------------------------- .K2 "Who is in Control?" .Rf ch-control \*(SN .PP When an application's object files are loaded into the interpreter dynamically or are linked with the interpreter using @[.\f2linkscheme\fP], control initially rests in the interpreter. In contrast, when the application is linked using @[.\f2module.o\fP] and @[.\f2Elk_Init()\fP] as shown in the previous section, it defines its own \f2main()\fP function, and hence the application is ``in control'' on startup. .PP From a technical point of view, it does not really make a difference whether control rests in the interpreter or in the application initially. In the first case, the main ``driving logic'' (or ``main loop'') of the application can simply be wrapped in a Scheme primitive which is then called by the Scheme toplevel on startup to pass control back to the application, if this is desired. In any case, control usually changes frequently between the Scheme interpreter and the actual application anyway\*-the Scheme interpreter invokes callback functions or Scheme primitives provided by the application, which may in turn invoke Scheme procedures or load Scheme files, and so on. .PP The @[.Tcl]-like style of use, where control rests in the C-part of the application most of the time, and where this C code ``calls out'' to the interpreter occasionally by passing it an extension language expression or a small script, is not typical for Elk. It is supported, though; Elk provides a simple extension to pass a Scheme expression to the interpreter as a C string and receive the result in the same form, similar to what \f2Tcl_Eval()\fP does in Tcl (see section @(ch-funcall)). In a typical Elk-based application the extension language serves as the ``backbone'' of the application: the application's driving logic or main loop is written entirely in Scheme, and this Scheme code calls out to the application's C layer, using the data types, primitives, and other callbacks exported to the extension language by the application. With the help of the @[.X11 extension]s, the entire (graphical) user interface of an application can be written in Scheme easily; control can then passed to the application's C/C++ layer whenever an Xt callback is triggered. In this case, the application's ``main loop'' consists of a call to the Scheme primitive corresponding to the X toolkit function \f2XtAppMainLoop()\fP (the main event dispatch loop). .\" --------------------------------------------------------------------------- .K1 "Notes for Writing C/C++ Code Using Elk" .Rf ch-notes \*(SN .PP This chapter describes general conventions and usage notes for Elk-based C/C++ code and introduces a few useful facilities that are not directly related to Scheme. .\" --------------------------------------------------------------------------- .K2 "Elk Include Files" .PP Every C or C++ file using functions, macros, or variables defined by Elk must @[.=include files]include the file @[.\f2scheme.h\fP]: .Es #include \f1or:\fP #include "scheme.h" .Ee .PP This include file resides in a subdirectory \f2include\fP of the directory where Elk has been installed on your system. You must insert a suitable \-I option into your Makefiles to add this directory to the C compiler's search path. ``scheme.h'' includes several other Elk-specific include files from the same directory and, in addition, the standard C include files @[.\f2\fP] and @[.\f2\%\fP]. .\" --------------------------------------------------------------------------- .K2 "Standard C and Function Prototypes" .PP All the examples shown in this manual are written in @[.ANSI/ISO C]. This assumes that the Elk include files have been installed with @[.function prototypes] enabled. Whether or not function prototypes are enabled is controlled by a definition in the platform- and compiler-specific ``config/system'' file that has been selected for configuring Elk. However, if the include files have function prototypes disabled, prototypes are enable automatically if you are compiling your code with a @[.C compiler] that defines the symbol @[.``_\^_STDC_\^_]'' as non-zero, or with a @[.C++ compiler] that defines @[.``_\^_cplusplus'']\**. .FS Although the public include files provided by Elk can be used by C++ code, Elk itself cannot be compiled with a C++ compiler. The interpreter has been written in C to maximize portability. .FE .PP Elk include files that have been installed with function prototypes disabled can also be ``upgraded'' by defining the symbol @[.``WANT_PROTOTYPES''] before including ``scheme.h''. Similarly, include files installed without function prototypes can be used with a non-ANSI C compiler by defining the symbol @[.``NO_PROTOTYPES''] before including ``scheme.h''. .\" --------------------------------------------------------------------------- .K2 "External Symbols Defined by Elk" .PP As extensions or applications are linked with Elk (regarless of whether dynamic loading or static linking is used), they can in general reference all external symbols exported by Elk. Of these, only the symbols described in this manual may be used safely. Use of other (private) symbols results in non-portable code, as the symbols may change their meaning or may even be removed from future releases of Elk. The same restriction applies to the macros and types defined by the include files of Elk. .PP In addition to the symbols defined by the Scheme interpreter kernel, those exported by other @[.Scheme extensions] that are present in the same executable (or have been loaded earlier) can be referenced from within C/C++ code. These extensions are not subject of this manual; you should refer to the relevant documentation and the public include files that are part of the extensions. .PP If Elk is linked with an application that has its own \f2main()\fP function, none of the functions exported by Elk must be used before the initial call to @[.\f2Elk_Init()\fP] (except \f2Set_App_Name()\fP). .\" --------------------------------------------------------------------------- .K2 "Calling Scheme Primitives" .Rf ch-prims \*(SN .PP A large subset of the symbols exported by the Scheme interpreter is the set of functions implementing the @[.Scheme primitives]. These may be used safely by extensions and applications. There exists one C function for each Scheme primitive. Its name is that of the corresponding primitive with the following conversions applied: .Rs .IP \(bu dashes are replaced by underscores, and the initial letters of the resulting word components are capitalized; .IP \(bu the prefix ``P_'' is prepended; .IP \(bu ``\(mi>'' is replaced by ``_To_'' (as in \f2vector\(mi>list\fP); .IP \(bu a trailing exclamation mark is deleted, except for \f2append!\fP and \f2reverse!\fP, where ``_Set'' is appended; .IP \(bu a trailing question mark is replaced by the letter `p' (except for \f2eq?, eqv?, equal?\&\fP and the string and character comparison primitives, where it is deleted); .Re .LP The names of a few functions are derived differently as shown by this table: .RS .TS box, tab(~); c c c l. Scheme Primitive~C Function _ <~P_Generic_Less() >~P_Generic_Greater() \&=~P_Generic_Equal() <=~P_Generic_Eq_Less() >=~P_Generic_Eq_Greater() 1+~P_Inc() 1\(mi and \(mi1+~P_Dec() +~P_Generic_Plus() \(mi~P_Generic_Minus() *~P_Generic_Multiply() /~P_Generic_Divide() let*~P_Letseq() .TE .RE .PP According to these rules, the primitive \f2exact\(mi>inexact\fP can be used from within C as \f2P_Exact_To_Inexact()\fP, the predicate \f2integer?\&\fP is available as \f2P_Integerp()\fP, etc. Authors of reusable Scheme extensions are encouraged to follow these (or similar) naming conventions in their code. .PP All the functions implementing Scheme primitives (as well as special forms, which are treated as primitives in Elk) receive Scheme objects or arrays thereof as their arguments and return Scheme objects as their values. The underlying C type will be described in the next chapter. For the semantics of the non-standard Scheme primitives defined by Elk refer to the Reference Manual for the interpreter. .\" --------------------------------------------------------------------------- .K2 "Portable alloca()" .Rf ch-alloca \*(SN .PP Elk provides a portable variant of @[.\f2alloca()\fP] as a set of macros that can be used by extensions and applications. \f2alloca()\fP, which is supported by most modern UNIX systems and C compilers, allocates memory in the caller's stack frame; the memory is automatically released when the function returns. Elk simulates this functionality on the (rare) platforms where \f2alloca()\fP is not available. .PP To allocate memory, the macro @[.\f2Alloca()\fP] is called with a variable to which the newly allocated memory is assigned, the type of that variable, and the number of bytes that are requested. The macro @[.\f2Alloca_End\fP] must be called (without an argument list) before returning from a function or block that uses @[.\f2Alloca()\fP]; this macro is empty on those platforms that support the ordinary \f2alloca()\fP. Finally, a call to the macro @[.\f2Alloca_Begin\fP] must be placed in the function's declarations. \f2Alloca()\fP usually is more efficient than \f2malloc()\fP and \f2free()\fP, and the memory need not be freed when the function is left prematurely because of an interrupt or by calling a @[.continuation]. .LP As an example, here is the skeleton of a function that is called with a filename prefix and a suffix, concatenates them (separated by a period), and opens the resulting file: .Es int some_function(char *prefix, char *suffix) { char *name; int len, fd; Alloca_Begin; .El len = strlen(prefix) + 1 + strlen(suffix) + 1; Alloca(name, char*, len); sprintf(name, "%s.%s", prefix, suffix); fd = open(name, ...); ... Alloca_End; } .Ee .\" --------------------------------------------------------------------------- .K2 "Other Useful Macros and Functions" .PP The preprocessor symbols @[.ELK_MAJOR] and @[.ELK_MINOR] expand to the major and minor version number of the current release of Elk. They did not exist in versions older than Elk \*(Vs. .PP @[.\f2index()\fP], @[.\f2bcopy()\fP], @[.\f2bcmp()\fP], and @[.\f2bzero()\fP] are defined as suitable macros on systems that do not have them in their C library; they may be used by source files that include ``scheme.h'', regardless of the actual platform. .LP Code linked with Elk may use the two functions .Es @[.=Safe_Malloc()]@[.=Safe_Realloc()] char *Safe_Malloc(unsigned size); char *Safe_Realloc(char *old_pointer, unsigned size); .Ee as alternatives to \f2malloc()\fP and \f2realloc()\fP. If the request for memory cannot be satisfied, the standard Elk error handler is called with a suitable error message. .\" --------------------------------------------------------------------------- .K1 "The Anatomy of Scheme Objects" .Rf ch-anatomy \*(SN .PP All Scheme objects, regarless of their Scheme type, are represented as instances of the type @[.\f2Object\fP] in C. \f2Object\fP is implemented as a small C \f2struct\fP in newer Elk releases and was an integral type earlier. However, code using Elk should not assume a specific representation, as it may change again in future revisions. An \f2Object\fP consists of three components: .Rs .IP \(bu the type of the corresponding Scheme object as a small integer (the @[.``type field''] or @[.``tag field'']), .IP \(bu the contents of the object, either directly (for small objects) or as a pointer into the Scheme @[.heap] (the @[.``pointer field'']), .IP \(bu a @[.``const bit''] which, if set, indicates that the object is read-only and cannot be modified by destructive Scheme primitives. .Re .PP Elk defines a few macros to retrieve and modify the fields of an \f2Object\fP independent of its representation: .Es @[.=TYPE()]@[.=POINTER()]@[.=ISCONST()]@[.=SETCONST()]@[.=SET()] TYPE(obj) ISCONST(obj) SET(obj,t,ptr) POINTER(obj) SETCONST(obj) .Ee .PP \f2TYPE()\fP returns the contents of the type field of an \f2Object\fP; \f2POINTER()\fP returns the contents of the pointer field as an \f2unsigned long\fP (different macros are provided for types which have their values stored directly in the \f2Object\fP rather than in the heap); \f2ISCONST()\fP returns the value of the const bit; and \f2SETCONST()\fP sets the const bit to 1 (it cannot be cleared once it has been set). \f2ISCONST()\fP and \f2SETCONST()\fP may only be applied to \f2Objects\fP that have their value stored on the heap (such as vectors, strings, etc.); all other types of Scheme objects are \f2ipso facto\fP read-only. Another macro, \f2SET()\fP, can be used to set both the type and pointer field of a new object. .PP Two objects can be compared by means of the macro @[.=EQ()] \f2EQ()\fP, which is also used as the basis for the Scheme predicate @[.\f2eq?\fP]: .Es EQ(obj1,obj2) .Ee \f2EQ()\fP expands to a non-zero value if the type fields and the pointer fields of the two objects are identical, else zero (regardless of whether the pointer field really holds a pointer or the object's actual value). As \f2EQ()\fP may evaluate its arguments twice, it should not be invoked with function calls or complex expressions. .\" --------------------------------------------------------------------------- .K2 "Type-specific Macros" .PP For each predefined Scheme type, there exists a preprocessor symbol that expands to the integer value of that type (the contents of the type field of members of the type). The name of each such symbol is the name of the type with the prefix ``T_'': .Es T_Boolean T_Pair T_Vector \f1etc...\fP .Ee These symbols are typically used as case labels in switch-statements to discriminate the possible types of a given object, or in if-statements to check whether a Scheme object is of a given type: .Es if (TYPE(obj) == T_Vector) ... .Ee In addition, each type defines a macro to extract the contents of an object of that type and to convert it to the correct C type. For example, the macro .Es @[.=CHAR()] CHAR(obj) .Ee is used to fetch the character value (a C \f2int\fP) from members of the Scheme type \f2character\fP, that is, from objects whose type field contains the value \f2T_Character\fP. Similarly, the macro .Es @[.=VECTOR()] VECTOR(obj) .Ee gets the heap pointer conveyed in objects of the Scheme type @[.\f2vector\fP]. For objects such as vectors, pairs, and procedures, the heap address is coerced to a pointer to a C \f2struct\fP defining the layout of the object. There exists one structure type declaration for each such Scheme type; their names are that of the type with ``S_'' prepended. For example, \f2VECTOR()\fP returns a pointer to a structure with the components \f2size\fP (the number of elements in the vector) and \f2data\fP (the elements as an array of \f2Objects\fP). These can be used from within C code like this: .Es int i, num = VECTOR(obj)->size; .El for (i = 0; i < num; i++) VECTOR(obj)->data[i] = ...; .Ee Similarly, the structure underlying the Scheme type @[.\f2pair\fP] is defined as: .Es struct S_Pair { Object car, cdr; }; .Ee and the macro \f2PAIR()\fP returns a (heap) pointer to a member of the structure \f2S_Pair\fP. Macros such as \f2VECTOR()\fP and \f2PAIR()\fP just convert the contents of the pointer field to a pointer of the correct type: .Es #define VECTOR(obj) ((struct S_Vector *)POINTER(obj)) #define PAIR(obj) ((struct S_Pair *)POINTER(obj)) .Ee .PP Authors of Scheme extensions and Elk-based applications are encouraged to follow these conventions in their code and, for each new type \f2xyz\fP, store the new type value (which is allocated by the interpreter when the type is registered) in a variable \f2T_Xyz\fP, and define a structure or class \f2S_Xyz\fP, and a macro \f2XYZ()\fP that makes a pointer to this structure from a member of the type. Capitalization may vary according to personal preference. .\" --------------------------------------------------------------------------- .K1 "Defining New Scheme Primitives" @[.=Scheme primitives] .Rf ch-defprim \*(SN .PP In Elk, there exists a one-to-one relationship between Scheme primitives and C functions: each Scheme primitive\*-whether predefined or user-defined\*-is implemented by a corresponding C function. This includes @[.special forms], which are treated as a special kind of primitives in Elk. Extensions and applications use the function @[.\f2Define_Primitive()\fP] to register a new Scheme primitive with the interpreter, supplying its name and the C function that implements it. In case of dynamically loadable extensions or application modules, the calls to \f2Define_Primitive()\fP are placed in the @[.extension initialization function]s that are called automatically as the object file is loaded. \f2Define_Primitive()\fP is declared as .Es void Define_Primitive((Object (*func)()), const char *name, int minargs, int maxargs, enum discipline disc); .Ee The arguments are: .Rs .IP \f2func\fP a pointer to the C function implementing the new primitive; .IP \f2name\fP the name of the primitive as a null-terminated C string; .IP \f2minargs\fP the minimum number of arguments accepted by the primitive; .IP \f2maxargs\fP the maximum number of arguments (identical to \f2minargs\fP in most cases); .IP \f2disc\fP the @[.\f2calling discipline\fP] (usually \f2EVAL\fP). .Re .PP \f2Define_Primitive()\fP creates a Scheme variable of the specified name in the current (i.\|e.\& the caller's) lexical environment and binds it to the newly created procedure. Each C function that implements a primitive has a return type of \f2Object\fP and, for a calling discipline of \f2EVAL\fP, zero or more arguments of type \f2Object\fP which are bound to the evaluated arguments passed to the Scheme primitive when it is called. The calling discipline must be one of the following: .Rs .IP \f2EVAL\fP\0\0 @[.=EVAL] The primitive expects a fixed number of arguments; \f2minargs\fP and \f2maxargs\fP must be identical\**. .FS Because of a limitation in the C language, primitives of type \f2EVAL\fP can only have a fixed maximum number of arguments (currently 10). If more arguments are required, \f2VARARGS\fP must be used instead. .FE .IP \f2VARARGS\fP @[.=VARARGS] The primitive has a variable number of arguments, and the underlying C function is called with an argument count and an array of arguments. Defining primitives with a variable number of arguments will explained in more detail in section @(ch-varargs). .IP \f2NOEVAL\fP @[.=NOEVAL] The arguments are passed as a Scheme list of unevaluated objects\*-a single argument of the type \f2Object\fP. Primitives using this discipline will then use \f2Eval()\fP as described in section @(ch-funcall) to evaluate some or all of the arguments. \f2NOEVAL\fP is only rarely used (with the exception of the built-in @[.special forms] of Elk); extensions and applications mostly use macros as a more convenient way to defined new syntactical forms. .Re .LP Figure @(defprim) shows a simple example for defining a new Scheme primitive. .Fs #include "scheme.h" .El Object p_vector_reverse(Object vec) { Object tmp, *s, *t; .El Check_Type(vec, T_Vector); for (s = VECTOR(vec)->data, t = s+VECTOR(vec)->size; --t > s; s++) tmp = *s, *s = *t, *t = tmp; return vec; } .El void elk_init_vector(void) { Define_Primitive(p_vector_reverse, "vector-reverse!", 1, 1, EVAL); } .Fc "Defining a new Scheme Primitive" .Fe defprim .PP The primitive @[.\f2vector-reverse!\fP] defined by the example extension reverses the elements of a Scheme @[.vector] in place and returns its argument (note the final exclamation mark indicating the destructive operation). @[.\f2Check_Type()\fP] is a simple macro that compares the type field of the first argument (an \f2Object\fP) with the second argument and signals and error if they do not match. This macro is used primarily for type-checking the arguments to Scheme primitives. A call to the macro @[.\f2Check_Mutable()\fP] with the vector as an argument could have been inserted before the loop to check whether the vector is read-only and to automatically raise an error if this is the case. The example code forms a complete extension including an @[.extension initialization function] and could be linked with the interpreter, or loaded dynamically into the interpreter as follows: .Es \f6%\fP cc \-c \-I/usr/elk/include vec.c; makedl vec.o vec.o \f6%\fP scheme \f6>\fP (load 'vec.o) \f6>\fP (define v '#(hello word)) \f6v >\fP (vector-reverse! v) \f6#(world hello) >\fP v \f6#(world hello) >\fP .Ee .\" --------------------------------------------------------------------------- .K2 "Making Objects Known to the Garbage Collector" .Rf ch-gc \*(SN @[.=garbage collector] .PP Consider the non-destructive version of the primitive @[.\f2vector-reverse\fP] shown in Figure @(vecrev1), which returns a new vector instead of altering the contents of the original vector. .Fs Object p_vector_reverse(Object vec) { Object ret; int i, j; .El Check_Type(vec, T_Vector); ret = Make_Vector(VECTOR(vec)->size, False); for (i = 0, j = VECTOR(vec)->size; --j >= 0; i++) VECTOR(ret)->data[i] = VECTOR(vec)->data[j]; return ret; } .Fc "Non-destructive Scheme primitive \f2vector-reverse\fP" .Fe vecrev1 .PP The code in Figure @(vecrev1) is identical to that shown in Figure @(defprim), except that a new vector is allocated, filled with the contents of the original vector in reverse order, and returned as the result of the primitive. @[.\f2Make_Vector()\fP] is declared by Elk: .Es Object Make_Vector(int size, Object fill); .Ee \f2size\fP is the length of the vector, and all elements are initialized to the Scheme object \f2fill\fP. In the example, the predefined global variable @[.\f2False\fP] is used as the \f2fill\fP object; it holds the boolean Scheme constant #f (any \f2Object\fP could have been used here). .PP Although the C function may look right, there is a problem when it comes to garbage collection. To understand the problem and its solution, it may be helpful to have a brief look at how the garbage collector\** .FS Elk actually employs two garbage collectors, one based on the traditional stop-and-copy strategy, and a generational, incremental garbage collector which is less disruptive but not supported on all platforms. .FE works (the following description presents a simplified view; the real algorithm is more complex). In Elk, a @[.garbage collection] is triggered automatically whenever a request for heap space cannot be satisfied because the @[.heap] is full, or explicitly by calling the primitive @[.\f2collect\fP] from within Scheme code. The garbage collector traces all ``live'' objects starting with a known @[.\f2root set\fP] of pointers to reachable objects (basically the interpreter's global lexical environment and its symbol table). Following these pointers, all accessible Scheme objects are located and copied to a new heap space in memory (``forwarded''), thereby compacting the heap. Whenever an object is relocated in memory during garbage collection, the contents of the @[.pointer field] of the corresponding C \f2Object\fP is updated to point to the new location. After that, any constituent objects (e.\|g.\& the elements of a vector) are forwarded in the same way. .PP As live objects are relocated in memory, \f2all\fP pointers to an object need to be updated properly when that object is forwarded during garbage collection. If a pointer to a live object were not in the root set (that is, not reachable by the garbage collector), the object would either become garbage erroneously during the next garbage collection, or, if it had been reached through some other pointer, the original pointer would now point to an invalid location.\** .FS The problem of managing an ``exact root set'' can be avoided by a technique called \f2conservative\fP garbage collection. A conservative garbage collector treats the data segment, stack, and registers of the running program as \f2ambiguous roots\fP. If the set of ambiguous roots is a superset of the \f2actual\fP roots, then a pointer that looks like a heap pointer can safely be considered as pointing to an accessible object that cannot be reclaimed. At the time Elk was designed, conservative GC was still in its infancy and sufficient experience did not exist. For this reason, and because of the implied risks on certain machine architectures, the inherent portability problems, and the inability to precisely determine the actual memory utilization, a traditional GC strategy was chosen for Elk. .FE This is exactly what happens in the example shown in Figure @(vecrev1). .PP The call to \f2Make_Vector()\fP in the example triggers a garbage collection if the heap is too full to satisfy the request for heap space. As the \f2Object\fP pointer stored in the argument \f2vec\fP is invisible to the garbage collector, its pointer field cannot be updated when the vector to which it points is forwarded during the garbage collection started inside \f2Make_Vector()\fP. As a result, all further references to \f2VECTOR(vec)\fP will return an invalid address and may cause the program to crash (immediately or, worse, at a later point). The solution is simple: the primitive just needs to add \f2vec\fP to the set of initial pointers used by the garbage collector. This is done by inserting the line .Es GC_Link(vec); .Ee at the beginning of the function before the call to \f2Make_Vector()\fP. @[.\f2GC_Link()\fP] is a macro. Another macro, @[.\f2GC_Unlink\fP], must be called later (e.\|g.\& at the end of the function) without an argument list to remove the object from the root set again. In addition, a call to @[.\f2GC_Node\fP] (again without an argument list) must be placed in the declarations at the beginning of the enclosing function or block. Figure @(vecrev2) shows the revised, correct code. .Fs Object p_vector_reverse(Object vec) { Object ret; int i, j; GC_Node; .El GC_Link(vec); Check_Type(vec, T_Vector); ret = Make_Vector(VECTOR(vec)->size, False); for (i = 0, j = VECTOR(vec)->size; --j >= 0; i++) VECTOR(ret)->data[i] = VECTOR(vec)->data[j]; GC_Unlink; return ret; } .Fc "Non-destructive Scheme primitive \f2vector-reverse\fP, corrected version" .Fe vecrev2 .PP Appendix A lists the C functions which can trigger a garbage collection. Any @[.local variable] or argument of type \f2Object\fP must be protected in the manner shown above if one of these functions is called during its lifetime. This may sound more burdensome than it really is, because most of the ``dangerous'' functions are rarely or never used from within C/C++ extensions or applications in practice. Most primitives that require calls to \f2GC_Link()\fP use some function that creates a new Scheme object, such as \f2Make_Vector()\fP in the example above. .PP To simplify GC protection of more than a single argument or variable, additional macros @[.\f2GC_Link2()\fP], @[.\f2GC_Link3()\fP], and so on up to \f2GC_Link7()\fP are provided. Each of these can be called with as many arguments of type \f2Object\fP as is indicated by the digit (separate macros are required, because macros with a variable number of arguments cannot be defined in C). A corresponding macro @[.\f2GC_Node2\fP], @[.\f2GC_Node3\fP], and so on, must be placed in the declarations. Different \f2GC_Link*()\fP calls cannot be mixed. All @[.local variable]s passed to one of the macros must have been initialized. GC protection is not required for ``pointer-less'' objects such as booleans and small integers, and for the arguments of primitives with a variable number of arguments (as described in section @(ch-varargs)). Section @(ch-gcglobal) will describe how global (external) \f2Object\fP variables can be added to the root set. .PP Here is how the implementation of the primitive @[.\f2cons\fP] uses \f2GC_Link2()\fP to protect its arguments (the @[.car] and the @[.cdr] of the new pair): .Es Object P_Cons(Object car, Object cdr) { Object new_pair; GC_Node2; .El GC_Link2(car, cdr); new_pair = \f2allocate heap space and initialize object\fP; GC_Unlink; return new_pair; } .Ee .PP There are a few pitfalls to be aware of when using ``dangerous'' functions from within your C/C++ code. For example, consider this code fragment which fills a Scheme vector with the program's environment strings that are available through the null-terminated string array \f2environ[]\fP: .Es Object vec = \f2new vector of the right size\fP; int i; GC_Node; .El GC_Link(vec); for (i = 0; environ[i] != 0; i++) VECTOR(vec)->data[i] = Make_String(environ[i], strlen(environ[i])); .Ee (\f2Make_String()\fP creates and initializes a new Scheme string.) The body of the for-loop contains a subtle bug: depending on the compiler used, the left hand side of the assignment (the expression involving \f2vec\fP) may be evaluated before @[.\f2Make_String()\fP] is invoked. As a result, a copy of the contents of \f2vec\fP might be, for instance, stored in a register before a garbage collection is triggered while evaluating the right hand side of the assignment. The garbage collector would then move the vector object in memory, updating the\*-properly GC-protected\*-variable \f2vec\fP, but not the temporary copy in the register, which is now a dangling reference. To avoid this, the loop must be modified along these lines: .Es for (i = 0; environ[i]; i++) { Object temp = Make_String(environ[i], strlen(environ[i])); VECTOR(vec)->data[i] = temp; } .Ee A related pitfall to watch out for is exemplified by this code fragment: .Es Object obj; \&... GC_Link(obj); \&... some_function(obj, P_Cons(car, cdr)); .Ee Here, the call to @[.\f2P_Cons()\fP]\*-just like \f2Make_String()\fP above\*-can trigger a garbage collection. Depending on the C compiler, the properly GC-protected object pointer \f2obj\fP may be pushed on the argument stack before \f2P_Cons()\fP is invoked, as the order in which function arguments\*-just like the operands of the assignment operator\*-are evaluated is undefined in the C language. In this case, if a garbage collection takes place and the heap object to which \f2obj\fP points is moved, \f2obj\fP will be updated properly, but the copy on the stack will not. Again, the problem can be avoided easily by assigning the result of the nested function call to a temporary \f2Object\fP variable and use this variable in the enclosing function call: .Es temp = P_Cons(car, cdr); some_function(obj, temp); .Ee .\" --------------------------------------------------------------------------- .K2 "Primitives with Variable-Length Argument Lists" .Rf ch-varargs \*(SN .PP Primitives with a variable number of arguments are registered with the interpreter by calling @[.\f2Define_Primitive()\fP] with the @[.calling discipline] @[.\f2VARARGS\fP] and with different values for \f2minargs\fP and \f2maxargs\fP. The special symbol @[.\f2MANY\fP] can be given as the maximum number of arguments to indicate that there is no upper limit on the primitive's number of actual arguments. The C/C++ function implementing a primitive with a variable number of arguments is called with two arguments: an integer count that specifies the number of actual arguments, and the Scheme arguments as an array of \f2Objects\fP (that is, a pointer to \f2Object\fP). The objects passed as the argument vector of \f2VARARGS\fP primitives are already registered with the garbage collector; calls to \f2GC_Link()\fP are not required. As an example for a primitive with an arbitrary number of arguments, here is the definition of a simplified variant of @[.\f2append!\fP] (which does not handle empty lists): .Es Object p_append_set (int argc, Object *argv); { int i; .El for (i = 0; i < argc-1; i++) (void)P_Set_Cdr (P_Last_Pair (argv[i]), argv[i+1]); return *argv; } .Ee The corresponding call to \f2Define_Primitive()\fP would read: .Es Define_Primitive(p_append_set, "append!", 0, MANY, VARARGS); .Ee .PP Besides implementing primitives with an indefinite maximum number of arguments, the \f2VARARGS\fP discipline is frequently used for primitives with an optional argument. For example, a primitive encapsulating the UNIX \f2open()\fP system call, which has two fixed arguments (filename, flags) and an optional third argument (the mode for newly created files, i.\|e.\& calls with the flag \f2O_CREAT\fP), could be defined as follows: .Es Object p_unix_open(int argc, Object *argv) { char *name = get_file_name(argv[0]); int flags = get_flags(argv[1]); mode_t mode; .El if (flags & O_CREAT) { if (argc < 3) \f2error--too few arguments\fP mode = get_mode(argv[2]); ... .Ee The call to \f2Define_Primitive()\fP could then be written as: .Es Define_Primitive(p_unix_open, "unix-open", 2, 3, VARARGS); .Ee .\" --------------------------------------------------------------------------- .K1 "Predefined Scheme Types" .Rf ch-types \*(SN .PP This chapter introduces the Scheme types predefined by Elk. It begins with the ``pointer-less'' types such as boolean, whose values are stored directly in the pointer field of an \f2Object\fP; followed by the types whose members are C \f2structs\fP that reside on the Scheme heap. .\" --------------------------------------------------------------------------- .K2 "Booleans (T_Boolean)" @[.=T_Boolean] .PP \f2Objects\fP of type \f2T_Boolean\fP can hold the values #t and #f. Two \f2Objects\fP initialized to #t and #f, respectively, are available as the external C variables \f2True\fP and \f2False\fP. The macro .Es @[.=Truep()] Truep(obj) .Ee can be used to check whether an arbitrary Scheme object is regarded as true. Use of \f2Truep()\fP is not necessarily equivalent to .Es !EQ(obj,False) .Ee because the empty list may count as false in addition to #f if backwards compatibility to older Scheme language versions has been enabled. \f2Truep()\fP may evaluate its argument twice and should therefore not be invoked with a function call or a complex expression. .LP The two functions .Es @[.=Eqv()]@[.=Equal()] int Eqv(Object, Object); int Equal(Object, Object); .Ee are identical to the primitives \f2P_Eqv()\fP and \f2P_Equal()\fP, except that they return a C integer rather than a Scheme boolean and therefore can be used more conveniently in C/C++. .\" --------------------------------------------------------------------------- .K2 "Characters (T_Character)" @[.=T_Character] .PP The character value stored in an \f2Object\fP of type \f2T_Character\fP can be obtained by the macro .Es @[.=CHAR()] CHAR(char_obj) .Ee as a non-negative \f2int\fP. A new character object is created by calling the function .Es @[.=Make_Char()] Object Make_Char(int c); .Ee The predefined external C variable @[.\f2Newline\fP] holds the newline character as a Scheme \f2Object\fP. .\" --------------------------------------------------------------------------- .K2 "Empty List (T_Null)" @[.=T_Null] .PP The type \f2T_Null\fP has exactly one member\*-the empty list; hence all \f2Objects\fP of this type are identical. The empty list is available as the external C variable @[.\f2Null\fP]. This variable is often used to initialize \f2Objects\fP that will be assigned their real values later, for example, as the fill element for newly created vectors or to initialize \f2Objects\fP in order to \f2GC_Link()\fP them. A macro \f2Nullp()\fP is provided as a shorthand for checking if an \f2Object\fP is the empty list: .Es @[.=Nullp()] #define Nullp(obj) (TYPE(obj) == T_Null) .Ee This macro is used frequently in the termination condition of for-loops that scan a Scheme list: .Es Object tail; \&... for (tail = some_list; !Nullp(tail); tail = Cdr(tail)) process_element(Car(tail)); .Ee (\f2Car()\fP and \f2Cdr()\fP essentially are shorthands for \f2P_Car()\fP and \f2P_Cdr()\fP and will be revisited in the section on pairs). .\" --------------------------------------------------------------------------- .K2 "End of File (T_End_Of_File)" @[.=T_End_Of_File] .PP The type \f2T_End_Of_File\fP has one member\*-the @[.end-of-file object]\*-and is only rarely used from within user-supplied C/C++ code. The external C variable @[.\f2Eof\fP] is initialized to the end-of-file object. .\" --------------------------------------------------------------------------- .K2 "Integers (T_Fixnum and T_Bignum)" @[.=T_Fixnum]@[.=T_Bignum] .PP Integers come in two flavors: @[.\f2fixnums\fP] and @[.\f2bignums\fP]. The former have their value stored directly in the pointer field and are wide enough to hold most C \f2ints\fP. Bignums can hold integers of arbitrary size and are stored in the heap. Two macros are provided to test whether a given signed (or unsigned, respectively) integer fits into a fixnum: .Es @[.=FIXNUM_FITS()]@[.=UFIXNUM_FITS()] FIXNUM_FITS(integer) UFIXNUM_FITS(unsigned_integer) .Ee The former always returns 1 in Elk \*(Vs, but the range of integer values that can be represented as a fixnum may be restricted in future revisions. It is guaranteed, however, that at least two bits less than the machine's word size will be available for fixnums in future versions of Elk. .LP The value stored in a fixnum can be obtained as a C \f2int\fP by calling the macro .Es @[.=FIXNUM()] FIXNUM(fixnum_obj) .Ee A macro .Es @[.=Check_Integer()] Check_Integer(obj) .Ee can be used as a shorthand for checking whether an \f2Object\fP is a fixnum or a bignum and raising an error otherwise. .LP The following functions are provided to convert C integers to Scheme integers: .Es @[.=Make_Integer()]@[.=Make_Unsigned()] @[.=Make_Long()]@[.=Make_Unsigned_Long()] Object Make_Integer(int); Object Make_Unsigned(unsigned); Object Make_Long(long); Object Make_Unsigned_Long(unsigned long); .Ee \f2Make_Integer()\fP returns a fixnum object if \f2FIXNUM_FITS()\fP returns true for the argument, otherwise a bignum. Likewise, \f2Make_Long()\fP usually returns a fixnum but may have to resort to bignums on architectures where a C \f2long\fP is wider than an \f2int\fP. \f2Make_Unsigned()\fP returns a bignum if the specified integer is larger than the largest positive \f2int\fP that fits into a fixnum (\f2UFIXNUM_FITS()\fP returns zero in this case). Another set of functions convert a Scheme number to a C integer: .Es @[.=Get_Integer()]@[.=Get_Exact_Integer()] int Get_Integer(Object); int Get_Exact_Integer(Object); .El @[.=Get_Unsigned()]@[.=Get_Exact_Unsigned()] unsigned Get_Unsigned(Object); unsigned Get_Exact_Unsigned(Object); .El @[.=Get_Long()]@[.=Get_Exact_Long()] long Get_Long(Object); long Get_Exact_Long(Object); .El @[.=Get_Unsigned_Long()]@[.=Get_Exact_Unsigned_Long()] unsigned long Get_Unsigned_Long(Object); unsigned long Get_Exact_Unsigned_Long(Object); .Ee These functions signal an error if one of the following conditions is true: .Rs .IP \(bu the argument is neither a fixnum, nor a bignum, nor a flonum (real number) with a fractional part of zero (more about @[.flonums] in the next section); .IP \(bu the function is one of the ``unsigned'' variants and the argument is a negative number; .IP \(bu the argument is a bignum too large for the respective return type; .IP \(bu the function is one of the ``exact'' variants and the argument is neither a fixnum nor a bignum; .IP \(bu the argument is a flonum that cannot be coerced to the respective return type. .Re .LP As all of the above functions include suitable type-checks, primitives receiving integer arguments can be written in a simple and straightforward way. For example, a primitive encapsulating the UNIX \f2dup\fP system call (which returns an integer file descriptor pointing to the same file as the original one) can be written as: .Es Object p_unix_dup(Object fd) { return Make_Integer(dup(Get_Exact_Unsigned(fd))); .Ee Note that if \f2Get_Unsigned()\fP (or \f2Get_Integer()\fP) had been used here in place of the ``exact'' conversion function, it would be possible to write expressions such as: .Es (define fd (unix-dup (truncate 1.2))) .Ee .\" --------------------------------------------------------------------------- .K2 "Floating Point Numbers (T_Flonum)" @[.=T_Flonum] .PP @[.=real numbers] Real and @[.inexact number]s are represented as \f2Objects\fP of type \f2T_Flonum\fP. Each such object holds a pointer to a structure on the heap with a component \f2val\fP of type \f2double\fP, so that the expression .Es @[.=FLONUM()] FLONUM(flonum_obj)->val .Ee can be used to obtain the \f2double\fP value. To convert a Scheme number to a \f2double\fP regardless of its type, the more general function .Es @[.=Get_Double()] double Get_Double(Object); .Ee can be used. It raises an error if the argument is not a fixnum, bignum, or flonum, or if it is a bignum too large to fit into a \f2double\fP. .LP The functions .Es @[.=Make_Flonum()]@[.=Make_Reduced_Flonum()] Object Make_Flonum(double); Object Make_Reduced_Flonum(double); .Ee convert a C \f2double\fP to a flonum; the latter returns a fixnum if the \f2double\fP is small enough to fit into a fixnum and has a fractional part of zero. The macro .Es @[.=Check_Number()] Check_Number(obj) .Ee checks whether the given \f2Object\fP is a number (that is, a fixnum, bignum, or flonum in the current revision of Elk) and raises an error otherwise. .\" --------------------------------------------------------------------------- .K2 "Pairs (T_Pair)" @[.=T_Pair] .PP Pairs have two components of type \f2Object\fP, the @[.car] and the @[.cdr], that can be accessed as: .Es @[.=PAIR()] PAIR(pair_obj)->car PAIR(pair_obj)->cdr .Ee Two macros @[.\f2Car()\fP] and @[.\f2Cdr()\fP] are provided as shorthands for these expressions, and another macro @[.\f2Cons()\fP] can be used in place of @[.\f2P_Cons()\fP] to create a new pair. The macro .Es @[.=Check_List()] Check_List(obj) .Ee checks whether the specified \f2Object\fP is either a pair or the empty list and signals an error otherwise. The predefined function .Es @[.=Fast_Length()] int Fast_Length(Object list); .Ee can be used to compute the length of the given Scheme list. This function is more efficient than the primitive \f2P_Length()\fP, because it neither checks the type of the argument nor whether the given list is proper, and the result need not be converted to a Scheme number. The function .Es @[.=Copy_List()] Object Copy_List(Object list); .Ee returns a copy of the specified list (including all its sublists). .PP As explained in section @(ch-gc), care must be taken when mixing calls to these macros, because \f2Cons()\fP may trigger a garbage collection: an expression such as .Es Car(x) = Cons(y, z); .Ee is wrong, even if \f2x\fP is properly ``GC_Linked'', and should be replaced by .Es tmp = Cons(x, y); Car(x) = tmp; .Ee or a similar sequence. .\" --------------------------------------------------------------------------- .K2 "Symbols (T_Symbol)" @[.=T_Symbol] .PP \f2Objects\fP of type \f2T_Symbol\fP have one public component\*-the symbol's name as a Scheme string (that is, an \f2Object\fP of type \f2T_String\fP): .Es @[.=SYMBOL] SYMBOL(symbol_obj)->name .Ee A new symbol can be created by calling one of the functions .Es @[.=Intern()]@[.=CI_Intern()] Object Intern(const char *); Object CI_Intern(const char *); .Ee with the new symbol's name as the argument. \f2CI_Intern()\fP is the case-insensitive variant of \f2Intern()\fP; it maps all upper case characters to lower case. \f2EQ()\fP yields true for all \f2Objects\fP returned by calls to \f2Intern()\fP with strings with the same contents (or calls to \f2CI_Intern()\fP with strings that are identical after case conversion). This is the main property that distinguishes symbols from strings in Scheme. .PP A symbol that is used by more than one function can be stored in a global variable to save calls to \f2Intern()\fP. This can be done using the convenience function .Es @[.=Define_Symbol()] void Define_Symbol(Object *var, const char *name); .Ee \f2Define_Symbol()\fP is called with the address of a variable where the newly-interned symbol is stored and the name of the symbol to be handed to \f2Intern()\fP. The function adds the new symbol to the garbage collector's @[.root set] to make it reachable (as described in section @(ch-gcglobal). Example: .Es static Object sym_else; \&... void elk_init_example(void) { Define_Symbol(&sym_else, "else"); ... } .Ee .\" --------------------------------------------------------------------------- .K3 "The Non-Printing Symbol" .PP By convention, Scheme primitives that do not have a useful return value (for example the output primitives) return the @[.``non-printing symbol''] in Elk. The name of this symbol consists of the empty string; it does not produce any output when it is printed, for example, by the toplevel read-eval-print loop. In Scheme code, the non-printing symbol can be generated by using the reader syntax ``#v'' or by calling \f2string\(mi>symbol\fP with the empty string. On the C language level, the non-printing symbol is available as the external variable @[.\f2Void\fP], so that primitives lacking a useful return value can use .Es return Void; .Ee .\" --------------------------------------------------------------------------- .K2 "Strings (T_String)" @[.=T_String] .PP \f2Objects\fP of type string have two components\*-the length and the contents of the string as a pointer to \f2char\fP: .Es STRING(string_obj)->size STRING(string_obj)->data .Ee The \f2data\fP component is not null-terminated, as a string itself may contain a null-byte as a valid character in Elk. A Scheme string is created by calling the function .Es @[.=Make_String()] Object Make_String(const char *init, int size); .Ee \f2size\fP is the length of the newly-created string. \f2init\fP is either the null-pointer or a pointer to \f2size\fP characters that are copied into the new Scheme string. For example, the sequence .Es Object str; \&... str = Make_String(0, 100); bzero(STRING(str)->data, 100); .Ee generates a string holding 100 null-bytes. .PP Most primitives that receive a Scheme string as one of their arguments pass the string's contents to a C function (for example a C library function) that expects an ordinary, null-terminated C string. For this purpose Elk provides a function .Es @[.=Get_String()] char *Get_String(Object); .Ee that returns the contents of the Scheme string argument as a null-terminated C string. An error is raised if the argument is not a string. \f2Get_String()\fP has to create a copy of the contents of the Scheme string in order to append the null-character. To avoid requiring the caller to provide and release space for the copy, \f2Get_String()\fP operates on and returns @[.NUMSTRBUFS] internal, cyclically reused buffers (the value of NUMSTRBUFS is 3 in Elk \*(Vs). Consequently, no more than NUMSTRBUFS results of \f2Get_String()\fP can be used simultaneously (which is rarely a problem in practice). As an example, a Scheme primitive that calls the C library function \f2getenv()\fP and returns #f on error can be written as .Es Object p_getenv(Object name) { char *ret = getenv(Get_String(name)); return ret ? Make_String(ret, strlen(ret)) : False; } .Ee .PP If more strings are to be used simultaneously, the macro @[.\f2Get_String_Stack()\fP] can be used instead. It is called with the Scheme object and the name of a variable of type ``char*'' to which the C string will be assigned. \f2Get_String_Stack()\fP allocates space by means of @[.\f2Alloca()\fP] (as explained in section @(ch-alloca)); hence a call to @[.\f2Alloca_Begin\fP] must be placed in the declarations of the enclosing function or block, and @[.\f2Alloca_End\fP] must be called before returning from it. .PP An additional function @[.\f2Get_Strsym()\fP] and an additional macro @[.\f2Get_Strsym_Stack()\fP] are provided by Elk; these are identical to \f2Get_String()\fP and \f2Get_String_Stack()\fP, respectively, except that the Scheme object may also be a symbol. In this case, the symbol's name is taken as the string to be converted. .PP As an example for the use of \f2Get_String_Stack()\fP, here is a simple Scheme primitive \f2exec\fP that is called with the name of a program and one more more arguments and passes them to the \f2execv()\fP system call: .Es Object p_exec(int argc, Object *argv) { char **argp; int i; Alloca_Begin; .El Alloca(argp, char**, argc*sizeof(char *)); for (i = 1; i < argc; i++) Get_String_Stack(argv[i], argp[i-1]); argp[i-1] = 0; execv(Get_String(*argv), argp); /* must not return */ \f2error...\fP } .El elk_init_example() { Define_Primitive(p_exec, "exec", 2, MANY, VARARGS); } .Ee The primitive can be used as follows: .Es (exec "/bin/ls" "ls" "-l") .Ee \f2Get_String()\fP could not be used in this primitive, because the number of string arguments may exceed the number of static buffers maintained by \f2Get_String()\fP. .\" --------------------------------------------------------------------------- .K2 "Vectors (T_Vector)" @[.=T_Vector] .PP The layout of \f2Objects\fP of type vector is identical to that of strings, except that the \f2data\fP component is an array of \f2Objects\fP. A function @[.\f2Make_Vector()\fP] creates a new vector as has been explained in section @(ch-gc) above. .\" --------------------------------------------------------------------------- .K2 "Ports (T_Port)" @[.=T_Port] .PP The components of \f2Objects\fP of type \f2T_Port\fP are not normally accessed directly from within C/C++ code, except for .Es PORT(port_obj)->closefun .Ee which is a pointer to a function receiving an argument of type ``FILE*'' (for example, a pointer to \f2fclose()\fP), provided that the port is a file port. It is called automatically whenever the port is closed, either because \f2close-input-port\fP or \f2close-output-port\fP is applied to it or because the garbage collector has determined that the port is no longer reachable. .LP A new file port is created by calling .Es @[.=Make_Port()] Object Make_Port(int flags, FILE *f, Object name); .Ee with a first argument of either zero (output port), \f2P_INPUT\fP (input port) or \f2P_BIDIR\fP (bidirectional port), the file pointer, and the name of the file as a Scheme string. The macros .Es @[.=Check_Input_Port()]@[.=Check_Output_Port()] Check_Input_Port(obj) Check_Output_Port(obj) .Ee check whether the specified port is open and is capable of input (or output, respectively); an error is raised otherwise. .PP To arrange for a newly-created port to be closed automatically when it becomes garbage, it must be passed to the function \f2Register_Object()\fP as follows: .Es @[.=Register_Object()]@[.=Terminate_File()] Register_Object(the_port, 0, Terminate_File, 0); .Ee \f2Register_Object()\fP will be described in section @(ch-term). The current input and output port as well as ports pointing to the program's initial standard input and output are available as four external variables of type \f2Object\fP: .Es @[.=Curr_Input_Port]@[.=Curr_Output_Port] @[.=Standard_Input_Port]@[.=Standard_Output_Port] Curr_Input_Port Standard_Input_Port Curr_Output_Port Standard_Output_Port .Ee The function .Es @[.=Reset_IO()] void Reset_IO(int destructive_flag); .Ee clears any input queued at the current input port, then flushes the current output port (if \f2destructive_flag\fP is zero) or discards characters queued at the output port (if \f2destructive_flag\fP is non-zero), and finally resets the current input and current output port to their initial values (the program's standard input and standard output). This function is typically used in error situations to reset the current ports to a defined state. .PP In addition to the standard Scheme primitives for output, extensions and applications can use a function .Es @[.=Printf()] void Printf(Object port, char *fmt, ...); .Ee to send output to a Scheme port using C \f2printf\fP. The first argument to \f2Printf()\fP is the Scheme port to which the output will be sent (it must be an output port); the remaining arguments are that of the C library function \f2printf()\fP. .LP To output a Scheme object, the following function can be used in addition to the usual primitives: .Es @[.=Print_Object()] void Print_Object(Object obj, Object port, int raw_flag, int print_depth, int print_length); .Ee The arguments to \f2Print_Object()\fP are identical to the arguments of the ``print function'' that must be supplied for each user-defined Scheme type (as described in section @(ch-deftype): the \f2Object\fP to be printed, the output port, a flag indicating that the object should be printed in human-readable form (\f2display\fP sets the flag, \f2write\fP does not), and the ``print depth'' and ``print length'' for that operation. For debugging purposes, the macro .Es @[.=Print()] Print(obj); .Ee may be used to output an \f2Object\fP to the current output port. .LP A function .Es @[.=Load_Source_Port()] void Load_Source_Port(Object port); .Ee can be used to load Scheme expressions from a file that has already been opened as a Scheme port. .\" --------------------------------------------------------------------------- .K2 "Miscellaneous Types" .PP Other built-in Scheme types are lexical environments, primitive procedures, compound procedures, macros, continuations (also called ``control points'' at a few places in Elk), and promises. These types are not normally created or manipulated from within C or C++ code. If you are writing a specialized extension that depends on the C representation of these types, refer to the declarations in the public include file ``object.h'' (which is included automatically via ``scheme.h''). .PP Lexical environments are identical to pairs except that the type is @[.\f2T_Environment\fP] rather than \f2T_Pair\fP. The current environment and the initial (gobal) environment are available as the external C variables @[.\f2The_Environment\fP] and @[.\f2Global_Environment\fP]. The predefined type constants for primitives, compound procedures (the results of evaluating lambda expressions), and macros are @[.\f2T_Primitive\fP], @[.\f2T_Compound\fP], and @[.\f2T_Macro\fP], respectively. The function .Es @[.=Check_Procedure()] void Check_Procedure(Object); .Ee checks whether the specified object is either a compound procedure or a primitive procedure with a calling discipline different from \f2NOEVAL\fP and raises an error otherwise. The type constant for continuations is @[.\f2T_Control\fP]. ``Promise'' is the type of object returned by the special form \f2delay\fP; the corresponding type constant is named @[.\f2T_Promise\fP]. .\" --------------------------------------------------------------------------- .K1 "Defining New Scheme Types" .Rf ch-deftype \*(SN .PP A new, disjoint Scheme type is registered with Elk by calling the function @[.\f2Define_Type()\fP], similar to \f2Define_Primitive()\fP for new primitives. Making a new type known to Elk involves passing it information about the underlying C/C++ representation of the type and a number of C or C++ functions that are ``called back'' by the interpreter in various situations to pass control to the code that implements the type. The prototype of \f2Define_Type()\fP is: .Es int Define_Type(int zero, const char *name, int (*size)(Object), int const_size, int (*eqv)(Object, Object), int (*equal)(Object, Object), int (*print)(Object, Object, int, int, int), int (*visit)(Object*, int (*)(Object*))); .Ee The arguments to \f2Define_Primitive()\fP are in detail: .Rs .IP \f2zero\fP 1 The first argument must be zero (in early versions of Elk it could be used to request a fixed, predefined type number for the new type); .IP \f2name\fP 1 The name of the new type. .IP "\f2size, const_size\fP" 1 The size of the corresponding C type (usually a \f2struct\fP) in bytes, given as one of two, mutually-exclusive arguments: \f2size\fP, a pointer to a function called by the interpreter to determine the size of an object (for types whose individual members are of different sizes, such as the \f2vector\fP type); and \f2const_size\fP, the size as a constant (for all other types). A null-pointer is given for \f2const_size\fP if \f2size\fP is to be used instead. .IP "\f2eqv, equal\fP" 1 Pointers to (callback) functions that are invoked by the interpreter whenever the Scheme predicate \f2equal?\&\fP, or \f2eqv?\&\fP respectively, is applied to members of the newly defined type. As an application-defined type is opaque from the interpreter's point of view, the equality predicates have to be supplied by the application or extension. Each of these (boolean) functions is passed two objects of the new type as arguments when called back. .IP \f2print\fP 1 A pointer to a function that is used by the interpreter to print a member of this type. When calling the print function, the interpreter passes as arguments the Scheme object to be printed, a Scheme \f2port\fP to which the output is to be sent, a flag indicating whether output is to be rendered in human-readable form (\f2display\fP Scheme primitive) or machine-readable, read-write-invariance preserving form (\f2write\fP), and finally the current remainders of the maximum \f2print depth\fP and \f2print length\fP. The return value of this function is not used (the type is \f2int\fP for historical reasons). .IP \f2visit\fP 1 A pointer to a @[.``visit'' function] called by the @[.garbage collector] when tracing the set of all currently accessible objects. This function is only required if other Scheme objects are reachable from objects of the newly defined type (a null pointer can be given otherwise). It is invoked with two arguments: a pointer to the object being visited by the garbage collector, and a pointer to another function to be called once with the address of each object accessible through the original object. For example, the implementation of pairs would supply a visit function that invokes its second argument twice\*-once with the address of the car of the original object, and once with the address of the cdr. .Re .PP The return value of \f2Define_Type()\fP is a small, unique integer identifying the type; it is usually stored in a ``T_*'' (or ``t_*'') variable following the convention used for the built-in types. .PP In the current version of Elk, \f2Define_Type()\fP cannot be used to define new ``pointer-less'' types resembling built-in types such as \f2fixnum\fP or \f2boolean\fP. .PP The first component of the C structure implementing a user-defined Scheme type must be an \f2Object\fP; its space is used by the @[.garbage collector] to store a special tag indicating that the object has been forwarded. If you are defining a type that has several components one of which is an \f2Object\fP, just move the \f2Object\fP to the front of the \f2struct\fP declaration. Otherwise insert an additional \f2Object\fP component. .PP The Scheme primitive that instantiates a new type can request heap space for the new object by calling the function @[.\f2Alloc_Object()\fP]: .Es Object Alloc_Object(int size, int type, int const_flag); .Ee The arguments to \f2Alloc_Object()\fP are the size of the object in bytes (usually obtained by applying \f2sizeof\fP to the underlying \f2struct\fP), the type of which the new object is a member (i.\|e.\& the return value of \f2Define_Type()\fP), and a flag indicating whether the newly created object is to be made read-only. The return value is a fully initialized \f2Object\fP. .\" --------------------------------------------------------------------------- .K2 "Example for a User-Defined Scheme Type" .PP Figure @(ndbm1) shows the skeleton of an extension that provides a simple Scheme interface to the UNIX \f2ndbm\fP library; it can be loaded dynamically into the Scheme interpreter, or into an Elk-based application that needs access to a simple database from within the extension language. Please refer to your system's documentation if you are not familiar with \f2ndbm\fP. The extension defines a new, first-class Scheme type \f2dbm-file\fP corresponding to the \f2DBM\fP type defined by the C library. Again, note the naming convention to use lower-case for new identifiers (in contrast to the predefined ones). .Fs #include #include .El int t_dbm; .El struct s_dbm { Object unused; DBM *dbm; char alive; /* 0: has been closed, else 1 */ }; .El #define DBMF(obj) ((struct s_dbm *)POINTER(obj)) .El int dbm_equal(Object a, Object b) { return DBMF(a)->alive && DBMF(b)->alive && DBMF(a)->dbm == DBMF(b)->dbm; } .El int dbm_print(Object d, Object port, int raw, int length, int depth) { Printf(port, "#[dbm-file %lu]", DBMF(d)->dbm); return 0; } .El Object p_is_dbm(Object d) { return TYPE(d) == t_dbm ? True : False; } .El void elk_init_dbm(void) { t_dbm = Define_Type(0, "dbm-file", 0, sizeof(struct s_dbm), dbm_equal, dbm_equal, dbm_print, 0); .El Define_Primitive(p_is_dbm, "dbm-file?", 1, 1, EVAL); Define_Primitive(p_dbm_open, "dbm-open", 2, 3, VARARGS); Define_Primitive(p_dbm_close, "dbm-close", 1, 1, EVAL); } .Fc "Skeleton of a UNIX ndbm extension" .Fe ndbm1 .PP The code shown in Figure @(ndbm1) declares a variable \f2t_dbm\fP to hold the return value of \f2Define_Primitive()\fP, and the C structure \f2s_dbm\fP that represents the new type. The structure is composed of the required initial \f2Object\fP, the \f2DBM\fP pointer returned by the C library function \f2dbm_open()\fP, and a flag indicating whether the database pointed to by this object has already been closed (in this case the flag is cleared). As a \f2dbm-file\fP Scheme object can still be passed to primitives after the \f2DBM\fP handle has been closed by a call to \f2dbm_close()\fP, the \f2alive\fP flag had to be added to avoid further use of a ``stale'' object: the ``dbm'' primitives include an initial check for the flag and raise an error if it is zero. .PP The macro \f2DBMF\fP is used to cast the pointer field of an \f2Object\fP of type \f2t_dbm\fP to a pointer to the correct structure type. \f2dbm_equal()\fP implements both the \f2eqv?\&\fP and the \f2equal?\&\fP predicates; it returns true if the \f2Objects\fP compared point to an open database and contain identical \f2DBM\fP pointers. The print function just prints the numeric value of the \f2DBM\fP pointer; this could be improved by printing the name of the database file instead, which must then be included in each Scheme object. The primitive \f2p_is_dbm()\fP provides the usual @[.type predicate]. Finally, an @[.extension initialization function] is supplied to enable @[.dynamic loading] of the compiled code; it registers the new type and three primitives operating on it. Note that a @[.visit function] (the final argument to \f2Define_Type()\fP) is not required here, as the new type does not include any components of type \f2Object\fP that the garbage collector must know of\*-the required initial \f2Object\fP is not used here and therefore can be neglected. The type constructor primitive \f2dbm-open\fP and the primitive \f2dbm-close\fP are shown in Figure @(ndbm2). .PP .Fs Object p_dbm_open(int argc, Object *argv) { DBM *dp; int flags = O_RDWR|O_CREAT; Object d, sym = argv[1]; .El Check_Type(sym, T_Symbol); if (EQ(sym, Intern("reader"))) flags = O_RDONLY; else if (EQ(sym, Intern("writer"))) flags = O_RDWR; else if (!EQ(sym, Intern("create"))) Primitive_Error("invalid argument: ~s", sym); if ((dp = dbm_open(Get_String(argv[0]), flags, argc == 3 ? Get_Integer(argv[2]) : 0666)) == 0) return False; d = Alloc_Object(sizeof(struct s_dbm), t_dbm, 0); DBMF(d)->dbm = dp; DBMF(d)->alive = 1; return d; } .El Object p_dbm_close(Object d) { Check_Type(d, t_dbm); if (!DBMF(d)->alive) Primitive_Error("invalid dbm-file: ~s", d); DBMF(d)->alive = 0; dbm_close(DBMF(d)->dbm); return Void; } .Fc "Implementation of \f2dbm-open\fP and \f2dbm-close\fP" .Fe ndbm2 .PP The primitive \f2dbm-open\fP shown in Figure @(ndbm2) is called with the name of the database file, a symbol indicating the type of access (\f2reader\fP for read-only access, \f2writer\fP for read/write access, and \f2create\fP for creating a new file with read/write access), and an optional third argument specifying the file permissions for a newly-created database file. A default of 0666 is used for the file permissions if the primitive is invoked with just two arguments. Section @(ch-symbits) will introduce a set of functions that avoid clumsy if-cascades such as the one at the beginning of \f2p_dbm_open()\fP. @[.\f2Primitive_Error()\fP] is called with a @[.``format string''] and zero or more arguments and signals a Scheme error (see section @(ch-error)). \f2dbm-open\fP returns #f if the database file could not be opened, so that the caller can deal with the error. .PP Note that \f2dbm-close\fP first checks the \f2alive\fP bit to raise an error if the database pointer is no longer valid because of an earlier call to \f2dbm-close\fP. This check needs to be performed by all primitives working on \f2dbm-file\fP objects; it may be useful to wrap it in a separate function\*-together with the initial type-check. Ideally, database objects should be closed automatically during @[.garbage collection] when they become inaccessible; section @(ch-term) will introduce functions to accomplish this. .PP At least two primitives \f2dbm-store\fP and \f2dbm-fetch\fP need to be added to the database extension to make it really useful; these are not shown here (their implementation is fairly simple and straightforward). Using these primitives, the extension discussed in this section can be used to write Scheme code such as this procedure (which looks up an electronic mailbox name in the mail alias database maintained on most UNIX systems): .Es (define expand-mail-alias (lambda (alias) (let ((d (dbm-open "/etc/aliases" 'reader))) (if (not d) (error 'expand-mail-alias "cannot open database")) (unwind-protect (dbm-fetch d alias) (dbm-close d))))) .El (define address-of-staff (expand-mail-alias "staff")) .Ee .\" --------------------------------------------------------------------------- .K1 "Advanced Topics" .Rf ch-advanced \*(SN .\" --------------------------------------------------------------------------- .K2 "Converting between Symbols, Integers, and Bitmasks" .Rf ch-symbits \*(SN .PP Symbols are frequently used as the arguments to Scheme primitives which call an underlying C or C++ function with some kind of @[.bitmask] or with a predefined enumeration constant or preprocessor symbol. For example, the primitive \f2dbm-open\fP shown in Figure @(ndbm2) above uses symbols to represent the symbolic constants passed to \f2dbm_open()\fP. Similarly, a Scheme primitive corresponding to the UNIX system call \f2open()\fP could receive a list of symbols represending the logical OR of the usual \f2open()\fP flags, so that one can write Scheme code such as: .Es (let ((tty-fd (unix-open "/dev/ttya" '(read write exclusive))) (tmp-fd (unix-open "/tmp/somefile '(write create)))) ... .Ee .PP To facilitate conversion of symbols to C integers or enumeration constants and vice versa, these two functions are provided: .Es @[.=Symbols_To_Bits()]@[.=Bits_To_Symbols()] unsigned long Symbols_To_Bits(Object syms, int mask_flag, SYMDESCR *table); Object Bits_To_Symbols(unsigned long bits, int mask_flag, SYMDESCR *table); .Ee The type @[.\f2SYMDESCR\fP] is defined as: .Es typedef struct { char *name; unsigned long val; } SYMDESCR; .Ee .PP \f2Symbols_To_Bits()\fP converts a symbol or a list of symbols to an integer; \f2Bits_To_Symbols()\fP is the reverse operation and is usually applied to the return value of a C/C++ function to convert it to a Scheme representation. Both functions receive as the third argument a table specifying the correspondence between symbols and C constants; each table entry is a pair consisting of the \f2name\fP of a symbol as a C string and an integer \f2val\fP (typically an enumeration constant or a \f2#define\fP constant). Each \f2SYMDESCR\fP array is terminated by an entry with a zero \f2name\fP component: .Es SYMDESCR lseek_syms[] = { { "set", SEEK_SET }, { "current", SEEK_CUR }, { "end", SEEK_END }, { 0, 0 } }; .Ee .PP The second argument to the conversion functions controls whether a single symbol is converted to an integer or vice versa (\f2mask_flag\fP is zero), or whether a list of symbols is converted to the logical OR of a set of matching values or vice versa (\f2mask_flag\fP is non-zero). \f2Symbols_To_Bits()\fP signals an error if the symbol does not match any of the names in the given table or, if \f2mask_flag\fP is non-zero, if any of the list elements does not match. The empty list is converted to zero. If \f2Bits_To_Symbols()\fP is called with a non-zero \f2mask_flag\fP, it matches the \f2val\fP components against the \f2bits\fP argument using logical AND. Regardless of \f2mask_flag\fP, \f2Bits_To_Symbols\fP returns the empty list if no match occurs. Figure @(ndbm3) shows an improved version of \f2p_dbm_open()\fP using \f2Symbols_To_Bits()\fP in place of nested if-statements. .Fs static SYMDESCR flag_syms[] = { { "reader", O_RDONLY }, { "writer", O_RDWR }, { "create", O_RDWR|O_CREAT }, { 0, 0 } }; .El Object p_dbm_open(int argc, Object *argv) { DBM *dp; Object d; .El dp = dbm_open(Get_String(argv[0]), Symbols_To_Bits(argv[1], 0, flag_syms), argc == 3 ? Get_Integer(argv[2]) : 0666); if (dp == 0) return False; d = Alloc_Object(sizeof(struct s_dbm), t_dbm, 0); DBMF(d)->dbm = dp; DBMF(d)->alive = 1; return d; } .Fc "Improved version of \f2dbm-open\fP using \f2Symbols_To_Bits()\fP" .Fe ndbm3 .PP A Scheme primitive calling the UNIX system call \f2access()\fP could use \f2Symbols_To_Bits()\fP with a non-zero \f2mask_flag\fP to construct a bitmask: .Es Object p_access(Object fn, Object mode) { access(Get_String(fn), (int)Symbols_To_Bits(mode, 1, access_syms)); ... .Ee where \f2access_syms\fP is defined as: .Es static SYMDESCR access_syms[] = { { "read", R_OK }, { "write", W_OK }, { "execute", X_OK }, { 0, 0 } }; .Ee Note that in this example the empty list can be passed as the \f2mode\fP argument to test for existence of the file, because in this case \f2Symbols_To_Bits()\fP returns zero (the value of \f2F_OK\fP). .\" --------------------------------------------------------------------------- .K2 "Calling Scheme Procedures, Evaluating Scheme Code" .Rf ch-funcall \*(SN .PP A Scheme procedure can be called from within C or C++ code using the function .Es @[.=Funcall()] Object Funcall(Object fun, Object argl, int eval_flag); .Ee The first argument is the Scheme procedure\*-either a primitive procedure (\f2T_Primitive\fP) or a compound procedure (\f2T_Compound\fP). The second argument is the list of arguments to be passed to the procedure, as a Scheme list. The third argument, if non-zero, specifies that the arguments need to be evaluated before calling the Scheme procedure. This is usually not the case (except in some special forms). The return value of \f2Funcall()\fP is the result of the Scheme procedure. .PP \f2Funcall()\fP is frequently used from within C callback functions that can be registered for certain events, such as the user-supplied X11 error handlers, X11 event handlers, timeout handlers, the C++ \f2new\fP handler, etc. Here, use of \f2Funcall()\fP allows to register a user-defined Scheme procedure for this event from within a Scheme program. As an example, Figure @(funcall) shows the generic signal handler that is associated with various UNIX signals by the UNIX extension. .Fs void scheme_signal_handler(int sig) { Object fun, args; .El Set_Error_Tag("signal-handler"); Reset_IO(1); args = Bits_To_Symbols((unsigned long)sig, 0, signal_syms); args = Cons(args, Null); fun = VECTOR(handlers)->data[sig]; if (TYPE(fun) != T_Compound) Fatal_Error("no handler for signal %d", sig); (void)Funcall(fun, args, 0); Printf(Curr_Output_Port, "\en\e7Signal!\en"); (void)P_Reset(); /*NOTREACHED*/ } .Fc "Using \f2Funcall()\fP to call a Scheme procedure" .Fe funcall .PP The signal handler shown in Figure @(funcall) uses the signal number supplied by the system to index a vector of user-defined Scheme procedures (that is, \f2Objects\fP of type \f2T_Compound\fP). @[.\f2Reset_IO()\fP] is used here to ensure that the current input and output port are in defined state when the Scheme signal handler starts executing. The argument list is constructed by calling @[.\f2Cons()\fP]; it consists of a single element\*-the signal number as a Scheme symbol. \f2signal_syms\fP is an array of @[.\f2SYMDESCR\fP] records that maps the UNIX signal names (\f2sighup\fP, \f2sigint\fP, etc.) to corresponding Scheme symbols of the same names. The Scheme procedure called from the signal handler is not supposed to return (it usually invokes a continuation); therefore the result of \f2Funcall()\fP is ignored. In case the Scheme handler (and thus the call to \f2Funcall()\fP) does return, a message is printed and the primitive \f2reset\fP is called to return to the application's toplevel or standard Scheme toplevel. .PP An S-expression can be evaluated by calling the function .Es @[.=Eval()] Object Eval(Object expr); .Ee which is identical to the primitive \f2eval\fP (\f2P_Eval()\fP in C), except that no optional environment can be supplied. \f2Eval()\fP is very rarely used by extensions or applications, mainly by implementations of new special forms. Both \f2Eval()\fP and \f2Funcall()\fP can trigger a @[.garbage collection]; all @[.local variable]s holding Scheme \f2Objects\fP with heap pointers must be properly registered with the garbage collector to survive calls to these functions. .PP Occasionally an S-expression needs to be evaluated that exists as a C string, for example, when a Scheme expression has been entered through a ``text widget'' in a graphical user interface. Here, evaluation requires calling the Scheme reader to parse the expression; therefore a straightforward solution is to create a @[.string port] holding the string and then just ``load'' the contents of the port: .Es void eval_string(char *expr) { Object port; GC_Node; .El port = P_Open_Input_String(Make_String(expr, strlen(expr))); GC_Link(port); Load_Source_Port(port); GC_Unlink; (void)P_Close_Input_Port(port); } .Ee If a more sophisticated function is required, the \f2eval-string\fP extension included in the Elk distribution can be used (``lib/misc/elk-eval.c''). This extension provides a function .Es @[.=Elk_Eval()] char *Elk_Eval(char *expr); .Ee that converts the result of evaluating the stringized expression back to a C string and returns it as a result. A null pointer is returned if an error occurs during evaluation. .PP Applications should not use this function as the primary interface to the extension language. In contrast to languages such as @[.Tcl], the semantic concepts and data structures of Scheme are not centered around strings, and strings are not a practicable representation for S-expressions. Instead, applications should pass control to the extension language by calling Scheme procedures (using @[.\f2Funcall()\fP]) or by loading files containing Scheme code. The extension language then calls back into the application's C/C++ layer by invoking application-supplied Scheme primitives and other forms of callbacks as explained in section @(ch-control). .\" --------------------------------------------------------------------------- .K2 "GC-Protecting Global Objects" .Rf ch-gcglobal \*(SN .PP Section @(ch-gc) explained when\*-and how\*-to register with the @[.garbage collector] function-local \f2Object\fP variables holding heap pointers. Similarly, @[.global variable]s must usually be added to the set of reachable objects as well if they are to survive garbage collections (a useful exception to this rule will be introduced in section @(ch-term)). In contrast to local variables, global variables are only made known to the garbage collector once\*-after initialization\*-as their lifetime is that of the entire program. To add a global variable to the garbage collector's root set, the macro .Es @[.=Global_GC_Link()] Global_GC_Link(obj) .Ee must be called with the properly initialized variable of type \f2Object\fP. The macro takes the address of the specified object. If that is a problem, an equivalent functional interface can be used: .Es @[.=Func_Global_GC_Link()] void Func_Global_GC_Link(Object *obj_ptr); .Ee This function must be supplied the address of the global variable to be registered with the garbage collector. .PP When writing extensions that maintain global \f2Object\fP variables, \f2Global_GC_Link()\fP (or \f2Func_Global_GC_Link()\fP) is usually called from within the @[.extension initialization function] right after each variable is assigned a value. For instance, the global Scheme vector \f2handlers\fP that was used in Figure @(funcall) to associate procedures with UNIX signals is initialized and GC-protected as follows: .Es void elk_init_unix_signal(void) { handlers = Make_Vector(NSIG, False); Global_GC_Link(handlers); ... } .Ee \f2NSIG\fP is the number of UNIX signal types as defined by the system include file. The signal handling Scheme procedures that are inserted into the vector later need not be registered with the garbage collector, because they are now reachable through another object which itself is reachable. .\" --------------------------------------------------------------------------- .K3 "Dynamic C Data Structures" .PP Dynamic data structures, such as the nodes of a linked list containing Scheme \f2Objects\fP, cannot be easily registered with the garbage collector. The simplest solution is to build these data structures in Scheme rather than in C or C++ in the first place. For example, a linked list of Scheme objects can be built from Scheme pairs much more naturally and more straightforward than from C structures or the like, in particular if the list will be traversed and manipulated using Scheme primitives anyway. Besides, data structures programmed in Scheme benefit from automatic memory management, whereas use of \f2malloc()\fP and \f2free()\fP in C frequently is a source of memory leaks and related errors. .PP If for some reason a dynamic data structure must be built in C or C++ rather than in Scheme, reachability problems can be avoided by inserting all \f2Objects\fP into a global, GC-protected vector (such as \f2handlers\fP in Figure @(funcall)) and then use the corresponding vector indexes rather than the actual \f2Objects\fP. This sounds more difficult than it really is; Appendix B shows the complete source code of a small module to register \f2Objects\fP in a Scheme vector. The module exports three functions: \f2register_object()\fP inserts an \f2Object\fP into the vector and returns the index as an \f2int\fP; \f2deregister_object()\fP removes an \f2Object\fP with a given index from the vector; and \f2get_object()\fP returns the \f2Object\fP stored under a given index. \f2register_object()\fP dynamically grows the vector to avoid artificial limits. .PP A dynamic data structure (e.\|g.\& linked list) implementation using this module would call \f2register_object()\fP when inserting a new \f2Object\fP into the list and then use the integer return value in place of the \f2Object\fP itself. Similarly, it would call \f2deregister_object()\fP whenever a node is removed from the list. \f2get_object()\fP would be used to retrieve the \f2Object\fP associated with a given list element. Note that with these functions the same \f2Object\fP can be registered multiple times (each time under a new index) without having to maintain reference counts: the garbage collector does not care how often a particular \f2Object\fP is traversed during garbage collection, as long as it will be reached at least once. .\" --------------------------------------------------------------------------- .K2 "Weak Pointers and Object Termination" .Rf ch-term \*(SN .PP A data structure implementation may deliberately use \f2Objects\fP that are not added to the global set of reachable pointers (as described in the previous section) and are thus invisible to the @[.garbage collector]. In this case, it becomes possible to determine whether or not garbage collection has found any \f2other\fP pointers to the same Scheme objects. This property can be exploited in several ways by extensions or applications using Elk. .PP Pointers that are not included in the garbage collector's reachability search are called @[.``weak pointers'']. The memory occupied by a Scheme object that is only referenced by weak pointers will be reclaimed. The term \f2weak\fP expresses the notion that the pointer is not strong enough to prevent the object it points to from being garbage collected. Code using weak pointers can scan the pointers immediately after each garbage collection and check whether the target object has been visited by the just-finished garbage collection. If this is the case, normal (strong) pointers to the object must exist (which can therefore be considered ``live''), and the weak pointer is updated manually to point to the object's new location. On the other hand, if the object has not been visited, no more (normal) references to it exist and the memory occupied by it has been reclaimed. .PP Weak pointers are useful in implementing certain types of data structures where the sole existence of a (weak) pointer to an object from within this data structure should not keep the object alive (\f2weak sets\fP, \f2populations\fP, certain kinds of hash tables, etc.). Objects that are not reachable through @[.strong pointers] are then removed from the @[.weak data structure] after garbage collection. In this case, it is frequently useful to invoke a @[.``termination function''] for each such object, e.\|g.\& for objects that contain resources of which only a finite amount is available, such as UNIX file descriptors (or FILE structures), X displays and windows, etc. The termination function for Scheme ports closes the file pointer encapsulated in a port object if it is still open; likewise, the termination function for X windows closes the window and thereby removes it from the display, and so on. Thus, should an object holding some kind of resource go inaccessible before it was terminated ``properly'' by calling the respective Scheme primitive (\f2close-input-port\fP, \f2close-output-port\fP, \f2destroy-window\fP, etc.), then resource will be reclaimed after the next garbage collection run. .\" --------------------------------------------------------------------------- .K3 "Using Weak Pointers" .PP Code using @[.weak pointers] must scan the pointers immediately after each @[.garbage collection], but \f2before\fP the interpreter resumes normal operation, because the memory referenced by the weak pointers can be reused the next time heap space is requested. This can be accomplished by registering a so-called @[.``after-GC function]. Elk's garbage collector invokes all after-GC functions (without arguments) upon completion. To register an after-GC functions, the function .Es @[.=Register_After_GC()] void Register_After_GC((void (*func)(void))); .Ee is used, typically in an @[.extension initializer]. Similarly, extensions and applications can register @[.=before-GC function]``before-GC functions'' using .Es @[.=Register_Before_GC()] void Register_Before_GC((void (*func)(void))); .Ee These functions are called immediately before each garbage collection and may be used, for instance, to change the application's cursor to an hourglass symbol. After-GC and before-GC functions must not trigger another garbage collection. .PP An after-GC function scanning a set of weak pointers makes use of the three macros @[.\f2IS_ALIVE()\fP], @[.\f2WAS_FORWARDED()\fP], and @[.\f2UPDATE_OBJ()\fP]. For example, an after-GC function scanning a table of elements holding \f2Objects\fP with weak pointers could be written as shown in Figure @(aftergc). .Fs void scan_weak_table(void) { int i; .El for (i = 0; i < table_size; i++) { Object obj = table[i].obj; if (IS_ALIVE(obj)) { /* object is still reachable */ if (WAS_FORWARDED(obj)) UPDATE_OBJ(obj); } else { terminate_object(obj); /* object is dead; finalize... */ table[i] = 0; /* and remove it from the table */ } } } .Fc "After-GC function that scans a table containing weak pointers" .Fe aftergc .PP The function \f2scan_weak_table()\fP shown in Figure @(aftergc) can then be registered as an after-GC function by invoking .Es Register_After_GC(scan_weak_table); .Ee .PP The then-part of the if-statement in \f2scan_weak_table()\fP is entered if the just-completed garbage collection has encountered any pointers to the Scheme object pointed to by \f2obj\fP; in this case the pointer conveyed in \f2obj\fP is updated manually using \f2UPDATE_OBJ()\fP (when using the generational garbage collector included in Elk, reachability of an object does not necessarily imply that it was forwarded, hence the additional call to \f2WAS_FORWARDED()\fP). If \f2IS_ALIVE()\fP returns false, no more strong pointers to the object exist and it can be terminated and removed from the weak data structure. \f2terminate_object()\fP typically would release any external resources contained in the Scheme object, but it must neither create any new objects nor attempt to ``revive'' the dead object in any way (e.\|g.\& create a new strong pointer to it by inserting it into another, live object). .\" --------------------------------------------------------------------------- .K3 "Functions for Automatic Object Termination" .PP As automatic termination of Scheme objects using user-supplied @[.termination function]s is the most frequent use of @[.weak pointers], Elk offers a set of convenience functions for this purpose. Extensions and applications can insert \f2Objects\fP into a @[.weak list] maintained by Elk and remove them from the list using the two functions .Es @[.=Register_Object()]@[.=Deregister_Object()] void Register_Object(Object obj, char *group, (Object (*term)(Object)), int leader_flag); void Deregister_Object(Object obj); .Ee .PP \f2term\fP is the termination function that is called automatically with \f2obj\fP when the object becomes unreachable (its result is not used); \f2group\fP is an opaque ``cookie'' associated with \f2obj\fP and can be used to explicitly terminate all objects with the same value for \f2group\fP; a non-zero \f2leader_flag\fP indicates that \f2obj\fP is the ``leader'' of the specified \f2group\fP. Elk automatically registers an @[.after-GC function] to scan the weak list maintained by these two functions and to call the \f2term\fP function for all objects that could be proven unreachable by the garbage collector, similar to the function shown in Figure @(aftergc). .PP Object termination takes place in two phases: first all objects registered with a zero \f2leader_flag\fP are terminated, after that the termination functions of the leaders are invoked. This group and leader notion is used, for example, by the @[.Xlib extension] to associate windows (and other resources) with an X display: the ID of the display to which a window belongs is used as the window's group, and the display is marked as the group leader. Thus, if a display becomes unreachable or is closed by the program, all its windows are closed before the display is finally destroyed\**. .FS This interface has evolved in a slightly \f2ad hoc\fP way; the two-stage relationship expressed by groups and group leaders may not be sufficient for more complex hierarchies than those used in X. .FE .LP Two additional functions are provided for explicitly calling the termination functions: .Es @[.=Terminate_Type()]@[.=Terminate_Group()] void Terminate_Type(int type); void Terminate_Group(char *group); .Ee \f2Terminate_Type()\fP invokes the termination function (if any) for all objects of a given type and deletes them from the weak list. For example, to close all ports currently held open by Elk (and thus apply \f2fclose()\fP to the FILE pointers embedded in them), one would call .Es @[.=T_Port] Terminate_Type(T_Port) .Ee \f2Terminate_Group()\fP calls the termination functions of all non-leader objects belonging to the specified \f2group\fP. .LP Finally, another function, @[.\f2Find_Object()\fP], locates an object in the weak list: .Es Object Find_Object(int type, char *group, (int (*match_func)(Object, ...)), ...); .Ee Arguments are a Scheme type, a group, and a match function called once for each object in the weak list that has the specified type and group. The match function is passed the \f2Object\fP and the remaining arguments to \f2Find_Object()\fP, if any. If the match function returns true for an object, this object becomes the return value of \f2Find_Object()\fP; otherwise it returns \f2Null\fP. .PP Complicated as it may seem, \f2Find_Object()\fP is quite useful\*-extensions can check whether a Scheme object with certain properties has already been registered with the weak list earlier and, if this is the case, return \f2this\fP object instead of creating a new one. This is critical for Scheme objects encapsulating some kind of external resource, such as file descriptors or X windows. Consider, for example, a Scheme primitive that obtains the topmost window on a given X display and returns it as a Scheme \f2window\fP object. If the primitive just were to instantiate a Scheme object encapsulating the corresponding X window ID for each call, it would become possible for two or more distinct Scheme \f2window\fP objects to reference the same real X window. This is not acceptable, because two Scheme objects pointing to the same X object should certainly be equal in the sense of \f2eq?\&\fP, not to mention the problems that would ensue if one of the Scheme \f2window\fP objects were closed (thereby destroying the underlying X window) and the second one were still be operated on afterwards. Example uses of \f2Find_Object()\fP can be found in the @[.Xlib extension] and in the @[.Xt extension] that are included in the Elk distribution. .\" --------------------------------------------------------------------------- .K2 "Errors" .Rf ch-error \*(SN .PP User-supplied code can signal an error by calling @[.\f2Primitive_Error()\fP] with a @[.format string] and as many additional arguments (\f2Objects\fP) as there are @[.format specifier]s in the format string: .Es void Primitive_Error(char *fmt, ...); .Ee \f2Primitive_Error()\fP calls the default or user-defined @[.error handler] as described in the Elk Reference Manual, passing it an @[.``error tag''] identifying the source of the error, the format string, and the remaining arguments. A special format specifier ``~E'' can be used to interpolate the standard error message text corresponding to the UNIX error number @[.\f2errno\fP]; this is useful for primitives that invoke UNIX system calls or certain C library functions (if ``~e'' is used, the first character of the text is converted to lower case). If this format specifier is used, the current \f2errno\fP must be assigned to a variable @[.\f2Saved_Errno\fP] prior to calling \f2Primitive_Error()\fP to prevent it from being overwritten by the next system call or C library function. \f2Primitive_Error()\fP does not return. .PP Applications that need to supply their own error handler by redefining \f2error-handler\fP usually do so in Scheme, typically at the beginning of the initial Scheme file loaded in \f2main()\fP. .PP If \f2Primitive_Error()\fP is called from within a C function that implements a Scheme primitive, an error tag is supplied by Elk (the name of the primitive). Applications may set the error tag explicitly at the beginning of sections of C/C++ code that reside outside of primitives, for example, before loading an initial Scheme file in the application's \f2main()\fP. Two functions are provided to set and query the current error tag: .Es @[.=Set_Error_Tag()]@[.=Get_Error_Tag()] void Set_Error_Tag(const char *tag); char *Get_Error_Tag(void); .Ee The following three functions can be used by primitives to signal errors with standardized messages in certain situations: .Es @[.=Range_Error()]@[.=Wrong_Type()]@[.=Wrong_Type_Combination()] void Range_Error(Object offending_obj); void Wrong_Type(Object offending_obj, int expected_type); void Wrong_Type_Combination(Object offending_obj, char *expected_type); .Ee \f2Range_Error()\fP can be used when an argument to a primitive is out of range (typically some kind of index). \f2Wrong_Type()\fP signals a failed type-check for the given \f2Object\fP; the second argument is the expected type of the \f2Object\fP. This function is used, for example, by @[.\f2Check_Type()\fP]. \f2Wrong_Type_Combination()\fP is similar to \f2Wrong_Type()\fP; the expected type is specified as a string. This is useful if an \f2Object\fP can be a member of one out of two or more types, e.\|g.\& a string or a symbol. .LP Fatal errors can be signaled using the functions .Es @[.=Fatal_Error()]@[.=Panic()] void Fatal_Error(char *fmt, ...); void Panic(char *msg); .Ee \f2Fatal_Error()\fP passes its arguments to \f2printf()\fP and then terminates the program. \f2Panic()\fP is used in situations that ``cannot happen'' (failed consistency checks or failed assertions); it prints the specified message and terminates the program with a core dump. .\" --------------------------------------------------------------------------- .K2 "Exceptions" .PP As explained in the Elk Reference Manual, a user-supplied Scheme procedure is called each time an @[.\f2exception\fP] is raised. Currently, the set of UNIX @[.signals] that are caught by the interpreter or an extension (at least \f2interrupt\fP and \f2alarm\fP) are used as exceptions. As signals occur asynchronously, extensions and applications must be able to protect non-reentrant or otherwise critical code sections from the delivery of signals. In particular, calls to external library functions are frequently not reentrant\** and need to be protected from being disrupted. .FS Fortunately, with the advent of multithreading, vendors are now beginning to provide reentrant versions of their system libraries. .FE .PP Extensions may call the macros @[.\f2Disable_Interrupts\fP] and @[.\f2Enable_Interrupts\fP] (without arguments) to enclose code fragments that must be protected from exceptions. Calls to these macros can be nested, and they are also available as Scheme primitives on the Scheme-language level. As all modern UNIX versions provide a facility to temporarily block the delivery of signals, a signal that occurs after a call to \f2Disable_Interrupts\fP will be delayed until the outermost matching \f2Enable_Interrupts\fP is executed. Two additional macros, @[.\f2Force_Disable_Interrupts\fP] and @[.\f2Force_Enable_Interrupts\fP] can be used to enable and disable signal delivery regarless of the current nesting level. Extensions that use additional signals (such as the \f2alarm\fP signal) must register these with the interpreter core to make sure they are included in the \f2mask\fP of signals that is maintained by \f2Disable_Interrupts\fP and \f2Enable_Interrupts\fP (the interface for registering signals is still being revised; refer to the source code of the UNIX extension for an example). .PP The ability to protect code from exceptions is particularly useful for primitives that temporarily open a file or allocate some other kind of resource that must subsequently be released again. If the relevant code fragment were not enclosed by calls to \f2Disable_Interrupts\fP and \f2Enable_Interrupts\fP, an exception handler could abandon execution of the code section by calling a continuation, thus causing the file to remain open forever. While situations like this can be handled by \f2dynamic-wind\fP on the Scheme level, some form of \f2try/catch\fP facility is not available on the C-language level, and using the C function implementing the \f2dynamic-wind\fP primitive would be cumbersome. .LP The function .Es @[.=Signal_Exit()] void Signal_Exit(int signal_number); .Ee may be used as the handler for signals that must terminate the application; it ensures that the temporary files maintained by Elk are removed and calls the @[.extension finalization functions] in the normal way. .\" --------------------------------------------------------------------------- .K2 "Defining Scheme Variables" .PP User-supplied C/C++ code can define global Scheme variables that are maintained as corresponding \f2Object\fP C variables. The Scheme interpreter itself defines several such variables, for example, the variable @[.\f2load-path\fP] (see section @(ch-dynl)) which can be modified and read both from Scheme and from C. The function @[.\f2Define_Variable()\fP] is used to define a Scheme variable and bind an initial value to it: .Es void Define_Variable(Object *var, const char *name, Object init); .Ee \f2var\fP is the address of the C variable corresponding to the newly-created Scheme variable, \f2name\fP is the name of the Scheme variable, and \f2init\fP is its initial value. \f2Define_Variable()\fP calls @[.\f2Intern()\fP] to create the variable name included in the new binding and @[.\f2Func_Global_GC_Link()\fP] to properly register the C variable with the garbage collector. .LP The C side of a Scheme variable cannot be accessed directly; the functions .Es @[.=Var_Set()]@[.=Var_Get()] Var_Set(Object variable, Object value); Var_Get(Object variable) Var_Is_True(Object variable) .Ee must be used instead to assign a value to the variable and to read its current value; the first argument to each function is the \f2Object\fP whose address was passed to \f2Define_Variable()\fP. \f2Var_Is_True()\fP is convenient for boolean variables and tests whether the contents of the variable is true in the sense of \f2Truep()\fP. As an example, Figure @(defvar) shows how the @[.Xt extension] defines a Scheme variable that is associated with the user-defined ``warning handler'' called by the Xt library to output warning messages. .Fs Object V_Xt_Warning_Handler; .El void Xt_Warning(char *msg) { Object args, fun; .El args = Cons(Make_String(msg, strlen(msg)), Null); fun = Var_Get(V_Xt_Warning_Handler); if (TYPE(fun) == T_Compound) (void)Funcall(fun, args, 0); else Printf(Curr_Output_Port, "%s\en", msg); } .El void elk_init_xt_error(void) { Define_Variable(&V_Xt_Warning_Handler, "xt-warning-handler", Null); XtSetWarningHandler(Xt_Warning); } .Fc "The Xt extension defines a Scheme variable holding a ``warning handler''" .Fe defvar .PP In the example in Figure @(defvar), the function \f2Xt_Warning()\fP is registered as the Xt ``warning handler'' by passing it to \f2XtSetWarningHandler()\fP. It is invoked by Xt with a warning message. The message is converted to a Scheme string, and, if the Scheme variable \f2xt-warning-handler\fP has been assigned a procedure, this procedure is called with the string using @[.\f2Funcall()\fP]. Otherwise the string is just sent to the current output port. The call to \f2Define_Variable()\fP in the extension initialization function associates the Scheme variable \f2xt-warning-handler\fP with the C variable \f2V_Xt_Warning_Handler\fP (as a convention, Elk uses the prefix ``V_'' for variables of this kind). .\" --------------------------------------------------------------------------- .K2 "Defining Readers" .PP In addition or as an alternative to the constructor primitive for a new Scheme type, applications and extensions may define a @[.\f2reader\fP function] for each new type. The @[.bitstring extension], for example, defines a reader to allow input of bitstring literals using the \f2#*10110001\fP syntax. Each user-defined read syntax is introduced by the `#' symbol followed by one more character, identifying the type of the object. To define a reader, the following function is called (typically from within an @[.extension initialization function]): .Es @[.=Define_Reader()] void Define_Reader(int c, (Object (*func)(Object port, int c, int const_flag))); .Ee .PP The arguments to \f2Define_Reader()\fP are the as yet unused character identifying the type (e.\|g.\& `*' for bitstrings) and a pointer to a \f2reader function\fP that is invoked by the Scheme parser whenever the newly defined syntax is encountered. This reader function is passed a Scheme input port from which it reads the next token, the character following the `#' symbol (to facilitate using the same reader for different types), and a flag indicating whether the newly-created object is expected to be made read-only (this is true when expressions are loaded from a file). The reader function must return a new object of the given type. .PP You may want to refer to the bitstring extension included in the Elk distribution for an example definition of a reader function (``lib/misc/bitstring.c''), and for the macros that can be used by reader functions to efficiently read characters from a port. .\" --------------------------------------------------------------------------- .K2 "Fork Handlers" .PP Extensions may need to be notified when a copy of the running interpreter (or application) is created by means of the \f2fork()\fP UNIX system call. For example, consider an extension that stores information in a temporary file and removes this file on termination of the program. If another extension created a copy of the running interpreter by calling \f2fork()\fP, the child process would remove the temporary file on exit\*-the file would not be available to the original instance of the interpreter (i.\|e.\& the parent process) any longer. To prevent premature removal of the file, the extension that owns it can define a @[.\f2fork handler\fP] by calling @[.\f2Register_Onfork()\fP] with a pointer to a C function: .Es void Register_Onfork((void (*func)(void))); .Ee The function could create an additional link to the file, so that a child process would just remove this link on exit, leaving the original link intact. .PP Extensions that use \f2fork()\fP without executing a new program in the child process (e.\|g.\& the @[.UNIX extension] which defines a \f2unix-fork\fP primitive) are required to call the function @[.\f2Call_Onfork()\fP] in the newly created child process to invoke all currently defined fork handlers: .Es void Call_Onfork(void); .Ee .\" --------------------------------------------------------------------------- .AP "Appendix A: Functions that can Trigger a Garbage Collection" .PP This appendix lists the functions exported by Elk that may trigger a @[.garbage collection]. Within C/C++ code, local Scheme objects must be protected as shown in section @(ch-gc) when one of these functions is called during the objects' lifetime. .PP The C functions corresponding to the following Scheme primitives can cause a garbage collection: .Es append load read-string apply macro-body require autoload macro-expand reverse backtrace-list make-list string call-with-input-file make-string string->list call-with-output-file make-vector string->number call/cc map string->symbol command-line-args oblist string-append cons open-input-file string-copy dump open-input-output-file substring dynamic-wind open-input-string symbol-plist eval open-output-file tilde-expand for-each open-output-string type force port-line-number vector get-output-string procedure-lambda vector->list list provide vector-copy list->string put with-input-from-file list->vector read with-output-to-file .El .ft 2 all special forms all mathematical primitives except predicates all output primitives if output is sent to a string port .ft .Ee .PP In practice, most of these functions, in particular the special forms, are rarely or never used in extensions or Elk-based applications. In addition to these primitives, the following C functions can trigger a garbage collection: .Es Alloc_Object() Make_Reduced_Flonum() Make_String() Make_Port() Make_Flonum() Make_Const_String() Load_Source_Port() Define_Primitive() Intern() Load_File() Printf() CI_Intern() Copy_List() Print_Object() Define_Variable() Const_Cons() General_Print_Object() Define_Symbol() Make_Integer() Format() Bits_To_Symbols() Make_Unsigned() Eval() Make_Vector() Make_Long() Funcall() Make_Const_Vector() Make_Unsigned_Long() .Ee .LP Note: \f2Make_Integer()\fP, \f2Make_Unsigned()\fP, \f2Make_Long()\fP, and \f2Make_Unsigned_Long()\fP can only trigger a garbage collection if \f2FIXNUM_FITS()\fP (or \f2UFIXNUM_FITS()\fP, respectively) returns zero for the given argument. .\" --------------------------------------------------------------------------- .AP "Appendix B: Convenience Functions for GC-Safe Data Structures" .PP Figure @(gcroot) shows the source code for a set of functions to insert Scheme objects into a vector that has been registered with the garbage collector, to delete objects from the vector, and to retrieve the object stored under a given vector index. These functions help building dynamic data structures (such as linked lists or hash tables) containing Scheme objects. There is nothing application-specific in the code; if you find it useful, you can directly include it in your Elk extension or Elk-based application without any changes. See section @(ch-gcglobal) for a detailed description. .Fs nofloat static int max_objects = 32; /* initial size */ static int num_objects; static Object objects; static int inx; .El int register_object(Object x) { Object v; int n; GC_Node; .El if (num_objects == max_objects) { max_objects *= 2; GC_Link(x); v = Make_Vector(max_objects, Null); GC_Unlink; memcpy(VECTOR(v)->data, VECTOR(objects)->data, num_objects * sizeof(Object)); objects = v; inx = num_objects; } for (n = 0; !Nullp(VECTOR(objects)->data[inx]); inx++, inx %= max_objects) { n++; assert(n < max_objects); } VECTOR(objects)->data[inx] = x; num_objects++; return inx; } .El void deregister_object(int i) { VECTOR(objects)->data[i] = Null; --num_objects; assert(num_objects >= 0); } .El Object get_object(int i) { return VECTOR(objects)->data[i]; } .El void elk_init_gcroot(void) { objects = Make_Vector(max_objects, Null); Global_GC_Link(objects); } .Fc "Functions to map Scheme objects to indexes into a GC-safe vector" .Fe gcroot .\" --------------------------------------------------------------------------- .AP "Appendix C: Summary of Functions, Macros, Types, and Variables" .PP This appendix provides a quick overview of the functions and other definitions exported by the Elk kernel. The list is divided in groups of definitions with related functionality; the entries are presented in roughly the same order in which they are introduced in the above chapters. Full function prototypes are given for functions; in some prototypes, arguments are given names for clarification. The initial keywords \f3function\fP, \f3macro\fP, \f3typedef\fP, and \f3variable\fP indicate the type of each entry (function, preprocessor symbol with or without arguments, type definition, and external variable defined by Elk, respectively). The functions corresponding to Scheme primitives (as described in section @(ch-prims)) have been omitted from the list. .SH Accessing the Scheme Object Representation .LP .Cs \f3typedef\fP Object .Cl \f3macro\fP TYPE(obj) \f3macro\fP POINTER(obj) \f3macro\fP ISCONST(obj) \f3macro\fP SETCONST(obj) \f3macro\fP SET(obj, type, ptr) \f3macro\fP EQ(obj1, obj2) .Ce .SH Defining Scheme Primitives .LP .Cs \f3function\fP void Define_Primitive((Object (*func)()), const char *name, int minargs, int maxargs, enum discipline disc); .Ce .SH Making Objects Known to the Garbage Collector .LP .Cs \f3macro\fP GC_Node, GC_Node2, ... \f3macro\fP GC_Link(obj), GC_Link2(obj1, obj2), ... \f3macro\fP GC_Unlink \f3macro\fP Global_GC_Link(obj) \f3function\fP void Func_Global_GC_Link(obj_ptr); .Ce .SH Booleans .LP .Cs \f3macro\fP T_Boolean \f3macro\fP Truep(obj) .Cl \f3variable\fP Object True \f3variable\fP Object False .Cl \f3function\fP int Eqv(Object, Object); \f3function\fP int Equal(Object, Object); .Ce .SH Characters .LP .Cs \f3macro\fP T_Character \f3macro\fP CHAR(char_obj) \f3function\fP Object Make_Char(int); \f3variable\fP Object Newline .Ce .SH Pairs and Lists .LP .Cs \f3macro\fP T_Null \f3macro\fP Nullp(obj) \f3variable\fP Null .Cl \f3macro\fP T_Pair \f3macro\fP PAIR(pair_obj) \f3macro\fP Car(obj) \f3macro\fP Cdr(obj) \f3macro\fP Cons(obj1, obj2) .Cl \f3macro\fP Check_List(obj) \f3function\fP int Fast_Length(Object); \f3function\fP Object Copy_List(Object); .Ce .SH Integers (Fixnums and Bignums) .LP .Cs \f3macro\fP T_Fixnum \f3macro\fP T_Bignum \f3macro\fP FIXNUM_FITS(integer) \f3macro\fP UFIXNUM_FITS(unsigned_integer) \f3macro\fP FIXNUM(fixnum_obj) \f3macro\fP BIGNUM(bignum_obj) .Cl \f3macro\fP Check_Integer(obj) \f3macro\fP Check_Number(obj) .Cl \f3function\fP Object Make_Integer(int); \f3function\fP Object Make_Unsigned(unsigned); \f3function\fP Object Make_Long(long); \f3function\fP Object Make_Unsigned_Long(unsigned long); .Cl \f3function\fP int Get_Integer(Object); \f3function\fP unsigned Get_Unsigned(Object); \f3function\fP long Get_Long(Object); \f3function\fP unsigned long Get_Unsigned_Long(Object); .Cl \f3function\fP int Get_Exact_Integer(Object); \f3function\fP unsigned Get_Exact_Unsigned(Object); \f3function\fP long Get_Exact_Long(Object); \f3function\fP unsigned long Get_Exact_Unsigned_Long(Object); .Ce .SH Floating Point Numbers (Reals) .LP .Cs \f3macro\fP T_Flonum \f3macro\fP FLONUM(flonum_obj) \f3function\fP Object Make_Flonum(double); \f3function\fP Object Make_Reduced_Flonum(double); \f3function\fP double Get_Double(Object); .Ce .SH Symbols .LP .Cs \f3macro\fP T_Symbol \f3macro\fP SYMBOL(symbol_obj) \f3function\fP Object Intern(const char *); \f3function\fP Object CI_Intern(const char *); \f3function\fP void Define_Symbol(Object *var, const char *name); \f3variable\fP Object Void .Cl \f3typedef\fP SYMDESCR \f3function\fP unsigned long Symbols_To_Bits(Object syms, int mask_flag, SYMDESCR *table); \f3function\fP Object Bits_To_Symbols(unsigned long bits, int mask_flag, SYMDESCR *table); .Ce .SH Strings .LP .Cs \f3macro\fP T_String \f3macro\fP STRING(string_obj) \f3function\fP Object Make_String(const char *init, int size); \f3function\fP char *Get_String(Object); \f3function\fP char *Get_Strsym(Object); \f3macro\fP Get_String_Stack(obj, char_ptr) \f3macro\fP Get_Strsym_Stack(obj, char_ptr) .Ce .SH Vectors .LP .Cs \f3macro\fP T_Vector \f3macro\fP VECTOR(vector_obj) \f3function\fP Object Make_Vector(int size, Object fill); .Ce .SH Ports .LP .Cs \f3macro\fP T_Port \f3macro\fP PORT(port_obj) \f3function\fP Object Make_Port(int flags, FILE *f, Object name); \f3function\fP Object Terminate_File(Object port); \f3macro\fP Check_Input_Port(obj) \f3macro\fP Check_Output_Port(obj) \f3variable\fP Object Curr_Input_Port, Curr_Output_Port \f3variable\fP Object Standard_Input_Port, Standard_Output_Port \f3function\fP void Reset_IO(int destructive_flag); \f3function\fP void Printf(Object port, char *fmt, ...); \f3function\fP void Print_Object(Object obj, Object port, int raw_flag, int print_depth, int print_length); \f3macro\fP Print(obj) \f3function\fP void Load_Source_Port(Object port); \f3function\fP void Load_File(char *filename); .Ce .SH Miscellaneous Types .LP .Cs \f3macro\fP T_End_Of_File \f3variable\fP Object Eof .Cl \f3macro\fP T_Environment \f3variable\fP Object The_Environment, Global_Environment .Cl \f3macro\fP T_Primitive \f3macro\fP T_Compound \f3function\fP void Check_Procedure(Object); .Cl \f3macro\fP T_Control_Point \f3macro\fP T_Promise \f3macro\fP T_Macro .Ce .SH Defining Scheme Types and Allocating Objects .LP .Cs \f3function\fP int Define_Type(int zero, const char *name, int (*size)(Object), int const_size, int (*eqv)(Object, Object), int (*equal)(Object, Object), int (*print)(Object, Object, int, int, int), int (*visit)(Object*, int (*)(Object*))); \f3function\fP Object Alloc_Object(int size, int type, int const_flag); .Ce .SH Calling Scheme Procedures and Evaluating Scheme Code .LP .Cs \f3function\fP Object Funcall(Object fun, Object argl, int eval_flag); \f3function\fP Object Eval(Object expr); \f3function\fP char *String_Eval(char *expr); .Ce .SH Weak Pointers and Object Termination .LP .Cs \f3function\fP void Register_Before_GC((void (*func)(void))); \f3function\fP void Register_After_GC((void (*func)(void))); .Cl \f3macro\fP IS_ALIVE(obj) \f3macro\fP WAS_FORWARDED(obj) \f3macro\fP UPDATE_OBJ(obj) .Cl \f3function\fP void Register_Object(Object obj, char *group, (Object (*term)(Object)), int leader_flag); \f3function\fP void Deregister_Object(Object obj); \f3function\fP void Terminate_Type(int type); \f3function\fP void Terminate_Group(char *group); \f3function\fP Object Find_Object(int type, char *group, (int (*match_func)(Object, ...)), ...); .Ce .SH Signaling Errors .LP .Cs \f3function\fP void Primitive_Error(char *fmt, ...); \f3function\fP void Set_Error_Tag(const char *tag); \f3function\fP char *Get_Error_Tag(void); \f3function\fP void Set_App_Name(char *name); \f3function\fP void Range_Error(Object offending_obj); \f3function\fP void Wrong_Type(Object offending_obj, int expected_type); \f3function\fP void Wrong_Type_Combination(Object offending_obj, char *expected_type); \f3function\fP void Fatal_Error(char *fmt, ...); \f3function\fP void Panic(char *msg); \f3variable\fP int Saved_Errno .Ce .SH Exceptions (Signals) .LP .Cs \f3macro\fP Disable_Interrupts, Enable_Interrupts \f3macro\fP Force_Disable_Interrupts, Force_Enable_Interrupts \f3function\fP void Signal_Exit(int signal_number); .Ce .SH Defining and Using Scheme Variables .LP .Cs \f3function\fP void Define_Variable(Object *var, const char *name, Object init); \f3function\fP void Var_Set(Object var, Object val); \f3function\fP Object Var_Get(Object var); \f3function\fP int Var_Is_True(Object var); .Ce .SH Defining Reader Functions .LP .Cs \f3function\fP void Define_Reader(int c, (Object (*func)(Object port, int c, int const_flag))); .Ce .SH Fork Handlers .LP .Cs \f3function\fP void Register_Onfork((void (*func)(void))); \f3function\fP void Call_Onfork(void); .Ce .SH Allocating Memory .LP .Cs \f3function\fP char *Safe_Malloc(unsigned size); \f3function\fP char *Safe_Realloc(char *old_pointer, unsigned size); .Cl \f3macro\fP Alloca_Begin, Alloca_End \f3macro\fP Alloca(char_ptr, type, size) .Ce .SH Initializing Elk from an Application's main() .LP .Cs \f3function\fP void Elk_Init(int argc, char **argv, int init_flag, char *filename); .Ce .SH Miscellaneous Macros .LP .Cs \f3macro\fP ELK_MAJOR, ELK_MINOR \f3macro\fP NO_PROTOTYPES, WANT_PROTOTYPES .Ce .\" --------------------------------------------------------------------------- .\" XXX: dynamic loading + dump .\" --------------------------------------------------------------------------- .if !\n(.U .so ../util/tmac.index .if !\n(.U .so side.inx .Tc