## MLton 20241230+git20251029+dfsg-5

# MLtonFinalizable

    signature MLTON_FINALIZABLE =
       sig
          type 'a t

          val addFinalizer: 'a t * ('a -> unit) -> unit
          val finalizeBefore: 'a t * 'b t -> unit
          val new: 'a -> 'a t
          val touch: 'a t -> unit
          val withValue: 'a t * ('a -> 'b) -> 'b
       end

A finalizable value is a container to which finalizers can be attached. A container holds a value, which is reachable as long as the container itself is reachable. A finalizer is a function that runs at some point after garbage collection determines that the container to which it is attached has become unreachable. A finalizer is treated like a signal handler, in that it runs asynchronously in a separate thread, with signals blocked, and will not interrupt a critical section (see MLtonThread).

- `addFinalizer (v, f)`

  adds `f` as a finalizer to `v`. This means that sometime after the last call to `withValue` on `v` completes and `v` becomes unreachable, `f` will be called with the value of `v`.

- `finalizeBefore (v1, v2)`

  ensures that `v1` will be finalized before `v2`. A cycle of values `v` = `v1`, …​, `vn` = `v` with `finalizeBefore (vi, vi+1)` will result in none of the `vi` being finalized.

- `new x`

  creates a new finalizable value, `v`, with value `x`. The finalizers of `v` will run sometime after the last call to `withValue` on `v` when the garbage collector determines that `v` is unreachable.

- `touch v`

  ensures that `v`’s finalizers will not run before the call to `touch`.

- `withValue (v, f)`

  returns the result of applying `f` to the value of `v` and ensures that `v`’s finalizers will not run before `f` completes. The call to `f` is a nontail call.

## Example

Suppose that `finalizable.sml` contains the following:

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

Suppose that `cons.c` contains the following.

    Unresolved directive in MLtonFinalizable.adoc - include::https://raw.github.com/MLton/mlton/master/doc/examples/finalizable/cons.c[indent=0]

We can compile these to create an executable with

    % mlton -default-ann 'allowFFI true' finalizable.sml cons.c

Running this executable will create output like the following.

    % finalizable
    0x08072890 = listSing (2)
    0x080728a0 = listCons (2)
    0x080728b0 = listCons (2)
    0x080728c0 = listCons (2)
    0x080728d0 = listCons (2)
    0x080728e0 = listCons (2)
    0x080728f0 = listCons (2)
    listSum
    listSum(l) = 14
    listFree (0x080728f0)
    listFree (0x080728e0)
    listFree (0x080728d0)
    listFree (0x080728c0)
    listFree (0x080728b0)
    listFree (0x080728a0)
    listFree (0x08072890)

## Synchronous Finalizers

Finalizers in MLton are asynchronous. That is, they run at an unspecified time, interrupting the user program. It is also possible, and sometimes useful, to have synchronous finalizers, where the user program explicitly decides when to run enabled finalizers. We have considered this in MLton, and it seems possible, but there are some unresolved design issues. See the thread at

- http://www.mlton.org/pipermail/mlton/2004-September/016570.html

## Also see

- Boehm03