Struct Mutex

Source

pub struct Mutex<T: ?Sized> {
    state: AtomicUsize,
    lock_ops: Event,
    data: UnsafeCell<T>,
}

Expand description

An async mutex.

The locking mechanism uses eventual fairness to ensure locking will be fair on average without sacrificing performance. This is done by forcing a fair lock whenever a lock operation is starved for longer than 0.5 milliseconds.

§Examples

use async_lock::Mutex;

let m = Mutex::new(1);

let mut guard = m.lock().await;
*guard = 2;

assert!(m.try_lock().is_none());
drop(guard);
assert_eq!(*m.try_lock().unwrap(), 2);

Fields§

§state: AtomicUsize

Current state of the mutex.

The least significant bit is set to 1 if the mutex is locked. The other bits hold the number of starved lock operations.

§lock_ops: Event

Lock operations waiting for the mutex to be released.

§data: UnsafeCell<T>

The value inside the mutex.

Implementations§

Source §

impl<T> Mutex<T>

Source

pub const fn new(data: T) -> Mutex<T>

Creates a new async mutex.

§Examples

use async_lock::Mutex;

let mutex = Mutex::new(0);

Source

pub fn into_inner(self) -> T

Consumes the mutex, returning the underlying data.

§Examples

use async_lock::Mutex;

let mutex = Mutex::new(10);
assert_eq!(mutex.into_inner(), 10);

Source §

impl<T: ?Sized> Mutex<T>

Source

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

Acquires the mutex.

Returns a guard that releases the mutex when dropped.

§Examples

use async_lock::Mutex;

let mutex = Mutex::new(10);
let guard = mutex.lock().await;
assert_eq!(*guard, 10);

Source

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

Acquires the mutex using the blocking strategy.

Returns a guard that releases the mutex when dropped.

§Blocking

Rather than using asynchronous waiting, like the lock method, this method will block the current thread until the lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a mutex can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

§Examples

use async_lock::Mutex;

let mutex = Mutex::new(10);
let guard = mutex.lock_blocking();
assert_eq!(*guard, 10);

Source

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

Attempts to acquire the mutex.

If the mutex could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the mutex when dropped.

§Examples

use async_lock::Mutex;

let mutex = Mutex::new(10);
if let Some(guard) = mutex.try_lock() {
    assert_eq!(*guard, 10);
}

Source

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

Returns a mutable reference to the underlying data.

Since this call borrows the mutex mutably, no actual locking takes place – the mutable borrow statically guarantees the mutex is not already acquired.

§Examples

use async_lock::Mutex;

let mut mutex = Mutex::new(0);
*mutex.get_mut() = 10;
assert_eq!(*mutex.lock().await, 10);

Source

pub(crate) unsafe fn unlock_unchecked(&self)

Unlocks the mutex directly.

§Safety

This function is intended to be used only in the case where the mutex is locked, and the guard is subsequently forgotten. Calling this while you don’t hold a lock on the mutex will likely lead to UB.

Source §

impl<T: ?Sized> Mutex<T>

Source

pub fn lock_arc(self: &Arc<Self>) -> LockArc<T> ⓘ

Acquires the mutex and clones a reference to it.

Returns an owned guard that releases the mutex when dropped.

§Examples

use async_lock::Mutex;
use std::sync::Arc;

let mutex = Arc::new(Mutex::new(10));
let guard = mutex.lock_arc().await;
assert_eq!(*guard, 10);

Source

pub fn lock_arc_blocking(self: &Arc<Self>) -> MutexGuardArc<T>

Acquires the mutex and clones a reference to it using the blocking strategy.

Returns an owned guard that releases the mutex when dropped.

§Blocking

Rather than using asynchronous waiting, like the lock_arc method, this method will block the current thread until the lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a mutex can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

§Examples

use async_lock::Mutex;
use std::sync::Arc;

let mutex = Arc::new(Mutex::new(10));
let guard = mutex.lock_arc_blocking();
assert_eq!(*guard, 10);

Source

pub fn try_lock_arc(self: &Arc<Self>) -> Option<MutexGuardArc<T>>

Attempts to acquire the mutex and clone a reference to it.

If the mutex could not be acquired at this time, then None is returned. Otherwise, an owned guard is returned that releases the mutex when dropped.

§Examples

use async_lock::Mutex;
use std::sync::Arc;

let mutex = Arc::new(Mutex::new(10));
if let Some(guard) = mutex.try_lock() {
    assert_eq!(*guard, 10);
}