Struct kernel::mutex::Mutex [−] [src]

pub struct Mutex<T> {
    // some fields omitted
}

This type provides MUTual EXclusion based on spinning.

Description

This structure behaves a lot like a normal Mutex. There are some differences:

It may be used outside the runtime.
- A normal mutex will fail when used without the runtime, this will just lock
- When the runtime is present, it will call the deschedule function when appropriate
No lock poisoning. When a fail occurs when the lock is held, no guarantees are made

When calling rust functions from bare threads, such as C pthreads, this lock will be very helpful. In other cases however, you are encouraged to use the locks from the standard library.

Simple example

use spin;
let spin_mutex = spin::Mutex::new(0);

// Modify the data
{
    let mut data = spin_mutex.lock();
    *data = 2;
}

// Read the data
let answer =
{
    let data = spin_mutex.lock();
    *data
};

assert_eq!(answer, 2);

Thread-safety example

use spin;
use core::sync::{Arc, Barrier};

let numthreads = 1000;
let spin_mutex = Arc::new(spin::Mutex::new(0));

// We use a barrier to ensure the readout happens after all writing
let barrier = Arc::new(Barrier::new(numthreads + 1));

for _ in (0..numthreads)
{
    let my_barrier = barrier.clone();
    let my_lock = spin_mutex.clone();
    std::thread::spawn(move||
    {
        let mut guard = my_lock.lock();
        *guard += 1;

        // Release the lock to prevent a deadlock
        drop(guard);
        my_barrier.wait();
    });
}

barrier.wait();

let answer = { *spin_mutex.lock() };
assert_eq!(answer, numthreads);

Methods

`impl<T> Mutex<T>`

`fn new(user_data: T) -> Mutex<T>`

Creates a new spinlock wrapping the supplied data.

`fn lock(&self, file_line: &'static (&'static str, u32)) -> MutexGuard<T>`

Locks the spinlock and returns a guard.

The returned value may be dereferenced for data access and the lock will be dropped when the guard falls out of scope.

let mylock = spin::Mutex::new(0);
{
    let mut data = mylock.lock();
    // The lock is now locked and the data can be accessed
    *data += 1;
    // The lock is implicitly dropped
}

`unsafe fn destroy(&'static self)`

Deallocates resources associated with this static mutex.

This method is unsafe because it provides no guarantees that there are no active users of this mutex, and safety is not guaranteed if there are active users of this mutex.

This method is required to ensure that there are no memory leaks on all platforms. It may be the case that some platforms do not leak memory if this method is not called, but this is not guaranteed to be true on all platforms.