Saved-States

Saved-states are just a special case of QOF files. The save_program/[1,2] predicate will save the entire Prolog database into a QOF file, and then in addition will make that QOF file executable. Under UNIX, the QOF file is made executable by making the first line of the file be a sh(1) script. This script runs the executable that the QOF file was saved from, telling it to load the QOF file.

So, if a saved-state is created as follows:

     | ?- save_program(savedstate).
     

then if we look at the first line of the file we will see something like the following. Note that +L is a Prolog command line option to load a QOF file ($0 will be the name of the QOF file and $* will be any other arguments given when it is run).

     % head -1 savedstate
     exec /usr/local/quintus/bin3.5/sun4-5/prolog +L $0 $*
     

This QOF file can then be run from the command line as follows:

     % savedstate
     

In addition to the user's code from the Prolog database, a saved-state saved by save_program/[1,2] also contains Prolog system information such as flag settings, debugging information and so forth. When the saved-state is loaded this system state is also restored, which is convenient for continued development.

Apart from being made executable, and containing additional Prolog system information, a saved-state saved through save_program/[1,2] is just a standard QOF file. This means that it can be used anywhere you would otherwise use a QOF file, for such things as loading into Prolog, linking together with other QOF files, and linking into executables (see sap-srs for information on these linking capabilities).

A saved-state, or any QOF file, can be restored using the restore/1 predicate from within Prolog:

     | ?- restore(savedstate).
     

The restore/1 predicate will re-execute the running executable (using the execv(3) system call) in order to obtain a completely new environment, and will then load the QOF file. If the QOF file was saved with save_program/[1,2] then this will restore exactly the same Prolog database state as when the saved-state was saved. In runtime systems, however, it is the application program's responsibility to load the file into the restarted executable, see mpg-ref-restore and sap-srs-sqf.

Note that the executable that will be re-executed by restore/1 is the one currently running. This may be different from the one named in the first line in the QOF file, if that QOF file was saved from some different executable. To use the executable that originally saved the QOF file you should return to the command interpreter and run the QOF file directly. To use the executable you are currently running, you should use restore/1.

If the loaded QOF file has object file dependencies then those object files will be re-linked and re-loaded as part of loading the QOF file. If the object file cannot be found or linked, then an exception will be raised. Similarly, QOF dependencies are also reloaded at this point.

Windows caveat:

Under Windows, it is not possible to replace a running executable with another. Under Windows, restore/1 will instead start a new sub-process and then terminate the running process. For more details see the Microsoft documentation for execv().

In a Windows command prompt window, the command interpreter does not wait when a process executes an execv() library call. Thus after restore/1, the program gives the appearance of running in the background.

Please note: The QOF file saved by save_program/2 does not contain any of the Prolog code that is statically linked into the executable. Only the Prolog database (both compiled and dynamic) that has been built since the executable started running is saved. This is done to avoid code duplication in the saved-state. However, this does mean that if the QOF-file is loaded into a different executable, then the program may be missing some code that it assumes should be there, because it was present in the original executable. An example would be a saved-state that was saved from an executable containing Quintus' ProWINDOWS add-on product. If that saved-state is loaded into a normal Prolog executable without ProWINDOWS then any calls to ProWINDOWS will not work (they will generate undefined predicate exceptions). The correct thing to do is clearly to make sure that you use either the original executable, or an executable that contains the necessary programs, or you load the necessary programs in addition to loading the saved-state QOF file.

The save_program/2 predicate can be used to specify an initial goal that will be run when the saved-state is re-loaded. This usage of save_program/2 replaces the most common uses of the old save/[1,2] predicates that are no longer available. For example:

     | ?- save_program(saved_state,initial_goal([a,b,c])).
     

When saved_state is loaded initial_goal/1 will be called. This allows saved-states to be generated that will immediately start running the user's program when they are executed. In addition to this save_program/2 facility there is also a comprehensive facility for programs to set up initializations to be run when they are loaded or otherwise started. This is described below in ref-sls-igs.