Module sync/once
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
Fields
| Name | Type | Description |
|---|---|---|
_cell | __yo_atomic_cell(_OnceState) |
impl(Once, ...)
new : (Once) fn() -> OnceCreate a Once that has not run yet — Rust's Once::new.
Returns: Once
call : (Once) fn(self : &Once, f : &mut Impl(FnMut() -> unit)) -> unitRun 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
| Name | Type | Notes |
|---|---|---|
self | Once | |
f | Impl(FnMut() -> unit) |
Returns: unit
is_done : (Once) fn(self : &Once) -> boolWhether 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
| Name | Type | Notes |
|---|---|---|
self | Once |
Returns: bool
Type Parameters
| Name | Type | Notes |
|---|---|---|
T | Type | comptime |
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)) -> unitWrite a clone of self into the uninitialized slot dst, which has
room for size_of_val(self) bytes at align_of_val(self).
Parameters
| Name | Type | Notes |
|---|---|---|
self | Self | |
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