Module sync/once

sync/once
Stability: unstable — may still change; see below.

One-time initialization primitives.

Once runs a side-effecting closure exactly once; OnceCell(T) stores the value that closure produced and hands it back on every later call.

Example

{ Once, OnceCell } :: import("std/sync/once");

init := Once.new();
// Only the first call executes the function
init.call(() => {
  println("initialized!");
});
init.call(() => {
  println("this will NOT run");
});

cell := OnceCell(i32).new();
a := cell.get_or_init(() => i32(42)); // runs the closure
b := cell.get_or_init(() => i32(99)); // lends the stored 42, closure not run
assert(b.* == i32(42), "get_or_init returns a &T into the cell");

Stability

unstable — the mechanism is settled (double-checked locking over Mutex.with_lock, concurrently tested in tests/sync/once.test.yo), but one NAME is wrong against the Rust vocabulary the rest of this library follows: OnceCell(T) here is thread-safe, which is Rust's OnceLock<T>, while Rust's OnceCell<T> is the single-threaded one. Renaming it — or adding a genuinely single-threaded cell beside it — is a live question, so the name is not frozen. LazyLock's counterpart is also still missing (plans/archive/STD_API_STABILIZATION_FINDINGS.md item 10); that one is additive. Neither type has poisoning: an initializer that exits early leaves the Once un-done and the next caller retries.

Types

Once struct
Once

Fields

NameTypeDescription
_cell__yo_atomic_cell(_OnceState)
impl(Once, ...)
new : (Once) fn() -> Once

Create a Once that has not run yet — Rust's Once::new.

Returns: Once

call : (Once) fn(self : &Once, f : &mut Impl(FnMut() -> unit)) -> unit

Run f the first time this is called, and never again — Rust's Once::call_once.

Every later call is a no-op, and a call that arrives WHILE another thread is running f blocks until that f returns, so f has finished for every caller that this returns to. The already-done case costs one Acquire load and takes no lock.

_done is set only after f RETURNS, so an f that exits early leaves the Once un-done and the next caller runs it again. That is the one divergence from Rust, which poisons a Once whose closure panicked and then propagates the panic to every later call_once: Yo has no poisoned state, and marking a half-finished initialization "done" would be worse than retrying it.

f cannot throw — a closure cannot capture an Exception — so there is no "the mutex stayed locked" case to worry about; release is structural through Mutex.with_lock either way.

Parameters

NameTypeNotes
selfOnce
fImpl(FnMut() -> unit)

Returns: unit

is_done : (Once) fn(self : &Once) -> bool

Whether the closure has already run to completion — Rust's Once::is_completed.

A lock-free Acquire load, so it is cheap, and it is honest in the direction that matters: true means the initialization is finished and its writes are visible to this thread. false can be stale the instant it is read — another thread may be inside f — so do not use it to decide whether call will block.

Parameters

NameTypeNotes
selfOnce

Returns: bool

OnceCell type-function
fn(T : Type) -> Type

Type Parameters

NameTypeNotes
TTypecomptime

Trait Implementations

impl(generic(T : Type), where(T <: Clone), T : (Clone))
impl(generic(T : Type), where(T <: Clone), T : (Clone), CloneInto)
clone_into : fn(self : &Self, dst : *(Self)) -> unit

Write a clone of self into the uninitialized slot dst, which has room for size_of_val(self) bytes at align_of_val(self).

Parameters

NameTypeNotes
selfSelf
dst*(Self)

Returns: unit

impl(generic(T : Type), where(T <: Send), OnceCell(T), ...)
new : (fn() -> Self)

Create an empty cell.

Returns: Self

_init : (fn(self : &Self, f : &mut Impl(FnMut() -> T)) -> unit)

Store f() unless the cell already holds a value. f runs at most once across all threads; every other caller blocks until it finishes.

Returns: unit

get_or_init : (fn(self : &Self, f : &mut Impl(FnMut() -> T)) -> &(T, self))

Return a reference to the stored value, initializing it with f if this is the first call. f runs at most once across all threads; every other caller blocks until it finishes and then sees its value. The value stays in the cell, so a move-only T is read in place, as Rust's OnceLock::get_or_init lends it.

The result's origin is the receiver alone (-> &(T, self)): the initializer is released when the call returns, so a capture it wrote is readable again while the returned reference lives.

Returns: &(T, self)

get : (fn(self : &Self) -> Option(&T))

Return a reference to the stored value, or None if the cell has not been initialized. Never runs an initializer.

Returns: Option(&T)

is_initialized : (fn(self : &Self) -> bool)

Whether the cell holds a value.

Returns: bool