README.md
1parking_lot
2============
3
4[](https://travis-ci.org/Amanieu/parking_lot) [](https://ci.appveyor.com/project/Amanieu/parking-lot/branch/master) [](https://crates.io/crates/parking_lot)
5
6[Documentation (synchronization primitives)](https://docs.rs/parking_lot/)
7
8[Documentation (core parking lot API)](https://docs.rs/parking_lot_core/)
9
10[Documentation (type-safe lock API)](https://docs.rs/lock_api/)
11
12This library provides implementations of `Mutex`, `RwLock`, `Condvar` and
13`Once` that are smaller, faster and more flexible than those in the Rust
14standard library, as well as a `ReentrantMutex` type which supports recursive
15locking. It also exposes a low-level API for creating your own efficient
16synchronization primitives.
17
18When tested on x86_64 Linux, `parking_lot::Mutex` was found to be 1.5x
19faster than `std::sync::Mutex` when uncontended, and up to 5x faster when
20contended from multiple threads. The numbers for `RwLock` vary depending on
21the number of reader and writer threads, but are almost always faster than
22the standard library `RwLock`, and even up to 50x faster in some cases.
23
24## Features
25
26The primitives provided by this library have several advantages over those
27in the Rust standard library:
28
291. `Mutex` and `Once` only require 1 byte of storage space, while `Condvar`
30 and `RwLock` only require 1 word of storage space. On the other hand the
31 standard library primitives require a dynamically allocated `Box` to hold
32 OS-specific synchronization primitives. The small size of `Mutex` in
33 particular encourages the use of fine-grained locks to increase
34 parallelism.
352. Since they consist of just a single atomic variable, have constant
36 initializers and don't need destructors, these primitives can be used as
37 `static` global variables. The standard library primitives require
38 dynamic initialization and thus need to be lazily initialized with
39 `lazy_static!`.
403. Uncontended lock acquisition and release is done through fast inline
41 paths which only require a single atomic operation.
424. Microcontention (a contended lock with a short critical section) is
43 efficiently handled by spinning a few times while trying to acquire a
44 lock.
455. The locks are adaptive and will suspend a thread after a few failed spin
46 attempts. This makes the locks suitable for both long and short critical
47 sections.
486. `Condvar`, `RwLock` and `Once` work on Windows XP, unlike the standard
49 library versions of those types.
507. `RwLock` takes advantage of hardware lock elision on processors that
51 support it, which can lead to huge performance wins with many readers.
528. `RwLock` uses a task-fair locking policy, which avoids reader and writer
53 starvation, whereas the standard library version makes no guarantees.
549. `Condvar` is guaranteed not to produce spurious wakeups. A thread will
55 only be woken up if it timed out or it was woken up by a notification.
5610. `Condvar::notify_all` will only wake up a single thread and requeue the
57 rest to wait on the associated `Mutex`. This avoids a thundering herd
58 problem where all threads try to acquire the lock at the same time.
5911. `RwLock` supports atomically downgrading a write lock into a read lock.
6012. `Mutex` and `RwLock` allow raw unlocking without a RAII guard object.
6113. `Mutex<()>` and `RwLock<()>` allow raw locking without a RAII guard
62 object.
6314. `Mutex` and `RwLock` support [eventual fairness](https://trac.webkit.org/changeset/203350)
64 which allows them to be fair on average without sacrificing performance.
6515. A `ReentrantMutex` type which supports recursive locking.
6616. An *experimental* deadlock detector that works for `Mutex`,
67 `RwLock` and `ReentrantMutex`. This feature is disabled by default and
68 can be enabled via the `deadlock_detection` feature.
6917. `RwLock` supports atomically upgrading an "upgradable" read lock into a
70 write lock.
71
72## The parking lot
73
74To keep these primitives small, all thread queuing and suspending
75functionality is offloaded to the *parking lot*. The idea behind this is
76based on the Webkit [`WTF::ParkingLot`](https://webkit.org/blog/6161/locking-in-webkit/)
77class, which essentially consists of a hash table mapping of lock addresses
78to queues of parked (sleeping) threads. The Webkit parking lot was itself
79inspired by Linux [futexes](http://man7.org/linux/man-pages/man2/futex.2.html),
80but it is more powerful since it allows invoking callbacks while holding a queue
81lock.
82
83## Nightly vs stable
84
85There are a few restrictions when using this library on stable Rust:
86
87- `Mutex` and `Once` will use 1 word of space instead of 1 byte.
88- You will have to use `lazy_static!` to statically initialize `Mutex`,
89 `Condvar` and `RwLock` types instead of `const fn`.
90- `RwLock` will not be able to take advantage of hardware lock elision for
91 readers, which improves performance when there are multiple readers.
92
93To enable nightly-only functionality, you need to enable the `nightly` feature
94in Cargo (see below).
95
96## Usage
97
98Add this to your `Cargo.toml`:
99
100```toml
101[dependencies]
102parking_lot = "0.6"
103```
104
105and this to your crate root:
106
107```rust
108extern crate parking_lot;
109```
110
111To enable nightly-only features, add this to your `Cargo.toml` instead:
112
113```toml
114[dependencies]
115parking_lot = {version = "0.6", features = ["nightly"]}
116```
117
118The experimental deadlock detector can be enabled with the
119`deadlock_detection` Cargo feature.
120
121The core parking lot API is provided by the `parking_lot_core` crate. It is
122separate from the synchronization primitives in the `parking_lot` crate so that
123changes to the core API do not cause breaking changes for users of `parking_lot`.
124
125## Minimum Rust version
126
127The current minimum required Rust version is 1.24. Any change to this is
128considered a breaking change and will require a major version bump.
129
130## License
131
132Licensed under either of
133
134 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
135 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
136
137at your option.
138
139### Contribution
140
141Unless you explicitly state otherwise, any contribution intentionally submitted
142for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
143additional terms or conditions.
144
){kind=link}
){kind=link}