diff --git a/wgpu-core/src/device/queue.rs b/wgpu-core/src/device/queue.rs index 1008f0168..f7da650da 100644 --- a/wgpu-core/src/device/queue.rs +++ b/wgpu-core/src/device/queue.rs @@ -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, - // 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>, + + /// 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. diff --git a/wgpu-core/src/device/resource.rs b/wgpu-core/src/device/resource.rs index 2d6b26a14..27eb6dbcd 100644 --- a/wgpu-core/src/device/resource.rs +++ b/wgpu-core/src/device/resource.rs @@ -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. diff --git a/wgpu-hal/src/vulkan/mod.rs b/wgpu-hal/src/vulkan/mod.rs index 04efc6fa5..0afcd854a 100644 --- a/wgpu-hal/src/vulkan/mod.rs +++ b/wgpu-hal/src/vulkan/mod.rs @@ -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());