Skip to content
Please note that GitHub no longer supports Internet Explorer.

We recommend upgrading to the latest Microsoft Edge, Google Chrome, or Firefox.

Learn more
Compact and efficient synchronization primitives for Rust. Also provides an API for creating custom synchronization primitives.
Rust
Branch: master
Clone or download
bors and Tomasz Miąsko Merge #210
210: Synchronize on compare_exchange failure in create_hashtable r=Amanieu a=tmiasko



Co-authored-by: Tomasz Miąsko <tomasz.miasko@gmail.com>
Latest commit fa294cd Jan 22, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmark Upgrade benchmark crate to Rust 2018 Mar 31, 2019
core Synchronize on compare_exchange failure in create_hashtable Jan 22, 2020
lock_api Fix `try_lock` implementation in `lock_api` example Jan 18, 2020
src Fixed comment typo. "and" -> "an" Jan 13, 2020
.gitignore Initial commit May 13, 2016
.travis.yml Bump minimum Rust version to 1.36 Nov 4, 2019
CHANGELOG.md Fixed typo in changelog Nov 27, 2019
Cargo.toml Add changelog entries and bump versions for 0.10.0 release Nov 25, 2019
LICENSE-APACHE
LICENSE-MIT Initial commit May 13, 2016
README.md Remove usage of `extern crate` in README Nov 25, 2019
appveyor.yml Bump minimum Rust version to 1.36 Nov 4, 2019

README.md

parking_lot

Build Status Build status Crates.io

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.

Features

The primitives provided by this library have several advantages over those in the Rust standard library:

  1. Mutex and Once only require 1 byte of storage space, while Condvar and RwLock only require 1 word of storage space. On the other hand the standard library primitives require a dynamically allocated Box to hold OS-specific synchronization primitives. The small size of Mutex in particular encourages the use of fine-grained locks to increase parallelism.
  2. Since they consist of just a single atomic variable, have constant initializers and don't need destructors, these primitives can be used as static global variables. The standard library primitives require dynamic initialization and thus need to be lazily initialized with lazy_static!.
  3. Uncontended lock acquisition and release is done through fast inline paths which only require a single atomic operation.
  4. Microcontention (a contended lock with a short critical section) is efficiently handled by spinning a few times while trying to acquire a lock.
  5. The locks are adaptive and will suspend a thread after a few failed spin attempts. This makes the locks suitable for both long and short critical sections.
  6. Condvar, RwLock and Once work on Windows XP, unlike the standard library versions of those types.
  7. RwLock takes advantage of hardware lock elision on processors that support it, which can lead to huge performance wins with many readers.
  8. RwLock uses a task-fair locking policy, which avoids reader and writer starvation, whereas the standard library version makes no guarantees.
  9. Condvar is guaranteed not to produce spurious wakeups. A thread will only be woken up if it timed out or it was woken up by a notification.
  10. Condvar::notify_all will only wake up a single thread and requeue the rest to wait on the associated Mutex. This avoids a thundering herd problem where all threads try to acquire the lock at the same time.
  11. RwLock supports atomically downgrading a write lock into a read lock.
  12. Mutex and RwLock allow raw unlocking without a RAII guard object.
  13. Mutex<()> and RwLock<()> allow raw locking without a RAII guard object.
  14. Mutex and RwLock support eventual fairness which allows them to be fair on average without sacrificing performance.
  15. A ReentrantMutex type which supports recursive locking.
  16. An experimental deadlock detector that works for Mutex, RwLock and ReentrantMutex. This feature is disabled by default and can be enabled via the deadlock_detection feature.
  17. RwLock supports atomically upgrading an "upgradable" read lock into a write lock.
  18. Optional support for serde. Enable via the feature serde. NOTE! this support is for Mutex, ReentrantMutex, and RwLock only; Condvar and Once are not currently supported.

The parking lot

To 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.

Nightly vs stable

There are a few restrictions when using this library on stable Rust:

  • You will have to use lazy_static! or equivalent to statically initialize Mutex and RwLock types. They use generics and can't be const fns on stable yet.
  • RwLock will not be able to take advantage of hardware lock elision for readers, which improves performance when there are multiple readers.

To enable nightly-only functionality, you need to enable the nightly feature in Cargo (see below).

Usage

Add this to your Cargo.toml:

[dependencies]
parking_lot = "0.10"

To enable nightly-only features, add this to your Cargo.toml instead:

[dependencies]
parking_lot = { version = "0.10", features = ["nightly"] }

The experimental deadlock detector can be enabled with the deadlock_detection Cargo feature.

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.

Minimum Rust version

The current minimum required Rust version is 1.36. Any change to this is considered a breaking change and will require a major version bump.

License

Licensed under either of

at your option.

Contribution

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.

You can’t perform that action at this time.