Alice Project

The Pickle structure

________ Synopsis ____________________________________________________

    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

________ Import ______________________________________________________

Imported implicitly.

________ Interface ___________________________________________________

    signature PICKLE =
	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)

________ Description _________________________________________________

exception Sited

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.

exception Corrupt

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.

save (name, package)

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.

Equivalent to: (name, Component.fromPackage package)
load name

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.

Equivalent to:

	ComponentManager.eval (url, Component.load url)

where url = Url.fromString name.

Save (val file = name signature S = S structure X = X)

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)
Load (val file = name signature S = 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
SaveVal (val file = name type t = t val x = v)
LoadVal (val file = name type t = t)

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)

last modified 2007/Mar/30 17:10