## MLton 20241230+git20251029+dfsg-5

# MLtonThread

    signature MLTON_THREAD =
       sig
          structure AtomicState:
             sig
                datatype t = NonAtomic | Atomic of int
             end

          val atomically: (unit -> 'a) -> 'a
          val atomicBegin: unit -> unit
          val atomicEnd: unit -> unit
          val atomicState: unit -> AtomicState.t

          structure Runnable:
             sig
                type t
             end

          type 'a t

          val atomicSwitch: ('a t -> Runnable.t) -> 'a
          val new: ('a -> unit) -> 'a t
          val prepend: 'a t * ('b -> 'a) -> 'b t
          val prepare: 'a t * 'a -> Runnable.t
          val switch: ('a t -> Runnable.t) -> 'a
       end

`MLton.Thread` provides access to MLton’s user-level thread implementation (i.e. not OS-level threads). Threads are lightweight data structures that represent a paused computation. Runnable threads are threads that will begin or continue computing when `switch`-ed to. `MLton.Thread` does not include a default scheduling mechanism, but it can be used to implement both preemptive and non-preemptive threads.

- `type AtomicState.t`

  the type of atomic states.

- `atomically f`

  runs `f` in a critical section.

- `atomicBegin ()`

  begins a critical section.

- `atomicEnd ()`

  ends a critical section.

- `atomicState ()`

  returns the current atomic state.

- `type Runnable.t`

  the type of threads that can be resumed.

- `type 'a t`

  the type of threads that expect a value of type `'a`.

- `atomicSwitch f`

  like `switch`, but assumes an atomic calling context. Upon `switch`-ing back to the current thread, an implicit `atomicEnd` is performed.

- `new f`

  creates a new thread that, when run, applies `f` to the value given to the thread. `f` must terminate by `switch`ing to another thread or exiting the process.

- `prepend (t, f)`

  creates a new thread (destroying `t` in the process) that first applies `f` to the value given to the thread and then continues with `t`. This is a constant time operation.

- `prepare (t, v)`

  prepares a new runnable thread (destroying `t` in the process) that will evaluate `t` on `v`.

- `switch f`

  applies `f` to the current thread to get `rt`, and then start running thread `rt`. It is an error for `f` to perform another `switch`. `f` is guaranteed to run atomically.

## Example of non-preemptive threads

    Unresolved directive in MLtonThread.adoc - include::https://raw.github.com/MLton/mlton/master/doc/examples/thread/non-preemptive-threads.sml[indent=0]

## Example of preemptive threads

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