Import Upstream version 20180207

[hcoop/debian/mlton.git] / doc / guide / src / MLtonWorld.adoc

MLtonWorld
==========

[source,sml]
----
signature MLTON_WORLD =
   sig
      datatype status = Clone | Original

      val load: string -> 'a
      val save: string -> status
      val saveThread: string * Thread.Runnable.t -> unit
   end
----

* `datatype status`
+
specifies whether a world is original or restarted (a clone).

* `load f`
+
loads the saved computation from file `f`.

* `save f`
+
saves the entire state of the computation to the file `f`.  The
computation can then be restarted at a later time using `World.load`
or the `load-world` <:RunTimeOptions:runtime option>.  The call to
`save` in the original computation returns `Original` and the call in
the restarted world returns `Clone`.

* `saveThread (f, rt)`
+
saves the entire state of the computation to the file `f` that will
resume with thread `rt` upon restart.


== Notes ==

<!Anchor(ASLR)>
Executables that save and load worlds are incompatible with
http://en.wikipedia.org/wiki/Address_space_layout_randomization[address space layout randomization (ASLR)]
of the executable (though, not of shared libraries).  The state of a
computation includes addresses into the code and data segments of the
executable (e.g., static runtime-system data, return addresses); such
addresses are invalid when interpreted by the executable loaded at a
different base address.

Executables that save and load worlds should be compiled with an
option to suppress the generation of position-independent executables.

* <:RunningOnDarwin:Darwin 11 (Mac OS X Lion) and higher> : `-link-opt -fno-PIE`


== Example ==

Suppose that `save-world.sml` contains the following.
[source,sml]
----
sys::[./bin/InclGitFile.py mlton master doc/examples/save-world/save-world.sml]
----

Then, if we compile `save-world.sml` and run it, the `Original`
branch will execute, and a file named `world` will be created.
----
% mlton save-world.sml
% ./save-world
I am the original
----

We can then load `world` using the `load-world`
<:RunTimeOptions:run time option>.
----
% ./save-world @MLton load-world world --
I am the clone
----