3.10 Saving and Restoring Program States

Once a program has been read, the system will have available all the information necessary for its execution. This information is called a program state.

The saved state of a program may be saved on disk for future execution. To save a program into a file File, type the following query.

| ?- save_program(File).

You can also specify a goal to be run when a saved program is restored. This is done by:

| ?- save_program(File, start).

where start/0 is the predicate to be called.

Under UNIX, e.g. like macOS or Linux, a saved state file can be executed directly by typing:

% file argument…

This is equivalent to:

% sicstus -r file -- argument…

Please note: saved states do not store the complete path of the binary sicstus. Instead, they call the main executable using the version specific name sicstus-4.9.0, which is assumed to be found in the shell’s path. If there are several versions of SICStus installed, then it is up to the user to make sure that the correct start-script is found.

Notice that the flags are not available when executing saved states—all the command-line arguments are treated as Prolog arguments.

Once a program has been saved into a file File, the following query will restore the system to the saved state:

| ?- restore(File).

If a saved state has been moved or copied to another machine, or if it is a symbolic link, then the path names of foreign resources and other files needed upon restore are typically different at restore time from their save time values. To solve this problem, certain atoms will be renamed during restore as follows:

• Atoms that had $SP_PATH/library (the name of the directory containing the Prolog Library) as prefix at save time will have that prefix replaced by the corresponding restore time value.
• Atoms that had the name of the directory containing File as prefix at save time will have that prefix replaced by the corresponding restore time value.

The purpose of this procedure is to be able to build and deploy an application consisting of a saved state and other files as a directory tree with the saved state at the root: as long as the other files maintain their relative position in the deployed copy, they can still be found upon restore. See Building for a Target Machine for an example.

Please note: When creating a saved state with save_program/[1,2], the names and paths of foreign resources, are included in the saved state. After restoring a saved state, this information is used to reload the foreign resources again.

The state of the foreign resource in terms of global C variables and allocated memory is thus not preserved. Foreign resources may define init and deinit functions to take special action upon loading and unloading; see Init and Deinit Functions.

Partial saved states corresponding to a set of source files, modules, and predicates can be created by the built-in predicates save_files/2, save_modules/2, and save_predicates/2 respectively. These predicates create files in a binary format, by default with the suffix ‘.po’ (for Prolog object), which can be loaded by load_files/[1,2]. In fact, PO files use exactly the same binary format as saved states, and are subject to the same above-mentioned atom renaming rules. For example, to compile a program split into several source files into a single PO file, type:

| ?- compile(Files), save_files(Files, Object).

For each filename given, the first goal will try to locate a source file and compile it into memory. The second goal will save the program just compiled into a PO file whose default suffix is ‘.po’. Thus the PO file will contain a partial memory image.

Please note: PO files can be created with any suffix, but cannot be loaded unless the suffix is ‘.po’!