zwasm_sdk/
lib.rs

1//! # zwasm-sdk
2//!
3//! Rust bindings for [zwasm](https://github.com/zwasm/zwasm): a small, fast, and spec-complete WebAssembly runtime written in Zig.
4//!
5//! ## Features
6//! - **Tiny and fast**: ~1.2MB binary, JIT for ARM64/x86_64, full SIMD, threads, GC, exception handling, and more.
7//! - **100% spec conformance**: Passes all official Wasm spec tests and proposals through 3.0.
8//! - **Component Model**: WIT parser, Canonical ABI, WASI Preview 1+2, component linking.
9//! - **Security**: Deny-by-default WASI, capability flags, resource limits.
10//! - **Zero dependencies**: Pure Zig core, no libc required.
11//! - **Interruption support**: cancel a running invocation from another thread with [`CancelHandle`].
12//!
13//! ## Supported platforms
14//! - Linux (x86_64, aarch64)
15//! - macOS (aarch64)
16//!
17//! ## Example
18//! ```no_run
19//! use zwasm_sdk::{Module};
20//!
21//! fn main() -> Result<(), Box<dyn std::error::Error>> {
22//!     let wasm_bytes: &[u8] = &[
23//!         0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x05, 0x01, 0x60, 0x00, 0x01,
24//!         0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x05, 0x01, 0x01, 0x66, 0x00, 0x00, 0x0a, 0x06,
25//!         0x01, 0x04, 0x00, 0x41, 0x2a, 0x0b,
26//!     ];
27//!     let module = Module::new(wasm_bytes)?;
28//!     let results = module.invoke("f", &[])?;
29//!     assert_eq!(results[0], 42);
30//!     Ok(())
31//! }
32//! ```
33//!
34//! For long-running Wasm, enable cancellation in [`Config`] and use [`Module::cancel_handle`]
35//! to interrupt an in-progress invocation from another thread. Interrupted calls can be
36//! recognized with [`ZwasmError::is_interrupted`].
37//!
38//! ## Design
39//! zwasm uses a 4-tier execution pipeline:
40//! - Bytecode → Predecoded IR → Register IR → Native JIT (ARM64/x86_64)
41//! - All Wasm 3.0 proposals, threads, SIMD, GC, exception handling supported
42//! - Allocator-parameterized: caller controls memory allocation
43//!
44//! ## Examples
45//! See practical examples in the repository:
46//! - `examples/run_wasm.rs`
47//! - `examples/host_imports.rs`
48//! - `examples/memory_io.rs`
49//! - `examples/wasi_config.rs`
50//!
51//! See the upstream [README](https://github.com/zwasm/zwasm) and [ARCHITECTURE.md](https://github.com/zwasm/zwasm/blob/v1.11.1/ARCHITECTURE.md) for details.
52mod config;
53mod error;
54mod ffi;
55mod imports;
56mod module;
57#[cfg(test)]
58mod test_fixtures;
59mod utils;
60mod wasi;
61
62pub use config::Config;
63pub use error::ZwasmError;
64pub use imports::Imports;
65pub use module::{CancelHandle, Module};
66pub use wasi::WasiConfig;
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71
72    #[test]
73    fn test_multiple_modules() {
74        let m1 = Module::new(test_fixtures::RETURN42_WASM).expect("Failed to create module 1");
75        let m2 = Module::new(test_fixtures::ADD_WASM).expect("Failed to create module 2");
76        let m3 = Module::new(test_fixtures::MEMORY_WASM).expect("Failed to create module 3");
77
78        let r1 = m1.invoke("f", &[]).expect("invoke m1.f");
79        assert_eq!(r1[0], 42, "m1.f() == 42");
80
81        let args = [100, 200];
82        let r2 = m2.invoke("add", &args).expect("invoke m2.add");
83        assert_eq!(r2[0], 300, "m2.add(100,200) == 300");
84
85        assert!(m3.memory_size() >= 65536, "m3 has memory");
86    }
87
88    #[test]
89    fn test_repeated_create_destroy() {
90        for i in 0..100 {
91            let module =
92                Module::new(test_fixtures::RETURN42_WASM).expect("Failed to create module in loop");
93            let results = module
94                .invoke("f", &[])
95                .expect("Failed to invoke function in loop");
96            assert_eq!(results[0], 42, "f() == 42 in loop iteration {}", i);
97        }
98    }
99}
zwasm_sdk/lib.rs

zwasm_sdk/
lib.rs
