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 (either directly, i.e. with
21//! `RUSTFLAGS='--cfg wgpu_validate_locks'`, or via the
22//! `wgpu_validate_locks_debug` `cfg` alias in `build.rs` that conditionally
23//! enables it when debug assertions are also enabled), `wgpu-core` uses the
24//! [`ranked`] module's locks. `.config/cargo.toml` in the `wgpu` tree specifies
25//! `wgpu_validate_locks_debug`, so lock validation is active by default in
26//! `wgpu` CI and `wgpu` development trees, but not in `wgpu`-using applications
27//! unless specifically requested.
28//!
29//! If the `observe_locks` feature is enabled, `wgpu-core` uses the
30//! [`observing`] module's locks.
31//!
32//! Otherwise, `wgpu-core` uses the [`vanilla`] module's locks.
33//!
34//! [`Mutex`]: wgpu_sync::Mutex
35//! [`RwLock`]: wgpu_sync::RwLock
36//! [`SnatchLock`]: crate::snatch::SnatchLock
37
38pub mod rank;
39
40#[cfg(feature = "std")] // requires thread-locals to work
41#[cfg_attr(not(wgpu_validate_locks), allow(dead_code))]
42mod ranked;
43
44#[cfg(feature = "observe_locks")]
45#[cfg_attr(wgpu_validate_locks, allow(dead_code))]
46mod observing;
47
48#[cfg_attr(any(wgpu_validate_locks, feature = "observe_locks"), allow(dead_code))]
49mod vanilla;
50
51#[cfg(wgpu_validate_locks)]
52use ranked as chosen;
53
54#[cfg(all(not(wgpu_validate_locks), feature = "observe_locks"))]
55use observing as chosen;
56
57#[cfg(not(any(wgpu_validate_locks, feature = "observe_locks")))]
58use vanilla as chosen;
59
60pub use chosen::{Mutex, MutexGuard, RankData, RwLock, RwLockReadGuard, RwLockWriteGuard};