Crate lock_api

This library provides type-safe and fully-featured Mutex and RwLock types which wrap a simple raw mutex or rwlock type. This has several benefits: not only does it eliminate a large portion of the work in implementing custom lock types, it also allows users to write code which is generic with regards to different lock implementations.

Basic usage of this crate is very straightforward:

1. Create a raw lock type. This should only contain the lock state, not any data protected by the lock.
2. Implement the RawMutex trait for your custom lock type.
3. Export your mutex as a type alias for lock_api::Mutex, and your mutex guard as a type alias for lock_api::MutexGuard. See the example below for details.

This process is similar for RwLocks, except that two guards need to be exported instead of one. (Or 3 guards if your type supports upgradable read locks, see extension traits below for details)

Example

use lock_api::{RawMutex, Mutex, GuardSend};
use std::sync::atomic::{AtomicBool, Ordering};

// 1. Define our raw lock type
pub struct RawSpinlock(AtomicBool);

// 2. Implement RawMutex for this type
unsafe impl RawMutex for RawSpinlock {
    const INIT: RawSpinlock = RawSpinlock(AtomicBool::new(false));

    // A spinlock guard can be sent to another thread and unlocked there
    type GuardMarker = GuardSend;

    fn lock(&self) {
        // Note: This isn't the best way of implementing a spinlock, but it
        // suffices for the sake of this example.
        while !self.try_lock() {}
    }

    fn try_lock(&self) -> bool {
        self.0
            .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
            .is_ok()
    }

    unsafe fn unlock(&self) {
        self.0.store(false, Ordering::Release);
    }
}

// 3. Export the wrappers. This are the types that your users will actually use.
pub type Spinlock<T> = lock_api::Mutex<RawSpinlock, T>;
pub type SpinlockGuard<'a, T> = lock_api::MutexGuard<'a, RawSpinlock, T>;

Extension traits

In addition to basic locking & unlocking functionality, you have the option of exposing additional functionality in your lock types by implementing additional traits for it. Examples of extension features include:

• Fair unlocking (RawMutexFair, RawRwLockFair)
• Lock timeouts (RawMutexTimed, RawRwLockTimed)
• Downgradable write locks (RawRwLockDowngradable)
• Recursive read locks (RawRwLockRecursive)
• Upgradable read locks (RawRwLockUpgrade)

The Mutex and RwLock wrappers will automatically expose this additional functionality if the raw lock type implements these extension traits.

Cargo features

This crate supports three cargo features:

• owning_ref: Allows your lock types to be used with the owning_ref crate.
• arc_lock: Enables locking from an Arc. This enables types such as ArcMutexGuard. Note that this requires the alloc crate to be present.

Structs

• ArcMutexGuardarc_lock
  An RAII mutex guard returned by the Arc locking operations on Mutex.
• ArcReentrantMutexGuardatomic_usize and arc_lock
  An RAII mutex guard returned by the Arc locking operations on ReentrantMutex.
• ArcRwLockReadGuardarc_lock
  An RAII rwlock guard returned by the Arc locking operations on RwLock.
• ArcRwLockUpgradableReadGuardarc_lock
  An RAII rwlock guard returned by the Arc locking operations on RwLock. This is similar to the RwLockUpgradableReadGuard struct, except instead of using a reference to unlock the RwLock it uses an Arc<RwLock>. This has several advantages, most notably that it has an 'static lifetime.
• ArcRwLockWriteGuardarc_lock
  An RAII rwlock guard returned by the Arc locking operations on RwLock. This is similar to the RwLockWriteGuard struct, except instead of using a reference to unlock the RwLock it uses an Arc<RwLock>. This has several advantages, most notably that it has an 'static lifetime.
• GuardNoSend
  Marker type which indicates that the Guard type for a lock is not Send.
• GuardSend
  Marker type which indicates that the Guard type for a lock is Send.
• MappedMutexGuard
  An RAII mutex guard returned by MutexGuard::map, which can point to a subfield of the protected data.
• MappedReentrantMutexGuardatomic_usize
  An RAII mutex guard returned by ReentrantMutexGuard::map, which can point to a subfield of the protected data.
• MappedRwLockReadGuard
  An RAII read lock guard returned by RwLockReadGuard::map, which can point to a subfield of the protected data.
• MappedRwLockWriteGuard
  An RAII write lock guard returned by RwLockWriteGuard::map, which can point to a subfield of the protected data.
• Mutex
  A mutual exclusion primitive useful for protecting shared data
• MutexGuard
  An RAII implementation of a “scoped lock” of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
• RawReentrantMutexatomic_usize
  A raw mutex type that wraps another raw mutex to provide reentrancy.
• ReentrantMutexatomic_usize
  A mutex which can be recursively locked by a single thread.
• ReentrantMutexGuardatomic_usize
  An RAII implementation of a “scoped lock” of a reentrant mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
• RwLock
  A reader-writer lock
• RwLockReadGuard
  RAII structure used to release the shared read access of a lock when dropped.
• RwLockUpgradableReadGuard
  RAII structure used to release the upgradable read access of a lock when dropped.
• RwLockWriteGuard
  RAII structure used to release the exclusive write access of a lock when dropped.

Traits

• GetThreadIdatomic_usize
  Helper trait which returns a non-zero thread ID.
• RawMutex
  Basic operations for a mutex.
• RawMutexFair
  Additional methods for mutexes which support fair unlocking.
• RawMutexTimed
  Additional methods for mutexes which support locking with timeouts.
• RawRwLock
  Basic operations for a reader-writer lock.
• RawRwLockDowngrade
  Additional methods for RwLocks which support atomically downgrading an exclusive lock to a shared lock.
• RawRwLockFair
  Additional methods for RwLocks which support fair unlocking.
• RawRwLockRecursive
  Additional methods for RwLocks which support recursive read locks.
• RawRwLockRecursiveTimed
  Additional methods for RwLocks which support recursive read locks and timeouts.
• RawRwLockTimed
  Additional methods for RwLocks which support locking with timeouts.
• RawRwLockUpgrade
  Additional methods for RwLocks which support atomically upgrading a shared lock to an exclusive lock.
• RawRwLockUpgradeDowngrade
  Additional methods for RwLocks which support upgradable locks and lock downgrading.
• RawRwLockUpgradeFair
  Additional methods for RwLocks which support upgradable locks and fair unlocking.
• RawRwLockUpgradeTimed
  Additional methods for RwLocks which support upgradable locks and locking with timeouts.