Module async/mutex

Async (event-loop) mutex — a critical section that may SPAN AWAITS (plans/archive/STD_API_AUDIT.md §7 P0 item 6 / D7). std/sync/mutex's blocking lock inside a future parks the entire event loop; this one suspends the waiting task instead. It is a task's lock, as tokio::sync::Mutex is: a task that awaits INSIDE a critical section yields the loop mid-section, and plain variables are only task-safe between suspension points.

A Mutex is a move-only value, shared as Arc(Mutex(T)) (Rust's Arc<tokio::sync::Mutex<T>>; plans/VALUES_BY_DEFAULT.md §3.13 A5). Copying one is an error; each task takes its own handle on the Arc, and lock's future borrows the mutex through it (lock(self : &Self, io)). A shared borrow through an Arc may live across a suspension, because no handle writes an Arc's payload (§3.13 A2): the lock state changes only inside the mutex. An Rc's payload is read-only through the handle too (decision 46), so Rc(Mutex(T)) is the single-thread sharing, Rust's Rc<Mutex<T>>.

It is thread-safe (Send and Sync when T is Send), which is what Arc requires: a short blocking guard (std/sync's RawMutex, never held across an await) protects the lock state, so tasks on different threads' loops may contend for one mutex. A waker fired from another thread resumes its task on that task's own loop (std/async/waker).

Contended acquisition is WAKER-BASED and FIFO, across loops as within one. A task that finds the lock held parks itself and puts its waker at the back of a queue; unlock HANDS the lock to the waiter at the front: the lock stays held, marked as that waiter's, and the waiter owns it when it resumes, with no re-check a later arrival or a try_lock could win. So the order the tasks arrived in is the order they acquire, whichever thread's loop each runs on. There is no timer under it, so a hand-off costs a loop turn rather than a millisecond. A waiter whose task is cancelled leaves the queue; one cancelled after the lock was handed to it passes the lock on to the next waiter, when its task's last reference goes away (unlock skips a same-loop waiter that refused its wake at once). Until 2026-09-11 this re-checked on a 1 ms tick and was explicitly unfair (plans/archive/WAKER_BASED_SCHEDULING.md stage 3); until 2026-10-17 unlock freed the lock and woke the front waiter to re-check, which was FIFO only among one loop's tasks (issues/fixed/2026-10-16-the-async-mutex-is-not-fifo-across-event-loops.md).

{ Mutex } :: import("std/async/mutex");
m := arc(Mutex(i64).new(i64(0)));
io.await(m.*.lock(io), io);
// ... awaits allowed here — the section stays exclusive ...
m.*.set(m.*.get() + i64(1));
m.*.unlock();

Stability

unstable — new, lock, with_lock, try_lock, unlock, is_locked, get and set are intended to keep their names and meanings. What changed under them in 2026-09-11 is the MECHANISM (a waiter queue instead of a 1 ms tick) and one guarantee that is now stronger than it was: acquisition is FIFO, where the timer version documented itself as unfair. On 2026-10-14 the mutex became a move-only value shared as Arc(Mutex(T)); it was a copyable handle over Rc state before. On 2026-10-17 unlock began handing the lock over instead of freeing it, which made the FIFO order hold across loops.