Skip to main content

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//! To get `ranked`, build with the `wgpu_validate_locks` config set, perhaps
21//! with `RUSTFLAGS='--cfg wgpu_validate_locks'`. The `"std"` feature must also
22//! be enabled, as `ranked` needs thread-local storage.
23//!
24//! To get `ranked` only when debug assertions are also enabled, build with the
25//! `wgpu_validate_locks_debug` config set. The `wgpu` crate selects this via
26//! its `.cargo/config.toml` file, so lock validation is active by default in
27//! `wgpu` CI and `wgpu` development trees, but not in `wgpu`-using applications
28//! unless specifically requested.
29//!
30//! To get `observing`, enable the `"observe_locks"` feature. This also enables
31//! `"std"`. You must also ensure that `wgpu_validate_locks` is not set, as that
32//! takes precedence --- and it's enabled automatically in debug builds for
33//! `wgpu`, as explained above.
34//!
35//! Otherwise, `wgpu-core` uses the [`vanilla`] module's locks.
36//!
37//! [`Mutex`]: wgpu_sync::Mutex
38//! [`RwLock`]: wgpu_sync::RwLock
39//! [`SnatchLock`]: crate::snatch::SnatchLock
40
41pub mod rank;
42
43// Include all the implementations in the build whenever they can be
44// compiled, even if they're not selected, to catch errors and help
45// `rust-analyzer` find references.
46
47#[cfg(feature = "std")] // requires thread-locals to work
48#[cfg_attr(not(wgpu_validate_locks), allow(dead_code))]
49mod ranked;
50
51// The `observing` module requires the `serde` and `ron` dependencies
52// and the "std" feature for thread-locals. All are enabled by the
53// `"observe_locks"` feature.
54#[cfg(feature = "observe_locks")]
55#[cfg_attr(wgpu_validate_locks, allow(dead_code))]
56mod observing;
57
58// If "std" is not enabled, then none of the other modules can be built.
59#[cfg_attr(
60    all(feature = "std", any(wgpu_validate_locks, feature = "observe_locks")),
61    allow(dead_code)
62)]
63mod vanilla;
64
65#[cfg(all(wgpu_validate_locks, feature = "std"))]
66use ranked as chosen;
67
68#[cfg(all(not(wgpu_validate_locks), feature = "observe_locks"))]
69use observing as chosen;
70
71// We must use `vanilla`:
72// - whenever `"std"` is not selected, and
73// - whenever neither of the instrumented locks are enabled.
74#[cfg(any(
75    not(feature = "std"),
76    not(any(wgpu_validate_locks, feature = "observe_locks"))
77))]
78use vanilla as chosen;
79
80pub use chosen::{Mutex, MutexGuard, RankData, RwLock, RwLockReadGuard, RwLockWriteGuard};