Add WebGPU uncaptured-error handling and safety

Author: JimBobSquarePants

src/ImageSharp.Drawing.WebGPU/WebGPUDeviceContext.cs

@@ -104,6 +104,11 @@ internal WebGPUDeviceContext(Configuration configuration, WebGPUDeviceHandle dev
 
         this.DeviceHandle = deviceHandle;
         this.QueueHandle = queueHandle;
+
+        // Device-scoped shared state owns the uncaptured-error callback, so create it
+        // before any later surface or render-target work can report native validation errors.
+        _ = WebGPURuntime.GetOrCreateDeviceState(WebGPURuntime.GetApi(), deviceHandle);
+
         this.Backend = new WebGPUDrawingBackend();
         this.Configuration = configuration;
     }

src/ImageSharp.Drawing.WebGPU/WebGPUEnvironment.cs

@@ -9,6 +9,15 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 /// </summary>
 public static class WebGPUEnvironment
 {
+    /// <summary>
+    /// Gets or sets the callback invoked when the native WebGPU runtime reports an uncaptured device error.
+    /// </summary>
+    /// <remarks>
+    /// The callback can be raised from a native WebGPU callback thread. Keep handlers short and non-blocking.
+    /// Exceptions thrown by the handler are not propagated back through the native callback.
+    /// </remarks>
+    public static Action<WebGPUErrorType, string>? UncapturedError { get; set; }
+
     /// <summary>
     /// Probes whether the library-managed WebGPU device and queue are available.
     /// </summary>
@@ -28,4 +37,26 @@ public static WebGPUEnvironmentError ProbeAvailability()
     /// </returns>
     public static WebGPUEnvironmentError ProbeComputePipelineSupport()
         => WebGPURuntime.ProbeComputePipelineSupport();
+
+    /// <summary>
+    /// Reports one uncaptured native WebGPU error to the configured public callback.
+    /// </summary>
+    internal static void ReportUncapturedError(WebGPUErrorType errorType, string message)
+    {
+        Action<WebGPUErrorType, string>? callback = UncapturedError;
+        if (callback is null)
+        {
+            return;
+        }
+
+        try
+        {
+            callback(errorType, message);
+        }
+        catch
+        {
+            // The native WebGPU callback has no managed caller to receive exceptions.
+            // Letting them escape through the unmanaged callback boundary can terminate the process.
+        }
+    }
 }

src/ImageSharp.Drawing.WebGPU/WebGPUErrorType.cs

@@ -0,0 +1,40 @@
+// Copyright (c) Six Labors.
+// Licensed under the Six Labors Split License.
+
+namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
+
+/// <summary>
+/// Error categories reported by the native WebGPU runtime.
+/// </summary>
+public enum WebGPUErrorType
+{
+    /// <summary>
+    /// No error was reported.
+    /// </summary>
+    NoError = 0,
+
+    /// <summary>
+    /// The native runtime rejected a command or resource because it violated WebGPU validation rules.
+    /// </summary>
+    Validation = 1,
+
+    /// <summary>
+    /// The native runtime could not allocate the requested GPU resource.
+    /// </summary>
+    OutOfMemory = 2,
+
+    /// <summary>
+    /// The native runtime reported an internal implementation failure.
+    /// </summary>
+    Internal = 3,
+
+    /// <summary>
+    /// The native runtime reported an uncategorized failure.
+    /// </summary>
+    Unknown = 4,
+
+    /// <summary>
+    /// The WebGPU device was lost.
+    /// </summary>
+    DeviceLost = 5
+}

src/ImageSharp.Drawing.WebGPU/WebGPURuntime.DeviceSharedState.cs

@@ -2,6 +2,7 @@
 // Licensed under the Six Labors Split License.
 
 using System.Collections.Concurrent;
+using System.Runtime.InteropServices;
 using Silk.NET.WebGPU;
 using WgpuBuffer = Silk.NET.WebGPU.Buffer;
 
@@ -10,6 +11,7 @@ namespace SixLabors.ImageSharp.Drawing.Processing.Backends;
 internal static unsafe partial class WebGPURuntime
 {
     private static readonly ConcurrentDictionary<nint, DeviceSharedState> DeviceStateCache = new();
+    private static readonly object DeviceStateCacheSync = new();
 
     /// <summary>
     /// Gets or creates process-scoped shared resources for the specified device.
@@ -20,32 +22,34 @@ internal static unsafe partial class WebGPURuntime
     internal static DeviceSharedState GetOrCreateDeviceState(WebGPU api, WebGPUDeviceHandle deviceHandle)
     {
         nint cacheKey = deviceHandle.DangerousGetHandle();
-        if (DeviceStateCache.TryGetValue(cacheKey, out DeviceSharedState? existing))
-        {
-            return existing;
-        }
 
-        DeviceSharedState created = new(api, deviceHandle);
-        DeviceSharedState winner = DeviceStateCache.GetOrAdd(cacheKey, created);
-        if (!ReferenceEquals(winner, created))
+        lock (DeviceStateCacheSync)
         {
-            created.Dispose();
-        }
+            if (DeviceStateCache.TryGetValue(cacheKey, out DeviceSharedState? existing))
+            {
+                return existing;
+            }
 
-        return winner;
+            DeviceSharedState created = new(api, deviceHandle);
+            DeviceStateCache[cacheKey] = created;
+            return created;
+        }
     }
 
     /// <summary>
     /// Disposes all cached device-scoped shared state.
     /// </summary>
     private static void ClearDeviceStateCache()
     {
-        foreach (DeviceSharedState state in DeviceStateCache.Values)
+        lock (DeviceStateCacheSync)
         {
-            state.Dispose();
-        }
+            foreach (DeviceSharedState state in DeviceStateCache.Values)
+            {
+                state.Dispose();
+            }
 
-        DeviceStateCache.Clear();
+            DeviceStateCache.Clear();
+        }
     }
 
     /// <summary>
@@ -59,6 +63,7 @@ internal sealed class DeviceSharedState : IDisposable
         private readonly ConcurrentDictionary<string, SharedBufferInfrastructure> sharedBuffers = new(StringComparer.Ordinal);
         private readonly HashSet<FeatureName> deviceFeatures;
         private WebGPUHandle.HandleReference deviceReference;
+        private PfnErrorCallback uncapturedErrorCallback;
         private bool disposed;
 
         internal DeviceSharedState(WebGPU api, WebGPUDeviceHandle deviceHandle)
@@ -68,12 +73,15 @@ internal DeviceSharedState(WebGPU api, WebGPUDeviceHandle deviceHandle)
 
             try
             {
+                this.uncapturedErrorCallback = PfnErrorCallback.From(HandleUncapturedError);
                 this.Device = (Device*)this.deviceReference.Handle;
+                this.Api.DeviceSetUncapturedErrorCallback(this.Device, this.uncapturedErrorCallback, null);
                 this.deviceFeatures = EnumerateDeviceFeatures(api, this.Device);
                 this.MaxStorageBufferBindingSize = QueryMaxStorageBufferBindingSize(api, this.Device);
             }
             catch
             {
+                this.uncapturedErrorCallback.Dispose();
                 this.deviceReference.Dispose();
                 throw;
             }
@@ -121,6 +129,34 @@ internal DeviceSharedState(WebGPU api, WebGPUDeviceHandle deviceHandle)
         public bool HasFeature(FeatureName feature)
             => this.deviceFeatures.Contains(feature);
 
+        /// <summary>
+        /// Forwards uncaptured native WebGPU errors through the public environment callback.
+        /// </summary>
+        private static void HandleUncapturedError(ErrorType errorType, byte* message, void* userData)
+        {
+            _ = userData;
+
+            string errorMessage = message is null
+                ? string.Empty
+                : Marshal.PtrToStringUTF8((nint)message) ?? string.Empty;
+
+            WebGPUEnvironment.ReportUncapturedError(ToPublicErrorType(errorType), errorMessage);
+        }
+
+        /// <summary>
+        /// Maps Silk's native error enum to the public API enum without exposing Silk types.
+        /// </summary>
+        private static WebGPUErrorType ToPublicErrorType(ErrorType errorType)
+            => errorType switch
+            {
+                ErrorType.NoError => WebGPUErrorType.NoError,
+                ErrorType.Validation => WebGPUErrorType.Validation,
+                ErrorType.OutOfMemory => WebGPUErrorType.OutOfMemory,
+                ErrorType.Internal => WebGPUErrorType.Internal,
+                ErrorType.DeviceLost => WebGPUErrorType.DeviceLost,
+                _ => WebGPUErrorType.Unknown
+            };
+
         /// <summary>
         /// Snapshots the feature set currently reported by the native device.
         /// </summary>
@@ -190,23 +226,7 @@ public bool TryGetOrCreateCompositePipeline(
             bindGroupLayout = null;
             pipeline = null;
 
-            if (this.disposed)
-            {
-                error = "WebGPU device state is disposed.";
-                return false;
-            }
-
-            if (string.IsNullOrWhiteSpace(pipelineKey))
-            {
-                error = "Composite pipeline key cannot be empty.";
-                return false;
-            }
-
-            if (shaderCode.IsEmpty)
-            {
-                error = $"Composite shader code is missing for pipeline '{pipelineKey}'.";
-                return false;
-            }
+            ObjectDisposedException.ThrowIf(this.disposed, this);
 
             CompositePipelineInfrastructure infrastructure = this.compositePipelines.GetOrAdd(
                 pipelineKey,
@@ -276,29 +296,7 @@ public bool TryGetOrCreateCompositeComputePipeline(
             bindGroupLayout = null;
             pipeline = null;
 
-            if (this.disposed)
-            {
-                error = "WebGPU device state is disposed.";
-                return false;
-            }
-
-            if (string.IsNullOrWhiteSpace(pipelineKey))
-            {
-                error = "Composite compute pipeline key cannot be empty.";
-                return false;
-            }
-
-            if (shaderCode.IsEmpty)
-            {
-                error = $"Composite compute shader code is missing for pipeline '{pipelineKey}'.";
-                return false;
-            }
-
-            if (entryPoint.IsEmpty)
-            {
-                error = $"Composite compute entry point is missing for pipeline '{pipelineKey}'.";
-                return false;
-            }
+            ObjectDisposedException.ThrowIf(this.disposed, this);
 
             CompositeComputePipelineInfrastructure infrastructure = this.compositeComputePipelines.GetOrAdd(
                 pipelineKey,
@@ -365,23 +363,7 @@ public bool TryGetOrCreateSharedBuffer(
             buffer = null;
             capacity = 0;
 
-            if (this.disposed)
-            {
-                error = "WebGPU device state is disposed.";
-                return false;
-            }
-
-            if (string.IsNullOrWhiteSpace(bufferKey))
-            {
-                error = "Shared buffer key cannot be empty.";
-                return false;
-            }
-
-            if (requiredSize == 0)
-            {
-                error = $"Shared buffer '{bufferKey}' requires a non-zero size.";
-                return false;
-            }
+            ObjectDisposedException.ThrowIf(this.disposed, this);
 
             SharedBufferInfrastructure infrastructure = this.sharedBuffers.GetOrAdd(
                 bufferKey,
@@ -467,6 +449,10 @@ public void Dispose()
 
             this.sharedBuffers.Clear();
 
+            // Clear the native callback slot before freeing Silk's delegate thunk.
+            this.Api.DeviceSetUncapturedErrorCallback(this.Device, default, null);
+            this.uncapturedErrorCallback.Dispose();
+
             this.deviceReference.Dispose();
             this.disposed = true;
         }