doc/guide/localhost/MLtonWorld

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta name="generator" content="AsciiDoc 8.6.9">
   6 <title>MLtonWorld</title>
   7 <link rel="stylesheet" href="./asciidoc.css" type="text/css">
   8 <link rel="stylesheet" href="./pygments.css" type="text/css">
   9
  10
  11 <script type="text/javascript" src="./asciidoc.js"></script>
  12 <script type="text/javascript">
  13 /*<![CDATA[*/
  14 asciidoc.install();
  15 /*]]>*/
  16 </script>
  17 <link rel="stylesheet" href="./mlton.css" type="text/css">
  18 </head>
  19 <body class="article">
  20 <div id="banner">
  21 <div id="banner-home">
  22 <a href="./Home">MLton 20180207</a>
  23 </div>
  24 </div>
  25 <div id="header">
  26 <h1>MLtonWorld</h1>
  27 </div>
  28 <div id="content">
  29 <div id="preamble">
  30 <div class="sectionbody">
  31 <div class="listingblock">
  32 <div class="content"><div class="highlight"><pre><span class="k">signature</span><span class="w"> </span><span class="n">MLTON_WORLD</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
  33 <span class="w">   </span><span class="k">sig</span><span class="w"></span>
  34 <span class="w">      </span><span class="k">datatype</span><span class="w"> </span><span class="n">status</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">Clone</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="n">Original</span><span class="w"></span>
  35
  36 <span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">load</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">&#39;a</span><span class="w"></span>
  37 <span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">save</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">status</span><span class="w"></span>
  38 <span class="w">      </span><span class="k">val</span><span class="w"> </span><span class="n">saveThread</span><span class="p">:</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">Thread</span><span class="p">.</span><span class="n">Runnable</span><span class="p">.</span><span class="n">t</span><span class="w"> </span><span class="p">-&gt;</span><span class="w"> </span><span class="n">unit</span><span class="w"></span>
  39 <span class="w">   </span><span class="k">end</span><span class="w"></span>
  40 </pre></div></div></div>
  41 <div class="ulist"><ul>
  42 <li>
  43 <p>
  44 <span class="monospaced">datatype status</span>
  45 </p>
  46 <div class="paragraph"><p>specifies whether a world is original or restarted (a clone).</p></div>
  47 </li>
  48 <li>
  49 <p>
  50 <span class="monospaced">load f</span>
  51 </p>
  52 <div class="paragraph"><p>loads the saved computation from file <span class="monospaced">f</span>.</p></div>
  53 </li>
  54 <li>
  55 <p>
  56 <span class="monospaced">save f</span>
  57 </p>
  58 <div class="paragraph"><p>saves the entire state of the computation to the file <span class="monospaced">f</span>.  The
  59 computation can then be restarted at a later time using <span class="monospaced">World.load</span>
  60 or the <span class="monospaced">load-world</span> <a href="RunTimeOptions">runtime option</a>.  The call to
  61 <span class="monospaced">save</span> in the original computation returns <span class="monospaced">Original</span> and the call in
  62 the restarted world returns <span class="monospaced">Clone</span>.</p></div>
  63 </li>
  64 <li>
  65 <p>
  66 <span class="monospaced">saveThread (f, rt)</span>
  67 </p>
  68 <div class="paragraph"><p>saves the entire state of the computation to the file <span class="monospaced">f</span> that will
  69 resume with thread <span class="monospaced">rt</span> upon restart.</p></div>
  70 </li>
  71 </ul></div>
  72 </div>
  73 </div>
  74 <div class="sect1">
  75 <h2 id="_notes">Notes</h2>
  76 <div class="sectionbody">
  77 <div class="paragraph"><p><a id="ASLR"></a>
  78 Executables that save and load worlds are incompatible with
  79 <a href="http://en.wikipedia.org/wiki/Address_space_layout_randomization">address space layout randomization (ASLR)</a>
  80 of the executable (though, not of shared libraries).  The state of a
  81 computation includes addresses into the code and data segments of the
  82 executable (e.g., static runtime-system data, return addresses); such
  83 addresses are invalid when interpreted by the executable loaded at a
  84 different base address.</p></div>
  85 <div class="paragraph"><p>Executables that save and load worlds should be compiled with an
  86 option to suppress the generation of position-independent executables.</p></div>
  87 <div class="ulist"><ul>
  88 <li>
  89 <p>
  90 <a href="RunningOnDarwin">Darwin 11 (Mac OS X Lion) and higher</a> : <span class="monospaced">-link-opt -fno-PIE</span>
  91 </p>
  92 </li>
  93 </ul></div>
  94 </div>
  95 </div>
  96 <div class="sect1">
  97 <h2 id="_example">Example</h2>
  98 <div class="sectionbody">
  99 <div class="paragraph"><p>Suppose that <span class="monospaced">save-world.sml</span> contains the following.</p></div>
 100 <div class="listingblock">
 101 <div class="content"><div class="highlight"><pre><span class="k">open</span><span class="w"> </span><span class="n">MLton</span><span class="p">.</span><span class="n">World</span><span class="w"></span>
 102
 103 <span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
 104 <span class="w">   </span><span class="k">case</span><span class="w"> </span><span class="n">save</span><span class="w"> </span><span class="s">&quot;world&quot;</span><span class="w"> </span><span class="k">of</span><span class="w"></span>
 105 <span class="w">      </span><span class="n">Original</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="s">&quot;I am the original</span><span class="se">\n</span><span class="s">&quot;</span><span class="w"></span>
 106 <span class="w">    </span><span class="p">|</span><span class="w"> </span><span class="n">Clone</span><span class="w"> </span><span class="p">=&gt;</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="s">&quot;I am the clone</span><span class="se">\n</span><span class="s">&quot;</span><span class="w"></span>
 107 </pre></div></div></div>
 108 <div class="paragraph"><p>Then, if we compile <span class="monospaced">save-world.sml</span> and run it, the <span class="monospaced">Original</span>
 109 branch will execute, and a file named <span class="monospaced">world</span> will be created.</p></div>
 110 <div class="listingblock">
 111 <div class="content monospaced">
 112 <pre>% mlton save-world.sml
 113 % ./save-world
 114 I am the original</pre>
 115 </div></div>
 116 <div class="paragraph"><p>We can then load <span class="monospaced">world</span> using the <span class="monospaced">load-world</span>
 117 <a href="RunTimeOptions">run time option</a>.</p></div>
 118 <div class="listingblock">
 119 <div class="content monospaced">
 120 <pre>% ./save-world @MLton load-world world --
 121 I am the clone</pre>
 122 </div></div>
 123 </div>
 124 </div>
 125 </div>
 126 <div id="footnotes"><hr></div>
 127 <div id="footer">
 128 <div id="footer-text">
 129 </div>
 130 <div id="footer-badges">
 131 </div>
 132 </div>
 133 </body>
 134 </html>