docs: Improve documentation of submission processing

Improve internal documentation for:

- `wgpu_core::device::queue::PendingSubmission`
- `wgpu_core::device::Device::is_valid` and `check_is_valid`
- `wgpu_core::device::Device::maintain`
- `wgpu_hal::vulkan::Queue::submit`
This commit is contained in:
Jim Blandy authored and Andy Leiserson committed 2026-08-14 18:59:00 -07:00
1 parent eaa3de5045
commit 61040094ef
3 files changed
+108 -18

No files matched your search

+66 -8
View File
@@ -626,24 +626,82 @@ impl WebGpuError for QueueSubmitError {
}
}
/// A partially-assembled submission.
/// A command submission in the process of being assembled.
///
/// Within `wgpu_core`, enqueuing commands for execution on the GPU is a
/// three-step process:
///
/// 1) Call [`Queue::allocate_submission`] to acquire the necessary locks,
/// assign a submission index, wrap them all up as a [`PendingSubmission`],
/// and return it.
///
/// 2) Add the command buffers to be submitted to [`executions`], and note any
/// surface textures they reference in [`surface_textures`]. Contribute to
/// [`Queue::pending_writes`] as necessary.
///
/// 3) Acquire the pending writes lock. This may be done at any point between
/// the return from [`Queue::allocate_submission`] and the call to
/// [`submit`]. Typically it should be done as late as is possible given
/// any necessary pending writes activity.
///
/// 4) Call the `PendingSubmission`'s [`submit`] method (which is a convenience
/// wrapper around [`Queue::submit_pending_submission`]). Pass the pending
/// writes mutex guard to [`submit`].
///
/// It is also acceptable to drop the `PendingSubmission` without submitting;
/// this frees its locks in the appropriate order. This may be necessary when
/// those locks are required to access the state that determines whether a
/// submission is needed at all.
///
/// This split allows the various places in `wgpu_core` that need to submit
/// commands to the GPU to share the common initial code for locking and final
/// code for actually submitting the commands to `wgpu_hal`:
///
/// - [`Queue::submit`] just submits user-constructed [`CommandBuffer`]s.
///
/// - [`Queue::prepare_surface_texture_for_present`] examines the surface
/// texture being presented, and submits deferred initialization commands and
/// barriers to get it ready.
///
/// - [`Queue::flush_writes_for_buffer`] and [`Queue::flush_pending_writes`]
/// simply submit the operations already staged in [`Queue::pending_writes`].
///
/// Returned from [`Queue::allocate_submission`] and consumed by [`submit`].
/// These are internal APIs used in `Queue::submit` and other places within
/// `wgpu-core` that need to submit work.
///
/// [`submit`]: `PendingSubmission::submit`
/// [`submit`]: PendingSubmission::submit
/// [`executions`]: PendingSubmission::executions
/// [`surface_textures`]: PendingSubmission::surface_textures
pub(crate) struct PendingSubmission<'a> {
queue: &'a Queue,
// The lock ordering checker cares about the drop order for these guards.
// These lock guards must appear in this struct in the order given.
//
// The instrumented locks in [`lock::ranked`] require that locks be acquired
// and released in a stack-like order. Since `rank::DEVICE_COMMAND_INDICES`
// follows `rank::DEVICE_SNATCHABLE_LOCK`, the lock on
// `Device::command_indices` must be released before the lock on
// `Device::snatchable_lock`. Rust drops struct members from first to last,
// so this ordering of fields ensures the order we want.
/// A guard for the lock on `Device::command_indices`.
command_index_guard: RwLockWriteGuard<'a, CommandIndices>,
/// A guard for the lock on `Device::snatchable_lock`.
snatch_guard: SnatchGuard<'a>,
// Command buffers to be executed, along with trackers for the resources they use.
/// Command buffers to be submitted, along with trackers for the resources
/// they use.
pub executions: Vec<EncoderInFlight>,
// Surface textures referenced by command buffers in this submission. These need to be
// passed to the HAL `submit` call. Deduplicated using a hashmap to avoid vulkan
// deadlocking from the same surface texture being submitted multiple times.
/// Surface textures referenced by command buffers in this submission.
///
/// These need to be passed to [`wgpu_hal::Queue::submit`], which
/// requires that the list contains no duplicates, so we store them in a
/// `HashMap` keyed by `SurfaceTexture` address.
surface_textures: FastHashMap<*const Texture, Arc<Texture>>,
/// The index this submission has been assigned.
pub index: SubmissionIndex,
}
@@ -1686,7 +1744,7 @@ impl Queue {
/// Returns the index and a [`PendingSubmission`].
///
/// The caller passes in the already-acquired [`SnatchGuard`]. This function acquires
/// the fence lock and the command index lock.
/// the command index lock.
///
/// The caller should update [`PendingSubmission::executions`] with details of the
/// submission.
+36 -8
View File
@@ -780,10 +780,25 @@ impl Device {
self.adapter.backend()
}
/// Return true if `self` is still valid.
///
/// Note that a `false` result here does *not* guarantee that no further activity will
/// occur on the `Device`. A [`Device`] can be marked invalid at any time, even while
/// locks are held, meaning that operations begun before the `Device` was marked
/// invalid will still generally run to completion. This is a consequence of
/// making [`Device::valid`] an `AtomicBool`. It could be avoided by making
/// [`Device::valid`] an ordinary `bool` field protected by the same locks that
/// all other operations acquire, but we use an `AtomicBool` because there
/// are many device validity checks and we want those to be cheap.
pub fn is_valid(&self) -> bool {
self.valid.load(Ordering::Acquire)
}
/// Return `Err(DeviceError)` if `self` is not valid. Otherwise, return `Ok(())`.
///
/// Note that an `Err` result here does *not* guarantee that no further activity will
/// occur on the `Device`. See the documentation for [`is_valid`][Self::is_valid] for
/// details.
pub fn check_is_valid(&self) -> Result<(), DeviceError> {
if self.is_valid() {
Ok(())
@@ -1035,14 +1050,27 @@ impl Device {
}
};
// Prevent new commands from being submitted as we want to act on `queue_empty`.
let command_indices = self.command_indices.read();
// Check that the device is valid. This is combined with queue empty to decide whether
// to destroy all resources. Queue.submit blocks on command indices being writable
// and rejects if invalid so if the device in now invalid, and all submissions are
// finished, there will be no more submissions.
let device_valid = self.is_valid();
drop(command_indices);
// When a device is marked invalid, we must destroy all its hal resources once its
// queue is empty, by calling `release_gpu_resources`.
//
// However, checking device validity for this purpose is tricky. A device can be
// marked invalid at any time, regardless of what locks are held. This means that,
// even though queue submission does check device validity at the start (in
// `Queue::allocate_submission`), the submission will proceed even if the
// device gets marked invalid after that check. Thus, other threads can observe
// the queue becoming non-empty even after they have observed the device to be
// invalid.
//
// In this function, for `release_gpu_resources` to work as intended, we must be
// sure that no further work can be submitted. Specifically, we must be sure that
// if we see the device marked invalid, then so will any subsequent attempts to
// submit work to the queue, causing them to fail. To accomplish this, it suffices
// to hold the same lock while we call `is_valid` that `Queue::allocate_submission`
// holds while it does the submission.
let device_valid = {
let _command_indices_guard = self.command_indices.read();
self.is_valid()
};
// Maintain all finished submissions on the queue, updating the relevant user closures and
// collecting if the queue is empty.
+6 -2
View File
@@ -1427,8 +1427,12 @@ impl crate::Queue for Queue {
let mut wait_semaphores = SemaphoreList::new(SemaphoreListMode::Wait);
let mut signal_semaphores = SemaphoreList::new(SemaphoreListMode::Signal);
// Double check that the same swapchain image isn't being given to us multiple times,
// as that will deadlock when we try to lock them all.
// Assert that we will not deadlock as we try to lock each `SurfaceTexture`'s
// metadata.
//
// The documentation for [`wgpu_hal::Queue::submit`] requires that
// `surface_textures` must not contain duplicates, so simply iterating over
// the slice and locking each one should be fine.
debug_assert!(
{
let mut check = HashSet::with_capacity(surface_textures.len());