std::ref

std/src/ref.mo

A shared, mutable slot.

Ref is the primitive a server needs for state that outlives a request (a session store, a rate-limit table, a hot-reload version cell). It is deliberately small: get, set, and one atomic read-modify-write.

Concurrency: native fibers are OS threads, so an unlocked slot would be a data race. Ref.update applies a PURE function atomically and is the only correct way to do a read-modify-write across fibers. No lock is held while the function runs: if another fiber stores first, the function is applied again to the new value, so it may run more than once.

On wasi/web the runtime is single-threaded; the API and the atomicity contract are the same. A Ref is never matched or compared; the constructor is not built by user code.

typeRef#
pub type Ref (A : Type) { ref }

A shared, mutable slot.

Ref is the primitive a server needs for state that outlives a request (a session store, a rate-limit table, a hot-reload version cell). It is deliberately small: get, set, and one atomic read-modify-write.

Concurrency: native fibers are OS threads, so an unlocked slot would be a data race. Ref.update applies a PURE function atomically and is the only correct way to do a read-modify-write across fibers. No lock is held while the function runs: if another fiber stores first, the function is applied again to the new value, so it may run more than once.

On wasi/web the runtime is single-threaded; the API and the atomicity contract are the same. A Ref is never matched or compared; the constructor is not built by user code.

instance_#
pub instance {A : Type} Copy (Ref A) {
    def copy (r : Ref A) : Pair (Ref A) (Ref A) := Pair.pair r r
}

A Ref is a shared handle: duplicating it duplicates the REFERENCE, not the payload, so every holder observes the same slot -- which is exactly the point of a shared cell. Unconditional, like Copy (Shared A).

defRef.new#
pub def Ref.new (init : A) : IO (Ref A)
defRef.get#
pub def Ref.get (r : Ref A) : IO A
defRef.set#
pub def Ref.set (r : Ref A) (v : A) : IO Unit
defRef.update#
pub def Ref.update (r : Ref A) (f : A -> A) : IO A

Apply a pure f to the current value and store the result atomically. Returns the new value. f may run more than once under contention.

defRef.add_i64#
pub def Ref.add_i64 (r : Ref I64) (delta : I64) : IO I64

An atomic integer add, for counters (rate limits, sequence numbers) where a general update would allocate a closure per call.

defRef.modify#
pub def Ref.modify (r : Ref A) (f : A -> A) : IO Unit

Ref.update with the result discarded.