Skip to main content

Module lock

Module lock 

Source
Expand description

Instrumented lock types.

This module defines a set of instrumented wrappers for the lock types used in wgpu-core (Mutex, RwLock, and SnatchLock) that help us understand and validate wgpu-core synchronization.

  • The ranked module defines lock types that perform run-time checks to ensure that each thread acquires locks only in a specific order, to prevent deadlocks.

  • The [observing] module defines lock types that record wgpu-core’s lock acquisition activity to disk, for later analysis by the lock-analyzer binary.

  • The vanilla module defines lock types that are uninstrumented, no-overhead wrappers around the standard lock types.

To get ranked, build with the wgpu_validate_locks config set, perhaps with RUSTFLAGS='--cfg wgpu_validate_locks'. The "std" feature must also be enabled, as ranked needs thread-local storage.

To get ranked only when debug assertions are also enabled, build with the wgpu_validate_locks_debug config set. The wgpu crate selects this via its .cargo/config.toml file, so lock validation is active by default in wgpu CI and wgpu development trees, but not in wgpu-using applications unless specifically requested.

To get observing, enable the "observe_locks" feature. This also enables "std". You must also ensure that wgpu_validate_locks is not set, as that takes precedence — and it’s enabled automatically in debug builds for wgpu, as explained above.

Otherwise, wgpu-core uses the vanilla module’s locks.

Re-exports§

pub use chosen::Mutex;
pub use chosen::MutexGuard;
pub use chosen::RankData;
pub use chosen::RwLock;
pub use chosen::RwLockReadGuard;
pub use chosen::RwLockWriteGuard;

Modules§

rank
Ranks for wgpu-core locks, restricting acquisition order.
ranked 🔒 std
Lock types that enforce well-ranked lock acquisition order.
vanilla 🔒
Plain, uninstrumented wrappers around wgpu_sync lock types.