1 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
2 #![cfg_attr(docsrs, feature(doc_cfg))]
3 #![deny(missing_docs)]
4
5 //! This crate provides [spin-based](https://en.wikipedia.org/wiki/Spinlock) versions of the
6 //! primitives in `std::sync` and `std::lazy`. Because synchronization is done through spinning,
7 //! the primitives are suitable for use in `no_std` environments.
8 //!
9 //! # Features
10 //!
11 //! - `Mutex`, `RwLock`, `Once`/`SyncOnceCell`, and `SyncLazy` equivalents
12 //!
13 //! - Support for `no_std` environments
14 //!
15 //! - [`lock_api`](https://crates.io/crates/lock_api) compatibility
16 //!
17 //! - Upgradeable `RwLock` guards
18 //!
19 //! - Guards can be sent and shared between threads
20 //!
21 //! - Guard leaking
22 //!
23 //! - Ticket locks
24 //!
25 //! - Different strategies for dealing with contention
26 //!
27 //! # Relationship with `std::sync`
28 //!
29 //! While `spin` is not a drop-in replacement for `std::sync` (and
30 //! [should not be considered as such](https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html))
31 //! an effort is made to keep this crate reasonably consistent with `std::sync`.
32 //!
33 //! Many of the types defined in this crate have 'additional capabilities' when compared to `std::sync`:
34 //!
35 //! - Because spinning does not depend on the thread-driven model of `std::sync`, guards ([`MutexGuard`],
36 //! [`RwLockReadGuard`], [`RwLockWriteGuard`], etc.) may be sent and shared between threads.
37 //!
38 //! - [`RwLockUpgradableGuard`] supports being upgraded into a [`RwLockWriteGuard`].
39 //!
40 //! - Guards support [leaking](https://doc.rust-lang.org/nomicon/leaking.html).
41 //!
42 //! - [`Once`] owns the value returned by its `call_once` initializer.
43 //!
44 //! - [`RwLock`] supports counting readers and writers.
45 //!
46 //! Conversely, the types in this crate do not have some of the features `std::sync` has:
47 //!
48 //! - Locks do not track [panic poisoning](https://doc.rust-lang.org/nomicon/poisoning.html).
49 //!
50 //! ## Feature flags
51 //!
52 //! The crate comes with a few feature flags that you may wish to use.
53 //!
54 //! - `lock_api` enables support for [`lock_api`](https://crates.io/crates/lock_api)
55 //!
56 //! - `ticket_mutex` uses a ticket lock for the implementation of `Mutex`
57 //!
58 //! - `fair_mutex` enables a fairer implementation of `Mutex` that uses eventual fairness to avoid
59 //! starvation
60 //!
61 //! - `std` enables support for thread yielding instead of spinning
62
63 #[cfg(any(test, feature = "std"))]
64 extern crate core;
65
66 #[cfg(feature = "portable_atomic")]
67 extern crate portable_atomic;
68
69 #[cfg(not(feature = "portable_atomic"))]
70 use core::sync::atomic;
71 #[cfg(feature = "portable_atomic")]
72 use portable_atomic as atomic;
73
74 #[cfg(feature = "barrier")]
75 #[cfg_attr(docsrs, doc(cfg(feature = "barrier")))]
76 pub mod barrier;
77 #[cfg(feature = "lazy")]
78 #[cfg_attr(docsrs, doc(cfg(feature = "lazy")))]
79 pub mod lazy;
80 #[cfg(feature = "mutex")]
81 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
82 pub mod mutex;
83 #[cfg(feature = "once")]
84 #[cfg_attr(docsrs, doc(cfg(feature = "once")))]
85 pub mod once;
86 pub mod relax;
87 #[cfg(feature = "rwlock")]
88 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
89 pub mod rwlock;
90
91 #[cfg(feature = "mutex")]
92 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
93 pub use mutex::MutexGuard;
94 #[cfg(feature = "std")]
95 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
96 pub use relax::Yield;
97 pub use relax::{RelaxStrategy, Spin};
98 #[cfg(feature = "rwlock")]
99 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
100 pub use rwlock::RwLockReadGuard;
101
102 // Avoid confusing inference errors by aliasing away the relax strategy parameter. Users that need to use a different
103 // relax strategy can do so by accessing the types through their fully-qualified path. This is a little bit horrible
104 // but sadly adding a default type parameter is *still* a breaking change in Rust (for understandable reasons).
105
106 /// A primitive that synchronizes the execution of multiple threads. See [`barrier::Barrier`] for documentation.
107 ///
108 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
109 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
110 #[cfg(feature = "barrier")]
111 #[cfg_attr(docsrs, doc(cfg(feature = "barrier")))]
112 pub type Barrier = crate::barrier::Barrier;
113
114 /// A value which is initialized on the first access. See [`lazy::Lazy`] for documentation.
115 ///
116 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
117 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
118 #[cfg(feature = "lazy")]
119 #[cfg_attr(docsrs, doc(cfg(feature = "lazy")))]
120 pub type Lazy<T, F = fn() -> T> = crate::lazy::Lazy<T, F>;
121
122 /// A primitive that synchronizes the execution of multiple threads. See [`mutex::Mutex`] for documentation.
123 ///
124 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
125 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
126 #[cfg(feature = "mutex")]
127 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
128 pub type Mutex<T> = crate::mutex::Mutex<T>;
129
130 /// A primitive that provides lazy one-time initialization. See [`once::Once`] for documentation.
131 ///
132 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
133 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
134 #[cfg(feature = "once")]
135 #[cfg_attr(docsrs, doc(cfg(feature = "once")))]
136 pub type Once<T = ()> = crate::once::Once<T>;
137
138 /// A lock that provides data access to either one writer or many readers. See [`rwlock::RwLock`] for documentation.
139 ///
140 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
141 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
142 #[cfg(feature = "rwlock")]
143 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
144 pub type RwLock<T> = crate::rwlock::RwLock<T>;
145
146 /// A guard that provides immutable data access but can be upgraded to [`RwLockWriteGuard`]. See
147 /// [`rwlock::RwLockUpgradableGuard`] for documentation.
148 ///
149 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
150 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
151 #[cfg(feature = "rwlock")]
152 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
153 pub type RwLockUpgradableGuard<'a, T> = crate::rwlock::RwLockUpgradableGuard<'a, T>;
154
155 /// A guard that provides mutable data access. See [`rwlock::RwLockWriteGuard`] for documentation.
156 ///
157 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax
158 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path.
159 #[cfg(feature = "rwlock")]
160 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
161 pub type RwLockWriteGuard<'a, T> = crate::rwlock::RwLockWriteGuard<'a, T>;
162
163 /// Spin synchronisation primitives, but compatible with [`lock_api`](https://crates.io/crates/lock_api).
164 #[cfg(feature = "lock_api")]
165 #[cfg_attr(docsrs, doc(cfg(feature = "lock_api")))]
166 pub mod lock_api {
167 /// A lock that provides mutually exclusive data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
168 #[cfg(feature = "mutex")]
169 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
170 pub type Mutex<T> = lock_api_crate::Mutex<crate::Mutex<()>, T>;
171
172 /// A guard that provides mutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
173 #[cfg(feature = "mutex")]
174 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))]
175 pub type MutexGuard<'a, T> = lock_api_crate::MutexGuard<'a, crate::Mutex<()>, T>;
176
177 /// A lock that provides data access to either one writer or many readers (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
178 #[cfg(feature = "rwlock")]
179 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
180 pub type RwLock<T> = lock_api_crate::RwLock<crate::RwLock<()>, T>;
181
182 /// A guard that provides immutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
183 #[cfg(feature = "rwlock")]
184 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
185 pub type RwLockReadGuard<'a, T> = lock_api_crate::RwLockReadGuard<'a, crate::RwLock<()>, T>;
186
187 /// A guard that provides mutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
188 #[cfg(feature = "rwlock")]
189 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
190 pub type RwLockWriteGuard<'a, T> = lock_api_crate::RwLockWriteGuard<'a, crate::RwLock<()>, T>;
191
192 /// A guard that provides immutable data access but can be upgraded to [`RwLockWriteGuard`] (compatible with [`lock_api`](https://crates.io/crates/lock_api)).
193 #[cfg(feature = "rwlock")]
194 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))]
195 pub type RwLockUpgradableReadGuard<'a, T> =
196 lock_api_crate::RwLockUpgradableReadGuard<'a, crate::RwLock<()>, T>;
197 }
198
199 /// In the event of an invalid operation, it's best to abort the current process.
200 #[cfg(feature = "fair_mutex")]
abort() -> !201 fn abort() -> ! {
202 #[cfg(not(feature = "std"))]
203 {
204 // Panicking while panicking is defined by Rust to result in an abort.
205 struct Panic;
206
207 impl Drop for Panic {
208 fn drop(&mut self) {
209 panic!("aborting due to invalid operation");
210 }
211 }
212
213 let _panic = Panic;
214 panic!("aborting due to invalid operation");
215 }
216
217 #[cfg(feature = "std")]
218 {
219 std::process::abort();
220 }
221 }
222