Quintus Prolog

`restore/1`

Synopsis

restore(+FileSpec)

Restores a saved-state.

Arguments

FileSpec file_spec: The name of a QOF file.

Description

restore(file) terminates the currently running executable and restarts it with the command line arguments +L file old args where old args are the arguments specified when the executable was started. file is normally a file previously created by a call to save_program, but it can be any QOF file. The +L option causes file to be loaded into the executable as it starts up.

If file was created by save_program/[1,2], then it includes information about operator declarations, debugging and advice information, Prolog flags, and file_search_path and library_directory tables, as well as the Prolog code that was saved. Thus restoring file will create the same Prolog state and database that existed at the time the save_program was done (assuming that the same executable that was used for the save_program is used for the restore).

It is also possible to give any QOF file to restore/1. In this case, the running executable is reinitialized, and then the QOF file is reloaded into the system. As such QOF files store no state information, the state is the same as in a freshly started Prolog system.

It is not normally useful to use restore/1 in a runtime system. In a runtime system, command-line arguments are not interpreted by the system, so the re-started runtime system will just begin again at runtime_entry(start) and will not load the specified file automatically. An application could, if the programmer so chose, pick up the arguments with unix(argv(L)), and then take some appropriate action. For example:

     runtime_entry(start) :-
         unix(argv(['+L',File|_])),
         !,
         load_files(File),
         start_after_restore.
     runtime_entry(start) :-
         normal_start.

See ref-pro-arg and too-too-prolog for a description of the +L option.

Exceptions

instantiation_error: FileSpec is not bound.
type_error: FileSpec is not a valid file specification.
domain_error: FileSpec is not a QOF file.
permission_error: FileSpec is not readable

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.

restore/1