rustc_data_structures/
sync.rs

1//! This module defines various operations and types that are implemented in
2//! one way for the serial compiler, and another way the parallel compiler.
3//!
4//! Operations
5//! ----------
6//! The parallel versions of operations use Rayon to execute code in parallel,
7//! while the serial versions degenerate straightforwardly to serial execution.
8//! The operations include `join`, `parallel`, `par_iter`, and `par_for_each`.
9//!
10//! Types
11//! -----
12//! The parallel versions of types provide various kinds of synchronization,
13//! while the serial compiler versions do not.
14//!
15//! The following table shows how the types are implemented internally. Except
16//! where noted otherwise, the type in column one is defined as a
17//! newtype around the type from column two or three.
18//!
19//! | Type                    | Serial version      | Parallel version                |
20//! | ----------------------- | ------------------- | ------------------------------- |
21//! | `Lock<T>`               | `RefCell<T>`        | `RefCell<T>` or                 |
22//! |                         |                     | `parking_lot::Mutex<T>`         |
23//! | `RwLock<T>`             | `RefCell<T>`        | `parking_lot::RwLock<T>`        |
24//! | `MTLock<T>`        [^1] | `T`                 | `Lock<T>`                       |
25//!
26//! [^1]: `MTLock` is similar to `Lock`, but the serial version avoids the cost
27//! of a `RefCell`. This is appropriate when interior mutability is not
28//! required.
29
30use std::collections::HashMap;
31use std::hash::{BuildHasher, Hash};
32
33pub use parking_lot::{
34    MappedRwLockReadGuard as MappedReadGuard, MappedRwLockWriteGuard as MappedWriteGuard,
35    RwLockReadGuard as ReadGuard, RwLockWriteGuard as WriteGuard,
36};
37
38pub use self::atomic::AtomicU64;
39pub use self::freeze::{FreezeLock, FreezeReadGuard, FreezeWriteGuard};
40#[doc(no_inline)]
41pub use self::lock::{Lock, LockGuard, Mode};
42pub use self::mode::{is_dyn_thread_safe, set_dyn_thread_safe_mode};
43pub use self::parallel::{
44    broadcast, join, par_for_each_in, par_map, parallel_guard, scope, spawn, try_par_for_each_in,
45};
46pub use self::vec::{AppendOnlyIndexVec, AppendOnlyVec};
47pub use self::worker_local::{Registry, WorkerLocal};
48pub use crate::marker::*;
49
50mod freeze;
51mod lock;
52mod parallel;
53mod vec;
54mod worker_local;
55
56/// Keep the conditional imports together in a submodule, so that import-sorting
57/// doesn't split them up.
58mod atomic {
59    // Most hosts can just use a regular AtomicU64.
60    #[cfg(target_has_atomic = "64")]
61    pub use std::sync::atomic::AtomicU64;
62
63    // Some 32-bit hosts don't have AtomicU64, so use a fallback.
64    #[cfg(not(target_has_atomic = "64"))]
65    pub use portable_atomic::AtomicU64;
66}
67
68mod mode {
69    use std::sync::atomic::{AtomicU8, Ordering};
70
71    const UNINITIALIZED: u8 = 0;
72    const DYN_NOT_THREAD_SAFE: u8 = 1;
73    const DYN_THREAD_SAFE: u8 = 2;
74
75    static DYN_THREAD_SAFE_MODE: AtomicU8 = AtomicU8::new(UNINITIALIZED);
76
77    // Whether thread safety is enabled (due to running under multiple threads).
78    #[inline]
79    pub fn is_dyn_thread_safe() -> bool {
80        match DYN_THREAD_SAFE_MODE.load(Ordering::Relaxed) {
81            DYN_NOT_THREAD_SAFE => false,
82            DYN_THREAD_SAFE => true,
83            _ => panic!("uninitialized dyn_thread_safe mode!"),
84        }
85    }
86
87    // Whether thread safety might be enabled.
88    #[inline]
89    pub(super) fn might_be_dyn_thread_safe() -> bool {
90        DYN_THREAD_SAFE_MODE.load(Ordering::Relaxed) != DYN_NOT_THREAD_SAFE
91    }
92
93    // Only set by the `-Z threads` compile option
94    pub fn set_dyn_thread_safe_mode(mode: bool) {
95        let set: u8 = if mode { DYN_THREAD_SAFE } else { DYN_NOT_THREAD_SAFE };
96        let previous = DYN_THREAD_SAFE_MODE.compare_exchange(
97            UNINITIALIZED,
98            set,
99            Ordering::Relaxed,
100            Ordering::Relaxed,
101        );
102
103        // Check that the mode was either uninitialized or was already set to the requested mode.
104        assert!(previous.is_ok() || previous == Err(set));
105    }
106}
107
108// FIXME(parallel_compiler): Get rid of these aliases across the compiler.
109
110#[derive(Debug, Default)]
111pub struct MTLock<T>(Lock<T>);
112
113impl<T> MTLock<T> {
114    #[inline(always)]
115    pub fn new(inner: T) -> Self {
116        MTLock(Lock::new(inner))
117    }
118
119    #[inline(always)]
120    pub fn into_inner(self) -> T {
121        self.0.into_inner()
122    }
123
124    #[inline(always)]
125    pub fn get_mut(&mut self) -> &mut T {
126        self.0.get_mut()
127    }
128
129    #[inline(always)]
130    pub fn lock(&self) -> LockGuard<'_, T> {
131        self.0.lock()
132    }
133
134    #[inline(always)]
135    pub fn lock_mut(&self) -> LockGuard<'_, T> {
136        self.lock()
137    }
138}
139
140/// This makes locks panic if they are already held.
141/// It is only useful when you are running in a single thread
142const ERROR_CHECKING: bool = false;
143
144#[derive(Default)]
145#[repr(align(64))]
146pub struct CacheAligned<T>(pub T);
147
148pub trait HashMapExt<K, V> {
149    /// Same as HashMap::insert, but it may panic if there's already an
150    /// entry for `key` with a value not equal to `value`
151    fn insert_same(&mut self, key: K, value: V);
152}
153
154impl<K: Eq + Hash, V: Eq, S: BuildHasher> HashMapExt<K, V> for HashMap<K, V, S> {
155    fn insert_same(&mut self, key: K, value: V) {
156        self.entry(key).and_modify(|old| assert!(*old == value)).or_insert(value);
157    }
158}
159
160#[derive(Debug, Default)]
161pub struct RwLock<T>(parking_lot::RwLock<T>);
162
163impl<T> RwLock<T> {
164    #[inline(always)]
165    pub fn new(inner: T) -> Self {
166        RwLock(parking_lot::RwLock::new(inner))
167    }
168
169    #[inline(always)]
170    pub fn into_inner(self) -> T {
171        self.0.into_inner()
172    }
173
174    #[inline(always)]
175    pub fn get_mut(&mut self) -> &mut T {
176        self.0.get_mut()
177    }
178
179    #[inline(always)]
180    pub fn read(&self) -> ReadGuard<'_, T> {
181        if ERROR_CHECKING {
182            self.0.try_read().expect("lock was already held")
183        } else {
184            self.0.read()
185        }
186    }
187
188    #[inline(always)]
189    pub fn try_write(&self) -> Result<WriteGuard<'_, T>, ()> {
190        self.0.try_write().ok_or(())
191    }
192
193    #[inline(always)]
194    pub fn write(&self) -> WriteGuard<'_, T> {
195        if ERROR_CHECKING {
196            self.0.try_write().expect("lock was already held")
197        } else {
198            self.0.write()
199        }
200    }
201
202    #[inline(always)]
203    #[track_caller]
204    pub fn borrow(&self) -> ReadGuard<'_, T> {
205        self.read()
206    }
207
208    #[inline(always)]
209    #[track_caller]
210    pub fn borrow_mut(&self) -> WriteGuard<'_, T> {
211        self.write()
212    }
213}