Module local 

Synchronization primitives for the tasks of one shard.

Everything here is for tasks that share one shard (task::spawn_local, or the future block_on runs): the state sits in Rcs and plain cells, so the types are !Send and !Sync, and no path executes an atomic instruction or a fence. That makes them cheaper than their atomic twins in sync: CI counts the instructions of a message and of a one-shot reply on both (ci/op_budget.txt). The names and signatures mirror the atomic ones, so code switches by changing the path: mpsc for sync::mpsc, oneshot for sync::oneshot, Semaphore for sync::Semaphore and Mutex for sync::Mutex. The errors are the atomic ones.

fn send<T: Send>(_: T) {}
send(nuclei::sync::local::Mutex::new(0u8));

Fairness

Sends on a full bounded channel, acquires of the semaphore and locks of the mutex are served strictly in arrival order, with no barging: permits that come free are kept for the front waiter until its whole request fits, and try_ forms fail while anyone waits.

Cancel safety

Dropping any future of this module at any await loses no value, no permit and no wakeup, and leaks nothing: a waiting future gives up its place in line (the next waiter is served if it was the front), and one that was already granted its permits or the lock passes them on.

Cooperative scheduling

The budget of task::coop applies as for the atomic twins: a receive, an acquire or a lock that completes spends one operation of the task’s budget, and a bounded send or reservation that completes at its first attempt does too. A wait that queued and was granted spends nothing. The try_ forms never spend.

Interior mutability

The module keeps one rule. A cell is borrowed only inside one non-reentrant step, and nothing that can run user code (a Waker::wake, a value’s Drop, a waker’s clone) runs while any of them is borrowed: the waker or the values are taken out first, the borrow ends, and then they are woken or dropped. After a wake the state is read again; no borrow is reused.

Modules

mpsc

Multi-producer, single-consumer channels for the tasks of one shard.

oneshot

A channel that carries one value from one sender to one receiver, both on one shard.

Structs

Acquire

The wait for permits of Semaphore::acquire and Semaphore::acquire_many.

Lock

The wait of Mutex::lock.

Mutex

A mutual-exclusion lock whose wait is a future, for the tasks of one shard.

MutexGuard

Holds a Mutex locked; unlocks it when dropped.

Semaphore

A counting semaphore whose waits are futures, for the tasks of one shard.

SemaphorePermit

Permits taken from a Semaphore, returned when dropped.