archive-gh-me/wgpu
1
0
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2025-12-08 21:26:17 +00:00
Code Issues Projects Releases Wiki Activity

Update comments on IdentityValues (#8183)

Browse Source
This commit is contained in:
Andy Leiserson 2025-09-09 11:14:41 -07:00 committed by GitHub
parent a9638c8e3a
commit 1791064a30
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 23 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
wgpu-core/src/identity.rs
View File

@ -32,9 +32,20 @@ enum IdSource {
/// - `IdentityValues` reuses the index values of freed ids before returning /// - `IdentityValues` reuses the index values of freed ids before returning
/// ids with new index values. Freed vector entries get reused. /// ids with new index values. Freed vector entries get reused.
/// ///
/// - The non-reuse property is achieved by storing an `epoch` alongside the
/// index in an `Id`. Index values are reused, but only with a different
/// epoch.
///
/// `IdentityValues` can also be used to track the count of IDs allocated by
/// some external allocator. Combining internal and external allocation is not
/// allowed; calling both `alloc` and `mark_as_used` on the same
/// `IdentityValues` will result in a panic. The external mode is used when
/// [playing back a trace of wgpu operations][player].
///
/// [`Id`]: crate::id::Id /// [`Id`]: crate::id::Id
/// [`alloc`]: IdentityValues::alloc /// [`alloc`]: IdentityValues::alloc
/// [`release`]: IdentityValues::release /// [`release`]: IdentityValues::release
/// [player]: https://github.com/gfx-rs/wgpu/tree/trunk/player/
#[derive(Debug)] #[derive(Debug)]
pub(super) struct IdentityValues { pub(super) struct IdentityValues {
free: Vec<(Index, Epoch)>, free: Vec<(Index, Epoch)>,
@ -47,10 +58,11 @@ pub(super) struct IdentityValues {
} }
impl IdentityValues { impl IdentityValues {
/// Allocate a fresh, never-before-seen id with the given `backend`. /// Allocate a fresh, never-before-seen ID.
/// ///
/// The backend is incorporated into the id, so that ids allocated with /// # Panics
/// different `backend` values are always distinct. ///
/// If `mark_as_used` has previously been called on this `IdentityValues`.
pub fn alloc<T: Marker>(&mut self) -> Id<T> { pub fn alloc<T: Marker>(&mut self) -> Id<T> {
assert!( assert!(
self.id_source != IdSource::External, self.id_source != IdSource::External,
@ -70,6 +82,11 @@ impl IdentityValues {
} }
} }
/// Increment the count of used IDs.
///
/// # Panics
///
/// If `alloc` has previously been called on this `IdentityValues`.
pub fn mark_as_used<T: Marker>(&mut self, id: Id<T>) -> Id<T> { pub fn mark_as_used<T: Marker>(&mut self, id: Id<T>) -> Id<T> {
assert!( assert!(
self.id_source != IdSource::Allocated, self.id_source != IdSource::Allocated,
@ -81,7 +98,9 @@ impl IdentityValues {
id id
} }
/// Free `id`. It will never be returned from `alloc` again. /// Free `id` and/or decrement the count of used IDs.
///
/// Freed IDs will never be returned from `alloc` again.
pub fn release<T: Marker>(&mut self, id: Id<T>) { pub fn release<T: Marker>(&mut self, id: Id<T>) {
if let IdSource::Allocated = self.id_source { if let IdSource::Allocated = self.id_source {
let (index, epoch) = id.unzip(); let (index, epoch) = id.unzip();