<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.20">
<title>MLtonStructure</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<link rel="stylesheet" href="./asciidoctor.css">
<link rel="stylesheet" href="./mlton.css">

</head>
<body class="article">
<div id="mlton-header">
<div id="mlton-header-text">
<h2>
<a href="./Home">
MLton
20241230+git20251029+dfsg-ok1
</a>
</h2>
</div>
</div>
<div id="header">
<h1>MLtonStructure</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>The <code>MLton</code> structure contains a lot of functionality that is not
available in the <a href="BasisLibrary">Basis Library</a>.  As a warning,
please keep in mind that the <code>MLton</code> structure and its
substructures do change from release to release of MLton.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sml">structure MLton:
   sig
      val eq: 'a * 'a -&gt; bool
      val equal: 'a * 'a -&gt; bool
      val hash: 'a -&gt; Word32.word
      val isMLton: bool
      val share: 'a -&gt; unit
      val shareAll: unit -&gt; unit
      val size: 'a -&gt; IntInf.int
      val sizeAll: 'a -&gt; IntInf.int

      structure Array: MLTON_ARRAY
      structure BinIO: MLTON_BIN_IO
      structure CharArray: MLTON_MONO_ARRAY where type t = CharArray.array
                                            where type elem = CharArray.elem
      structure CharVector: MLTON_MONO_VECTOR where type t = CharVector.vector
                                              where type elem = CharVector.elem
      structure Cont: MLTON_CONT
      structure Exn: MLTON_EXN
      structure Finalizable: MLTON_FINALIZABLE
      structure GC: MLTON_GC
      structure IntInf: MLTON_INT_INF
      structure Itimer: MLTON_ITIMER
      structure LargeReal: MLTON_REAL where type t = LargeReal.real
      structure LargeWord: MLTON_WORD where type t = LargeWord.word
      structure Platform: MLTON_PLATFORM
      structure Pointer: MLTON_POINTER
      structure ProcEnv: MLTON_PROC_ENV
      structure Process: MLTON_PROCESS
      structure Profile: MLTON_PROFILE
      structure Random: MLTON_RANDOM
      structure Real: MLTON_REAL where type t = Real.real
      structure Real32: sig
                           include MLTON_REAL
                           val castFromWord: Word32.word -&gt; t
                           val castToWord: t -&gt; Word32.word
                        end where type t = Real32.real
      structure Real64: sig
                           include MLTON_REAL
                           val castFromWord: Word64.word -&gt; t
                           val castToWord: t -&gt; Word64.word
                        end where type t = Real64.real
      structure Rlimit: MLTON_RLIMIT
      structure Rusage: MLTON_RUSAGE
      structure Signal: MLTON_SIGNAL
      structure Syslog: MLTON_SYSLOG
      structure TextIO: MLTON_TEXT_IO
      structure Thread: MLTON_THREAD
      structure Vector: MLTON_VECTOR
      structure Weak: MLTON_WEAK
      structure Word: MLTON_WORD where type t = Word.word
      structure Word8: MLTON_WORD where type t = Word8.word
      structure Word16: MLTON_WORD where type t = Word16.word
      structure Word32: MLTON_WORD where type t = Word32.word
      structure Word64: MLTON_WORD where type t = Word64.word
      structure Word8Array: MLTON_MONO_ARRAY where type t = Word8Array.array
                                             where type elem = Word8Array.elem
      structure Word8Vector: MLTON_MONO_VECTOR where type t = Word8Vector.vector
                                               where type elem = Word8Vector.elem
      structure World: MLTON_WORLD
   end</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_substructures">Substructures</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><a href="MLtonArray">MLtonArray</a></p>
</li>
<li>
<p><a href="MLtonBinIO">MLtonBinIO</a></p>
</li>
<li>
<p><a href="MLtonCont">MLtonCont</a></p>
</li>
<li>
<p><a href="MLtonExn">MLtonExn</a></p>
</li>
<li>
<p><a href="MLtonFinalizable">MLtonFinalizable</a></p>
</li>
<li>
<p><a href="MLtonGC">MLtonGC</a></p>
</li>
<li>
<p><a href="MLtonIntInf">MLtonIntInf</a></p>
</li>
<li>
<p><a href="MLtonIO">MLtonIO</a></p>
</li>
<li>
<p><a href="MLtonItimer">MLtonItimer</a></p>
</li>
<li>
<p><a href="MLtonMonoArray">MLtonMonoArray</a></p>
</li>
<li>
<p><a href="MLtonMonoVector">MLtonMonoVector</a></p>
</li>
<li>
<p><a href="MLtonPlatform">MLtonPlatform</a></p>
</li>
<li>
<p><a href="MLtonPointer">MLtonPointer</a></p>
</li>
<li>
<p><a href="MLtonProcEnv">MLtonProcEnv</a></p>
</li>
<li>
<p><a href="MLtonProcess">MLtonProcess</a></p>
</li>
<li>
<p><a href="MLtonRandom">MLtonRandom</a></p>
</li>
<li>
<p><a href="MLtonReal">MLtonReal</a></p>
</li>
<li>
<p><a href="MLtonRlimit">MLtonRlimit</a></p>
</li>
<li>
<p><a href="MLtonRusage">MLtonRusage</a></p>
</li>
<li>
<p><a href="MLtonSignal">MLtonSignal</a></p>
</li>
<li>
<p><a href="MLtonSyslog">MLtonSyslog</a></p>
</li>
<li>
<p><a href="MLtonTextIO">MLtonTextIO</a></p>
</li>
<li>
<p><a href="MLtonThread">MLtonThread</a></p>
</li>
<li>
<p><a href="MLtonVector">MLtonVector</a></p>
</li>
<li>
<p><a href="MLtonWeak">MLtonWeak</a></p>
</li>
<li>
<p><a href="MLtonWord">MLtonWord</a></p>
</li>
<li>
<p><a href="MLtonWorld">MLtonWorld</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_values">Values</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><code>eq (x, y)</code></p>
<div class="paragraph">
<p>returns true if <code>x</code> and <code>y</code> are equal as pointers.  For simple types
like <code>char</code>, <code>int</code>, and <code>word</code>, this is the same as equals.  For
arrays, datatypes, strings, tuples, and vectors, this is a simple
pointer equality.  The semantics is a bit murky.</p>
</div>
</li>
<li>
<p><code>equal (x, y)</code></p>
<div class="paragraph">
<p>returns true if <code>x</code> and <code>y</code> are structurally equal.  For equality
types, this is the same as <a href="PolymorphicEquality">PolymorphicEquality</a>.  For other types,
it is a conservative approximation of equivalence.</p>
</div>
</li>
<li>
<p><code>hash x</code></p>
<div class="paragraph">
<p>returns a structural hash of <code>x</code>.  The hash function is consistent
between execution of the same program, but may not be consistent
between different programs.</p>
</div>
</li>
<li>
<p><code>isMLton</code></p>
<div class="paragraph">
<p>is always <code>true</code> in a MLton implementation, and is always <code>false</code> in a
stub implementation.</p>
</div>
</li>
<li>
<p><code>share x</code></p>
<div class="paragraph">
<p>maximizes sharing in the heap for the object graph reachable from <code>x</code>.</p>
</div>
</li>
<li>
<p><code>shareAll ()</code></p>
<div class="paragraph">
<p>maximizes sharing in the heap by sharing space for equivalent
immutable objects.  A call to <code>shareAll</code> performs a major garbage
collection, and takes time proportional to the size of the heap.</p>
</div>
</li>
<li>
<p><code>size x</code></p>
<div class="paragraph">
<p>returns the amount of heap space (in bytes) taken by the value of <code>x</code>,
including all objects reachable from <code>x</code> by following pointers.  It
takes time proportional to the size of <code>x</code>.  See below for an example.</p>
</div>
</li>
<li>
<p><code>sizeAll ()</code></p>
<div class="paragraph">
<p>returns the amount of heap space (in bytes) taken by all reachable
live data.  It takes time proportional to the size of live data.</p>
</div>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="size">Example of <code>MLton.size</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>This example, <code>size.sml</code>, demonstrates the application of <code>MLton.size</code>
to many different kinds of objects.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="sml">fun 'a printSize (name: string, value: 'a, use: 'a -&gt; unit): unit=
   (print "The size of "
    ; print name
    ; print " is "
    ; print (IntInf.toString (MLton.size value))
    ; print " bytes.\n"
    ; use value)

fun chk (x, y) =
   if x = y
      then ()
      else raise Fail "bug"

val l = [1, 2, 3, 4]

val _ =
   (printSize ("a char", #"c", fn _ =&gt; ())
    ; printSize ("an int list of length 4",
                 List.tabulate (4, fn i =&gt; i + 1), fn l =&gt;
                 chk (foldl (op +) 0 l, 10))
    ; printSize ("a string of length 10",
                 CharVector.tabulate (10, fn i =&gt; chr (ord #"0" + i)), fn s =&gt;
                 chk (CharVector.foldl (fn (c,s) =&gt; ord c + s) 0 s,  525))
    ; printSize ("an int array of length 10",
                 Array.tabulate (10, fn i =&gt; i), fn a =&gt;
                 chk (Array.foldl (op +) 0 a, 45))
    ; printSize ("a double array of length 10",
                 Array.tabulate (10, real), fn a =&gt;
                 chk (Real.floor (Array.foldl (op +) 0.0 a), 45))
    ; printSize ("an array of length 10 of 2-ples of ints",
                 Array.tabulate (10, fn i =&gt; (i, i + 1)), fn a =&gt;
                 chk (Array.foldl (fn ((a,b),s) =&gt; a + b + s) 0 a, 100))
    ; printSize ("a useless function",
                 fn _ =&gt; 13, fn f =&gt; ())
    )

local
   open MLton.Cont
in
   val rc: int option t option ref = ref NONE
   val _ =
      case callcc (fn k: int option t =&gt; (rc := SOME k; throw (k, NONE))) of
         NONE =&gt; ()
       | SOME i =&gt; print (concat [Int.toString i, "\n"])
end

val _ = printSize ("a continuation option ref",
                   rc, fn rc =&gt;
                   case !rc of
                      NONE =&gt; ()
                    | SOME k =&gt; (rc := NONE; MLton.Cont.throw (k, SOME 13)))</code></pre>
</div>
</div>
<div class="paragraph">
<p>Compile and run as usual.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>% mlton size.sml
% ./size
The size of a char is 0 bytes.
The size of an int list of length 4 is 96 bytes.
The size of a string of length 10 is 40 bytes.
The size of an int array of length 10 is 64 bytes.
The size of a double array of length 10 is 104 bytes.
The size of an array of length 10 of 2-ples of ints is 104 bytes.
The size of a useless function is 0 bytes.
The size of a continuation option ref is 5016 bytes.
13
The size of a continuation option ref is 16 bytes.</pre>
</div>
</div>
<div class="paragraph">
<p>Note that sizes are dependent upon the target platform and compiler
optimizations.</p>
</div>
</div>
</div>
</div>
</body>
</html>