| 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)] |
| 26 |
pub 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. |
| 44 |
macro_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 |
|
| 99 |
define_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_VIEWS "Texture::views" followed by { } |
| 149 |
rank BLAS_BUILT_INDEX "Blas::built_index" followed by { } |
| 150 |
rank TLAS_BUILT_INDEX "Tlas::built_index" followed by { } |
| 151 |
rank TLAS_DEPENDENCIES "Tlas::dependencies" followed by { } |
| 152 |
rank BUFFER_POOL "BufferPool::buffers" followed by { } |
| 153 |
|
| 154 |
#[cfg(test)] |
| 155 |
rank PAWN "pawn" followed by { ROOK, BISHOP } |
| 156 |
#[cfg(test)] |
| 157 |
rank ROOK "rook" followed by { KNIGHT } |
| 158 |
#[cfg(test)] |
| 159 |
rank KNIGHT "knight" followed by { } |
| 160 |
#[cfg(test)] |
| 161 |
rank BISHOP "bishop" followed by { } |
| 162 |
} |