Struct Mutex

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

A Futures-aware Mutex.

std::sync::Mutex cannot be used in an asynchronous environment like Tokio, because a mutex acquisition can block an entire reactor. This class can be used instead. It functions much like std::sync::Mutex. Unlike that class, it also has a builtin Arc, making it accessible from multiple threads. It’s also safe to clone. Also unlike std::sync::Mutex, this class does not detect lock poisoning.

Examples

let mtx = Mutex::<u32>::new(0);
let fut = mtx.lock().map(|mut guard| { *guard += 5; });
block_on(fut);
assert_eq!(mtx.try_unwrap().unwrap(), 5);

Implementations

impl<T> Mutex<T>

pub fn new(t: T) -> Mutex<T>

Create a new Mutex in the unlocked state.

pub fn try_unwrap(self) -> Result<T, Mutex<T>>

Consumes the Mutex and returns the wrapped data. If the Mutex still has multiple references (not necessarily locked), returns a copy of self instead.

impl<T: ?Sized> Mutex<T>

pub fn downgrade(this: &Mutex<T>) -> MutexWeak<T>

Create a MutexWeak reference to this Mutex.

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

Returns a reference to the underlying data, if there are no other clones of the Mutex.

Since this call borrows the Mutex mutably, no actual locking takes place – the mutable borrow statically guarantees no locks exist. However, if the Mutex has already been cloned, then None will be returned instead.

Examples

let mut mtx = Mutex::<u32>::new(0);
*mtx.get_mut().unwrap() += 5;
assert_eq!(mtx.try_unwrap().unwrap(), 5);

pub fn lock(&self) -> MutexFut<T>

Acquires a Mutex, blocking the task in the meantime. When the returned Future is ready, this task will have sole access to the protected data.

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

Attempts to acquire the lock.

If the operation would block, returns Err instead. Otherwise, returns a guard (not a Future).

Examples

let mut mtx = Mutex::<u32>::new(0);
match mtx.try_lock() {
    Ok(mut guard) => *guard += 5,
    Err(_) => println!("Better luck next time!")
};

pub fn ptr_eq(this: &Mutex<T>, other: &Mutex<T>) -> bool

Returns true if the two Mutex point to the same data else false.

impl<T: 'static + ?Sized> Mutex<T>

pub fn with<B, F, R>(&self, f: F) -> impl Future<Output = R>

where F: FnOnce(MutexGuard<T>) -> B + Send + 'static, B: Future<Output = R> + Send + 'static, R: Send + 'static, T: Send,

Available on crate feature tokio only.

Acquires a Mutex and performs a computation on its guarded value in a separate task. Returns a Future containing the result of the computation.

When using Tokio, this method will often hold the Mutex for less time than chaining a computation to lock. The reason is that Tokio polls all tasks promptly upon notification. However, Tokio does not guarantee that it will poll all futures promptly when their owning task gets notified. So it’s best to hold Mutexes within their own tasks, lest their continuations get blocked by slow stacked combinators.

Examples

let mtx = Mutex::<u32>::new(0);
let mut rt = Runtime::new().unwrap();
rt.block_on(async {
    mtx.with(|mut guard| {
        *guard += 5;
        ready::<()>(())
    }).await
});
assert_eq!(mtx.try_unwrap().unwrap(), 5);

pub fn with_local<B, F, R>(&self, f: F) -> impl Future<Output = R>

where F: FnOnce(MutexGuard<T>) -> B + 'static, B: Future<Output = R> + 'static + Unpin, R: 'static,

Available on crate feature tokio only.

Like with but for Futures that aren’t Send. Spawns a new task on a single-threaded Runtime to complete the Future.

Examples

// Note: Rc is not `Send`
let mtx = Mutex::<Rc<u32>>::new(Rc::new(0));
let mut rt = Runtime::new().unwrap();
rt.block_on(async {
    mtx.with_local(|mut guard| {
        *Rc::get_mut(&mut *guard).unwrap() += 5;
        ready(())
    }).await
});
assert_eq!(*mtx.try_unwrap().unwrap(), 5);

Trait Implementations

impl<T: ?Sized> Clone for Mutex<T>

fn clone(&self) -> Mutex<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Mutex<T>

Returns the “default value” for a type.

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

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