= 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

[[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]
----
include::https://raw.github.com/MLton/mlton/master/doc/examples/save-world/save-world.sml[indent=0]
----

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
----
