Asynchronous operations in webgpu.h return a WGPUFuture. This is an opaque handle which applications may use to poll or wait for completion of the asynchronous operation.
On all implementations of webgpu.h, it must be possible to react to async operations without undue latency or spin-waiting.
All asynchronous operations start when the application calls an asynchronous webgpu.h function. These functions return WGPUFuture
, and take in their arguments a CallbackInfo
struct like WGPURequestDeviceCallbackInfo or WGPUBufferMapCallbackInfo. CallbackInfo
structs have the following members:
WGPUChainedStruct const * nextInChain
pointer, for extensions.mode
enum.callback
function pointer. For example: void* userdata1
void* userdata2
The callback
function pointer is called when the application observes completion of the asynchronous operation. The userdata1
and userdata2
members are passed back to the application as the last two arguments in the callback function. Callbacks might not be called unless the application explicitly flushes them in order to observe completion. The point in time a callback is called depends on the WGPUCallbackMode of the operation. webgpu.h provides three callback modes: WGPUCallbackMode_WaitAnyOnly
, WGPUCallbackMode_AllowProcessEvents
, and WGPUCallbackMode_AllowSpontaneous
.
0x00000001
Callbacks created withWGPUCallbackMode_WaitAnyOnly
:
fire when the asynchronous operation's future is passed to a call to
wgpuInstanceWaitAny
AND the operation has already completed or it completes inside the call towgpuInstanceWaitAny
.
0x00000002
Callbacks created withWGPUCallbackMode_AllowProcessEvents
:- fire for the same reasons as callbacks created with
WGPUCallbackMode_WaitAnyOnly
fire inside a call to
wgpuInstanceProcessEvents
if the asynchronous operation is complete.
0x00000003
Callbacks created withWGPUCallbackMode_AllowSpontaneous
:- fire for the same reasons as callbacks created with
WGPUCallbackMode_AllowProcessEvents
may fire spontaneously on an arbitrary or application thread, when the WebGPU implementations discovers that the asynchronous operation is complete.
Implementations should fire spontaneous callbacks as soon as possible.
- Note
- Because spontaneous callbacks may fire at an arbitrary time on an arbitrary thread, applications should take extra care when acquiring locks or mutating state inside the callback. It undefined behavior to re-entrantly call into the webgpu.h API if the callback fires while inside the callstack of another webgpu.h function that is not
wgpuInstanceWaitAny
orwgpuInstanceProcessEvents
.
WGPUWaitStatus wgpuInstanceWaitAny(WGPUInstance, size_t futureCount, WGPUFutureWaitInfo * futures, uint64_t timeoutNS)
Waits on any WGPUFuture in the list of futures
to complete for timeoutNS
nanoseconds. Returns when at least one WGPUFuture
is completed or timeoutNS
elapses, whichever is first. If timeoutNS
is zero, all futures
are polled once, without blocking.
Returns WGPUWaitStatus_Success
if at least one WGPUFuture
completes. WGPUFutureWaitInfo::completed is set to true for all completed futures. See WGPUWaitStatus for other status codes.
Within this call, for any WGPUFuture
s that completed, their respective callbacks will fire.
Use of timed waits (timeoutNS > 0
), must be enabled on the WGPUInstance in wgpuCreateInstance
with WGPUInstanceFeatures::timedWaitAnyEnable
, and the number of futures waited on must be less than or equal to WGPUInstanceFeatures::timedWaitAnyMaxCount
. Supported instance features may be queried using wgpuGetInstanceFeatures
.
Asynchronous operations may originate from different sources. There are CPU-timeline operations and there are Queue-timeline operations. Within a timed wait, it is only valid to wait on WGPUFuture
s originating from a single WGPUQueue
. Waiting on two futures from different queues, or waiting on a Queue-timeline future and some other CPU-timeline future is an error.
void wgpuInstanceProcessEvents(WGPUInstance)
Processes asynchronous events on this WGPUInstance
, calling any callbacks for asynchronous operations created with WGPUCallbackMode_AllowProcessEvents
that have completed. This is a non-blocking operation.
Device events are slightly different in that their callback info (WGPUDeviceLostCallbackInfo
and WGPUUncapturedErrorCallbackInfo
) are passed on the WGPUDeviceDescriptor
, instead of in a function argument. There is no WGPUFuture
returned for either callback.
The WGPUUncapturedErrorCallbackInfo
does not have a callback mode member. It is always as-if it were 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.