2.15 Saving a Core Image

A mechanism has been provided to save a running Lisp core image and to later restore it. This is convenient if you don’t want to load several files into a Lisp when you first start it up. The main problem is the large size of each saved Lisp image, typically at least 20 megabytes.

Function: extensions:save-lisp file &key :purify :root-structures :init-function :load-init-file :print-herald :site-init :process-command-line :batch-mode :executable ¶

The save-lisp function saves the state of the currently running Lisp core image in file. The keyword arguments have the following meaning:

:purify

If non-nil (the default), the core image is purified before it is saved (see purify.) This reduces the amount of work the garbage collector must do when the resulting core image is being run. Also, if more than one Lisp is running on the same machine, this maximizes the amount of memory that can be shared between the two processes.

[:root-structures]

This should be a list of the main entry points in any newly loaded systems. This need not be supplied, but locality and/or GC performance will be better if they are. Meaningless if :purify is nil. See purify.

:init-function

This is the function that starts running when the created core file is resumed. The default function simply invokes the top level read-eval-print loop. If the function returns the lisp will exit.

:load-init-file

If non-NIL, then load an init file; either the one specified on the command line or “init.fasl-type”, or, if “init.fasl-type” does not exist, init.lisp from the user’s home directory. If the init file is found, it is loaded into the resumed core file before the read-eval-print loop is entered.

:site-init

If non-NIL, the name of the site init file to quietly load. The default is library:site-init. No error is signalled if the file does not exist.

:print-herald

If non-NIL (the default), then print out the standard Lisp herald when starting.

:process-command-line

If non-NIL (the default), processes the command line switches and performs the appropriate actions.

:batch-mode

If NIL (the default), then the presence of the -batch command-line switch will invoke batch-mode processing upon resuming the saved core. If non-NIL, the produced core will always be in batch-mode, regardless of any command-line switches.

:executable

If non-NIL, an executable image is created. Normally, CMUCL consists of the C runtime along with a core file image. When :executable is non-NIL, the core file is incorporated into the C runtime, so one (large) executable is created instead of a new separate core file.

This feature is only available on some platforms, as indicated by having the feature :executable. Currently only x86 ports and the solaris/sparc port have this feature.

To resume a saved file, type:

lisp -core file

However, if the :executable option was specified, you can just use

  file

since the executable contains the core file within the executable.

Function: extensions:purify file &key :root-structures :environment-name ¶

This function optimizes garbage collection by moving all currently live objects into non-collected storage. Once statically allocated, the objects can never be reclaimed, even if all pointers to them are dropped. This function should generally be called after a large system has been loaded and initialized.

:root-structures

is an optional list of objects which should be copied first to maximize locality. This should be a list of the main entry points for the resulting core image. The purification process tries to localize symbols, functions, etc., in the core image so that paging performance is improved. The default value is NIL which means that Lisp objects will still be localized but probably not as optimally as they could be.

defstruct structures defined with the (:pure t) option are moved into read-only storage, further reducing GC cost. List and vector slots of pure structures are also moved into read-only storage.

:environment-name

is gratuitous documentation for the compacted version of the current global environment (as seen in c::*info-environment*.) If nil is supplied, then environment compaction is inhibited.