s48-refman/system/image.texi

@node Suspending and resuming heap images
@section Suspending and resuming heap images

@cindex dumping heap images
@cindex heap image dumping
@cindex image dumping
@cindex writing heap images
@cindex heap image writing
@cindex image writing
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 @code{write-image}, using the @embedref{Image-building commands,
command processor's facilities}, or with the static linker.  This
section describes only @code{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 @code{#!} line that invokes
@code{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 @code{,dump} & @code{,build} commands
(@pxref{Image-building commands}) write a blank line at the top; the
static linker
@c @embedref{Static linker, static linker}
puts a message stating that the
image was built by the static linker.)

@stindex write-images
@code{Write-image} is exported by the @code{write-images} structure.

@deffn procedure write-image filename startup-proc message @returns{} unspecified
Writes a heap image whose startup procedure is @var{startup-proc} and
that consists of every object accessible in some way from
@var{startup-proc}.  @var{Message} is put at the start of the heap
image file before the ASCII form-feed/page character.  When the image
is resumed, @var{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 @code{usual-resumer}
(see below).  On Unix, @var{startup-proc} must return an integer exit
code; otherwise the program will crash and burn with a very low-level
VM error message when @var{startup-proc} returns.
@end deffn

@subsection System initialization

@cindex usual resumer
@cindex heap image resumption
@cindex resuming heap images
@stindex usual-resumer
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 @code{-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 @dfn{usual resumer} abstraction, exported from the structure
@code{usual-resumer}.

@deffn procedure usual-resumer startup-proc @returns{} resumer-proc
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, @etc{} --- and
applies @var{startup-proc} to a list (not a vector) of the command-line
arguments.
@end deffn

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
@dfn{record resumers}; see @code{define-record-resumer} from the
@embedref{Records, @code{record-types} structure}.

@subsection Manual system initialization

If a programmer chooses not to use @code{usual-resumer} --- which is
@emph{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.

@strong{Warning:} Manual initialization of the run-time system is a
@emph{very} delicate operation.  Although one can potentially vastly
decrease the size of dumped heap images by doing it manually,
@footnote{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 @emph{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.} it is very error-prone and
difficult to do without exercising great care, which is why the usual
resumer facility exists.  Unless you @emph{@strong{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.