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/// [`Mutex`]: parking_lot::Mutex
22/// [`RwLock`]: parking_lot::RwLock
23/// [`SnatchLock`]: crate::snatch::SnatchLock
24/// [`CommandBuffer::data`]: crate::command::CommandBuffer::data
25#[derive(Debug, Copy, Clone)]
26pub struct LockRank {
27    /// The bit representing this lock.
28    ///
29    /// There should only be a single bit set in this value.
30    pub(super) bit: LockRankSet,
31
32    /// A bitmask of permitted successor ranks.
33    ///
34    /// If `rank` is the rank of the most recently acquired lock we
35    /// are still holding, then `rank.followers` is the mask of
36    /// locks we are allowed to acquire next.
37    ///
38    /// The `define_lock_ranks!` macro ensures that there are no
39    /// cycles in the graph of lock ranks and their followers.
40    pub(super) followers: LockRankSet,
41}
42
43/// Define a set of lock ranks, and each rank's permitted successors.
44macro_rules! define_lock_ranks {
45    {
46        $(
47            $( #[ $attr:meta ] )*
48            rank $name:ident $member:literal followed by { $( $follower:ident ),* $(,)? }
49        )*
50    } => {
51        // An enum that assigns a unique number to each rank.
52        #[allow(non_camel_case_types, clippy::upper_case_acronyms)]
53        enum LockRankNumber { $( $name, )* }
54
55        bitflags::bitflags! {
56            #[derive(Debug, Copy, Clone, Eq, PartialEq)]
57            /// A bitflags type representing a set of lock ranks.
58            pub struct LockRankSet: u64 {
59                $(
60                    const $name = 1 << (LockRankNumber:: $name as u64);
61                )*
62            }
63        }
64
65        impl LockRankSet {
66            pub fn member_name(self) -> &'static str {
67                match self {
68                    $(
69                        LockRankSet:: $name => $member,
70                    )*
71                    _ => "<unrecognized LockRankSet bit>",
72                }
73            }
74
75            #[cfg_attr(not(feature = "observe_locks"), allow(dead_code))]
76            pub fn const_name(self) -> &'static str {
77                match self {
78                    $(
79                        LockRankSet:: $name => stringify!($name),
80                    )*
81                    _ => "<unrecognized LockRankSet bit>",
82                }
83            }
84        }
85
86        $(
87            // If there is any cycle in the ranking, the initializers
88            // for `followers` will be cyclic, and rustc will give us
89            // an error message explaining the cycle.
90            $( #[ $attr ] )*
91            pub const $name: LockRank = LockRank {
92                bit: LockRankSet:: $name,
93                followers: LockRankSet::empty() $( .union($follower.bit) )*,
94            };
95        )*
96    }
97}
98
99define_lock_ranks! {
100    rank COMMAND_BUFFER_DATA "CommandBuffer::data" followed by {
101        DEVICE_SNATCHABLE_LOCK,
102        DEVICE_USAGE_SCOPES,
103        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
104        BUFFER_MAP_STATE,
105    }
106    rank DEVICE_SNATCHABLE_LOCK "Device::snatchable_lock" followed by {
107        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
108        DEVICE_TRACE,
109        BUFFER_MAP_STATE,
110        // Uncomment this to see an interesting cycle.
111        // COMMAND_BUFFER_DATA,
112    }
113    rank BUFFER_MAP_STATE "Buffer::map_state" followed by {
114        QUEUE_PENDING_WRITES,
115        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
116        DEVICE_TRACE,
117    }
118    rank QUEUE_PENDING_WRITES "Queue::pending_writes" followed by {
119        COMMAND_ALLOCATOR_FREE_ENCODERS,
120        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
121        QUEUE_LIFE_TRACKER,
122    }
123    rank QUEUE_LIFE_TRACKER "Queue::life_tracker" followed by {
124        COMMAND_ALLOCATOR_FREE_ENCODERS,
125        DEVICE_TRACE,
126    }
127    rank COMMAND_ALLOCATOR_FREE_ENCODERS "CommandAllocator::free_encoders" followed by {
128        SHARED_TRACKER_INDEX_ALLOCATOR_INNER,
129    }
130
131    rank BUFFER_BIND_GROUPS "Buffer::bind_groups" followed by { }
132    rank BUFFER_INITIALIZATION_STATUS "Buffer::initialization_status" followed by { }
133    rank DEVICE_COMMAND_INDICES "Device::command_indices" followed by {}
134    rank DEVICE_DEFERRED_DESTROY "Device::deferred_destroy" followed by {}
135    rank DEVICE_FENCE "Device::fence" followed by { }
136    #[allow(dead_code)]
137    rank DEVICE_TRACE "Device::trace" followed by { }
138    rank DEVICE_TRACKERS "Device::trackers" followed by { }
139    rank DEVICE_LOST_CLOSURE "Device::device_lost_closure" followed by { }
140    rank DEVICE_USAGE_SCOPES "Device::usage_scopes" followed by { }
141    rank IDENTITY_MANAGER_VALUES "IdentityManager::values" followed by { }
142    rank REGISTRY_STORAGE "Registry::storage" followed by { }
143    rank RESOURCE_POOL_INNER "ResourcePool::inner" followed by { }
144    rank SHARED_TRACKER_INDEX_ALLOCATOR_INNER "SharedTrackerIndexAllocator::inner" followed by { }
145    rank SURFACE_PRESENTATION "Surface::presentation" followed by { }
146    rank TEXTURE_BIND_GROUPS "Texture::bind_groups" followed by { }
147    rank TEXTURE_INITIALIZATION_STATUS "Texture::initialization_status" followed by { }
148    rank TEXTURE_CLEAR_MODE "Texture::clear_mode" followed by { }
149    rank TEXTURE_VIEWS "Texture::views" followed by { }
150    rank BLAS_BUILT_INDEX "Blas::built_index" followed by { }
151    rank BLAS_COMPACTION_STATE "Blas::compaction_size" followed by { }
152    rank TLAS_BUILT_INDEX "Tlas::built_index" followed by { }
153    rank TLAS_DEPENDENCIES "Tlas::dependencies" followed by { }
154    rank BUFFER_POOL "BufferPool::buffers" followed by { }
155
156    #[cfg(test)]
157    rank PAWN "pawn" followed by { ROOK, BISHOP }
158    #[cfg(test)]
159    rank ROOK "rook" followed by { KNIGHT }
160    #[cfg(test)]
161    rank KNIGHT "knight" followed by { }
162    #[cfg(test)]
163    rank BISHOP "bishop" followed by { }
164}
wgpu_core/lock/rank.rs

wgpu_core/lock/
rank.rs
