Previous: Records, Up: System facilities
Scheme48's virtual machine operates by loading a heap image into memory
and calling the initialization procedure specified in the image dump.
Heap images can be produced in several different ways: programmatically
with write-image
, using the command processor's facilities, or with the static linker. This
section describes only write-image
and the related system
resumption & initialization.
Heap image dumps begin with a sequence of characters terminated by an
ASCII form-feed/page character (codepoint 12). This content may be
anything; for example, it might be a Unix #!
line that invokes
scheme48vm
on the file, or it might be a silly message to
whomever reads the top of the heap image dump file. (The command
processor's ,dump
& ,build
commands
(see Image-building commands) write a blank line at the top; the
static linker
puts a message stating that the
image was built by the static linker.)
Write-image
is exported by the write-images
structure.
Writes a heap image whose startup procedure is startup-proc and that consists of every object accessible in some way from startup-proc. Message is put at the start of the heap image file before the ASCII form-feed/page character. When the image is resumed, startup-proc is passed a vector of program arguments, an input channel for standard input, an output channel for standard output, an output channel for standard error, and a vector of records to be resumed. This is typically simplified by
usual-resumer
(see below). On Unix, startup-proc must return an integer exit code; otherwise the program will crash and burn with a very low-level VM error message when startup-proc returns.
When suspended heap images are resumed by the VM, the startup procedure
specified in the heap image is applied to five arguments: a vector of
command-line arguments (passed after the -a
argument to the VM),
an input channel for standard input, an output channel for standard
output, an output channel for standard error, and a vector of records
to be resumed. The startup procedure is responsible for performing any
initialization necessary — including initializing the Scheme48
run-time system — as well as simply running the program. Typically,
this procedure is not written manually: resumers are ordinarily created
using the usual resumer abstraction, exported from the structure
usual-resumer
.
This returns a procedure that is suitable as a heap image resumer procedure. When the heap image is resumed, it initializes the run-time system — it resumes all the records, initializes the thread system, the dynamic state, the interrupt system, I/O system, &c. — and applies startup-proc to a list (not a vector) of the command-line arguments.
Some records may contain machine-, OS-, or other session-specific data.
When suspended in heap images and later resumed, this data may be
invalidated, and it may be necessary to reinitialize this data upon
resumption of suspended heap images. For this reason Scheme48 provides
record resumers; see define-record-resumer
from the
record-types
structure.
If a programmer chooses not to use usual-resumer
— which is
not a very common thing to do —, he is responsible for manual
initialization of the run-time system, including the I/O system,
resumption of records, the thread system and the root thread scheduler,
the interrupt system, and the condition system.
Warning: Manual initialization of the run-time system is a very delicate operation. Although one can potentially vastly decrease the size of dumped heap images by doing it manually, 1 it is very error-prone and difficult to do without exercising great care, which is why the usual resumer facility exists. Unless you really know what you are doing, you should just use the usual resumer.
At the present, documentation of manual system initialization is absent. However, if the reader knows enough about what he is doing that he desires to manually initialize the run-time system, he is probably sufficiently familiar with it already to be able to find the necessary information directly from Scheme48's source code and module descriptions.
[1] For example, the author of this manual, merely out of curiosity, compared the sizes of two images: one that used the usual resumer and printed each of its command-line arguments, and one that performed no run-time system initialization — which eliminated the run-time system in the image, because it was untraceable from the resumer — and wrote directly to the standard output channel. The difference was a factor of about twenty. However, also note that the difference is constant; the run-time system happened to account for nineteen twentieths of the larger image.