signature PICKLE structure Pickle : PICKLE
The Pickle structure provides functionality for pickling and unpickling arbitrary values and modules. A pickle is a serialized and closed representation of a (higher-order) value, stored in a file. Pickles can be used to exchange arbitrary data structures or even complete abstract type implementations between processes.
Pickles do not contain any futures. Instead, pickling requests all futures contained in the closure of the value.
Pickles may contain stateful values, like references or arrays. Pickling a stateful data structure implies a copying semantics: each time the value is unpickled, a fresh copy of all contained stateful values will be created. Sharing between stateful object is maintained inside a pickle, though.
A pickle may not contain local resources, so-called sited values (e.g. streams associated with files, first-class threads, or functions or modules containing creating such values). Any attempt to pickle a value whose closure contains sited values will result in an Io exception being raised, with the exception Sited indicating the cause.
Pickling is performed concurrently. The order in which values included in the pickle are visited is non-deterministic.
For more background, see the overview of pickling.
See also: Sited, Package, Component, Future
signature PICKLE = sig exception Sited exception Corrupt val extension : string val save : string * package -> unit val load : string -> package functor Save (val file : string signature S structure X : S) : any functor Load (val file : string signature S) : S functor SaveVal (val file : string type t val x : t) : any functor LoadVal (val file : string type t) : (val x : t) end
used by the save operation to indicate that the argument contains sited data structures. This exception is not raised directly; it only appears as the cause of an IO.Io exception. Equal to Component.Sited.
used by the load operation to indicate that pickle file does have an invalid format. This exception is never raised directly; it only appears as the cause of an IO.Io exception. Equal to Component.Corrupt.
The default file name extension used for pickle files on the host system. Equal to Component.extension.
Saves package to the file named name. Synchronizes on all futures contained in (the closure of) the package. Raises IO.Io if writing the pickle fails. Particular causes for failure may be that package refers to sited values.
Component.save (name, Component.fromPackage package)
Loads a package from the file denoted by the URI name. The pickle is located and loaded as a component, via the function Component.load. Raises IO.Io if reading or evaluating the component fails. Particular causes for failure may be that file is corrupt, i.e. not a valid pickle file. This is indicated by the exception Component.Corrupt. Raises Component.Failure if the pickle is an unevaluated component whose evaluation fails.
ComponentManager.eval (url, Component.load url)
where url = Url.fromString name.
Creates a package of module X under signature S and writes it to the file named name, as with save. Equivalent to
save (name, pack X : S)
Reads a package from the file named name, as with load and tries to unpack it under signature S. Raises Package.Mismatch if unpacking fails. Equivalent to
unpack (load file) : S
Similar to Save and Load, but operate on value packages. Equivalent respectively to:
save (name, pack (val x = v) : (val x : t)) unpack (load name) : (val x : t)