Struct irq_safety::MutexIrqSafe

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

This type provides interrupt-safe MUTual EXclusion based on [spin::Mutex].

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 examples

use irq_safety;
let spin_mutex = irq_safety::MutexIrqSafe::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 irq_safety;
use std::sync::{Arc, Barrier};

let numthreads = 1000;
let spin_mutex = Arc::new(irq_safety::MutexIrqSafe::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);

Implementations

impl<T> MutexIrqSafe<T>

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

Creates a new spinlock wrapping the supplied data.

May be used statically:

use irq_safety;

static MutexIrqSafe: irq_safety::MutexIrqSafe<()> = irq_safety::MutexIrqSafe::new(());

fn demo() {
    let lock = MutexIrqSafe.lock();
    // do something with lock
    drop(lock);
}

pub fn into_inner(self) -> T

Consumes this MutexIrqSafe, returning the underlying data.

impl<T: ?Sized> MutexIrqSafe<T>

pub fn lock(&self) -> MutexIrqSafeGuard<'_, 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 = irq_safety::MutexIrqSafe::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
}

pub fn is_locked(&self) -> bool

Returns true if the lock is currently held.

Safety

This function provides no synchronization guarantees and so its result should be considered ‘out of date’ the instant it is called. Do not use it for synchronization purposes. However, it may be useful as a heuristic.

pub unsafe fn force_unlock(&self)

Force unlock the spinlock.

This is extremely unsafe if the lock is not held by the current thread. However, this can be useful in some instances for exposing the lock to FFI that doesn’t know how to deal with RAII.

If the lock isn’t held, this is a no-op.

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

Tries to lock the MutexIrqSafe. If it is already locked, it will return None. Otherwise it returns a guard within Some.

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

Returns a mutable reference to the underlying data.

Since this call borrows the MutexIrqSafe mutably, and a mutable reference is guaranteed to be exclusive in Rust, no actual locking needs to take place – the mutable borrow statically guarantees no locks exist. As such, this is a ‘zero-cost’ operation.

Example

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

Trait Implementations

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

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

Formats the value using the given formatter.

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

fn default() -> MutexIrqSafe<T>

Returns the “default value” for a type.

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

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