Module sync/mutex
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
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
| 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), 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
Fields
| Name | Type | Description |
|---|---|---|
_cell | __yo_atomic_cell(_RawMutexState) |
impl(RawMutex, ...)
new : (RawMutex) fn() -> RawMutexWrap 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) -> unitBlock 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
| Name | Type | Notes |
|---|---|---|
self | RawMutex |
Returns: unit
try_lock : (RawMutex) fn(self : &RawMutex) -> boolTake 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
| Name | Type | Notes |
|---|---|---|
self | RawMutex |
Returns: bool
unlock : (RawMutex) fn(self : &RawMutex) -> unitRelease 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
| Name | Type | Notes |
|---|---|---|
self | RawMutex |
Returns: unit
held_by_current_thread : (RawMutex) fn(self : &RawMutex) -> boolWhether 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
| Name | Type | Notes |
|---|---|---|
self | RawMutex |
Returns: bool