doc/guide/src/MLtonWorld.adoc

   1 MLtonWorld
   2 ==========
   3
   4 [source,sml]
   5 ----
   6 signature MLTON_WORLD =
   7    sig
   8       datatype status = Clone | Original
   9
  10       val load: string -> 'a
  11       val save: string -> status
  12       val saveThread: string * Thread.Runnable.t -> unit
  13    end
  14 ----
  15
  16 * `datatype status`
  17 +
  18 specifies whether a world is original or restarted (a clone).
  19
  20 * `load f`
  21 +
  22 loads the saved computation from file `f`.
  23
  24 * `save f`
  25 +
  26 saves the entire state of the computation to the file `f`.  The
  27 computation can then be restarted at a later time using `World.load`
  28 or the `load-world` <:RunTimeOptions:runtime option>.  The call to
  29 `save` in the original computation returns `Original` and the call in
  30 the restarted world returns `Clone`.
  31
  32 * `saveThread (f, rt)`
  33 +
  34 saves the entire state of the computation to the file `f` that will
  35 resume with thread `rt` upon restart.
  36
  37
  38 == Notes ==
  39
  40 <!Anchor(ASLR)>
  41 Executables that save and load worlds are incompatible with
  42 http://en.wikipedia.org/wiki/Address_space_layout_randomization[address space layout randomization (ASLR)]
  43 of the executable (though, not of shared libraries).  The state of a
  44 computation includes addresses into the code and data segments of the
  45 executable (e.g., static runtime-system data, return addresses); such
  46 addresses are invalid when interpreted by the executable loaded at a
  47 different base address.
  48
  49 Executables that save and load worlds should be compiled with an
  50 option to suppress the generation of position-independent executables.
  51
  52 * <:RunningOnDarwin:Darwin 11 (Mac OS X Lion) and higher> : `-link-opt -fno-PIE`
  53
  54
  55 == Example ==
  56
  57 Suppose that `save-world.sml` contains the following.
  58 [source,sml]
  59 ----
  60 sys::[./bin/InclGitFile.py mlton master doc/examples/save-world/save-world.sml]
  61 ----
  62
  63 Then, if we compile `save-world.sml` and run it, the `Original`
  64 branch will execute, and a file named `world` will be created.
  65 ----
  66 % mlton save-world.sml
  67 % ./save-world
  68 I am the original
  69 ----
  70
  71 We can then load `world` using the `load-world`
  72 <:RunTimeOptions:run time option>.
  73 ----
  74 % ./save-world @MLton load-world world --
  75 I am the clone
  76 ----