From b74f922d22e00382d774799f919926b61b2b7ba6 Mon Sep 17 00:00:00 2001
From: Kai Ninomiya <kainino@chromium.org>
Date: Tue, 3 Dec 2024 18:46:11 -0800
Subject: [PATCH] Document that error scopes are thread-local (#454)

---
 doc/articles/Errors.md |  7 +++++++
 webgpu.h               | 11 +++++++++++
 webgpu.yml             |  9 ++++++---
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/doc/articles/Errors.md b/doc/articles/Errors.md
index 8c6fd710..3914ed8b 100644
--- a/doc/articles/Errors.md
+++ b/doc/articles/Errors.md
@@ -17,6 +17,13 @@ These errors include:
 - Enum values which are require features not enabled on the device (a [content-timeline](https://www.w3.org/TR/webgpu/#content-timeline) error in JavaScript), for example compressed texture formats.
 - Other content-timeline errors where specified.
 
+### Error Scopes {#ErrorScopes}
+
+Error scopes are used via @ref wgpuDevicePushErrorScope, @ref wgpuDevicePopErrorScope, and @ref WGPUDeviceDescriptor::uncapturedErrorCallbackInfo. These behave the same as in the JavaScript API, except for considerations around multi-threading (which JavaScript doesn't have at the time of this writing):
+
+- The error scope stack state is **thread-local**: each thread has a separate stack, which is initially empty. The error scope that captures an error depends on which thread made the API call that generated the error.
+- The UncapturedError callback receives uncaptured errors from all threads.
+
 ## Callback Error {#CallbackError}
 
 These behave similarly to the Promise-returning JavaScript APIs. Instead of there being two callbacks like in JavaScript (one for resolve and one for reject), there is a single callback which receives a status code, and depending on the status, _either_ a valid result with an empty message string (`{NULL, 0}`), _or_ an invalid result with a non-empty message string.
diff --git a/webgpu.h b/webgpu.h
index 2e17a34b..6107babe 100644
--- a/webgpu.h
+++ b/webgpu.h
@@ -3707,6 +3707,9 @@ typedef struct WGPUDeviceDescriptor {
      */
     WGPUDeviceLostCallbackInfo deviceLostCallbackInfo;
     /**
+     * Called when there is an uncaptured error on this device, from any thread.
+     * See @ref ErrorScopes.
+     *
      * The `INIT` macro sets this to @ref WGPU_UNCAPTURED_ERROR_CALLBACK_INFO_INIT.
      */
     WGPUUncapturedErrorCallbackInfo uncapturedErrorCallbackInfo;
@@ -5571,7 +5574,15 @@ WGPU_EXPORT WGPUStatus wgpuDeviceGetLimits(WGPUDevice device, WGPULimits * limit
 WGPU_EXPORT WGPUFuture wgpuDeviceGetLostFuture(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT WGPUQueue wgpuDeviceGetQueue(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT WGPUBool wgpuDeviceHasFeature(WGPUDevice device, WGPUFeatureName feature) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Pops an error scope to the current thread's error scope stack,
+ * asynchronously returning the result. See @ref ErrorScopes.
+ */
 WGPU_EXPORT WGPUFuture wgpuDevicePopErrorScope(WGPUDevice device, WGPUPopErrorScopeCallbackInfo callbackInfo) WGPU_FUNCTION_ATTRIBUTE;
+/**
+ * Pushes an error scope to the current thread's error scope stack.
+ * See @ref ErrorScopes.
+ */
 WGPU_EXPORT void wgpuDevicePushErrorScope(WGPUDevice device, WGPUErrorFilter filter) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuDeviceSetLabel(WGPUDevice device, WGPUStringView label) WGPU_FUNCTION_ATTRIBUTE;
 WGPU_EXPORT void wgpuDeviceAddRef(WGPUDevice device) WGPU_FUNCTION_ATTRIBUTE;
diff --git a/webgpu.yml b/webgpu.yml
index 26835714..9b4a5ee0 100644
--- a/webgpu.yml
+++ b/webgpu.yml
@@ -1952,7 +1952,8 @@ structs:
         type: callback.device_lost
       - name: uncaptured_error_callback_info
         doc: |
-          TODO
+          Called when there is an uncaptured error on this device, from any thread.
+          See @ref ErrorScopes.
         type: callback.uncaptured_error
   - name: extent_3D
     doc: |
@@ -4144,7 +4145,8 @@ objects:
           passed_with_ownership: true
       - name: push_error_scope
         doc: |
-          TODO
+          Pushes an error scope to the current thread's error scope stack.
+          See @ref ErrorScopes.
         args:
           - name: filter
             doc: |
@@ -4152,7 +4154,8 @@ objects:
             type: enum.error_filter
       - name: pop_error_scope
         doc: |
-          TODO
+          Pops an error scope to the current thread's error scope stack,
+          asynchronously returning the result. See @ref ErrorScopes.
         callback: callback.pop_error_scope
       - name: set_label
         doc: |