doc/guide/src/MLtonStructure.adoc

   1 MLtonStructure
   2 ==============
   3
   4 The `MLton` structure contains a lot of functionality that is not
   5 available in the <:BasisLibrary:Basis Library>.  As a warning,
   6 please keep in mind that the `MLton` structure and its
   7 substructures do change from release to release of MLton.
   8
   9 [source,sml]
  10 ----
  11 structure MLton:
  12    sig
  13       val eq: 'a * 'a -> bool
  14       val equal: 'a * 'a -> bool
  15       val hash: 'a -> Word32.word
  16       val isMLton: bool
  17       val share: 'a -> unit
  18       val shareAll: unit -> unit
  19       val size: 'a -> int
  20
  21       structure Array: MLTON_ARRAY
  22       structure BinIO: MLTON_BIN_IO
  23       structure CharArray: MLTON_MONO_ARRAY where type t = CharArray.array
  24                                             where type elem = CharArray.elem
  25       structure CharVector: MLTON_MONO_VECTOR where type t = CharVector.vector
  26                                               where type elem = CharVector.elem
  27       structure Cont: MLTON_CONT
  28       structure Exn: MLTON_EXN
  29       structure Finalizable: MLTON_FINALIZABLE
  30       structure GC: MLTON_GC
  31       structure IntInf: MLTON_INT_INF
  32       structure Itimer: MLTON_ITIMER
  33       structure LargeReal: MLTON_REAL where type t = LargeReal.real
  34       structure LargeWord: MLTON_WORD where type t = LargeWord.word
  35       structure Platform: MLTON_PLATFORM
  36       structure Pointer: MLTON_POINTER
  37       structure ProcEnv: MLTON_PROC_ENV
  38       structure Process: MLTON_PROCESS
  39       structure Profile: MLTON_PROFILE
  40       structure Random: MLTON_RANDOM
  41       structure Real: MLTON_REAL where type t = Real.real
  42       structure Real32: sig
  43                            include MLTON_REAL
  44                            val castFromWord: Word32.word -> t
  45                            val castToWord: t -> Word32.word
  46                         end where type t = Real32.real
  47       structure Real64: sig
  48                            include MLTON_REAL
  49                            val castFromWord: Word64.word -> t
  50                            val castToWord: t -> Word64.word
  51                         end where type t = Real64.real
  52       structure Rlimit: MLTON_RLIMIT
  53       structure Rusage: MLTON_RUSAGE
  54       structure Signal: MLTON_SIGNAL
  55       structure Syslog: MLTON_SYSLOG
  56       structure TextIO: MLTON_TEXT_IO
  57       structure Thread: MLTON_THREAD
  58       structure Vector: MLTON_VECTOR
  59       structure Weak: MLTON_WEAK
  60       structure Word: MLTON_WORD where type t = Word.word
  61       structure Word8: MLTON_WORD where type t = Word8.word
  62       structure Word16: MLTON_WORD where type t = Word16.word
  63       structure Word32: MLTON_WORD where type t = Word32.word
  64       structure Word64: MLTON_WORD where type t = Word64.word
  65       structure Word8Array: MLTON_MONO_ARRAY where type t = Word8Array.array
  66                                              where type elem = Word8Array.elem
  67       structure Word8Vector: MLTON_MONO_VECTOR where type t = Word8Vector.vector
  68                                                where type elem = Word8Vector.elem
  69       structure World: MLTON_WORLD
  70    end
  71 ----
  72
  73
  74 == Substructures ==
  75
  76 * <:MLtonArray:>
  77 * <:MLtonBinIO:>
  78 * <:MLtonCont:>
  79 * <:MLtonExn:>
  80 * <:MLtonFinalizable:>
  81 * <:MLtonGC:>
  82 * <:MLtonIntInf:>
  83 * <:MLtonIO:>
  84 * <:MLtonItimer:>
  85 * <:MLtonMonoArray:>
  86 * <:MLtonMonoVector:>
  87 * <:MLtonPlatform:>
  88 * <:MLtonPointer:>
  89 * <:MLtonProcEnv:>
  90 * <:MLtonProcess:>
  91 * <:MLtonRandom:>
  92 * <:MLtonReal:>
  93 * <:MLtonRlimit:>
  94 * <:MLtonRusage:>
  95 * <:MLtonSignal:>
  96 * <:MLtonSyslog:>
  97 * <:MLtonTextIO:>
  98 * <:MLtonThread:>
  99 * <:MLtonVector:>
 100 * <:MLtonWeak:>
 101 * <:MLtonWord:>
 102 * <:MLtonWorld:>
 103
 104 == Values ==
 105
 106 * `eq (x, y)`
 107 +
 108 returns true if `x` and `y` are equal as pointers.  For simple types
 109 like `char`, `int`, and `word`, this is the same as equals.  For
 110 arrays, datatypes, strings, tuples, and vectors, this is a simple
 111 pointer equality.  The semantics is a bit murky.
 112
 113 * `equal (x, y)`
 114 +
 115 returns true if `x` and `y` are structurally equal.  For equality
 116 types, this is the same as <:PolymorphicEquality:>.  For other types,
 117 it is a conservative approximation of equivalence.
 118
 119 * `hash x`
 120 +
 121 returns a structural hash of `x`.  The hash function is consistent
 122 between execution of the same program, but may not be consistent
 123 between different programs.
 124
 125 * `isMLton`
 126 +
 127 is always `true` in a MLton implementation, and is always `false` in a
 128 stub implementation.
 129
 130 * `share x`
 131 +
 132 maximizes sharing in the heap for the object graph reachable from `x`.
 133
 134 * `shareAll ()`
 135 +
 136 maximizes sharing in the heap by sharing space for equivalent
 137 immutable objects.  A call to `shareAll` performs a major garbage
 138 collection, and takes time proportional to the size of the heap.
 139
 140 * `size x`
 141 +
 142 returns the amount of heap space (in bytes) taken by the value of `x`,
 143 including all objects reachable from `x` by following pointers.  It
 144 takes time proportional to the size of `x`.  See below for an example.
 145
 146
 147 == <!Anchor(size)>Example of `MLton.size` ==
 148
 149 This example, `size.sml`, demonstrates the application of `MLton.size`
 150 to many different kinds of objects.
 151 [source,sml]
 152 ----
 153 sys::[./bin/InclGitFile.py mlton master doc/examples/size/size.sml]
 154 ----
 155
 156 Compile and run as usual.
 157 ----
 158 % mlton size.sml
 159 % ./size
 160 The size of an int list of length 4 is 48 bytes.
 161 The size of a string of length 10 is 24 bytes.
 162 The size of an int array of length 10 is 52 bytes.
 163 The size of a double array of length 10 is 92 bytes.
 164 The size of an array of length 10 of 2-ples of ints is 92 bytes.
 165 The size of a useless function is 0 bytes.
 166 The size of a continuation option ref is 4544 bytes.
 167 13
 168 The size of a continuation option ref is 8 bytes.
 169 ----
 170
 171 Note that sizes are dependent upon the target platform and compiler
 172 optimizations.