Struct Mutex 

pub struct Mutex<T: ?Sized> { /* private fields */ }

A mutual-exclusion lock whose wait is a future.

Uncontended, try_lock and a guard’s drop are one atomic read-modify-write each and allocate nothing. A caller takes the lock whenever it is free, even while others wait; under contention lock spins briefly within the poll (see the module docs), then queues and returns Pending. An unlock wakes the oldest waiter to try again; a waiter that loses MAX_BYPASS times is handed the lock directly, and try_lock fails until it has had it.

It does not poison: a panic in a holder unlocks it.

use nuclei::sync::Mutex;

let counter = Mutex::new(0u32);
*counter.try_lock().expect("uncontended") += 1;
assert_eq!(counter.into_inner(), 1);

Implementations

impl<T> Mutex<T>

pub const fn new(value: T) -> Self

An unlocked mutex holding value.

pub const fn const_new(value: T) -> Self

An unlocked mutex holding value, usable in a static.

pub fn into_inner(self) -> T

Consumes the mutex and returns its value.

impl<T: ?Sized> Mutex<T>

pub fn try_lock(&self) -> Result<MutexGuard<'_, T>, TryLockError>

Locks the mutex if it is free and no handoff is owed.

Errors

TryLockError when the mutex is locked or owed to a waiter.

pub fn try_lock_owned( self: Arc<Self>, ) -> Result<OwnedMutexGuard<T>, TryLockError>

try_lock through an Arc, so the guard can outlive the borrow.

Errors

TryLockError when the mutex is locked or owed to a waiter.

pub fn lock(&self) -> Lock<'_, T>

Waits for the lock. Uncontended, the first poll is one load and one atomic read-modify-write. Contended, a poll may spin for up to the lock’s spin budget before it queues, and again after a retry it lost, before it returns Pending; it is lock-free, not wait-free: see Progress.

Dropping the future withdraws the wait, and passes on a lock handed to it meanwhile.

pub fn lock_owned(self: Arc<Self>) -> LockOwned<T>

lock through an Arc, so the guard can outlive the borrow.

pub fn blocking_lock(&self) -> MutexGuard<'_, T>

lock for a thread that may block: it parks the calling thread until the lock is free. On a nuclei shard (inside one of its tasks) it does not park the thread: it runs a nested block_on, so the shard keeps running its other tasks meanwhile. Inside another runtime’s task it blocks that task’s executor thread, so do not: the task that would unlock may be the one that thread was running.

Panics

On wasm32, where no other thread can unlock, when the lock is held: the call could never end.

pub fn blocking_lock_owned(self: Arc<Self>) -> OwnedMutexGuard<T>

blocking_lock through an Arc, so the guard can outlive the borrow.

Panics

As for blocking_lock.

pub fn get_mut(&mut self) -> &mut T

The value, borrowed mutably; &mut self proves no guard exists.

Trait Implementations

impl<T: ?Sized + Debug> Debug for Mutex<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Mutex<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> From<T> for Mutex<T>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T: ?Sized + Send> Send for Mutex<T>

impl<T: ?Sized + Send> Sync for Mutex<T>