Suspending and resuming heap images
===================================

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 Image-building commands, 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.

 -- procedure: write-image filename startup-proc message returns unspecified
     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.

System initialization
---------------------

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.

 -- 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 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 Records, record-types structure.

Manual system initialization
----------------------------

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, (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.) 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.