Struct Mutex

pub struct Mutex<T: ?Sized> {
    inner: Mutex,
    data: UnsafeCell<T>,
}

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

A mutual exclusion primitive useful for protecting shared data that does not keep track of lock poisoning.

For more information about mutexes, check out the documentation for the poisoning variant of this lock at poison::Mutex.

Examples

Note that this Mutex does not propagate threads that panic while holding the lock via poisoning. If you need this functionality, see poison::Mutex.

#![feature(nonpoison_mutex)]

use std::thread;
use std::sync::{Arc, nonpoison::Mutex};

let mutex = Arc::new(Mutex::new(0u32));
let mut handles = Vec::new();

for n in 0..10 {
    let m = Arc::clone(&mutex);
    let handle = thread::spawn(move || {
        let mut guard = m.lock();
        *guard += 1;
        panic!("panic from thread {n} {guard}")
    });
    handles.push(handle);
}

for h in handles {
    let _ = h.join();
}

println!("Finished, locked {} times", mutex.lock());

Fields

inner: Mutex

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

data: UnsafeCell<T>

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

Implementations

impl<T> Mutex<T>

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

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

Creates a new mutex in an unlocked state ready for use.

Examples

#![feature(nonpoison_mutex)]

use std::sync::nonpoison::Mutex;

let mutex = Mutex::new(0);

pub fn get_cloned(&self) -> T

where T: Clone,

🔬This is a nightly-only experimental API. (lock_value_accessors #133407)

Returns the contained value by cloning it.

Examples

#![feature(nonpoison_mutex)]
#![feature(lock_value_accessors)]

use std::sync::nonpoison::Mutex;

let mut mutex = Mutex::new(7);

assert_eq!(mutex.get_cloned(), 7);

pub fn set(&self, value: T)

🔬This is a nightly-only experimental API. (lock_value_accessors #133407)

Sets the contained value.

Examples

#![feature(nonpoison_mutex)]
#![feature(lock_value_accessors)]

use std::sync::nonpoison::Mutex;

let mut mutex = Mutex::new(7);

assert_eq!(mutex.get_cloned(), 7);
mutex.set(11);
assert_eq!(mutex.get_cloned(), 11);

pub fn replace(&self, value: T) -> T

🔬This is a nightly-only experimental API. (lock_value_accessors #133407)

Replaces the contained value with value, and returns the old contained value.

Examples

#![feature(nonpoison_mutex)]
#![feature(lock_value_accessors)]

use std::sync::nonpoison::Mutex;

let mut mutex = Mutex::new(7);

assert_eq!(mutex.replace(11), 7);
assert_eq!(mutex.get_cloned(), 11);

impl<T: ?Sized> Mutex<T>

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

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

Acquires a mutex, blocking the current thread until it is able to do so.

This function will block the local thread until it is available to acquire the mutex. Upon returning, the thread is the only thread with the lock held. An RAII guard is returned to allow scoped unlock of the lock. When the guard goes out of scope, the mutex will be unlocked.

The exact behavior on locking a mutex in the thread which already holds the lock is left unspecified. However, this function will not return on the second call (it might panic or deadlock, for example).

Panics

This function might panic when called if the lock is already held by the current thread.

Examples

#![feature(nonpoison_mutex)]

use std::sync::{Arc, nonpoison::Mutex};
use std::thread;

let mutex = Arc::new(Mutex::new(0));
let c_mutex = Arc::clone(&mutex);

thread::spawn(move || {
    *c_mutex.lock() = 10;
}).join().expect("thread::spawn failed");
assert_eq!(*mutex.lock(), 10);

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

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

Attempts to acquire this lock.

This function does not block. If the lock could not be acquired at this time, then WouldBlock is returned. Otherwise, an RAII guard is returned.

The lock will be unlocked when the guard is dropped.

Errors

If the mutex could not be acquired because it is already locked, then this call will return the WouldBlock error.

Examples

use std::sync::{Arc, Mutex};
use std::thread;

let mutex = Arc::new(Mutex::new(0));
let c_mutex = Arc::clone(&mutex);

thread::spawn(move || {
    let mut lock = c_mutex.try_lock();
    if let Ok(ref mut mutex) = lock {
        **mutex = 10;
    } else {
        println!("try_lock failed");
    }
}).join().expect("thread::spawn failed");
assert_eq!(*mutex.lock().unwrap(), 10);

pub fn into_inner(self) -> T

where T: Sized,

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

Consumes this mutex, returning the underlying data.

Examples

#![feature(nonpoison_mutex)]

use std::sync::nonpoison::Mutex;

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

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

🔬This is a nightly-only experimental API. (nonpoison_mutex #134645)

Returns a mutable reference to the underlying data.

Since this call borrows the Mutex mutably, no actual locking needs to take place – the mutable borrow statically guarantees no locks exist.

Examples

#![feature(nonpoison_mutex)]

use std::sync::nonpoison::Mutex;

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

pub fn data_ptr(&self) -> *mut T

🔬This is a nightly-only experimental API. (mutex_data_ptr #140368)

Returns a raw pointer to the underlying data.

The returned pointer is always non-null and properly aligned, but it is the user’s responsibility to ensure that any reads and writes through it are properly synchronized to avoid data races, and that it is not read or written through after the mutex is dropped.

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: ?Sized + Default> Default for Mutex<T>

fn default() -> Mutex<T>

Creates a Mutex<T>, with the Default value for T.

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

fn from(t: T) -> Self

Creates a new mutex in an unlocked state ready for use. This is equivalent to Mutex::new.

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

T must be Send for a Mutex to be Send because it is possible to acquire the owned T from the Mutex via into_inner.

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

T must be Send for Mutex to be Sync. This ensures that the protected data can be accessed safely from multiple threads without causing data races or other unsafe behavior.

Mutex<T> provides mutable access to T to one thread at a time. However, it’s essential for T to be Send because it’s not safe for non-Send structures to be accessed in this manner. For instance, consider Rc, a non-atomic reference counted smart pointer, which is not Send. With Rc, we can have multiple copies pointing to the same heap allocation with a non-atomic reference count. If we were to use Mutex<Rc<_>>, it would only protect one instance of Rc from shared access, leaving other copies vulnerable to potential data races.

Also note that it is not necessary for T to be Sync as &T is only made available to one thread at a time if T is not Sync.