Fix async WebGPU ops to settle promises on the calling runtime (#425)

wcandillon · web-flow · commit d282af7e4d7f · 2026-07-17T08:43:56.000+02:00
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUAdapter.cpp b/packages/webgpu/cpp/rnwgpu/api/GPUAdapter.cpp
@@ -23,6 +23,7 @@
 namespace rnwgpu {
 
 async::AsyncTaskHandle GPUAdapter::requestDevice(
+    jsi::Runtime &runtime,
     std::optional<std::shared_ptr<GPUDeviceDescriptor>> descriptor) {
   // Enable the react-native-wgpu "native-texture" umbrella by default, mirroring
   // the web where importExternalTexture is core and needs no feature request.
@@ -135,9 +136,15 @@ async::AsyncTaskHandle GPUAdapter::requestDevice(
       descriptor.has_value() ? descriptor.value()->label.value_or("") : "";
 
   auto creationRuntime = getCreationRuntime();
-  return _async->postTask(
+  // Post to the CALLING runtime's context so the promise settles on the
+  // thread that requested it (see GPUBuffer::mapAsync). The GPUDevice is also
+  // bound to this context, honoring the contract that a device belongs to the
+  // runtime that requested it.
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask(
       [this, aDescriptor, descriptor, label = std::move(label),
-       deviceLostBinding,
+       deviceLostBinding, context,
        creationRuntime](const async::AsyncTaskHandle::ResolveFunction &resolve,
                         const async::AsyncTaskHandle::RejectFunction &reject) {
         // Build a local mutable copy so we can chain Dawn's device toggles.
@@ -193,7 +200,7 @@ async::AsyncTaskHandle GPUAdapter::requestDevice(
         }
         _instance.RequestDevice(
             &deviceDesc, wgpu::CallbackMode::AllowProcessEvents,
-            [context = _async, resolve, reject, label, creationRuntime,
+            [context, resolve, reject, label, creationRuntime,
              deviceLostBinding](wgpu::RequestDeviceStatus status,
                                 wgpu::Device device, wgpu::StringView message) {
               if (message.length) {
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUAdapter.h b/packages/webgpu/cpp/rnwgpu/api/GPUAdapter.h
@@ -33,17 +33,18 @@ class GPUAdapter : public NativeObject<GPUAdapter> {
 public:
   std::string getBrand() { return CLASS_NAME; }
 
-  async::AsyncTaskHandle
-  requestDevice(std::optional<std::shared_ptr<GPUDeviceDescriptor>> descriptor);
+  async::AsyncTaskHandle requestDevice(
+      jsi::Runtime &runtime,
+      std::optional<std::shared_ptr<GPUDeviceDescriptor>> descriptor);
 
   std::unordered_set<std::string> getFeatures();
   std::shared_ptr<GPUSupportedLimits> getLimits();
   std::shared_ptr<GPUAdapterInfo> getInfo();
 
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installGetter(runtime, prototype, "__brand", &GPUAdapter::getBrand);
-    installMethod(runtime, prototype, "requestDevice",
-                  &GPUAdapter::requestDevice);
+    installMethodWithRuntime(runtime, prototype, "requestDevice",
+                             &GPUAdapter::requestDevice);
     installGetter(runtime, prototype, "features", &GPUAdapter::getFeatures);
     installGetter(runtime, prototype, "limits", &GPUAdapter::getLimits);
     installGetter(runtime, prototype, "info", &GPUAdapter::getInfo);
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUBuffer.cpp b/packages/webgpu/cpp/rnwgpu/api/GPUBuffer.cpp
@@ -37,7 +37,8 @@ GPUBuffer::getMappedRange(std::optional<size_t> o, std::optional<size_t> size) {
 
 void GPUBuffer::destroy() { _instance.Destroy(); }
 
-async::AsyncTaskHandle GPUBuffer::mapAsync(uint64_t modeIn,
+async::AsyncTaskHandle GPUBuffer::mapAsync(jsi::Runtime &runtime,
+                                           uint64_t modeIn,
                                            std::optional<uint64_t> offset,
                                            std::optional<uint64_t> size) {
   Convertor conv;
@@ -51,7 +52,16 @@ async::AsyncTaskHandle GPUBuffer::mapAsync(uint64_t modeIn,
   auto bufferHandle = _instance;
   uint64_t resolvedOffset = offset.value_or(0);
 
-  return _async->postTask(
+  // Post to the CALLING runtime's context, not the one captured at buffer
+  // creation (_async): the buffer may have been created on another runtime and
+  // boxed across (e.g. device created on the main JS runtime, mapAsync called
+  // from a worklet). The returned Promise lives on the calling runtime, so it
+  // must be settled from that runtime's own thread — and postTask itself
+  // schedules the pump through its context's runtime (setTimeout), which is
+  // only safe for the runtime we are currently executing on.
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask(
       [bufferHandle, mode, resolvedOffset,
        rangeSize](const async::AsyncTaskHandle::ResolveFunction &resolve,
                   const async::AsyncTaskHandle::RejectFunction &reject) {
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUBuffer.h b/packages/webgpu/cpp/rnwgpu/api/GPUBuffer.h
@@ -33,7 +33,7 @@ class GPUBuffer : public NativeObject<GPUBuffer> {
 public:
   std::string getBrand() { return CLASS_NAME; }
 
-  async::AsyncTaskHandle mapAsync(uint64_t modeIn,
+  async::AsyncTaskHandle mapAsync(jsi::Runtime &runtime, uint64_t modeIn,
                                   std::optional<uint64_t> offset,
                                   std::optional<uint64_t> size);
   std::shared_ptr<ArrayBuffer> getMappedRange(std::optional<size_t> offset,
@@ -53,7 +53,8 @@ class GPUBuffer : public NativeObject<GPUBuffer> {
 
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installGetter(runtime, prototype, "__brand", &GPUBuffer::getBrand);
-    installMethod(runtime, prototype, "mapAsync", &GPUBuffer::mapAsync);
+    installMethodWithRuntime(runtime, prototype, "mapAsync",
+                             &GPUBuffer::mapAsync);
     installMethod(runtime, prototype, "getMappedRange",
                   &GPUBuffer::getMappedRange);
     installMethod(runtime, prototype, "unmap", &GPUBuffer::unmap);
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUDevice.cpp b/packages/webgpu/cpp/rnwgpu/api/GPUDevice.cpp
@@ -348,6 +348,7 @@ std::shared_ptr<GPUSharedFence> GPUDevice::importSharedFence(
 }
 
 async::AsyncTaskHandle GPUDevice::createComputePipelineAsync(
+    jsi::Runtime &runtime,
     std::shared_ptr<GPUComputePipelineDescriptor> descriptor) {
   wgpu::ComputePipelineDescriptor desc{};
   Convertor conv;
@@ -360,12 +361,16 @@ async::AsyncTaskHandle GPUDevice::createComputePipelineAsync(
       descriptor->label.has_value() ? descriptor->label.value() : "");
   auto pipelineHolder = std::make_shared<GPUComputePipeline>(nullptr, label);
 
-  return _async->postTask([device = _instance, desc, descriptor,
-                           pipelineHolder](
-                              const async::AsyncTaskHandle::ResolveFunction
-                                  &resolve,
-                              const async::AsyncTaskHandle::RejectFunction
-                                  &reject) {
+  // Post to the CALLING runtime's context so the promise settles on the
+  // thread that requested it (see GPUBuffer::mapAsync).
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask([device = _instance, desc, descriptor,
+                            pipelineHolder](
+                               const async::AsyncTaskHandle::ResolveFunction
+                                   &resolve,
+                               const async::AsyncTaskHandle::RejectFunction
+                                   &reject) {
     (void)descriptor;
     device.CreateComputePipelineAsync(
         &desc, wgpu::CallbackMode::AllowProcessEvents,
@@ -389,6 +394,7 @@ async::AsyncTaskHandle GPUDevice::createComputePipelineAsync(
 }
 
 async::AsyncTaskHandle GPUDevice::createRenderPipelineAsync(
+    jsi::Runtime &runtime,
     std::shared_ptr<GPURenderPipelineDescriptor> descriptor) {
   wgpu::RenderPipelineDescriptor desc{};
   Convertor conv;
@@ -402,12 +408,16 @@ async::AsyncTaskHandle GPUDevice::createRenderPipelineAsync(
       descriptor->label.has_value() ? descriptor->label.value() : "");
   auto pipelineHolder = std::make_shared<GPURenderPipeline>(nullptr, label);
 
-  return _async->postTask([device = _instance, desc, descriptor,
-                           pipelineHolder](
-                              const async::AsyncTaskHandle::ResolveFunction
-                                  &resolve,
-                              const async::AsyncTaskHandle::RejectFunction
-                                  &reject) {
+  // Post to the CALLING runtime's context so the promise settles on the
+  // thread that requested it (see GPUBuffer::mapAsync).
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask([device = _instance, desc, descriptor,
+                            pipelineHolder](
+                               const async::AsyncTaskHandle::ResolveFunction
+                                   &resolve,
+                               const async::AsyncTaskHandle::RejectFunction
+                                   &reject) {
     (void)descriptor;
     device.CreateRenderPipelineAsync(
         &desc, wgpu::CallbackMode::AllowProcessEvents,
@@ -433,13 +443,18 @@ void GPUDevice::pushErrorScope(wgpu::ErrorFilter filter) {
   _instance.PushErrorScope(filter);
 }
 
-async::AsyncTaskHandle GPUDevice::popErrorScope() {
+async::AsyncTaskHandle GPUDevice::popErrorScope(jsi::Runtime &runtime) {
   auto device = _instance;
 
-  return _async->postTask([device](const async::AsyncTaskHandle::ResolveFunction
-                                       &resolve,
-                                   const async::AsyncTaskHandle::RejectFunction
-                                       &reject) {
+  // Post to the CALLING runtime's context so the promise settles on the
+  // thread that requested it (see GPUBuffer::mapAsync).
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask([device](
+                               const async::AsyncTaskHandle::ResolveFunction
+                                   &resolve,
+                               const async::AsyncTaskHandle::RejectFunction
+                                   &reject) {
     device.PopErrorScope(
         wgpu::CallbackMode::AllowProcessEvents,
         [resolve, reject](wgpu::PopErrorScopeStatus status,
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUDevice.h b/packages/webgpu/cpp/rnwgpu/api/GPUDevice.h
@@ -136,8 +136,10 @@ class GPUDevice : public NativeObject<GPUDevice> {
   std::shared_ptr<GPURenderPipeline>
   createRenderPipeline(std::shared_ptr<GPURenderPipelineDescriptor> descriptor);
   async::AsyncTaskHandle createComputePipelineAsync(
+      jsi::Runtime &runtime,
       std::shared_ptr<GPUComputePipelineDescriptor> descriptor);
   async::AsyncTaskHandle createRenderPipelineAsync(
+      jsi::Runtime &runtime,
       std::shared_ptr<GPURenderPipelineDescriptor> descriptor);
   std::shared_ptr<GPUCommandEncoder> createCommandEncoder(
       std::optional<std::shared_ptr<GPUCommandEncoderDescriptor>> descriptor);
@@ -146,7 +148,7 @@ class GPUDevice : public NativeObject<GPUDevice> {
   std::shared_ptr<GPUQuerySet>
   createQuerySet(std::shared_ptr<GPUQuerySetDescriptor> descriptor);
   void pushErrorScope(wgpu::ErrorFilter filter);
-  async::AsyncTaskHandle popErrorScope();
+  async::AsyncTaskHandle popErrorScope(jsi::Runtime &runtime);
 
   std::unordered_set<std::string> getFeatures();
   std::shared_ptr<GPUSupportedLimits> getLimits();
@@ -192,10 +194,10 @@ class GPUDevice : public NativeObject<GPUDevice> {
                   &GPUDevice::createComputePipeline);
     installMethod(runtime, prototype, "createRenderPipeline",
                   &GPUDevice::createRenderPipeline);
-    installMethod(runtime, prototype, "createComputePipelineAsync",
-                  &GPUDevice::createComputePipelineAsync);
-    installMethod(runtime, prototype, "createRenderPipelineAsync",
-                  &GPUDevice::createRenderPipelineAsync);
+    installMethodWithRuntime(runtime, prototype, "createComputePipelineAsync",
+                             &GPUDevice::createComputePipelineAsync);
+    installMethodWithRuntime(runtime, prototype, "createRenderPipelineAsync",
+                             &GPUDevice::createRenderPipelineAsync);
     installMethod(runtime, prototype, "createCommandEncoder",
                   &GPUDevice::createCommandEncoder);
     installMethod(runtime, prototype, "createRenderBundleEncoder",
@@ -204,8 +206,8 @@ class GPUDevice : public NativeObject<GPUDevice> {
                   &GPUDevice::createQuerySet);
     installMethod(runtime, prototype, "pushErrorScope",
                   &GPUDevice::pushErrorScope);
-    installMethod(runtime, prototype, "popErrorScope",
-                  &GPUDevice::popErrorScope);
+    installMethodWithRuntime(runtime, prototype, "popErrorScope",
+                             &GPUDevice::popErrorScope);
     installGetter(runtime, prototype, "features", &GPUDevice::getFeatures);
     installGetter(runtime, prototype, "limits", &GPUDevice::getLimits);
     installGetter(runtime, prototype, "queue", &GPUDevice::getQueue);
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUQueue.cpp b/packages/webgpu/cpp/rnwgpu/api/GPUQueue.cpp
@@ -78,9 +78,13 @@ void GPUQueue::writeBuffer(std::shared_ptr<GPUBuffer> buffer,
                         static_cast<size_t>(size64));
 }
 
-async::AsyncTaskHandle GPUQueue::onSubmittedWorkDone() {
+async::AsyncTaskHandle GPUQueue::onSubmittedWorkDone(jsi::Runtime &runtime) {
   auto queue = _instance;
-  return _async->postTask(
+  // Post to the CALLING runtime's context so the promise settles on the
+  // thread that requested it (see GPUBuffer::mapAsync).
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask(
       [queue](const async::AsyncTaskHandle::ResolveFunction &resolve,
               const async::AsyncTaskHandle::RejectFunction &reject) {
         queue.OnSubmittedWorkDone(
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUQueue.h b/packages/webgpu/cpp/rnwgpu/api/GPUQueue.h
@@ -37,7 +37,7 @@ class GPUQueue : public NativeObject<GPUQueue> {
   std::string getBrand() { return CLASS_NAME; }
 
   void submit(std::vector<std::shared_ptr<GPUCommandBuffer>> commandBuffers);
-  async::AsyncTaskHandle onSubmittedWorkDone();
+  async::AsyncTaskHandle onSubmittedWorkDone(jsi::Runtime &runtime);
   void writeBuffer(std::shared_ptr<GPUBuffer> buffer, uint64_t bufferOffset,
                    std::shared_ptr<ArrayBuffer> data,
                    std::optional<uint64_t> dataOffsetElements,
@@ -60,8 +60,8 @@ class GPUQueue : public NativeObject<GPUQueue> {
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installGetter(runtime, prototype, "__brand", &GPUQueue::getBrand);
     installMethod(runtime, prototype, "submit", &GPUQueue::submit);
-    installMethod(runtime, prototype, "onSubmittedWorkDone",
-                  &GPUQueue::onSubmittedWorkDone);
+    installMethodWithRuntime(runtime, prototype, "onSubmittedWorkDone",
+                             &GPUQueue::onSubmittedWorkDone);
     installMethod(runtime, prototype, "writeBuffer", &GPUQueue::writeBuffer);
     installMethod(runtime, prototype, "writeTexture", &GPUQueue::writeTexture);
     installMethod(runtime, prototype, "copyExternalImageToTexture",
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUShaderModule.cpp b/packages/webgpu/cpp/rnwgpu/api/GPUShaderModule.cpp
@@ -7,10 +7,15 @@
 
 namespace rnwgpu {
 
-async::AsyncTaskHandle GPUShaderModule::getCompilationInfo() {
+async::AsyncTaskHandle
+GPUShaderModule::getCompilationInfo(jsi::Runtime &runtime) {
   auto module = _instance;
 
-  return _async->postTask(
+  // Post to the CALLING runtime's context so the promise settles on the
+  // thread that requested it (see GPUBuffer::mapAsync).
+  auto context =
+      async::RuntimeContext::getOrCreate(runtime, _async->instance());
+  return context->postTask(
       [module](const async::AsyncTaskHandle::ResolveFunction &resolve,
                const async::AsyncTaskHandle::RejectFunction &reject) {
         auto result = std::make_shared<GPUCompilationInfo>();
diff --git a/packages/webgpu/cpp/rnwgpu/api/GPUShaderModule.h b/packages/webgpu/cpp/rnwgpu/api/GPUShaderModule.h
@@ -31,7 +31,7 @@ class GPUShaderModule : public NativeObject<GPUShaderModule> {
 public:
   std::string getBrand() { return CLASS_NAME; }
 
-  async::AsyncTaskHandle getCompilationInfo();
+  async::AsyncTaskHandle getCompilationInfo(jsi::Runtime &runtime);
 
   std::string getLabel() { return _label; }
   void setLabel(const std::string &label) {
@@ -41,8 +41,8 @@ class GPUShaderModule : public NativeObject<GPUShaderModule> {
 
   static void definePrototype(jsi::Runtime &runtime, jsi::Object &prototype) {
     installGetter(runtime, prototype, "__brand", &GPUShaderModule::getBrand);
-    installMethod(runtime, prototype, "getCompilationInfo",
-                  &GPUShaderModule::getCompilationInfo);
+    installMethodWithRuntime(runtime, prototype, "getCompilationInfo",
+                             &GPUShaderModule::getCompilationInfo);
     installGetterSetter(runtime, prototype, "label", &GPUShaderModule::getLabel,
                         &GPUShaderModule::setLabel);
   }
diff --git a/packages/webgpu/cpp/rnwgpu/async/RuntimeContext.h b/packages/webgpu/cpp/rnwgpu/async/RuntimeContext.h
@@ -56,8 +56,15 @@ namespace rnwgpu::async {
  * ProcessEvents on one instance is not guaranteed reentrant.
  *
  * Threading contract: a RuntimeContext must only be pumped from the runtime it
- * was created for. Create and use a GPUDevice (and the buffers/queues derived
- * from it) on the same runtime that requested the adapter.
+ * was created for. Request/response async entry points (mapAsync,
+ * onSubmittedWorkDone, popErrorScope, createComputePipelineAsync,
+ * createRenderPipelineAsync, getCompilationInfo, requestAdapter,
+ * requestDevice) must NOT use a context captured when the object was created —
+ * the object may have been boxed across to another runtime. They resolve the
+ * CALLING runtime's context via getOrCreate(runtime, instance) so the promise
+ * is settled on the thread it was created on. Spontaneous events (device.lost,
+ * uncapturederror) remain bound to the device's own context (best-effort, main
+ * runtime only; see the class doc above).
  */
 class RuntimeContext : public std::enable_shared_from_this<RuntimeContext> {
 public:
