Struct wgpu_core::device::life::LifetimeTracker

pub(crate) struct LifetimeTracker {
    mapped: Vec<Arc<Buffer>>,
    active: Vec<ActiveSubmission>,
    ready_to_map: Vec<Arc<Buffer>>,
    work_done_closures: SmallVec<[SubmittedWorkDoneClosure; 1]>,
    pub device_lost_closure: Option<DeviceLostClosure>,
}

Resource tracking for a device.

Host mapping buffers

A buffer cannot be mapped until all active queue submissions that use it have completed. To that end:

• Each buffer’s ResourceInfo::submission_index records the index of the most recent queue submission that uses that buffer.

• Calling Global::buffer_map_async adds the buffer to self.mapped, and changes Buffer::map_state to prevent it from being used in any new submissions.

• When the device is polled, the following LifetimeTracker methods decide what should happen next:

  1. triage_mapped drains self.mapped, checking the submission index of each buffer against the queue submissions that have finished execution. Buffers used by submissions still in flight go in self.active[index].mapped, and the rest go into self.ready_to_map.

  2. triage_submissions moves entries in self.active[i] for completed submissions to self.ready_to_map. At this point, both self.active and self.ready_to_map are up to date with the given submission index.

  3. handle_mapping drains self.ready_to_map and actually maps the buffers, collecting a list of notification closures to call.

Only calling Global::buffer_map_async clones a new Arc for the buffer. This new Arc is only dropped by handle_mapping.

Fields

mapped: Vec<Arc<Buffer>>

Buffers for which a call to Buffer::map_async has succeeded, but which haven’t been examined by triage_mapped yet to decide when they can be mapped.

active: Vec<ActiveSubmission>

Resources used by queue submissions still in flight. One entry per submission, with older submissions appearing before younger.

Entries are added by track_submission and drained by LifetimeTracker::triage_submissions. Lots of methods contribute data to particular entries.

ready_to_map: Vec<Arc<Buffer>>

Buffers the user has asked us to map, and which are not used by any queue submission still in flight.

work_done_closures: SmallVec<[SubmittedWorkDoneClosure; 1]>

Queue “on_submitted_work_done” closures that were initiated for while there is no currently pending submissions. These cannot be immediately invoked as they must happen after all mapped buffer callbacks are mapped, so we defer them here until the next time the device is maintained.

device_lost_closure: Option<DeviceLostClosure>

Closure to be called on “lose the device”. This is invoked directly by device.lose or by the UserCallbacks returned from maintain when the device has been destroyed and its queues are empty.

Implementations

impl LifetimeTracker

pub fn new() -> Self

pub fn queue_empty(&self) -> bool

Return true if there are no queue submissions still in flight.

pub fn track_submission( &mut self, index: SubmissionIndex, temp_resources: impl Iterator<Item = TempResource>, encoders: Vec<EncoderInFlight>, )

Start tracking resources associated with a new queue submission.

pub(crate) fn map(&mut self, value: &Arc<Buffer>)

pub fn get_buffer_latest_submission_index( &self, buffer: &Buffer, ) -> Option<SubmissionIndex>

Returns the submission index of the most recent submission that uses the given buffer.

pub fn get_texture_latest_submission_index( &self, texture: &Texture, ) -> Option<SubmissionIndex>

Returns the submission index of the most recent submission that uses the given texture.

pub fn triage_submissions( &mut self, last_done: SubmissionIndex, command_allocator: &CommandAllocator, ) -> SmallVec<[SubmittedWorkDoneClosure; 1]>

Sort out the consequences of completed submissions.

Assume that all submissions up through last_done have completed.

• Buffers used by those submissions are now ready to map, if requested. Add any buffers in the submission’s mapped list to self.ready_to_map, where LifetimeTracker::handle_mapping will find them.

Return a list of SubmittedWorkDoneClosures to run.

pub fn schedule_resource_destruction( &mut self, temp_resource: TempResource, last_submit_index: SubmissionIndex, )

pub fn add_work_done_closure(&mut self, closure: SubmittedWorkDoneClosure)

pub(crate) fn triage_mapped(&mut self)

Determine which buffers are ready to map, and which must wait for the GPU.

See the documentation for LifetimeTracker for details.

pub(crate) fn handle_mapping( &mut self, raw: &dyn DynDevice, snatch_guard: &SnatchGuard<'_>, ) -> Vec<BufferMapPendingClosure>

Map the buffers in self.ready_to_map.

Return a list of mapping notifications to send.

See the documentation for LifetimeTracker for details.