Module sync/mutex

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

Mutual exclusion lock primitives.

Phase D (THREAD_SAFETY): Mutex parameterized over the protected data. Access is granted via with_lock(closure) — the closure receives a v : &mut T that is second-class (cannot escape the closure scope). The private __MutexUnlocker handles unlock on both normal return and unwind via its Drop impl.

Stability

unstable — the closure-scoped shape (with_lock / try_with_lock, no guard type) is settled and concurrently tested (tests/sync/mutex.test.yo, 12/12), but ONE row of plans/archive/STD_API_STABILIZATION.md §4 "Concurrency" is still open and it is on this surface: _raw_lock / _raw_unlock / _raw_handle_ptr are reachable from outside the module and are meant to be removed. They cannot go yet because Cond.wait takes the raw handle they hand out — Mutex(T) has no guard to pass instead — so freezing this module waits on a condvar API that couples to a Mutex(T) without exposing its primitive. There is also no poisoning: a thread that unwinds out of body releases the lock and leaves the data as it was, where Rust would mark the Mutex poisoned. That is a deliberate choice (Yo has no poisoned state anywhere), not an omission, and it is not what is holding the freeze.

Types

__YO_THREAD_SYNC_TYPE

Trait Implementations

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

A mutual-exclusion lock for async tasks, protecting a T.

A move-only value (it owns its value cell and a handle on its lock state): tasks share one as Arc(Mutex(T)), each holding its own handle, and lock's and with_lock's futures borrow the mutex through it (io.await(m.*.lock(io), io); plans/VALUES_BY_DEFAULT.md §3.13 A2 and A5). Its methods take self : &Self and change the state inside the cells under the core's guard, Rust's interior mutability.

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), Mutex(T), Send())
impl(generic(T : Type), where(T <: Send), Mutex(T), Sync())
impl(generic(T : Type), where(T <: Send), Mutex(T), ...)
new : (fn(value : T) -> Self)

Wrap value in a new, unlocked mutex — Rust's Mutex::new.

value moves INTO the lock and is thereafter reachable only through with_lock / try_with_lock. Creating the OS primitive is the only allocation-time cost; there is no lazy initialization on first lock.

Returns: Self

with_lock : ( fn( generic(R : Type), self : &Self, body : &mut Impl(FnMut(v : &mut T) -> R) ) -> R )

Take the lock, run body on the protected value, release the lock, and return body's result — Rust's lock().unwrap() plus the guard's scope, in one call.

This blocks until the lock is available, parking the thread rather than spinning. body receives a v : &mut T, so it may mutate the protected value in place; the mutation is visible to the next holder.

Release is structural, not by falling off the end: a private __MutexUnlocker is created inside the critical section and its Drop impl unlocks, so an early return out of body or an unwind through this frame still releases the lock. Nothing marks the mutex poisoned in that case (see the type doc).

Re-entering the same mutex from the same thread PANICS — on every platform, with a message naming this API. (The POSIX primitive would deadlock and the Windows CRITICAL_SECTION would silently recurse; the owner check in _raw_lock replaces both with one trap.) Nest different mutexes, not the same one.

Returns: R

try_with_lock : ( fn( generic(R : Type), self : &Self, body : &mut Impl(FnMut(v : &mut T) -> R) ) -> Option(R) )

Run body under the lock IF it can be taken without waiting, and return .Some(result); .None when another thread holds it.

The closure-scoped counterpart of Rust's try_lock. Rust hands back a Result<MutexGuard, TryLockError>; Mutex(T) deliberately has no guard type — access is only ever granted inside a closure — so the "did I get it" answer is the Option instead. body not running IS the failure case, which is why the result is optional rather than the lock state being reported separately: there is no way to observe "not acquired" and still have a value.

Release is by the same __MutexUnlocker with_lock uses, so an early return or an unwind out of body still unlocks.

Do not spin on this. A while(!took, ...) loop around try_with_lock is a busy-wait that starves the holder on a single core; with_lock parks instead. try_with_lock is for the case where there is other useful work to do when the lock is busy.

The thread that ALREADY holds this mutex gets .None, on every platform (a Windows CRITICAL_SECTION is recursive and would have said .Some; the owner check masks that so the answer is portable).

Returns: Option(R)

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

True when the mutex is NOT held right now.

Advisory only, and racy by construction: it takes the lock to find out and releases it again, so the answer describes a moment that has already passed. Never branch on this to decide whether a later with_lock will block — that is a TOCTOU bug. It exists for assertions and diagnostics, which is why it is spelled as a question about the past rather than as can_lock.

Returns: bool

_raw_lock : (fn(self : &Self) -> unit)

Returns: unit

_raw_unlock : (fn(self : &Self) -> unit)

Returns: unit

_raw_handle_ptr : (fn(self : &mut Self) -> *__YO_THREAD_SYNC_TYPE)

Returns: *__YO_THREAD_SYNC_TYPE

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

Whether the calling thread holds this mutex (exact for the caller).

Returns: bool

_park_begin : (fn(self : &Self) -> unit)

Bracket a condvar wait: the OS wait releases and re-takes the mutex behind our back, so the owner record is cleared before parking and restored after. Both panic-check that the caller holds the mutex.

Returns: unit

_park_end : (fn(self : &Self) -> unit)

Returns: unit

RawMutex struct
RawMutex

Fields

NameTypeDescription
_cell__yo_atomic_cell(_RawMutexState)
impl(RawMutex, ...)
new : (RawMutex) fn() -> RawMutex

Wrap value in a new, unlocked mutex — Rust's Mutex::new.

value moves INTO the lock and is thereafter reachable only through with_lock / try_with_lock. Creating the OS primitive is the only allocation-time cost; there is no lazy initialization on first lock.

Returns: RawMutex

lock : (RawMutex) fn(self : &RawMutex) -> unit

Block until the lock is taken. Locking again from the thread that holds it PANICS (it would deadlock on POSIX and silently recurse on Windows; D5 makes it one behaviour).

Parameters

NameTypeNotes
selfRawMutex

Returns: unit

try_lock : (RawMutex) fn(self : &RawMutex) -> bool

Take the lock if it is free; true = taken (you must unlock). false for the thread that already holds it, on every platform (a Windows CRITICAL_SECTION would re-enter).

Parameters

NameTypeNotes
selfRawMutex

Returns: bool

unlock : (RawMutex) fn(self : &RawMutex) -> unit

Release the lock. PANICS unless THIS thread holds it — an unlock without a lock, or from another thread, is undefined behaviour in the OS primitive and is refused here instead.

Parameters

NameTypeNotes
selfRawMutex

Returns: unit

held_by_current_thread : (RawMutex) fn(self : &RawMutex) -> bool

Whether the calling thread holds this lock. Exact for the caller (only it can change that fact); the answer about any OTHER thread is advisory. This is what lets a lock taken in one function be released in another without a guard — std/thread's submission lock.

Parameters

NameTypeNotes
selfRawMutex

Returns: bool