]>
Commit | Line | Data |
---|---|---|
83c7162d XL |
1 | // Copyright 2016 Amanieu d'Antras |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or | |
4 | // http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or | |
5 | // http://opensource.org/licenses/MIT>, at your option. This file may not be | |
6 | // copied, modified, or distributed except according to those terms. | |
7 | ||
8 | //! This library exposes a low-level API for creating your own efficient | |
9 | //! synchronization primitives. | |
10 | //! | |
11 | //! # The parking lot | |
12 | //! | |
13 | //! To keep synchronization primitives small, all thread queuing and suspending | |
14 | //! functionality is offloaded to the *parking lot*. The idea behind this is based | |
15 | //! on the Webkit [`WTF::ParkingLot`](https://webkit.org/blog/6161/locking-in-webkit/) | |
16 | //! class, which essentially consists of a hash table mapping of lock addresses | |
17 | //! to queues of parked (sleeping) threads. The Webkit parking lot was itself | |
18 | //! inspired by Linux [futexes](http://man7.org/linux/man-pages/man2/futex.2.html), | |
19 | //! but it is more powerful since it allows invoking callbacks while holding a | |
20 | //! queue lock. | |
21 | //! | |
22 | //! There are two main operations that can be performed on the parking lot: | |
23 | //! | |
24 | //! - *Parking* refers to suspending the thread while simultaneously enqueuing it | |
25 | //! on a queue keyed by some address. | |
26 | //! - *Unparking* refers to dequeuing a thread from a queue keyed by some address | |
27 | //! and resuming it. | |
28 | //! | |
29 | //! See the documentation of the individual functions for more details. | |
30 | //! | |
31 | //! # Building custom synchronization primitives | |
32 | //! | |
33 | //! Building custom synchronization primitives is very simple since the parking | |
34 | //! lot takes care of all the hard parts for you. A simple example for a | |
35 | //! custom primitive would be to integrate a `Mutex` inside another data type. | |
36 | //! Since a mutex only requires 2 bits, it can share space with other data. | |
37 | //! For example, one could create an `ArcMutex` type that combines the atomic | |
38 | //! reference count and the two mutex bits in the same atomic word. | |
39 | ||
40 | #![warn(missing_docs)] | |
e1599b0c | 41 | #![warn(rust_2018_idioms)] |
9fa01778 | 42 | #![cfg_attr( |
e1599b0c XL |
43 | all(target_env = "sgx", target_vendor = "fortanix"), |
44 | feature(sgx_platform) | |
45 | )] | |
46 | #![cfg_attr( | |
47 | all( | |
48 | feature = "nightly", | |
49 | target_arch = "wasm32", | |
50 | target_feature = "atomics" | |
51 | ), | |
72b1a166 | 52 | feature(stdsimd) |
e1599b0c XL |
53 | )] |
54 | #![cfg_attr( | |
55 | all(feature = "nightly", target_os = "cloudabi",), | |
72b1a166 | 56 | feature(thread_local) |
9fa01778 | 57 | )] |
83c7162d | 58 | |
b7449926 | 59 | mod parking_lot; |
83c7162d | 60 | mod spinwait; |
e1599b0c | 61 | mod thread_parker; |
b7449926 | 62 | mod util; |
83c7162d | 63 | mod word_lock; |
83c7162d | 64 | |
e1599b0c XL |
65 | pub use self::parking_lot::deadlock; |
66 | pub use self::parking_lot::{park, unpark_all, unpark_filter, unpark_one, unpark_requeue}; | |
67 | pub use self::parking_lot::{ | |
68 | FilterOp, ParkResult, ParkToken, RequeueOp, UnparkResult, UnparkToken, | |
69 | }; | |
70 | pub use self::parking_lot::{DEFAULT_PARK_TOKEN, DEFAULT_UNPARK_TOKEN}; | |
71 | pub use self::spinwait::SpinWait; |