Debian Codegraph @

third_party/rust/wgpu-core/src/lock/observing.rs

raw
1 //! Lock types that observe lock acquisition order.
2 //!
3 //! This module's [`Mutex`] type is instrumented to observe the
4 //! nesting of `wgpu-core` lock acquisitions. Whenever `wgpu-core`
5 //! acquires one lock while it is already holding another, we note
6 //! that nesting pair. This tells us what the [`LockRank::followers`]
7 //! set for each lock would need to include to accommodate
8 //! `wgpu-core`'s observed behavior.
9 //!
10 //! When `wgpu-core`'s `observe_locks` feature is enabled, if the
11 //! `WGPU_CORE_LOCK_OBSERVE_DIR` environment variable is set to the
12 //! path of an existing directory, then every thread that acquires a
13 //! lock in `wgpu-core` will write its own log file to that directory.
14 //! You can then run the `wgpu` workspace's `lock-analyzer` binary to
15 //! read those files and summarize the results. The output from
16 //! `lock-analyzer` has the same form as the lock ranks given in
17 //! [`lock/rank.rs`].
18 //!
19 //! If the `WGPU_CORE_LOCK_OBSERVE_DIR` environment variable is not
20 //! set, then no instrumentation takes place, and the locks behave
21 //! normally.
22 //!
23 //! To make sure we capture all acquisitions regardless of when the
24 //! program exits, each thread writes events directly to its log file
25 //! as they occur. A `write` system call is generally just a copy from
26 //! userspace into the kernel's buffer, so hopefully this approach
27 //! will still have tolerable performance.
28 //!
29 //! [`lock/rank.rs`]: ../../../src/wgpu_core/lock/rank.rs.html
30
31 use alloc::{format, string::String};
32 use core::{cell::RefCell, panic::Location};
33 use std::{
34 fs::File,
35 path::{Path, PathBuf},
36 };
37
38 use super::rank::{LockRank, LockRankSet};
39 use crate::FastHashSet;
40
41 /// A `Mutex` instrumented for lock acquisition order observation.
42 ///
43 /// This is just a wrapper around a [`parking_lot::Mutex`], along with
44 /// its rank in the `wgpu_core` lock ordering.
45 ///
46 /// For details, see [the module documentation][self].
47 pub struct Mutex<T> {
48 inner: parking_lot::Mutex<T>,
49 rank: LockRank,
50 }
51
52 /// A guard produced by locking [`Mutex`].
53 ///
54 /// This is just a wrapper around a [`parking_lot::MutexGuard`], along
55 /// with the state needed to track lock acquisition.
56 ///
57 /// For details, see [the module documentation][self].
58 pub struct MutexGuard<'a, T> {
59 inner: parking_lot::MutexGuard<'a, T>,
60 _state: LockStateGuard,
61 }
62
63 impl<T> Mutex<T> {
64 pub fn new(rank: LockRank, value: T) -> Mutex<T> {
65 Mutex {
66 inner: parking_lot::Mutex::new(value),
67 rank,
68 }
69 }
70
71 #[track_caller]
72 pub fn lock(&self) -> MutexGuard<T> {
73 let saved = acquire(self.rank, Location::caller());
74 MutexGuard {
75 inner: self.inner.lock(),
76 _state: LockStateGuard { saved },
77 }
78 }
79
80 pub fn into_inner(self) -> T {
81 self.inner.into_inner()
82 }
83 }
84
85 impl<'a, T> core::ops::Deref for MutexGuard<'a, T> {
86 type Target = T;
87
88 fn deref(&self) -> &Self::Target {
89 self.inner.deref()
90 }
91 }
92
93 impl<'a, T> core::ops::DerefMut for MutexGuard<'a, T> {
94 fn deref_mut(&mut self) -> &mut Self::Target {
95 self.inner.deref_mut()
96 }
97 }
98
99 impl<T: core::fmt::Debug> core::fmt::Debug for Mutex<T> {
100 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
101 self.inner.fmt(f)
102 }
103 }
104
105 /// An `RwLock` instrumented for lock acquisition order observation.
106 ///
107 /// This is just a wrapper around a [`parking_lot::RwLock`], along with
108 /// its rank in the `wgpu_core` lock ordering.
109 ///
110 /// For details, see [the module documentation][self].
111 pub struct RwLock<T> {
112 inner: parking_lot::RwLock<T>,
113 rank: LockRank,
114 }
115
116 /// A read guard produced by locking [`RwLock`] for reading.
117 ///
118 /// This is just a wrapper around a [`parking_lot::RwLockReadGuard`], along with
119 /// the state needed to track lock acquisition.
120 ///
121 /// For details, see [the module documentation][self].
122 pub struct RwLockReadGuard<'a, T> {
123 inner: parking_lot::RwLockReadGuard<'a, T>,
124 _state: LockStateGuard,
125 }
126
127 /// A write guard produced by locking [`RwLock`] for writing.
128 ///
129 /// This is just a wrapper around a [`parking_lot::RwLockWriteGuard`], along
130 /// with the state needed to track lock acquisition.
131 ///
132 /// For details, see [the module documentation][self].
133 pub struct RwLockWriteGuard<'a, T> {
134 inner: parking_lot::RwLockWriteGuard<'a, T>,
135 _state: LockStateGuard,
136 }
137
138 impl<T> RwLock<T> {
139 pub fn new(rank: LockRank, value: T) -> RwLock<T> {
140 RwLock {
141 inner: parking_lot::RwLock::new(value),
142 rank,
143 }
144 }
145
146 #[track_caller]
147 pub fn read(&self) -> RwLockReadGuard<T> {
148 let saved = acquire(self.rank, Location::caller());
149 RwLockReadGuard {
150 inner: self.inner.read(),
151 _state: LockStateGuard { saved },
152 }
153 }
154
155 #[track_caller]
156 pub fn write(&self) -> RwLockWriteGuard<T> {
157 let saved = acquire(self.rank, Location::caller());
158 RwLockWriteGuard {
159 inner: self.inner.write(),
160 _state: LockStateGuard { saved },
161 }
162 }
163 }
164
165 impl<'a, T> RwLockWriteGuard<'a, T> {
166 pub fn downgrade(this: Self) -> RwLockReadGuard<'a, T> {
167 RwLockReadGuard {
168 inner: parking_lot::RwLockWriteGuard::downgrade(this.inner),
169 _state: this._state,
170 }
171 }
172 }
173
174 impl<T: core::fmt::Debug> core::fmt::Debug for RwLock<T> {
175 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
176 self.inner.fmt(f)
177 }
178 }
179
180 impl<'a, T> core::ops::Deref for RwLockReadGuard<'a, T> {
181 type Target = T;
182
183 fn deref(&self) -> &Self::Target {
184 self.inner.deref()
185 }
186 }
187
188 impl<'a, T> core::ops::Deref for RwLockWriteGuard<'a, T> {
189 type Target = T;
190
191 fn deref(&self) -> &Self::Target {
192 self.inner.deref()
193 }
194 }
195
196 impl<'a, T> core::ops::DerefMut for RwLockWriteGuard<'a, T> {
197 fn deref_mut(&mut self) -> &mut Self::Target {
198 self.inner.deref_mut()
199 }
200 }
201
202 /// A container that restores a prior per-thread lock state when dropped.
203 ///
204 /// This type serves two purposes:
205 ///
206 /// - Operations like `RwLockWriteGuard::downgrade` would like to be able to
207 /// destructure lock guards and reassemble their pieces into new guards, but
208 /// if the guard type itself implements `Drop`, we can't destructure it
209 /// without unsafe code or pointless `Option`s whose state is almost always
210 /// statically known.
211 ///
212 /// - We can just implement `Drop` for this type once, and then use it in lock
213 /// guards, rather than implementing `Drop` separately for each guard type.
214 struct LockStateGuard {
215 /// The youngest lock that was already held when we acquired this
216 /// one, if any.
217 saved: Option<HeldLock>,
218 }
219
220 impl Drop for LockStateGuard {
221 fn drop(&mut self) {
222 release(self.saved)
223 }
224 }
225
226 /// Check and record the acquisition of a lock with `new_rank`.
227 ///
228 /// Log the acquisition of a lock with `new_rank`, and
229 /// update the per-thread state accordingly.
230 ///
231 /// Return the `Option<HeldLock>` state that must be restored when this lock is
232 /// released.
233 fn acquire(new_rank: LockRank, location: &'static Location<'static>) -> Option<HeldLock> {
234 LOCK_STATE.with_borrow_mut(|state| match *state {
235 ThreadState::Disabled => None,
236 ThreadState::Initial => {
237 let Ok(dir) = std::env::var("WGPU_CORE_LOCK_OBSERVE_DIR") else {
238 *state = ThreadState::Disabled;
239 return None;
240 };
241
242 // Create the observation log file.
243 let mut log = ObservationLog::create(dir)
244 .expect("Failed to open lock observation file (does the dir exist?)");
245
246 // Log the full set of lock ranks, so that the analysis can even see
247 // locks that are only acquired in isolation.
248 for rank in LockRankSet::all().iter() {
249 log.write_rank(rank);
250 }
251
252 // Update our state to reflect that we are logging acquisitions, and
253 // that we have acquired this lock.
254 *state = ThreadState::Enabled {
255 held_lock: Some(HeldLock {
256 rank: new_rank,
257 location,
258 }),
259 log,
260 };
261
262 // Since this is the first acquisition on this thread, we know that
263 // there is no prior lock held, and thus nothing to log yet.
264 None
265 }
266 ThreadState::Enabled {
267 ref mut held_lock,
268 ref mut log,
269 } => {
270 if let Some(ref held_lock) = held_lock {
271 log.write_acquisition(held_lock, new_rank, location);
272 }
273
274 core::mem::replace(
275 held_lock,
276 Some(HeldLock {
277 rank: new_rank,
278 location,
279 }),
280 )
281 }
282 })
283 }
284
285 /// Record the release of a lock whose saved state was `saved`.
286 fn release(saved: Option<HeldLock>) {
287 LOCK_STATE.with_borrow_mut(|state| {
288 if let ThreadState::Enabled {
289 ref mut held_lock, ..
290 } = *state
291 {
292 *held_lock = saved;
293 }
294 });
295 }
296
297 std::thread_local! {
298 static LOCK_STATE: RefCell<ThreadState> = const { RefCell::new(ThreadState::Initial) };
299 }
300
301 /// Thread-local state for lock observation.
302 enum ThreadState {
303 /// This thread hasn't yet checked the environment variable.
304 Initial,
305
306 /// This thread checked the environment variable, and it was
307 /// unset, so this thread is not observing lock acquisitions.
308 Disabled,
309
310 /// Lock observation is enabled for this thread.
311 Enabled {
312 held_lock: Option<HeldLock>,
313 log: ObservationLog,
314 },
315 }
316
317 /// Information about a currently held lock.
318 #[derive(Debug, Copy, Clone)]
319 struct HeldLock {
320 /// The lock's rank.
321 rank: LockRank,
322
323 /// Where we acquired the lock.
324 location: &'static Location<'static>,
325 }
326
327 /// A log to which we can write observations of lock activity.
328 struct ObservationLog {
329 /// The file to which we are logging lock observations.
330 log_file: File,
331
332 /// [`Location`]s we've seen so far.
333 ///
334 /// This is a hashset of raw pointers because raw pointers have
335 /// the [`Eq`] and [`Hash`] relations we want: the pointer value, not
336 /// the contents. There's no unsafe code in this module.
337 locations_seen: FastHashSet<*const Location<'static>>,
338
339 /// Buffer for serializing events, retained for allocation reuse.
340 buffer: String,
341 }
342
343 #[allow(trivial_casts)]
344 impl ObservationLog {
345 /// Create an observation log in `dir` for the current pid and thread.
346 fn create(dir: impl AsRef<Path>) -> Result<Self, std::io::Error> {
347 let mut path = PathBuf::from(dir.as_ref());
348 path.push(format!(
349 "locks-{}.{:?}.ron",
350 std::process::id(),
351 std::thread::current().id()
352 ));
353 let log_file = File::create(&path)?;
354 Ok(ObservationLog {
355 log_file,
356 locations_seen: FastHashSet::default(),
357 buffer: String::new(),
358 })
359 }
360
361 /// Record the acquisition of one lock while holding another.
362 ///
363 /// Log that we acquired a lock of `new_rank` at `new_location` while still
364 /// holding other locks, the most recently acquired of which has
365 /// `older_rank`.
366 fn write_acquisition(
367 &mut self,
368 older_lock: &HeldLock,
369 new_rank: LockRank,
370 new_location: &'static Location<'static>,
371 ) {
372 self.write_location(older_lock.location);
373 self.write_location(new_location);
374 self.write_action(&Action::Acquisition {
375 older_rank: older_lock.rank.bit.number(),
376 older_location: addr(older_lock.location),
377 newer_rank: new_rank.bit.number(),
378 newer_location: addr(new_location),
379 });
380 }
381
382 fn write_location(&mut self, location: &'static Location<'static>) {
383 if self.locations_seen.insert(location) {
384 self.write_action(&Action::Location {
385 address: addr(location),
386 file: location.file(),
387 line: location.line(),
388 column: location.column(),
389 });
390 }
391 }
392
393 fn write_rank(&mut self, rank: LockRankSet) {
394 self.write_action(&Action::Rank {
395 bit: rank.number(),
396 member_name: rank.member_name(),
397 const_name: rank.const_name(),
398 });
399 }
400
401 fn write_action(&mut self, action: &Action) {
402 use std::io::Write;
403
404 self.buffer.clear();
405 ron::ser::to_writer(&mut self.buffer, &action)
406 .expect("error serializing `lock::observing::Action`");
407 self.buffer.push('\n');
408 self.log_file
409 .write_all(self.buffer.as_bytes())
410 .expect("error writing `lock::observing::Action`");
411 }
412 }
413
414 /// An action logged by a thread that is observing lock acquisition order.
415 ///
416 /// Each thread's log file is a sequence of these enums, serialized
417 /// using the [`ron`] crate, one action per line.
418 ///
419 /// Lock observation cannot assume that there will be any convenient
420 /// finalization point before the program exits, so in practice,
421 /// actions must be written immediately when they occur. This means we
422 /// can't, say, accumulate tables and write them out when they're
423 /// complete. The `lock-analyzer` binary is then responsible for
424 /// consolidating the data into a single table of observed transitions.
425 #[derive(serde::Serialize)]
426 enum Action {
427 /// A location that we will refer to in later actions.
428 ///
429 /// We write one of these events the first time we see a
430 /// particular `Location`. Treating this as a separate action
431 /// simply lets us avoid repeating the content over and over
432 /// again in every [`Acquisition`] action.
433 ///
434 /// [`Acquisition`]: Action::Acquisition
435 Location {
436 address: usize,
437 file: &'static str,
438 line: u32,
439 column: u32,
440 },
441
442 /// A lock rank that we will refer to in later actions.
443 ///
444 /// We write out one these events for every lock rank at the
445 /// beginning of each thread's log file. Treating this as a
446 /// separate action simply lets us avoid repeating the names over
447 /// and over again in every [`Acquisition`] action.
448 ///
449 /// [`Acquisition`]: Action::Acquisition
450 Rank {
451 bit: u32,
452 member_name: &'static str,
453 const_name: &'static str,
454 },
455
456 /// An attempt to acquire a lock while holding another lock.
457 Acquisition {
458 /// The number of the already acquired lock's rank.
459 older_rank: u32,
460
461 /// The source position at which we acquired it. Specifically,
462 /// its `Location`'s address, as an integer.
463 older_location: usize,
464
465 /// The number of the rank of the lock we are acquiring.
466 newer_rank: u32,
467
468 /// The source position at which we are acquiring it.
469 /// Specifically, its `Location`'s address, as an integer.
470 newer_location: usize,
471 },
472 }
473
474 impl LockRankSet {
475 /// Return the number of this rank's first member.
476 fn number(self) -> u32 {
477 self.bits().trailing_zeros()
478 }
479 }
480
481 /// Convenience for `core::ptr::from_ref(t) as usize`.
482 fn addr<T>(t: &T) -> usize {
483 core::ptr::from_ref(t) as usize
484 }