Compact and efficient synchronization primitives for Rust. Also provides an API for creating custom synchronization primitives.
APACHE-2.0 License
Documentation (synchronization primitives)
Documentation (core parking lot API)
Documentation (type-safe lock API)
This library provides implementations of Mutex
, RwLock
, Condvar
and
Once
that are smaller, faster and more flexible than those in the Rust
standard library, as well as a ReentrantMutex
type which supports recursive
locking. It also exposes a low-level API for creating your own efficient
synchronization primitives.
When tested on x86_64 Linux, parking_lot::Mutex
was found to be 1.5x
faster than std::sync::Mutex
when uncontended, and up to 5x faster when
contended from multiple threads. The numbers for RwLock
vary depending on
the number of reader and writer threads, but are almost always faster than
the standard library RwLock
, and even up to 50x faster in some cases.
The primitives provided by this library have several advantages over those in the Rust standard library:
Mutex
and Once
only require 1 byte of storage space, while Condvar
RwLock
only require 1 word of storage space. On the other hand onBox
to hold OS-specific synchronizationMutex
in particular encourages the useCondvar
, RwLock
and Once
work on Windows XP, unlike the standardRwLock
takes advantage of hardware lock elision on processors thathardware-lock-elision
feature.RwLock
uses a task-fair locking policy, which avoids reader and writerCondvar
is guaranteed not to produce spurious wakeups. A thread willCondvar::notify_all
will only wake up a single thread and requeue theMutex
. This avoids a thundering herdRwLock
supports atomically downgrading a write lock into a read lock.Mutex
and RwLock
allow raw unlocking without a RAII guard object.Mutex<()>
and RwLock<()>
allow raw locking without a RAII guardMutex
and RwLock
support eventual fairnessReentrantMutex
type which supports recursive locking.Mutex
,RwLock
and ReentrantMutex
. This feature is disabled by default anddeadlock_detection
feature.RwLock
supports atomically upgrading an "upgradable" read lock into aserde
. NOTE! this support is for Mutex
, ReentrantMutex
,RwLock
only; Condvar
and Once
are not currently supported.send_guard
feature isTo keep these primitives small, all thread queuing and suspending
functionality is offloaded to the parking lot. The idea behind this is
based on the Webkit WTF::ParkingLot
class, which essentially consists of a hash table mapping of lock addresses
to queues of parked (sleeping) threads. The Webkit parking lot was itself
inspired by Linux futexes,
but it is more powerful since it allows invoking callbacks while holding a queue
lock.
There are a few restrictions when using this library on stable Rust:
wasm32-unknown-unknown
target is only fully supported on nightly with-C target-feature=+atomics
in RUSTFLAGS
and -Zbuild-std=panic_abort,std
-C target-feature=+atomics
on stable as thatTo enable nightly-only functionality, you need to enable the nightly
feature
in Cargo (see below).
Add this to your Cargo.toml
:
[dependencies]
parking_lot = "0.12"
To enable nightly-only features, add this to your Cargo.toml
instead:
[dependencies]
parking_lot = { version = "0.12", features = ["nightly"] }
The experimental deadlock detector can be enabled with the
deadlock_detection
Cargo feature.
To allow sending MutexGuard
s and RwLock*Guard
s to other threads, enable the
send_guard
option.
Note that the deadlock_detection
and send_guard
features are incompatible
and cannot be used together.
Hardware lock elision support for x86 can be enabled with the
hardware-lock-elision
feature. This requires Rust 1.59 due to the use of
inline assembly.
The core parking lot API is provided by the parking_lot_core
crate. It is
separate from the synchronization primitives in the parking_lot
crate so that
changes to the core API do not cause breaking changes for users of parking_lot
.
The current minimum required Rust version is 1.56. Any change to this is considered a breaking change and will require a major version bump.
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.