Struct spin::mutex::ticket::TicketMutex

pub struct TicketMutex<T: ?Sized, R = Spin> { /* private fields */ }

Available on crate features mutex and ticket_mutex only.

A spin-based ticket lock providing mutually exclusive access to data.

A ticket lock is analogous to a queue management system for lock requests. When a thread tries to take a lock, it is assigned a ‘ticket’. It then spins until its ticket becomes next in line. When the lock guard is released, the next ticket will be processed.

Ticket locks significantly reduce the worse-case performance of locking at the cost of slightly higher average-time overhead.

Example

use spin;

let lock = spin::mutex::TicketMutex::<_>::new(0);

// Modify the data
*lock.lock() = 2;

// Read the data
let answer = *lock.lock();
assert_eq!(answer, 2);

Thread safety example

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

let thread_count = 1000;
let spin_mutex = Arc::new(spin::mutex::TicketMutex::<_>::new(0));

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

for _ in (0..thread_count) {
    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, thread_count);

Implementations

impl<T, R> TicketMutex<T, R>

pub const fn new(data: T) -> Self

Creates a new TicketMutex wrapping the supplied data.

Example

use spin::mutex::TicketMutex;

static MUTEX: TicketMutex<()> = TicketMutex::<_>::new(());

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

pub fn into_inner(self) -> T

Consumes this TicketMutex and unwraps the underlying data.

Example

let lock = spin::mutex::TicketMutex::<_>::new(42);
assert_eq!(42, lock.into_inner());

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

Returns a mutable pointer to the underying data.

This is mostly meant to be used for applications which require manual unlocking, but where storing both the lock and the pointer to the inner data gets inefficient.

Example

let lock = spin::mutex::SpinMutex::<_>::new(42);

unsafe {
    core::mem::forget(lock.lock());

    assert_eq!(lock.as_mut_ptr().read(), 42);
    lock.as_mut_ptr().write(58);

    lock.force_unlock();
}

assert_eq!(*lock.lock(), 58);

impl<T: ?Sized, R: RelaxStrategy> TicketMutex<T, R>

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

Locks the TicketMutex and returns a guard that permits access to the inner data.

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

let lock = spin::mutex::TicketMutex::<_>::new(0);
{
    let mut data = lock.lock();
    // The lock is now locked and the data can be accessed
    *data += 1;
    // The lock is implicitly dropped at the end of the scope
}

impl<T: ?Sized, R> TicketMutex<T, R>

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 this TicketMutex, by serving the next ticket.

Safety

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.

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

Try to lock this TicketMutex, returning a lock guard if successful.

Example

let lock = spin::mutex::TicketMutex::<_>::new(42);

let maybe_guard = lock.try_lock();
assert!(maybe_guard.is_some());

// `maybe_guard` is still held, so the second call fails
let maybe_guard2 = lock.try_lock();
assert!(maybe_guard2.is_none());

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

Returns a mutable reference to the underlying data.

Since this call borrows the TicketMutex 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 = spin::mutex::TicketMutex::<_>::new(0);
*lock.get_mut() = 10;
assert_eq!(*lock.lock(), 10);

Trait Implementations

impl<T: ?Sized + Debug, R> Debug for TicketMutex<T, R>

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

Formats the value using the given formatter.

impl<T: ?Sized + Default, R> Default for TicketMutex<T, R>

fn default() -> Self

Returns the “default value” for a type.

impl<T, R> From<T> for TicketMutex<T, R>

fn from(data: T) -> Self

Converts to this type from the input type.

impl<R: RelaxStrategy> RawMutex for TicketMutex<(), R>

type GuardMarker = GuardSend

Marker type which determines whether a lock guard should be Send. Use one of the GuardSend or GuardNoSend helper types here.

const INIT: Self = _

Initial value for an unlocked mutex.

fn lock(&self)

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

fn try_lock(&self) -> bool

Attempts to acquire this mutex without blocking. Returns true if the lock was successfully acquired and false otherwise.

unsafe fn unlock(&self)

Unlocks this mutex.

fn is_locked(&self) -> bool

Checks whether the mutex is currently locked.

impl<T: ?Sized + Send, R> Send for TicketMutex<T, R>

impl<T: ?Sized + Send, R> Sync for TicketMutex<T, R>