Skip to main content

wgpu_core/lock/
rank.rs

1//! Ranks for `wgpu-core` locks, restricting acquisition order.
2//!
3//! See [`LockRank`].
4
5/// The rank of a lock.
6///
7/// Each [`Mutex`], [`RwLock`], and [`SnatchLock`] in `wgpu-core` has been
8/// assigned a *rank*: a node in the DAG defined at the bottom of
9/// `wgpu-core/src/lock/rank.rs`. The rank of the most recently
10/// acquired lock you are still holding determines which locks you may
11/// attempt to acquire next.
12///
13/// When you create a lock in `wgpu-core`, you must specify its rank
14/// by passing in a [`LockRank`] value. This module declares a
15/// pre-defined set of ranks to cover everything in `wgpu-core`, named
16/// after the type in which they occur, and the name of the type's
17/// field that is a lock. For example, [`CommandBuffer::data`] is a
18/// `Mutex`, and its rank here is the constant
19/// [`COMMAND_BUFFER_DATA`].
20///
21/// Building with `RUSTFLAGS="--cfg wgpu_validate_locks"`, replaces the
22/// lock implementation in `lock::vanilla` with in `lock::ranked`, which
23/// checks that the observed sequences of lock acquisition respect the
24/// ordering defined here.
25///
26/// TODO(<https://github.com/gfx-rs/wgpu/issues/5572>): Resolve invalid
27/// acquisitions of DEVICE_COMMAND_INDICES followed by COMMAND_BUFFER_DATA.
28///
29/// [`Mutex`]: wgpu_sync::Mutex
30/// [`RwLock`]: wgpu_sync::RwLock
31/// [`SnatchLock`]: crate::snatch::SnatchLock
32/// [`CommandBuffer::data`]: crate::command::CommandBuffer::data
33#[derive(Debug, Copy, Clone)]
34pub struct LockRank {
35    /// The bit representing this lock.
36    ///
37    /// There should only be a single bit set in this value.
38    pub(super) bit: LockRankSet,
39
40    /// A bitmask of permitted successor ranks.
41    ///
42    /// If `rank` is the rank of the most recently acquired lock we
43    /// are still holding, then `rank.followers` is the mask of
44    /// locks we are allowed to acquire next.
45    ///
46    /// The `define_lock_ranks!` macro ensures that there are no
47    /// cycles in the graph of lock ranks and their followers.
48    pub(super) followers: LockRankSet,
49}
50
51/// Define a set of lock ranks, and each rank's permitted successors.
52macro_rules! define_lock_ranks {
53    {
54        $(
55            $( #[ $attr:meta ] )*
56            rank $name:ident $member:literal followed by { $( $follower:ident ),* $(,)? }
57        )*
58    } => {
59        // An enum that assigns a unique number to each rank.
60        #[allow(non_camel_case_types, clippy::upper_case_acronyms)]
61        enum LockRankNumber { $( $name, )* }
62
63        bitflags::bitflags! {
64            #[derive(Debug, Copy, Clone, Eq, PartialEq)]
65            /// A bitflags type representing a set of lock ranks.
66            pub struct LockRankSet: u64 {
67                $(
68                    const $name = 1 << (LockRankNumber:: $name as u64);
69                )*
70            }
71        }
72
73        impl LockRankSet {
74            pub fn member_name(self) -> &'static str {
75                match self {
76                    $(
77                        LockRankSet:: $name => $member,
78                    )*
79                    _ => "<unrecognized LockRankSet bit>",
80                }
81            }
82
83            #[cfg_attr(not(feature = "observe_locks"), allow(dead_code))]
84            pub fn const_name(self) -> &'static str {
85                match self {
86                    $(
87                        LockRankSet:: $name => stringify!($name),
88                    )*
89                    _ => "<unrecognized LockRankSet bit>",
90                }
91            }
92        }
93
94        $(
95            // If there is any cycle in the ranking, the initializers
96            // for `followers` will be cyclic, and rustc will give us
97            // an error message explaining the cycle.
98            $( #[ $attr ] )*
99            pub const $name: LockRank = LockRank {
100                bit: LockRankSet:: $name,
101                followers: LockRankSet::empty() $( .union($follower.bit) )*,
102            };
103        )*
104    }
105}
106
107define_lock_ranks! {
108    // Non-leaf ranks, in topological order.
109    rank INSTANCE_DEVICES "InstanceDevices" followed by {
110        DEVICE_SNATCHABLE_LOCK,
111        DEVICE_COMMAND_INDICES,
112        QUEUE_PENDING_WRITES,
113        DEVICE_TRACKERS,
114        QUEUE_LIFE_TRACKER,
115        BUFFER_BIND_GROUPS,
116        DEVICE_TRACE,
117        TEXTURE_BIND_GROUPS,
118        TEXTURE_CLEAR_MODE,
119        TEXTURE_VIEWS,
120        DEVICE_DEFERRED_DESTROY,
121        DEVICE_LOST_CLOSURE,
122    }
123    // Includes stuff from INSTANCE_DEVICES to cover Device::maintain
124    // and SHARED_TRACKER_INDEX_ALLOCATOR_INNER to cover Texture::new.
125    // We do not expect all of these to be exercised in CI.
126    rank SURFACE_PRESENTATION "Surface::presentation" followed by {
127        DEVICE_SNATCHABLE_LOCK,
128        DEVICE_COMMAND_INDICES,
129        QUEUE_PENDING_WRITES,
130        DEVICE_TRACKERS,
131        QUEUE_LIFE_TRACKER,
132        BUFFER_BIND_GROUPS,
133        DEVICE_TRACE,
134        TEXTURE_BIND_GROUPS,
135        TEXTURE_CLEAR_MODE,
136        TEXTURE_VIEWS,
137        DEVICE_DEFERRED_DESTROY,
138        DEVICE_LOST_CLOSURE,
139        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
140    }
141    rank DEVICE_SNATCHABLE_LOCK "Device::snatchable_lock" followed by {
142        BUFFER_MAP_STATE,
143        COMMAND_BUFFER_DATA,
144        DEVICE_COMMAND_INDICES,
145        QUEUE_PENDING_WRITES,
146        DEVICE_TRACKERS,
147        QUEUE_LIFE_TRACKER,
148        BLAS_COMPACTION_STATE,
149        COMMAND_ALLOCATOR_FREE_ENCODERS,
150        BUFFER_BIND_GROUPS,
151        BUFFER_INITIALIZATION_STATUS,
152        BUFFER_POOL,
153        DEVICE_LOST_CLOSURE,
154        DEVICE_TRACE,
155        DEVICE_USAGE_SCOPES,
156        QUERY_SET_INITIALIZED_SLOTS,
157        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
158        TEXTURE_BIND_GROUPS,
159        TEXTURE_CLEAR_MODE,
160        TEXTURE_INITIALIZATION_STATUS,
161        TEXTURE_VIEWS,
162    }
163    rank DEVICE_COMMAND_INDICES "Device::command_indices" followed by {
164        COMMAND_BUFFER_DATA,
165        BUFFER_MAP_STATE,
166        BUFFER_POOL,
167        DEVICE_TRACKERS,
168        QUEUE_PENDING_WRITES,
169        QUEUE_LIFE_TRACKER,
170        BLAS_COMPACTION_STATE,
171        BLAS_BUILT_INDEX,
172        COMMAND_ALLOCATOR_FREE_ENCODERS,
173        DEVICE_DEFERRED_DESTROY,
174        DEVICE_TRACE,
175        QUERY_SET_INITIALIZED_SLOTS,
176        RESOURCE_POOL_INNER,
177        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
178        TEXTURE_CLEAR_MODE,
179        TEXTURE_INITIALIZATION_STATUS,
180        TLAS_BUILT_INDEX,
181        TLAS_DEPENDENCIES,
182        TLAS_MAX_INTERSECTION_IDX,
183        TLAS_REQUIRED_INTERSECTION_TYPES,
184    }
185    rank COMMAND_BUFFER_DATA "CommandBuffer::data" followed by {
186        BUFFER_MAP_STATE,
187        COMMAND_ALLOCATOR_FREE_ENCODERS,
188        BLAS_COMPACTION_STATE,
189        BUFFER_POOL,
190        DEVICE_TRACE,
191        DEVICE_USAGE_SCOPES,
192        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
193    }
194    rank QUEUE_PENDING_WRITES "Queue::pending_writes" followed by {
195        BUFFER_MAP_STATE,
196        DEVICE_TRACKERS,
197        COMMAND_ALLOCATOR_FREE_ENCODERS,
198        BUFFER_INITIALIZATION_STATUS,
199        TEXTURE_INITIALIZATION_STATUS,
200        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
201    }
202    rank DEVICE_TRACKERS "Device::trackers" followed by {
203        BUFFER_BIND_GROUPS,
204        BUFFER_INITIALIZATION_STATUS,
205        DEVICE_DEFERRED_DESTROY,
206        TEXTURE_BIND_GROUPS,
207        TEXTURE_CLEAR_MODE,
208        TEXTURE_INITIALIZATION_STATUS,
209        TEXTURE_VIEWS,
210    }
211    rank QUEUE_LIFE_TRACKER "Queue::life_tracker" followed by {
212        BLAS_COMPACTION_STATE,
213        BUFFER_MAP_STATE,
214        COMMAND_ALLOCATOR_FREE_ENCODERS,
215        BUFFER_INITIALIZATION_STATUS,
216        BUFFER_POOL,
217        DEVICE_DEFERRED_DESTROY,
218        DEVICE_TRACE,
219        RESOURCE_POOL_INNER,
220        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
221        TEXTURE_CLEAR_MODE,
222    }
223    rank BLAS_COMPACTION_STATE "Blas::compaction_state" followed by {
224        BLAS_BUILT_INDEX,
225    }
226    rank BUFFER_MAP_STATE "Buffer::map_state" followed by {
227        BUFFER_INITIALIZATION_STATUS,
228        DEVICE_TRACE,
229        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
230    }
231    rank COMMAND_ALLOCATOR_FREE_ENCODERS "CommandAllocator::free_encoders" followed by {
232        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
233    }
234    rank TLAS_BUILT_INDEX "Tlas::built_index" followed by {
235        TLAS_DEPENDENCIES,
236    }
237    rank TLAS_DEPENDENCIES "Tlas::dependencies" followed by {
238        BLAS_BUILT_INDEX,
239    }
240
241    // Leaf ranks reachable from the graph above, alphabetical.
242    rank BLAS_BUILT_INDEX "Blas::built_index" followed by { }
243    rank BUFFER_BIND_GROUPS "Buffer::bind_groups" followed by { }
244    rank BUFFER_INITIALIZATION_STATUS "Buffer::initialization_status" followed by { }
245    rank BUFFER_POOL "BufferPool::buffers" followed by { }
246    rank DEVICE_DEFERRED_DESTROY "Device::deferred_destroy" followed by { }
247    rank DEVICE_LOST_CLOSURE "Device::device_lost_closure" followed by { }
248    rank DEVICE_TRACE "Device::trace" followed by { }
249    rank DEVICE_USAGE_SCOPES "Device::usage_scopes" followed by { }
250    rank QUERY_SET_INITIALIZED_SLOTS "QuerySet::initialized_slots" followed by { }
251    rank RESOURCE_POOL_INNER "ResourcePool::inner" followed by { }
252    rank SHARED_TRACKER_INDEX_ALLOCATOR_INNER "SharedTrackerIndexAllocator::inner" followed by { }
253    rank TEXTURE_BIND_GROUPS "Texture::bind_groups" followed by { }
254    rank TEXTURE_CLEAR_MODE "Texture::clear_mode" followed by { }
255    rank TEXTURE_INITIALIZATION_STATUS "Texture::initialization_status" followed by { }
256    rank TEXTURE_VIEWS "Texture::views" followed by { }
257    rank TLAS_MAX_INTERSECTION_IDX "Tlas::max_intersection_index" followed by { }
258    rank TLAS_REQUIRED_INTERSECTION_TYPES "Tlas::required_intersection_types" followed by { }
259
260    #[cfg(test)]
261    rank PAWN "pawn" followed by { ROOK, BISHOP }
262    #[cfg(test)]
263    rank ROOK "rook" followed by { KNIGHT }
264    #[cfg(test)]
265    rank KNIGHT "knight" followed by { }
266    #[cfg(test)]
267    rank BISHOP "bishop" followed by { }
268}