Docs: multithreading and thread safety

doc/articles/Asynchronous Operations.md

@@ -69,3 +69,7 @@ Device events are slightly different in that their callback info (`WGPUDeviceLos
 The `WGPUUncapturedErrorCallbackInfo` _does not_ have a callback mode member. It is always as-if it were @ref WGPUCallbackMode_AllowSpontaneous. Note also that the uncaptured error callback is a _repeating_ callback that fires multiple times, unlike other callbacks in webgpu.h.
 
 The uncaptured error callback is guaranteed not to fire after the device becomes lost. When the device is lost, it is an appropriate time for the application to free userdata variables for the uncaptured error callback. Note that the device becomes lost _before_ the actual device lost callback fires. First the device state transitions to lost, then the device lost callback fires. The timing of the callback depends on the device lost callback mode.
+
+## Callback Reentrancy {#CallbackReentrancy}
+
+TODO

doc/articles/Multithreading.md

@@ -0,0 +1,43 @@
+# Multithreading {#Multithreading}
+
+`webgpu.h` implementations are allowed to require that all returned objects, except for `WGPUInstance`, can only be used from the thread they were created on, causing undefined behavior otherwise.
+
+Where multithreading is supported:
+
+- The implementation must provide the documented @ref ThreadSafety guarantees.
+- All objects must be freely usable on any thread at any time, except:
+    - Where APIs are specified as being non-thread-safe, they must mutexed.
+    - The exceptions for Wasm, below.
+- State must be thread-global, except where otherwise defined.
+    - For example, buffer map state is thread-global, and mapped memory ranges may be used from any thread.
+    - Note: Error scope state is thread-local. See @ref ErrorScopes.
+
+Native (non-Wasm) implementations **should** support multithreading.
+
+## In WebAssembly
+
+At the time of this writing, the JS WebGPU API is not multithreading-capable.
+Initial `webgpu.h` implementations will not be multithreading-capable.
+
+Wasm-on-JS implementations *may* implement multithreading by proxying calls to a single JS "thread", as long as the C API behavior is conformant.
+
+Once the JS API is multithreading-capable, there are still expected to be some thread-local behaviors:
+
+- Buffer mapping state may be thread-local.
+    - Implementations *should* make this state thread-global if feasible (e.g. by proxying all mapping calls to a single JS thread).
+- Any object which is non-shareable or non-transferable in JS may also be fully or partially non-shareable or non-transferable in Wasm (e.g. encoder objects may be thread-locked, similar to how they are not thread safe in `webgpu.h` in general). (In Rust terms, shareable = `Send`+`Sync`, transferable = `Send`.)
+    - Implementations *may* make them shareable. (For example, proxying all encoder methods to a single thread would make them fully shareable but be inefficient; alternatively, encoder commands can be buffered, which might enable some multithreaded use-cases even if `Finish()` still must happen on the thread that created the encoder.)
+
+## Thread Safety {#ThreadSafety}
+
+The `webgpu.h` API is thread-safe (when multithreading is supported). That is, its functions are reentrant and may be called during the execution of other functions, with the following exceptions:
+
+- Encoder objects (@ref WGPUCommandEncoder, @ref WGPUComputePassEncoder, @ref WGPURenderPassEncoder, and @ref WGPURenderBundleEncoder) are not thread-safe. Note these objects appear only in their own methods.
+    - Additionally, in Wasm, note these objects may be thread-locked as discussed above.
+- API calls may not be made during @ref WGPUCallbackMode_AllowSpontaneous callbacks. See @ref CallbackReentrancy.
+
+The following _are_ thread safe:
+
+- @ref wgpuInstanceWaitAny() and @ref wgpuInstanceProcessEvents
+- @ref wgpuDeviceDestroy()
+- @ref wgpuBufferDestroy(), @ref wgpuTextureDestroy(), and @ref wgpuQuerySetDestroy()

doc/articles/index.md

@@ -7,3 +7,4 @@
 - \subpage SentinelValues
 - \subpage Strings
 - \subpage StructChaining
+- \subpage Multithreading