## MLton 20241230+git20251029+dfsg-5

# MLtonStructure

The `MLton` structure contains a lot of functionality that is not available in the Basis Library. As a warning, please keep in mind that the `MLton` structure and its substructures do change from release to release of MLton.

    structure MLton:
       sig
          val eq: 'a * 'a -> bool
          val equal: 'a * 'a -> bool
          val hash: 'a -> Word32.word
          val isMLton: bool
          val share: 'a -> unit
          val shareAll: unit -> unit
          val size: 'a -> IntInf.int
          val sizeAll: 'a -> 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 -> t
                               val castToWord: t -> Word32.word
                            end where type t = Real32.real
          structure Real64: sig
                               include MLTON_REAL
                               val castFromWord: Word64.word -> t
                               val castToWord: t -> 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

## Substructures

- MLtonArray

- MLtonBinIO

- MLtonCont

- MLtonExn

- MLtonFinalizable

- MLtonGC

- MLtonIntInf

- MLtonIO

- MLtonItimer

- MLtonMonoArray

- MLtonMonoVector

- MLtonPlatform

- MLtonPointer

- MLtonProcEnv

- MLtonProcess

- MLtonRandom

- MLtonReal

- MLtonRlimit

- MLtonRusage

- MLtonSignal

- MLtonSyslog

- MLtonTextIO

- MLtonThread

- MLtonVector

- MLtonWeak

- MLtonWord

- MLtonWorld

## Values

- `eq (x, y)`

  returns true if `x` and `y` are equal as pointers. For simple types like `char`, `int`, and `word`, 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.

- `equal (x, y)`

  returns true if `x` and `y` are structurally equal. For equality types, this is the same as PolymorphicEquality. For other types, it is a conservative approximation of equivalence.

- `hash x`

  returns a structural hash of `x`. The hash function is consistent between execution of the same program, but may not be consistent between different programs.

- `isMLton`

  is always `true` in a MLton implementation, and is always `false` in a stub implementation.

- `share x`

  maximizes sharing in the heap for the object graph reachable from `x`.

- `shareAll ()`

  maximizes sharing in the heap by sharing space for equivalent immutable objects. A call to `shareAll` performs a major garbage collection, and takes time proportional to the size of the heap.

- `size x`

  returns the amount of heap space (in bytes) taken by the value of `x`, including all objects reachable from `x` by following pointers. It takes time proportional to the size of `x`. See below for an example.

- `sizeAll ()`

  returns the amount of heap space (in bytes) taken by all reachable live data. It takes time proportional to the size of live data.

## Example of `MLton.size`

This example, `size.sml`, demonstrates the application of `MLton.size` to many different kinds of objects.

    Unresolved directive in MLtonStructure.adoc - include::https://raw.github.com/MLton/mlton/master/doc/examples/size/size.sml[indent=0]

Compile and run as usual.

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

Note that sizes are dependent upon the target platform and compiler optimizations.