Module Cells.Make

Parameters

module Cell : CELL

Signature

type 'a t
type 'a segment
val make : unit -> 'a t

make () is a fresh sequence of cells.

val next_suspend : 'a t -> 'a segment * 'a Cell.t Atomic.t

next_suspend t atomically returns the next suspend cell and its segment.

If multiple domains call this at the same time, they will each get a different location.

The cell might or might not have already been filled in by a resumer. You need to handle both cases (typically by using Atomic.compare_and_set).

The segment can be used with cancel_cell.

This function is lock-free and is safe to call even from a signal handler or GC finalizer.

val next_resume : 'a t -> 'a Cell.t Atomic.t

next_resume t atomically returns the next resume cell.

If multiple domains call this at the same time, they will each get a different cell.

The cell might or might not contain a request from a suspender that got there first. You need to handle both cases (typically by using Atomic.compare_and_set).

Note: cancelled cells may or may not be skipped (you need to handle the case of the cell you get being cancelled before you can write to it, but you also can't rely on seeing every cancelled cell, as cancelled segments may be deleted).

This function is lock-free and is safe to call even from a signal handler or GC finalizer.

val resume_all : 'a t -> ('a Cell.t Atomic.t -> unit) -> unit

resume_all t f advances the resume position to the current suspend position, then calls f cell on each cell advanced over.

Note: as with next_resume, f may be called for some cancelled cells but not others.

f must not raise an exception (if it does, it will not be called on the remaining cells).

If the resume position is ahead of the suspend position, then calling this function does nothing.

This function is lock-free and is safe to call even from a signal handler or GC finalizer.

val cancel_cell : 'a segment -> unit

cancel_cell segment increments the segment's count of the number of cancelled cells.

Once all cells are cancelled it may be possible to discard the whole segment. This avoids leaking memory if a user keeps suspending and then cancelling.

You must not call this more than once per cell.

This function is lock-free and is safe to call even from a signal handler or GC finalizer.

val validate : _ t -> unit

validate t checks that t is in a valid state, assuming there are no operations currently in progress.

val dump : _ t Fmt.t

dump outputs the internal state of a _ t, for debugging.