wgpu_core/lock/mod.rs
1//! Instrumented lock types.
2//!
3//! This module defines a set of instrumented wrappers for the lock
4//! types used in `wgpu-core` ([`Mutex`], [`RwLock`], and
5//! [`SnatchLock`]) that help us understand and validate `wgpu-core`
6//! synchronization.
7//!
8//! - The [`ranked`] module defines lock types that perform run-time
9//! checks to ensure that each thread acquires locks only in a
10//! specific order, to prevent deadlocks.
11//!
12//! - The [`observing`] module defines lock types that record
13//! `wgpu-core`'s lock acquisition activity to disk, for later
14//! analysis by the `lock-analyzer` binary.
15//!
16//! - The [`vanilla`] module defines lock types that are
17//! uninstrumented, no-overhead wrappers around the standard lock
18//! types.
19//!
20//! If the `wgpu_validate_locks` config is set (for example, with
21//! `RUSTFLAGS='--cfg wgpu_validate_locks'`), `wgpu-core` uses the
22//! [`ranked`] module's locks. We hope to make this the default for
23//! debug builds soon.
24//!
25//! If the `observe_locks` feature is enabled, `wgpu-core` uses the
26//! [`observing`] module's locks.
27//!
28//! Otherwise, `wgpu-core` uses the [`vanilla`] module's locks.
29//!
30//! [`Mutex`]: parking_lot::Mutex
31//! [`RwLock`]: parking_lot::RwLock
32//! [`SnatchLock`]: crate::snatch::SnatchLock
33
34pub mod rank;
35
36#[cfg(feature = "std")] // requires thread-locals to work
37#[cfg_attr(not(wgpu_validate_locks), allow(dead_code))]
38mod ranked;
39
40#[cfg(feature = "observe_locks")]
41mod observing;
42
43#[cfg_attr(any(wgpu_validate_locks, feature = "observe_locks"), allow(dead_code))]
44mod vanilla;
45
46#[cfg(wgpu_validate_locks)]
47use ranked as chosen;
48
49#[cfg(feature = "observe_locks")]
50use observing as chosen;
51
52#[cfg(not(any(wgpu_validate_locks, feature = "observe_locks")))]
53use vanilla as chosen;
54
55pub use chosen::{Mutex, MutexGuard, RankData, RwLock, RwLockReadGuard, RwLockWriteGuard};