feat: improve & document javascript error handling

Author: oliverbestmann

README.md

@@ -33,6 +33,10 @@ genuinely fail, such as `RequestAdapter`.
 If maintaining panic-free code is essential for your needs, there exists a
 `Try` variant for most methods, such as `TryWriteBuffer(...) error`, which allows you to handle errors without panics.
 
+### WASM
+
+Error handling in the browser's WebGPU implementation is often asynchronous. For instance, an invalid WGSL shader file will not immediately return an error or throw an exception from `CreateShaderModule`. Some errors do cause synchronous exceptions, such as missing required properties. This library attempts to address these by catching synchronous exceptions in `Try` methods, but some validation errors, like an invalid `usage` attribute for buffer creation, might be missed.
+
 ## Prebuild libraries
 
 This repository uses prebuild libraries provided by `wgpu-native`. All libraries combined are more than 512mb in size,

wgpu/buffer_js.go

@@ -26,7 +26,14 @@ func (g *Buffer) GetMappedRange(offset, size uint) []byte {
 }
 
 func (g *Buffer) TryMapAsync(mode MapMode, offset uint64, size uint64, callback BufferMapCallback) (err error) {
-	_, ok := jsx.Await(g.jsValue.Call("mapAsync", uint32(mode), offset, size))
+	defer handleJsException(&err)
+
+	// mapAsync will just return a promise
+	promise := g.jsValue.Call("mapAsync", uint32(mode), offset, size)
+
+	// TODO probably better to use .Then(...) on the promise
+	//  to schedule the callback some time in the future and not to block here
+	_, ok := jsx.Await(promise)
 	if !ok {
 		callback(MapAsyncStatusError)
 		return
@@ -37,6 +44,8 @@ func (g *Buffer) TryMapAsync(mode MapMode, offset uint64, size uint64, callback
 }
 
 func (g *Buffer) TryUnmap() (err error) {
+	defer handleJsException(&err)
+
 	g.jsValue.Call("unmap")
 	return
 }

wgpu/command_encoder_js.go

@@ -25,60 +25,71 @@ func (g *CommandEncoder) BeginComputePass(descriptor *ComputePassDescriptor) *Co
 // TryCopyBufferToBuffer as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpucommandencoder-copybuffertobuffer
 func (g *CommandEncoder) TryCopyBufferToBuffer(source *Buffer, sourceOffset uint64, destination *Buffer, destinationOffset uint64, size uint64) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("copyBufferToBuffer", pointerToJS(source), sourceOffset, pointerToJS(destination), destinationOffset, size)
 	return nil
 }
 
 // TryCopyBufferToTexture as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpucommandencoder-copybuffertotexture
 func (g *CommandEncoder) TryCopyBufferToTexture(source *TexelCopyBufferInfo, destination *TexelCopyTextureInfo, copySize *Extent3D) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("copyBufferToTexture", pointerToJS(source), pointerToJS(destination), pointerToJS(copySize))
 	return nil
 }
 
 // TryCopyTextureToBuffer as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpucommandencoder-copytexturetobuffer
 func (g *CommandEncoder) TryCopyTextureToBuffer(source *TexelCopyTextureInfo, destination *TexelCopyBufferInfo, copySize *Extent3D) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("copyTextureToBuffer", pointerToJS(source), pointerToJS(destination), pointerToJS(copySize))
 	return nil
 }
 
 // TryCopyTextureToTexture as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpucommandencoder-copytexturetotexture
 func (g *CommandEncoder) TryCopyTextureToTexture(source *TexelCopyTextureInfo, destination *TexelCopyTextureInfo, copySize *Extent3D) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("copyTextureToTexture", pointerToJS(source), pointerToJS(destination), pointerToJS(copySize))
 	return nil
 }
 
 // TryFinish as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpucommandencoder-finish
-func (g *CommandEncoder) TryFinish(descriptor *CommandBufferDescriptor) (*CommandBuffer, error) {
+func (g *CommandEncoder) TryFinish(descriptor *CommandBufferDescriptor) (_ *CommandBuffer, err error) {
+	defer handleJsException(&err)
 	jsBuffer := g.jsValue.Call("finish", pointerToJS(descriptor))
 	return &CommandBuffer{
 		jsValue: jsBuffer,
 	}, nil
 }
 
-func (g *CommandEncoder) TryClearBuffer(buffer *Buffer, offset uint64, size uint64) error {
-	panic("unimplemented")
+func (g *CommandEncoder) TryClearBuffer(buffer *Buffer, offset uint64, size uint64) (err error) {
+	defer handleJsException(&err)
+	g.jsValue.Call("clearBuffer", buffer.toJS(), offset, size)
+	return nil
 }
 
-func (g *CommandEncoder) TryInsertDebugMarker(label string) error {
+func (g *CommandEncoder) TryInsertDebugMarker(label string) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("insertDebugMarker", label)
 	return nil
 }
 
-func (g *CommandEncoder) TryPopDebugGroup() error {
+func (g *CommandEncoder) TryPopDebugGroup() (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("popDebugGroup")
 	return nil
 }
 
-func (g *CommandEncoder) TryPushDebugGroup(label string) error {
+func (g *CommandEncoder) TryPushDebugGroup(label string) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("pushDebugGroup", label)
 	return nil
 }
 
-func (g *CommandEncoder) TryResolveQuerySet(querySet *QuerySet, query uint32, count uint32, destination *Buffer, offset uint64) error {
+func (g *CommandEncoder) TryResolveQuerySet(querySet *QuerySet, query uint32, count uint32, destination *Buffer, offset uint64) (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("resolveQuerySet", querySet.toJS(), query, count, destination.toJS(), offset)
 	return nil
 }

wgpu/compute_pass_encoder_js.go

@@ -54,7 +54,9 @@ func (g *ComputePassEncoder) DispatchWorkgroups(workgroupCountX, workgroupCountY
 
 // TryEnd as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpucomputepassencoder-end
-func (g *ComputePassEncoder) TryEnd() error {
+func (g *ComputePassEncoder) TryEnd() (err error) {
+	defer handleJsException(&err)
+
 	g.jsValue.Call("end")
 	return nil
 }

wgpu/device_ext_js.go

@@ -9,7 +9,9 @@ import (
 // TODO(kai): this only needs to be separate for js because
 //
 //	[Buffer.GetMappedRange] does not work correctly without GopherJS.
-func (g *Device) TryCreateBufferInit(descriptor *BufferInitDescriptor) (*Buffer, error) {
+func (g *Device) TryCreateBufferInit(descriptor *BufferInitDescriptor) (_ *Buffer, err error) {
+	defer handleJsException(&err)
+
 	if len(descriptor.Contents) == 0 {
 		return g.TryCreateBuffer(&BufferDescriptor{
 			Label:            descriptor.Label,

wgpu/device_js.go

@@ -6,104 +6,111 @@ package wgpu
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-queue
 func (g *Device) GetQueue() *Queue {
 	jsQueue := g.jsValue.Get("queue")
-	return &Queue{
-		jsValue: jsQueue,
-	}
+	return &Queue{jsValue: jsQueue}
 }
 
-func (g *Device) TryCreateQuerySet(descriptor *QuerySetDescriptor) (*QuerySet, error) {
+func (g *Device) TryCreateQuerySet(descriptor *QuerySetDescriptor) (_ *QuerySet, err error) {
+	defer handleJsException(&err)
+
 	jsQuerySet := g.jsValue.Call("createQuerySet", pointerToJS(descriptor))
 	return &QuerySet{jsQuerySet}, nil
 }
 
 // TryCreateCommandEncoder as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createcommandencoder
-func (g *Device) TryCreateCommandEncoder(descriptor *CommandEncoderDescriptor) (*CommandEncoder, error) {
+func (g *Device) TryCreateCommandEncoder(descriptor *CommandEncoderDescriptor) (_ *CommandEncoder, err error) {
+	defer handleJsException(&err)
+
 	jsEncoder := g.jsValue.Call("createCommandEncoder", pointerToJS(descriptor))
-	return &CommandEncoder{
-		jsValue: jsEncoder,
-	}, nil
+	return &CommandEncoder{jsValue: jsEncoder}, nil
 }
 
 // TryCreateBuffer as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createbuffer
-func (g *Device) TryCreateBuffer(descriptor *BufferDescriptor) (*Buffer, error) {
+func (g *Device) TryCreateBuffer(descriptor *BufferDescriptor) (_ *Buffer, err error) {
+	defer handleJsException(&err)
+
 	jsBuffer := g.jsValue.Call("createBuffer", pointerToJS(descriptor))
-	return &Buffer{
-		jsValue: jsBuffer,
-	}, nil
+	return &Buffer{jsValue: jsBuffer}, nil
 }
 
 // TryCreateShaderModule as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createshadermodule
-func (g *Device) TryCreateShaderModule(desc *ShaderModuleDescriptor) (*ShaderModule, error) {
+func (g *Device) TryCreateShaderModule(desc *ShaderModuleDescriptor) (_ *ShaderModule, err error) {
+	defer handleJsException(&err)
+
 	jsShader := g.jsValue.Call("createShaderModule", pointerToJS(desc))
-	return &ShaderModule{
-		jsValue: jsShader,
-	}, nil
+	return &ShaderModule{jsValue: jsShader}, nil
 }
 
 // TryCreateRenderPipeline as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createrenderpipeline
-func (g *Device) TryCreateRenderPipeline(descriptor *RenderPipelineDescriptor) (*RenderPipeline, error) {
+func (g *Device) TryCreateRenderPipeline(descriptor *RenderPipelineDescriptor) (_ *RenderPipeline, err error) {
+	defer handleJsException(&err)
+
 	jsPipeline := g.jsValue.Call("createRenderPipeline", pointerToJS(descriptor))
-	return &RenderPipeline{
-		jsValue: jsPipeline,
-	}, nil
+	return &RenderPipeline{jsValue: jsPipeline}, nil
 }
 
 // TryCreateBindGroup as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createbindgroup
-func (g *Device) TryCreateBindGroup(descriptor *BindGroupDescriptor) (*BindGroup, error) {
+func (g *Device) TryCreateBindGroup(descriptor *BindGroupDescriptor) (_ *BindGroup, err error) {
+	defer handleJsException(&err)
+
 	jsBindGroup := g.jsValue.Call("createBindGroup", pointerToJS(descriptor))
-	return &BindGroup{
-		jsValue: jsBindGroup,
-	}, nil
+	return &BindGroup{jsValue: jsBindGroup}, nil
 }
 
 // TryCreateBindGroupLayout as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createbindgrouplayout
-func (g *Device) TryCreateBindGroupLayout(descriptor *BindGroupLayoutDescriptor) (*BindGroupLayout, error) {
+func (g *Device) TryCreateBindGroupLayout(descriptor *BindGroupLayoutDescriptor) (_ *BindGroupLayout, err error) {
+	defer handleJsException(&err)
+
 	jsLayout := g.jsValue.Call("createBindGroupLayout", pointerToJS(descriptor))
-	return &BindGroupLayout{
-		jsValue: jsLayout,
-	}, nil
+	return &BindGroupLayout{jsValue: jsLayout}, nil
 }
 
 // TryCreatePipelineLayout as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createpipelinelayout
-func (g *Device) TryCreatePipelineLayout(descriptor *PipelineLayoutDescriptor) (*PipelineLayout, error) {
+func (g *Device) TryCreatePipelineLayout(descriptor *PipelineLayoutDescriptor) (_ *PipelineLayout, err error) {
+	defer handleJsException(&err)
+
 	jsLayout := g.jsValue.Call("createPipelineLayout", pointerToJS(descriptor))
-	return &PipelineLayout{
-		jsValue: jsLayout,
-	}, nil
+	return &PipelineLayout{jsValue: jsLayout}, nil
 }
 
 // TryCreateComputePipeline as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createcomputepipeline
-func (g *Device) TryCreateComputePipeline(descriptor *ComputePipelineDescriptor) (*ComputePipeline, error) {
+func (g *Device) TryCreateComputePipeline(descriptor *ComputePipelineDescriptor) (_ *ComputePipeline, err error) {
+	defer handleJsException(&err)
+
 	jsPipeline := g.jsValue.Call("createComputePipeline", pointerToJS(descriptor))
-	return &ComputePipeline{
-		jsValue: jsPipeline,
-	}, nil
+	return &ComputePipeline{jsValue: jsPipeline}, nil
 }
 
 // TryCreateTexture as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createtexture
-func (g *Device) TryCreateTexture(descriptor *TextureDescriptor) (*Texture, error) {
+func (g *Device) TryCreateTexture(descriptor *TextureDescriptor) (_ *Texture, err error) {
+	defer handleJsException(&err)
+
 	jsTexture := g.jsValue.Call("createTexture", pointerToJS(descriptor))
-	return &Texture{
-		jsValue: jsTexture,
-	}, nil
+	return &Texture{jsValue: jsTexture}, nil
 }
 
 // TryCreateSampler as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpudevice-createsampler
-func (g *Device) TryCreateSampler(descriptor *SamplerDescriptor) (*Sampler, error) {
+func (g *Device) TryCreateSampler(descriptor *SamplerDescriptor) (_ *Sampler, err error) {
+	defer handleJsException(&err)
+
 	jsSampler := g.jsValue.Call("createSampler", pointerToJS(descriptor))
-	return &Sampler{
-		jsValue: jsSampler,
-	}, nil
+	return &Sampler{jsValue: jsSampler}, nil
+}
+
+func (g *Device) TryCreateRenderBundleEncoder(descriptor *RenderBundleEncoderDescriptor) (_ *RenderBundleEncoder, err error) {
+	defer handleJsException(&err)
+
+	jsValue := g.jsValue.Call("createRenderBundleEncoder", descriptor.toJS())
+	return &RenderBundleEncoder{jsValue: jsValue}, nil
 }
 
 func (g *Device) GetLimits() Limits {
@@ -113,8 +120,3 @@ func (g *Device) GetLimits() Limits {
 func (g *Device) Poll(wait bool, wrappedSubmissionIndex *uint64) (queueEmpty bool) {
 	return false // no-op
 }
-
-func (g *Device) TryCreateRenderBundleEncoder(descriptor *RenderBundleEncoderDescriptor) (*RenderBundleEncoder, error) {
-	// TODO implement this
-	panic("unimplemented")
-}

wgpu/error_js.go

@@ -0,0 +1,46 @@
+package wgpu
+
+import (
+	"errors"
+	"fmt"
+	"runtime"
+	"strings"
+)
+
+func handleJsException(err *error) {
+	r := recover()
+	if r == nil {
+		return
+	}
+
+	// get the callers.
+	//  skip: this method, panic, js.Value.Call
+	var callers [1]uintptr
+	runtime.Callers(4, callers[:])
+
+	frames := runtime.CallersFrames(callers[:])
+	frame, _ := frames.Next()
+	context := frame.Func.Name()
+
+	// strip github.com/.../ from method name
+	if idx := strings.LastIndexByte(context, '/'); idx >= 0 {
+		context = context[idx+1:]
+	}
+
+	switch r := r.(type) {
+	case error:
+		*err = wrap(r, context)
+
+	case fmt.Stringer:
+		*err = Error{
+			Context: context,
+			Wrapped: errors.New(r.String()),
+		}
+
+	default:
+		*err = Error{
+			Context: context,
+			Wrapped: fmt.Errorf("%v", r),
+		}
+	}
+}

wgpu/queue_js.go

@@ -23,27 +23,29 @@ func (g *Queue) Submit(commandBuffers ...*CommandBuffer) SubmissionIndex {
 // TryWriteBuffer as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpuqueue-writebuffer
 func (g *Queue) TryWriteBuffer(buffer *Buffer, offset uint64, data []byte) (err error) {
-	defer runtime.KeepAlive(data)
-
+	defer handleJsException(&err)
 	address := uintptr(unsafe.Pointer(&data[0]))
 	queueWriteBuffer.Invoke(g.jsValue, pointerToJS(buffer), offset, address, uint64(0), len(data))
+	runtime.KeepAlive(data)
 	return
 }
 
 // TryWriteTexture as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpuqueue-writetexture
 func (g *Queue) TryWriteTexture(destination *TexelCopyTextureInfo, data []byte, dataLayout *TexelCopyBufferLayout, writeSize *Extent3D) (err error) {
-	defer runtime.KeepAlive(data)
+	defer handleJsException(&err)
 
 	address := uintptr(unsafe.Pointer(&data[0]))
 	queueWriteTexture.Invoke(g.jsValue, pointerToJS(destination), address, len(data), pointerToJS(dataLayout), pointerToJS(writeSize))
+	runtime.KeepAlive(data)
 	return
 }
 
 // OnSubmittedWorkDone as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpuqueue-onsubmittedworkdone
 func (g *Queue) OnSubmittedWorkDone(callback QueueWorkDoneCallback) {
-	jsx.Await(g.jsValue.Call("onSubmittedWorkDone")) // TODO(kai): is this correct?
+	// TODO should probably just schedule the callback using .then
+	jsx.Await(g.jsValue.Call("onSubmittedWorkDone"))
 	callback(QueueWorkDoneStatusSuccess)
 }
 

wgpu/render_pass_encoder_js.go

@@ -84,7 +84,8 @@ func (g *RenderPassEncoder) DrawIndexed(indexCount uint32, instanceCount uint32,
 
 // TryEnd as described:
 // https://gpuweb.github.io/gpuweb/#dom-gpurenderpassencoder-end
-func (g *RenderPassEncoder) TryEnd() error {
+func (g *RenderPassEncoder) TryEnd() (err error) {
+	defer handleJsException(&err)
 	g.jsValue.Call("end")
 	return nil
 }