Support explicit cancellation of Wasm execution

[jtakakura]

Summary

This PR implements a mechanism to explicitly cancel a running WebAssembly instance from an external thread, as requested in #27.

Previously, execution could only be stopped via pre-set fuel limits or deadline timeouts. This change introduces a thread-safe cancelled flag in the Vm struct, allowing host applications to interrupt long-running or infinite loops from a different thread.

Proposed Changes

Core VM Implementation

• Added cancelled: std.atomic.Value(bool) to the Vm struct for thread-safe concurrent access.
• Implemented Vm.cancel() to set the flag and ensured Vm.reset() clears it at the start of each invocation.
• Integrated the check into consumeInstructionBudget(). This allows the VM to stop execution at the next checkpoint (~every 1024 instructions).
• Updated the JIT execution path (jitFuelCheckHelper) to honor the cancellation flag.

Public API

• Zig API: Added WasmModule.cancel() as a high-level method to request cancellation.
• C API: Added zwasm_module_cancel(zwasm_module_t *module) to include/zwasm.h and src/c_api.zig.
• Errors: Added error.Canceled and updated the CLI to provide a descriptive error message when cancellation occurs.

Testing

• Added unit tests in src/vm.zig that simulate a background thread canceling both interpreter and JIT-compiled loops.
• Enhanced C API tests in test/c_api/test_ffi.c to verify that the zwasm_module_cancel symbol is correctly exported and functional in a multi-threaded C environment.

Related Issue

Closes #27

[chaploud]

Hi @jtakakura — thanks again for this contribution. Shipped in v1.9.0 (commit 231c7ca) via #43, which preserves your three commits verbatim as the base of the feature branch.

Refinements added on top (6 follow-up commits)

• loadLinked signature kept stable — dropped the positional cancellable: bool to preserve source compatibility. Hosts that need the opt-out can set result.module.vm.cancellable = false after load; the docstring points at this.
• Config.cancellable: ?bool — normalised to an optional to match the other override fields (fuel, force_interpreter, ...). The C ABI surface of zwasm_config_set_cancellable is unchanged.
• Zig WasmModule.cancel() docstring — spelled out the reset-at-invoke race you already accounted for in the FFI test, so Zig callers see the same note the C header carries.
• D134 in .dev/decisions.md — captures the design rationale (atomic flag on existing deadline checkpoints, JIT fuel cap, opt-out path).
• CHANGELOG entry + bench/history.yaml PR28 baseline — long benches within ±1% of v1.8.0, confirming the default-on periodic check has no measurable impact on the hot path.

Verified

• CI green (Ubuntu / macOS / Windows / size-matrix / benchmark).
• Ubuntu x86_64 Merge Gate locally via OrbStack — unit 407/410, spec 62263/62263, e2e 796/796, realworld 50/50, FFI 80/80, minimal 267/282.
• ClojureWasm downstream verification — test/run_all.sh --quick 4/4 pass against v1.9.0.

v1.9.0 is tagged and pushed. ClojureWasm bump PR: clojurewasm/ClojureWasm#3. Thanks for the patient and well-scoped work — the FFI thread-safety test in particular was a great addition. Closing this PR as merged.

[jtakakura]

@chaploud Thrilled to see v1.9.0 shipped ㊗️
Thanks for the refinements and for keeping my commits as the base.
I'm especially glad the FFI thread-safety tests were useful.
It’s been a great experience contributing to zwasm and I'm looking forward to using this in my own project.