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 //! - `std` enables support for thread yielding instead of spinning 59 60 #[cfg(any(test, feature = "std"))] 61 extern crate core; 62 63 #[cfg(feature = "barrier")] 64 #[cfg_attr(docsrs, doc(cfg(feature = "barrier")))] 65 pub mod barrier; 66 #[cfg(feature = "lazy")] 67 #[cfg_attr(docsrs, doc(cfg(feature = "lazy")))] 68 pub mod lazy; 69 #[cfg(feature = "mutex")] 70 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))] 71 pub mod mutex; 72 #[cfg(feature = "once")] 73 #[cfg_attr(docsrs, doc(cfg(feature = "once")))] 74 pub mod once; 75 #[cfg(feature = "rwlock")] 76 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 77 pub mod rwlock; 78 pub mod relax; 79 80 #[cfg(feature = "mutex")] 81 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))] 82 pub use mutex::MutexGuard; 83 #[cfg(feature = "rwlock")] 84 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 85 pub use rwlock::RwLockReadGuard; 86 pub use relax::{Spin, RelaxStrategy}; 87 #[cfg(feature = "std")] 88 #[cfg_attr(docsrs, doc(cfg(feature = "std")))] 89 pub use relax::Yield; 90 91 // Avoid confusing inference errors by aliasing away the relax strategy parameter. Users that need to use a different 92 // relax strategy can do so by accessing the types through their fully-qualified path. This is a little bit horrible 93 // but sadly adding a default type parameter is *still* a breaking change in Rust (for understandable reasons). 94 95 /// A primitive that synchronizes the execution of multiple threads. See [`barrier::Barrier`] for documentation. 96 /// 97 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 98 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 99 #[cfg(feature = "barrier")] 100 #[cfg_attr(docsrs, doc(cfg(feature = "barrier")))] 101 pub type Barrier = crate::barrier::Barrier; 102 103 /// A value which is initialized on the first access. See [`lazy::Lazy`] for documentation. 104 /// 105 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 106 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 107 #[cfg(feature = "lazy")] 108 #[cfg_attr(docsrs, doc(cfg(feature = "lazy")))] 109 pub type Lazy<T, F = fn() -> T> = crate::lazy::Lazy<T, F>; 110 111 /// A primitive that synchronizes the execution of multiple threads. See [`mutex::Mutex`] for documentation. 112 /// 113 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 114 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 115 #[cfg(feature = "mutex")] 116 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))] 117 pub type Mutex<T> = crate::mutex::Mutex<T>; 118 119 /// A primitive that provides lazy one-time initialization. See [`once::Once`] for documentation. 120 /// 121 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 122 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 123 #[cfg(feature = "once")] 124 #[cfg_attr(docsrs, doc(cfg(feature = "once")))] 125 pub type Once<T = ()> = crate::once::Once<T>; 126 127 /// A lock that provides data access to either one writer or many readers. See [`rwlock::RwLock`] for documentation. 128 /// 129 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 130 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 131 #[cfg(feature = "rwlock")] 132 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 133 pub type RwLock<T> = crate::rwlock::RwLock<T>; 134 135 /// A guard that provides immutable data access but can be upgraded to [`RwLockWriteGuard`]. See 136 /// [`rwlock::RwLockUpgradableGuard`] for documentation. 137 /// 138 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 139 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 140 #[cfg(feature = "rwlock")] 141 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 142 pub type RwLockUpgradableGuard<'a, T> = crate::rwlock::RwLockUpgradableGuard<'a, T>; 143 144 /// A guard that provides mutable data access. See [`rwlock::RwLockWriteGuard`] for documentation. 145 /// 146 /// A note for advanced users: this alias exists to avoid subtle type inference errors due to the default relax 147 /// strategy type parameter. If you need a non-default relax strategy, use the fully-qualified path. 148 #[cfg(feature = "rwlock")] 149 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 150 pub type RwLockWriteGuard<'a, T> = crate::rwlock::RwLockWriteGuard<'a, T>; 151 152 /// Spin synchronisation primitives, but compatible with [`lock_api`](https://crates.io/crates/lock_api). 153 #[cfg(feature = "lock_api")] 154 #[cfg_attr(docsrs, doc(cfg(feature = "lock_api")))] 155 pub mod lock_api { 156 /// A lock that provides mutually exclusive data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)). 157 #[cfg(feature = "mutex")] 158 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))] 159 pub type Mutex<T> = lock_api_crate::Mutex<crate::Mutex<()>, T>; 160 161 /// A guard that provides mutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)). 162 #[cfg(feature = "mutex")] 163 #[cfg_attr(docsrs, doc(cfg(feature = "mutex")))] 164 pub type MutexGuard<'a, T> = lock_api_crate::MutexGuard<'a, crate::Mutex<()>, T>; 165 166 /// A lock that provides data access to either one writer or many readers (compatible with [`lock_api`](https://crates.io/crates/lock_api)). 167 #[cfg(feature = "rwlock")] 168 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 169 pub type RwLock<T> = lock_api_crate::RwLock<crate::RwLock<()>, T>; 170 171 /// A guard that provides immutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)). 172 #[cfg(feature = "rwlock")] 173 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 174 pub type RwLockReadGuard<'a, T> = lock_api_crate::RwLockReadGuard<'a, crate::RwLock<()>, T>; 175 176 /// A guard that provides mutable data access (compatible with [`lock_api`](https://crates.io/crates/lock_api)). 177 #[cfg(feature = "rwlock")] 178 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 179 pub type RwLockWriteGuard<'a, T> = lock_api_crate::RwLockWriteGuard<'a, crate::RwLock<()>, T>; 180 181 /// A guard that provides immutable data access but can be upgraded to [`RwLockWriteGuard`] (compatible with [`lock_api`](https://crates.io/crates/lock_api)). 182 #[cfg(feature = "rwlock")] 183 #[cfg_attr(docsrs, doc(cfg(feature = "rwlock")))] 184 pub type RwLockUpgradableReadGuard<'a, T> = 185 lock_api_crate::RwLockUpgradableReadGuard<'a, crate::RwLock<()>, T>; 186 } 187