<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<title>The PolyML.SaveState structure</title>
</head>
<body bgcolor="#FFFFFF">
<h2><font face="Arial"><strong>PolyML.SaveState structure</strong></font></h2>
<p>The PolyML.SaveState structure provides a way for a program to save changes
without the expense of exporting and building a new executable. Unlike the PolyML.export
function which saves the complete state it is possible with the functions in
this structure to save just the modifications. In addition it avoids the need
for a linker which is needed to turn an exported object file into an executable.
Because only the modifications are saved a saved state can only be loaded into
the executable that created it.</p>
<PRE><STRONG>structure</STRONG> SaveState:
<STRONG>sig</STRONG>
<strong>val</strong> saveState : string -> unit
<strong>val</strong> loadState : string -> unit
<strong>val</strong> saveChild : string * int -> unit
<strong>val</strong> renameParent : {child: string, newParent: string} -> unit
<strong>val</strong> showHierarchy : unit -> string list
<strong>val</strong> showParent : string -> string option
<strong>end</strong></PRE>
<h3><font face="Arial, Helvetica, sans-serif">Simple Saved State</font></h3>
<p>For many purposes the simple saved state is sufficient. This is created with
saveState and loaded with loadState.</p>
<PRE><STRONG>val</STRONG> saveState : string -> unit</PRE>
<BLOCKQUOTE STYLE="margin-bottom: 0cm"> Saves the current state to a file whose
name is given as the argument. It saves the current values of all the mutable
data (i.e. refs and arrays) that were present in the executable together with
any other data that is now reachable from it</BLOCKQUOTE>
<PRE STYLE="margin-bottom: 0.5cm"><STRONG>val</STRONG> loadState : string -> unit</PRE>
<BLOCKQUOTE STYLE="margin-bottom: 0cm">
<p>Loads a saved state file. This overwrites any changes made before the load
with the contents of the load file. It does not affect mutables created since
the session began nor does it affect function arguments or local variables.</p>
</BLOCKQUOTE>
<h3><font face="Arial, Helvetica, sans-serif">Hierarchical Saved States</font></h3>
<p>The single level saved state created by saveState contains all the data that
is accessible by the program apart from immutable data present in the executable.
Hierarchical saved states extend this idea by allowing a program to save only
the data that is not present in a previously loaded state. Saving a state that
contains only the new data creates a "<em>child</em>" of the existing
saved state which is the "<em>parent</em>". When the child is loaded
in a new session the parent must also be loaded in order to provide the full
state. Since the parent may itself be a child of another saved state this forms
a chain of related saved states. A particular parent may have several children
depending on it. When loadState is called with a file name that refers to a
child saved state it automatically loads the parents using information held
in each file.</p>
<p>The run-time system retains information about the last file that was loaded
or saved and its parents. The information is updated whenever loadState, saveState
or saveChild are called.</p>
<PRE STYLE="margin-bottom: 0.5cm"><strong>val</strong> showHierarchy : unit -> string list</PRE>
<BLOCKQUOTE STYLE="margin-bottom: 0cm">
<p>Returns a list of the file names in the current hierarchy. The first item
in the list is the top-most saved state, the next is the immediate child of
that state and so on. The last item will be the file name that was actually
given as argument to loadState, saveState or saveChild.</p>
</BLOCKQUOTE>
<PRE STYLE="margin-bottom: 0.5cm"><STRONG>val</STRONG> saveChild : string * int -> unit</PRE>
<BLOCKQUOTE STYLE="margin-bottom: 0cm">
<p>saveChild (f, n) writes out a saved state to file name f at hierarchy level
n. n may be between zero and the current hierarchy level, inclusive. saveState(f)
is equivalent to saveChild(f, 0). Typically, saveChild will be called with
a new file name and a value for n which is the length of the current hierarchy
list. This will make a new child which contains only the information added
since the last call to loadState, saveState or saveChild. However, it is possible
to use a different value and this will cause the saved state to include data
from other saved states of the same or deeper hierarchy.</p>
</BLOCKQUOTE>
<PRE STYLE="margin-bottom: 0.5cm"><strong>val</strong> renameParent : {child: string, newParent: string} -> unit
<strong>val</strong> showParent : string -> string option</PRE>
<BLOCKQUOTE STYLE="margin-bottom: 0cm">
<p>A child saved state contains the file name of its parent so that when the
child is loaded the parent can be loaded automatically. If the parent file
is moved for any reason renameParent can be used to modify the parent file
name held in a child so that it can be loaded from the new location. showParent
returns the current value of the parent file name for a child saved state.
If the saved state has no parent showParent returns NONE.</p>
</BLOCKQUOTE>
<h3><font face="Arial, Helvetica, sans-serif">Comparison with the Persistent Store</font></h3>
<p>The persistent store of earlier versions of Poly/ML was similar to this in
that the <font face="Courier New, Courier, mono"><strong>commit</strong></font>
function saved only the changes back to the database. There was also a <font FACE="Courier" SIZE="3"><b>make_database</b></font>
function that created a child database that contained only the changes from
the parent. There are a number of differences. A saved state is read and written
as a whole and is not locked once it has been read. As a rough equivalent commit
and make_database can be written as</p>
<PRE><STRONG>fun</STRONG> commit() =
<strong>let val</strong> h = PolyML.SaveState.showHierarchy()
<strong>in</strong> saveChild(List.last h, length h - 1) <strong>end</strong>
<strong>and</strong> make_database f =
<strong>let val</strong> h = PolyML.SaveState.showHierarchy()
<strong>in</strong> saveChild(f, length h) <strong>end</strong>
</PRE>
<p>The definition of commit assumes that a saved state has already been loaded
and will fail if it has not.</p>
<p> </p>
</body>
</html>
