Crate parking_method

Zero cost abstraction for Locking Methods

‘parking_lot’ has a lot variants for locking, there is the normal blocking lock, a try_lock, two forms of timed try locks and all of these are available as recursive variant as well.

This leads to a some explosion on the api, dispatching to these variants in generic code becomes pretty bloated. This crate abstracts all the different locking variants into a single trait with a uniform API that takes policy objects for the dispatch on underlying locking methods

Example

// reexports parts of parking_lot as well
use parking_method::*;

let rwlock = RwLock::new(String::from("test"));

// Note the 2 following syntax forms are equivalent
assert_eq!(*Blocking.read(&rwlock).unwrap(), "test");
assert_eq!(*ReadLockMethod::read(&Blocking, &rwlock).unwrap(), "test");

assert_eq!(*TryLock.read(&rwlock).unwrap(), "test");

let timeout = Duration::from_millis(100);

assert_eq!(
    *ReadLockMethod::read(&timeout, &rwlock).unwrap(),
    "test"
);

assert_eq!(
    *ReadLockMethod::read(
        &Recursive(Instant::now() + Duration::from_millis(100)),
        &rwlock).unwrap(),
    "test"
);

The Locking methods

There are plenty flavors on how a lock can be obtained. The normal blocking way, trying to obtain a lock, possibly with timeouts, allow a thread to lock a single RwLock multiple times. These are (zero-cost) abstracted here.

Structs

Blocking

Marker for blocking locks, waits until the lock becomes available.

Duration

reexport for convenience A Duration type to represent a span of time, typically used for system timeouts.

Instant

reexport for convenience A measurement of a monotonically nondecreasing clock. Opaque and useful only with Duration.

Recursive

Marker for recursive locking. Allows to obtain a read-lock multiple times by a single thread.

TryLock

Marker for trying to obtain a lock in a fallible way.

Traits

MutexMethod

Trait for implementing read/write flavors on Mutex. Note that there are no Recursive locks in Mutex, use ReentrantMutex for that.

ReadLockMethod

Trait for implementing read flavors on RwLocks.

ReentrantMutexMethod

Trait for implementing read/write flavors on ReentantMutex.

WriteLockMethod

Trait for implementing write flavors on RwLocks.

Type Definitions

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.

ReentrantMutex

A mutex which can be recursively locked by a single thread.

ReentrantMutexGuard

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.

RwLockWriteGuard

RAII structure used to release the exclusive write access of a lock when dropped.