feat!: switch to raise-based error model (v0.7.0)

Author: Milky2018

.beads/issues.jsonl

@@ -19,6 +19,10 @@
 {"id":"wgpu_mbt-1mk.2","title":"Declare/bindings: render pipeline pos2 with explicit pipeline layout","description":"Add C stub + raw extern for render pipeline (pos2) that takes PipelineLayout* so we can bind uniform buffer.","status":"closed","priority":2,"issue_type":"task","owner":"842376130@qq.com","created_at":"2026-01-26T15:20:27.963986+08:00","created_by":"Milky2018","updated_at":"2026-01-26T15:23:43.754006+08:00","closed_at":"2026-01-26T15:23:43.754006+08:00","close_reason":"Closed","dependencies":[{"issue_id":"wgpu_mbt-1mk.2","depends_on_id":"wgpu_mbt-1mk","type":"parent-child","created_at":"2026-01-26T15:20:27.964737+08:00","created_by":"Milky2018"}]}
 {"id":"wgpu_mbt-1mk.3","title":"Test: offscreen render with uniform color (beads)","description":"Render 1x1 using pos2 vertex buffer + uniform vec4 color bound at group(0)/binding(0), assert pixel from readback.","status":"closed","priority":2,"issue_type":"task","owner":"842376130@qq.com","created_at":"2026-01-26T15:20:28.048084+08:00","created_by":"Milky2018","updated_at":"2026-01-26T15:23:43.755198+08:00","closed_at":"2026-01-26T15:23:43.755198+08:00","close_reason":"Closed","dependencies":[{"issue_id":"wgpu_mbt-1mk.3","depends_on_id":"wgpu_mbt-1mk","type":"parent-child","created_at":"2026-01-26T15:20:28.048735+08:00","created_by":"Milky2018"}]}
 {"id":"wgpu_mbt-1sn","title":"wgpu: indirect dispatch + draw","description":"Expose ComputePass dispatch_workgroups_indirect and RenderPass draw_indirect/draw_indexed_indirect, plus BufferUsage_Indirect constant. Add root tests that render a pixel via draw_indirect and run compute via dispatch_indirect.","status":"closed","priority":2,"issue_type":"task","owner":"842376130@qq.com","created_at":"2026-01-27T10:24:07.231141+08:00","created_by":"Milky2018","updated_at":"2026-01-27T10:33:44.119593+08:00","closed_at":"2026-01-27T10:33:44.119595+08:00","dependencies":[{"issue_id":"wgpu_mbt-1sn","depends_on_id":"wgpu_mbt-avd","type":"blocks","created_at":"2026-01-27T10:24:07.231847+08:00","created_by":"Milky2018"}],"comments":[{"id":11,"issue_id":"wgpu_mbt-1sn","author":"Milky2018","text":"Implemented indirect dispatch/draw APIs (ComputePass.dispatch_workgroups_indirect, RenderPass.draw_indirect/draw_indexed_indirect) and added root tests for draw_indirect + dispatch_indirect. Added buffer usage constants for INDIRECT and QUERY_RESOLVE.","created_at":"2026-01-27T02:33:44Z"}]}
+{"id":"wgpu_mbt-2de","title":"Breaking: switch error model to raise/try-catch (no Result)","description":"Replace public Result-returning APIs with raise-based error model (try/catch). Update docs/tests. Bump 0.x major.","status":"closed","priority":0,"issue_type":"epic","owner":"842376130@qq.com","created_at":"2026-02-02T20:35:32.23106+08:00","created_by":"Milky2018","updated_at":"2026-02-02T20:59:34.47554+08:00","closed_at":"2026-02-02T20:59:34.47554+08:00","close_reason":"Epic complete: error model is raise/try-catch end-to-end (no Result APIs)."}
+{"id":"wgpu_mbt-2de.1","title":"API: replace Result with raise","description":"Convert require_native/require_native_symbol, Instance::create/adapter/device acquisition, and RenderPipelineDescBuilder APIs to raise-based errors; remove Result from public signatures.","status":"closed","priority":0,"issue_type":"task","assignee":"Milky2018","owner":"842376130@qq.com","created_at":"2026-02-02T20:35:46.605218+08:00","created_by":"Milky2018","updated_at":"2026-02-02T20:59:34.178045+08:00","closed_at":"2026-02-02T20:59:34.178045+08:00","close_reason":"Switched public APIs from Result to raise-based errors (WgpuError/RenderPipelineDescError); updated C helpers for status/null checks.","dependencies":[{"issue_id":"wgpu_mbt-2de.1","depends_on_id":"wgpu_mbt-2de","type":"parent-child","created_at":"2026-02-02T20:35:46.606015+08:00","created_by":"Milky2018"}]}
+{"id":"wgpu_mbt-2de.2","title":"Update tests + examples for try/catch","description":"Adjust all tests and cmd examples to compile with raise-based API (no .unwrap()).","status":"closed","priority":0,"issue_type":"task","owner":"842376130@qq.com","created_at":"2026-02-02T20:35:46.713862+08:00","created_by":"Milky2018","updated_at":"2026-02-02T20:59:34.279389+08:00","closed_at":"2026-02-02T20:59:34.279389+08:00","close_reason":"Updated cmd tools and tests to use try/catch and new raising pipeline builder API.","dependencies":[{"issue_id":"wgpu_mbt-2de.2","depends_on_id":"wgpu_mbt-2de","type":"parent-child","created_at":"2026-02-02T20:35:46.714655+08:00","created_by":"Milky2018"}]}
+{"id":"wgpu_mbt-2de.3","title":"Docs + version bump + publish","description":"Update README to document try/catch usage. Bump version to 0.7.0, publish, verify CI and release assets.","status":"closed","priority":1,"issue_type":"task","owner":"842376130@qq.com","created_at":"2026-02-02T20:35:46.912121+08:00","created_by":"Milky2018","updated_at":"2026-02-02T20:59:34.377105+08:00","closed_at":"2026-02-02T20:59:34.377105+08:00","close_reason":"Updated README, bumped version to 0.7.0, ran moon info/fmt/check/test; ready to publish.","dependencies":[{"issue_id":"wgpu_mbt-2de.3","depends_on_id":"wgpu_mbt-2de","type":"parent-child","created_at":"2026-02-02T20:35:46.912936+08:00","created_by":"Milky2018"}]}
 {"id":"wgpu_mbt-2gy","title":"refactor: move wgpu -\u003e src and tests into src/tests","description":"Rename package directory wgpu/ to src/, add moon.mod.json source=src, move root tests to src/tests, and keep cmd runnable.","notes":"Applying directory rename + source root changes","status":"closed","priority":2,"issue_type":"task","owner":"842376130@qq.com","created_at":"2026-01-27T14:40:59.624223+08:00","created_by":"Milky2018","updated_at":"2026-01-27T14:43:53.915336+08:00","closed_at":"2026-01-27T14:43:53.915336+08:00","close_reason":"renamed wgpu/ -\u003e src/, set source=src, moved tests to src/tests, kept cmd runnable via symlink"}
 {"id":"wgpu_mbt-5px","title":"Hardening: safe init + auto-enable robustness","description":"Improve error model around native loading and make auto-enable markers robust to lib changes.","status":"closed","priority":1,"issue_type":"epic","owner":"842376130@qq.com","created_at":"2026-02-02T19:41:54.933202+08:00","created_by":"Milky2018","updated_at":"2026-02-02T20:05:38.571122+08:00","closed_at":"2026-02-02T20:05:38.571122+08:00","close_reason":"All child tasks completed and released (v0.6.5–v0.6.7): safe native init API, marker path binding, troubleshooting docs."}
 {"id":"wgpu_mbt-5px.1","title":"Error model: non-aborting Instance::try_create + require_native","description":"Add Result-returning APIs to avoid abort when libwgpu_native is missing: require_native(), Instance::try_create(), Instance::try_create_ptr(). Update cmd/main example and README.","status":"closed","priority":0,"issue_type":"task","assignee":"Milky2018","owner":"842376130@qq.com","created_at":"2026-02-02T19:42:02.940458+08:00","created_by":"Milky2018","updated_at":"2026-02-02T19:44:37.080202+08:00","closed_at":"2026-02-02T19:44:37.080202+08:00","close_reason":"Added NativeLoadError + require_native() + Instance::try_create/try_create_ptr to avoid aborts when libwgpu_native is missing; updated README and cmd/main.","dependencies":[{"issue_id":"wgpu_mbt-5px.1","depends_on_id":"wgpu_mbt-5px","type":"parent-child","created_at":"2026-02-02T19:42:02.941321+08:00","created_by":"Milky2018"}]}

README.mbt.md

@@ -179,20 +179,22 @@ This module does **not** try to locate the library via CWD.
 If neither location works, the process will abort when the first WebGPU symbol is used
 (because we `dlopen` the library lazily).
 
-To avoid aborts and surface a diagnostic string instead, use:
-- `@wgpu.require_native()` (returns `Result[Unit, NativeLoadError]`)
-- `Instance::try_create()` / `Instance::try_create_ptr(...)` (returns `Result[Instance, NativeLoadError]`)
+To avoid aborts and surface a diagnostic string instead, use `try/catch` around:
+- `@wgpu.require_native()` / `@wgpu.require_native_symbol("wgpu...")` (raises `WgpuError`)
+- `Instance::create()` / `Instance::create_ptr(...)` (raises `WgpuError`)
+- `Instance::request_adapter_sync()` / `Instance::request_adapter_sync_ptr(...)` (raises `WgpuError`)
+- `Adapter::request_device_sync()` / `Adapter::request_device_sync_ptr(...)` (raises `WgpuError`)
 
 ## Troubleshooting
 
 If you see crashes/aborts early in the program, it is usually because `libwgpu_native` cannot be located/loaded.
 
 - Inspect loader diagnostics:
   - `@wgpu.native_diagnostic()`
-- Avoid aborts while checking availability:
-  - `@wgpu.native_check()` / `@wgpu.require_native_symbol("wgpu...")`
-  - `Instance::try_create()` / `Instance::try_create_ptr(...)`
-  - `Instance::try_request_adapter_sync()` / `Adapter::try_request_device_sync(...)`
+- Avoid aborts while checking availability (use `try/catch`):
+  - `@wgpu.require_native()` / `@wgpu.require_native_symbol("wgpu...")`
+  - `Instance::create()` / `Instance::create_ptr(...)`
+  - `Instance::request_adapter_sync()` / `Adapter::request_device_sync(...)`
 - Fix typical causes:
   - Install the native library to the default per-user path (recommended) by running `python3 scripts/postadd.py`
   - Or set `MBT_WGPU_NATIVE_LIB` to an absolute path to your `.dylib` / `.so` / `.dll`
@@ -222,59 +224,44 @@ Minimal example (same as `src/cmd/main/main.mbt`):
 
 ```moonbit
 fn main {
-  let instance = match @wgpu.Instance::try_create() {
-    Ok(i) => i
-    Err(e) => {
+  try {
+    let instance = @wgpu.Instance::create()
+    let adapter = instance.request_adapter_sync()
+    let device = adapter.request_device_sync(instance)
+    let queue = device.queue()
+    let buf = device.create_buffer(
+      size=4UL,
+      usage=@wgpu.BufferUsage::from_u64(@wgpu.BUFFER_USAGE_COPY_DST),
+    )
+    ignore(buf.size())
+    let wgsl : String =
+      #|@compute @workgroup_size(1)
+      #|fn main() {}
+      #|
+    let sm = device.create_shader_module_wgsl(wgsl)
+    let pipeline = device.create_compute_pipeline(sm)
+    let encoder = device.create_command_encoder()
+    let pass = encoder.begin_compute_pass()
+    pass.set_pipeline(pipeline)
+    pass.dispatch_workgroups(1U, 1U, 1U)
+    pass.end()
+    pass.release()
+    let cmd = encoder.finish()
+    queue.submit_one(cmd)
+    buf.release()
+    cmd.release()
+    encoder.release()
+    pipeline.release()
+    sm.release()
+    queue.release()
+    device.release()
+    adapter.release()
+    instance.release()
+  } catch {
+    e => {
       println(e.message())
-      return
     }
   }
-  let adapter = match instance.try_request_adapter_sync() {
-    Ok(a) => a
-    Err(e) => {
-      println(e.message())
-      instance.release()
-      return
-    }
-  }
-  let device = match adapter.try_request_device_sync(instance) {
-    Ok(d) => d
-    Err(e) => {
-      println(e.message())
-      adapter.release()
-      instance.release()
-      return
-    }
-  }
-  let queue = device.queue()
-  let buf = device.create_buffer(
-    size=4UL,
-    usage=@wgpu.BufferUsage::from_u64(@wgpu.BUFFER_USAGE_COPY_DST),
-  )
-  ignore(buf.size())
-  let wgsl : String =
-    #|@compute @workgroup_size(1)
-    #|fn main() {}
-    #|
-  let sm = device.create_shader_module_wgsl(wgsl)
-  let pipeline = device.create_compute_pipeline(sm)
-  let encoder = device.create_command_encoder()
-  let pass = encoder.begin_compute_pass()
-  pass.set_pipeline(pipeline)
-  pass.dispatch_workgroups(1U, 1U, 1U)
-  pass.end()
-  pass.release()
-  let cmd = encoder.finish()
-  queue.submit_one(cmd)
-  buf.release()
-  cmd.release()
-  encoder.release()
-  pipeline.release()
-  sm.release()
-  queue.release()
-  device.release()
-  adapter.release()
-  instance.release()
 }
 ```
 

moon.mod.json

@@ -1,6 +1,6 @@
 {
   "name": "Milky2018/wgpu_mbt",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "readme": "README.mbt.md",
   "repository": "https://github.com/moonbit-community/wgpu-mbt.git",
   "license": "Apache-2.0",

src/c/pkg.generated.mbti

@@ -38,6 +38,8 @@ pub fn adapter_info_vendor_utf8(WGPUAdapter, Bytes, UInt64) -> Bool
 
 pub fn adapter_info_vendor_utf8_len(WGPUAdapter) -> UInt64
 
+pub fn adapter_is_null(WGPUAdapter) -> Bool
+
 pub fn adapter_limits_max_bind_groups_u32(WGPUAdapter) -> UInt
 
 pub fn adapter_limits_max_buffer_size_u64(WGPUAdapter) -> UInt64
@@ -50,6 +52,8 @@ pub fn adapter_release(WGPUAdapter) -> Unit
 
 pub fn adapter_request_device_sync(WGPUInstance, WGPUAdapter) -> WGPUDevice
 
+pub fn adapter_request_device_sync_last_status_u32() -> UInt
+
 pub fn adapter_request_device_sync_pipeline_statistics_query(WGPUInstance, WGPUAdapter) -> WGPUDevice
 
 pub fn adapter_request_device_sync_ptr(WGPUInstance, WGPUAdapter, WGPUDeviceDescriptorPtr) -> WGPUDevice
@@ -418,6 +422,8 @@ pub fn device_destroy_record_lost(WGPUDevice) -> Unit
 
 pub fn device_get_queue(WGPUDevice) -> WGPUQueue
 
+pub fn device_is_null(WGPUDevice) -> Bool
+
 pub fn device_limits_max_bind_groups_u32(WGPUDevice) -> UInt
 
 pub fn device_limits_max_buffer_size_u64(WGPUDevice) -> UInt64
@@ -496,6 +502,8 @@ pub fn instance_release(WGPUInstance) -> Unit
 
 pub fn instance_request_adapter_sync(WGPUInstance) -> WGPUAdapter
 
+pub fn instance_request_adapter_sync_last_status_u32() -> UInt
+
 pub fn instance_request_adapter_sync_options_u32(WGPUInstance, UInt, UInt, Bool, UInt, WGPUSurface) -> WGPUAdapter
 
 pub fn instance_request_adapter_sync_ptr(WGPUInstance, WGPURequestAdapterOptionsPtr) -> WGPUAdapter

src/c/raw_adapter_device.mbt

@@ -198,6 +198,9 @@ pub extern "C" fn adapter_request_device_sync_ptr(
   descriptor : WGPUDeviceDescriptorPtr,
 ) -> Device = "mbt_wgpu_adapter_request_device_sync_ptr"
 
+///|
+pub extern "C" fn adapter_request_device_sync_last_status_u32() -> UInt = "mbt_wgpu_adapter_request_device_sync_last_status_u32"
+
 ///|
 pub extern "C" fn adapter_request_device_sync_timestamp_query(
   instance : Instance,

src/c/raw_core.mbt

@@ -71,6 +71,12 @@ pub extern "C" fn null_submission_index_ptr() -> WGPUSubmissionIndexPtr = "mbt_w
 ///|
 pub extern "C" fn shader_module_is_null(shader_module : ShaderModule) -> Bool = "mbt_wgpu_shader_module_is_null"
 
+///|
+pub extern "C" fn adapter_is_null(adapter : Adapter) -> Bool = "mbt_wgpu_adapter_is_null"
+
+///|
+pub extern "C" fn device_is_null(device : Device) -> Bool = "mbt_wgpu_device_is_null"
+
 ///|
 pub extern "C" fn null_render_pipeline_descriptor_ptr() -> WGPURenderPipelineDescriptorPtr = "mbt_wgpu_null_ptr"
 

src/c/raw_instance.mbt

@@ -54,6 +54,9 @@ pub extern "C" fn instance_request_adapter_sync_ptr(
   options : WGPURequestAdapterOptionsPtr,
 ) -> Adapter = "mbt_wgpu_instance_request_adapter_sync_ptr"
 
+///|
+pub extern "C" fn instance_request_adapter_sync_last_status_u32() -> UInt = "mbt_wgpu_instance_request_adapter_sync_last_status_u32"
+
 ///|
 pub fn instance_request_adapter_sync_options_u32(
   instance : Instance,

src/c/wgpu_stub_core.c

@@ -27,6 +27,9 @@ bool mbt_wgpu_render_pipeline_descriptor_ptr_is_null(WGPURenderPipelineDescripto
   return p == NULL;
 }
 
+bool mbt_wgpu_adapter_is_null(WGPUAdapter adapter) { return adapter == NULL; }
+bool mbt_wgpu_device_is_null(WGPUDevice device) { return device == NULL; }
+
 bool mbt_wgpu_platform_is_macos(void) {
 #if defined(__APPLE__)
   return true;