Review Comments

Author: cwfitzgerald

tests/src/init.rs

@@ -44,6 +44,11 @@ pub fn initialize_instance(backends: wgpu::Backends, force_fxc: bool) -> Instanc
             },
             gl: wgpu::GlBackendOptions {
                 fence_behavior: if cfg!(target_family = "wasm") {
+                    // On WebGL, you cannot call Poll(Wait) with any timeout. This is because the
+                    // browser does not things to block. However all of our tests are written to
+                    // expect this behavior. This is the workaround to allow this to work.
+                    //
+                    // However on native you can wait, so we want to ensure that behavior as well.
                     wgpu::GlFenceBehavior::AutoFinish
                 } else {
                     wgpu::GlFenceBehavior::Normal

wgpu-core/src/device/global.rs

@@ -1878,7 +1878,8 @@ impl Global {
                     // We're happy
                     Ok(wgt::PollStatus::QueueEmpty) => {}
                     Ok(wgt::PollStatus::WaitSucceeded) => {
-                        // After the wait, the queue should be empty.
+                        // After the wait, the queue should be empty. It can only be non-empty
+                        // if another thread is submitting at the same time.
                         break 'error E::GpuWaitTimeout;
                     }
                     Ok(wgt::PollStatus::Poll) => {

wgpu-core/src/device/resource.rs

@@ -477,7 +477,7 @@ impl Device {
         let result = if queue_empty {
             if let Some(wait_submission_index) = wait_submission_index {
                 // Assert to ensure that if we received a queue empty status, the fence shows the correct value.
-                // This is defencive, as this should never be hit.
+                // This is defensive, as this should never be hit.
                 assert!(
                     current_finished_submission >= wait_submission_index,
                     "If the queue is empty, the current submission index ({}) should be at least the wait submission index ({})",

wgpu-types/src/lib.rs

@@ -4041,7 +4041,7 @@ impl<T> PollType<T> {
     }
 }
 
-/// Error states after a poll
+/// Error states after a device poll
 #[derive(Debug)]
 #[cfg_attr(feature = "std", derive(thiserror::Error))]
 pub enum PollError {
@@ -4053,7 +4053,7 @@ pub enum PollError {
     Timeout,
 }
 
-/// Status of poll operation.
+/// Status of device poll operation.
 #[derive(Debug, PartialEq, Eq)]
 pub enum PollStatus {
     /// There are no active submissions in flight as of the beginning of the poll call.

wgpu/src/api/surface.rs

@@ -75,6 +75,13 @@ impl Surface<'_> {
 
     /// Initializes [`Surface`] for presentation.
     ///
+    /// If the surface is already configured, this will wait for the GPU to come idle
+    /// before recreating the swapchain to prevent race conditions.
+    ///
+    /// # Validation Errors
+    /// - Submissions that happen _during_ the configure may cause the
+    ///   internal wait-for-idle to fail, raising a validation error.
+    ///
     /// # Panics
     ///
     /// - A old [`SurfaceTexture`] is still alive referencing an old surface.