From 458d3109168d2e94b856d166128ef67ab08353bb Mon Sep 17 00:00:00 2001 From: Andy Leiserson Date: Wed, 15 Apr 2026 16:29:59 -0700 Subject: [PATCH] docs: Update lock graph Related to #5572 --- wgpu-core/src/device/queue.rs | 3 +- wgpu-core/src/lock/rank.rs | 80 +++++++++++++++++++++++++++-------- wgpu-core/src/lock/ranked.rs | 4 ++ 3 files changed, 67 insertions(+), 20 deletions(-) diff --git a/wgpu-core/src/device/queue.rs b/wgpu-core/src/device/queue.rs index a66ff71be..157d54e80 100644 --- a/wgpu-core/src/device/queue.rs +++ b/wgpu-core/src/device/queue.rs @@ -137,8 +137,7 @@ impl Queue { .is_some_and(|mip| mip.check(0..1).is_some()) }; - // Fence lock must be acquired after the snatch lock and before - // pending_writes to match the lock ordering in Queue::submit. + // Note required lock order: snatch -> fence -> pending writes let mut fence = device.fence.write(); let mut pending_writes = self.pending_writes.lock(); diff --git a/wgpu-core/src/lock/rank.rs b/wgpu-core/src/lock/rank.rs index 527abf684..14bfd1023 100644 --- a/wgpu-core/src/lock/rank.rs +++ b/wgpu-core/src/lock/rank.rs @@ -18,6 +18,14 @@ /// `Mutex`, and its rank here is the constant /// [`COMMAND_BUFFER_DATA`]. /// +/// Building with `RUSTFLAGS="--cfg wgpu_validate_locks"`, replaces the +/// lock implementation in `lock::vanilla` with in `lock::ranked`, which +/// checks that the observed sequences of lock acquisition respect the +/// ordering defined here. +/// +/// TODO(): Resolve invalid +/// acquisitions of DEVICE_COMMAND_INDICES followed by COMMAND_BUFFER_DATA. +/// /// [`Mutex`]: parking_lot::Mutex /// [`RwLock`]: parking_lot::RwLock /// [`SnatchLock`]: crate::snatch::SnatchLock @@ -97,60 +105,96 @@ macro_rules! define_lock_ranks { } define_lock_ranks! { + // Non-leaf ranks, in topological order. rank COMMAND_BUFFER_DATA "CommandBuffer::data" followed by { DEVICE_SNATCHABLE_LOCK, - DEVICE_USAGE_SCOPES, - SHARED_TRACKER_INDEX_ALLOCATOR_INNER, BUFFER_MAP_STATE, + COMMAND_ALLOCATOR_FREE_ENCODERS, + BUFFER_POOL, + DEVICE_TRACE, + DEVICE_USAGE_SCOPES, + REGISTRY_STORAGE, + SHARED_TRACKER_INDEX_ALLOCATOR_INNER, } rank DEVICE_SNATCHABLE_LOCK "Device::snatchable_lock" followed by { - SHARED_TRACKER_INDEX_ALLOCATOR_INNER, - DEVICE_TRACE, BUFFER_MAP_STATE, + DEVICE_FENCE, + QUEUE_PENDING_WRITES, + TEXTURE_INITIALIZATION_STATUS, + QUEUE_LIFE_TRACKER, + BLAS_COMPACTION_STATE, + BUFFER_BIND_GROUPS, + BUFFER_INITIALIZATION_STATUS, + BUFFER_POOL, + DEVICE_TRACE, + DEVICE_USAGE_SCOPES, + REGISTRY_STORAGE, + SHARED_TRACKER_INDEX_ALLOCATOR_INNER, + TEXTURE_BIND_GROUPS, + TEXTURE_CLEAR_MODE, + TEXTURE_VIEWS, // Uncomment this to see an interesting cycle. // COMMAND_BUFFER_DATA, } rank BUFFER_MAP_STATE "Buffer::map_state" followed by { QUEUE_PENDING_WRITES, - SHARED_TRACKER_INDEX_ALLOCATOR_INNER, DEVICE_TRACE, + SHARED_TRACKER_INDEX_ALLOCATOR_INNER, + } + rank DEVICE_FENCE "Device::fence" followed by { + DEVICE_COMMAND_INDICES, + QUEUE_LIFE_TRACKER, + } + rank DEVICE_COMMAND_INDICES "Device::command_indices" followed by { + BUFFER_POOL, + QUEUE_PENDING_WRITES, + QUEUE_LIFE_TRACKER, + COMMAND_ALLOCATOR_FREE_ENCODERS, + DEVICE_DEFERRED_DESTROY, + SHARED_TRACKER_INDEX_ALLOCATOR_INNER, } rank QUEUE_PENDING_WRITES "Queue::pending_writes" followed by { - COMMAND_ALLOCATOR_FREE_ENCODERS, + TEXTURE_INITIALIZATION_STATUS, SHARED_TRACKER_INDEX_ALLOCATOR_INNER, - QUEUE_LIFE_TRACKER, + } + rank TEXTURE_INITIALIZATION_STATUS "Texture::initialization_status" followed by { + DEVICE_TRACKERS, + } + rank DEVICE_TRACKERS "Device::trackers" followed by { + TEXTURE_CLEAR_MODE, } rank QUEUE_LIFE_TRACKER "Queue::life_tracker" followed by { COMMAND_ALLOCATOR_FREE_ENCODERS, + DEVICE_DEFERRED_DESTROY, DEVICE_TRACE, + SHARED_TRACKER_INDEX_ALLOCATOR_INNER, } rank COMMAND_ALLOCATOR_FREE_ENCODERS "CommandAllocator::free_encoders" followed by { SHARED_TRACKER_INDEX_ALLOCATOR_INNER, } + // Leaf ranks reachable from the graph above, alphabetical. + rank BLAS_COMPACTION_STATE "Blas::compaction_state" followed by { } rank BUFFER_BIND_GROUPS "Buffer::bind_groups" followed by { } rank BUFFER_INITIALIZATION_STATUS "Buffer::initialization_status" followed by { } - rank DEVICE_COMMAND_INDICES "Device::command_indices" followed by {} - rank DEVICE_DEFERRED_DESTROY "Device::deferred_destroy" followed by {} - rank DEVICE_FENCE "Device::fence" followed by { } + rank BUFFER_POOL "BufferPool::buffers" followed by { } + rank DEVICE_DEFERRED_DESTROY "Device::deferred_destroy" followed by { } rank DEVICE_TRACE "Device::trace" followed by { } - rank DEVICE_TRACKERS "Device::trackers" followed by { } - rank DEVICE_LOST_CLOSURE "Device::device_lost_closure" followed by { } rank DEVICE_USAGE_SCOPES "Device::usage_scopes" followed by { } - rank IDENTITY_MANAGER_VALUES "IdentityManager::values" followed by { } rank REGISTRY_STORAGE "Registry::storage" followed by { } - rank RESOURCE_POOL_INNER "ResourcePool::inner" followed by { } rank SHARED_TRACKER_INDEX_ALLOCATOR_INNER "SharedTrackerIndexAllocator::inner" followed by { } - rank SURFACE_PRESENTATION "Surface::presentation" followed by { } rank TEXTURE_BIND_GROUPS "Texture::bind_groups" followed by { } - rank TEXTURE_INITIALIZATION_STATUS "Texture::initialization_status" followed by { } rank TEXTURE_CLEAR_MODE "Texture::clear_mode" followed by { } rank TEXTURE_VIEWS "Texture::views" followed by { } + + // Ranks not connected to the graph, alphabetical. rank BLAS_BUILT_INDEX "Blas::built_index" followed by { } - rank BLAS_COMPACTION_STATE "Blas::compaction_size" followed by { } + rank DEVICE_LOST_CLOSURE "Device::device_lost_closure" followed by { } + rank IDENTITY_MANAGER_VALUES "IdentityManager::values" followed by { } + rank RESOURCE_POOL_INNER "ResourcePool::inner" followed by { } + rank SURFACE_PRESENTATION "Surface::presentation" followed by { } rank TLAS_BUILT_INDEX "Tlas::built_index" followed by { } rank TLAS_DEPENDENCIES "Tlas::dependencies" followed by { } - rank BUFFER_POOL "BufferPool::buffers" followed by { } #[cfg(test)] rank PAWN "pawn" followed by { ROOK, BISHOP } diff --git a/wgpu-core/src/lock/ranked.rs b/wgpu-core/src/lock/ranked.rs index b633872ac..2e68b04dd 100644 --- a/wgpu-core/src/lock/ranked.rs +++ b/wgpu-core/src/lock/ranked.rs @@ -192,6 +192,10 @@ impl Mutex { saved: LockStateGuard(saved), } } + + pub fn into_inner(self) -> T { + self.inner.into_inner() + } } impl<'a, T> ops::Deref for MutexGuard<'a, T> {