wasm3x 0.1.0

//! Safe, [`wasmi`]/[`wasmtime`]-shaped Rust bindings for the [Wasm3] interpreter.
//!
//! This crate wraps the raw [`wasm3x-sys`] C-API in a small, safe, and efficient
//! API modeled after `wasmi` and `wasmtime`:
//!
//! - [`Engine`] wraps a shared Wasm3 environment and holds the [`Config`].
//! - [`Store`] owns all runtime state of the modules instantiated into it.
//! - [`Module`] is a parsed module that can be instantiated many times.
//! - [`Linker`] provides host functions and instantiates modules.
//! - [`Instance`], [`Func`]/[`TypedFunc`], [`Memory`], and [`Global`] give
//!   access to the instantiated module.
//!
//! # Example
//!
//! ```no_run
//! use wasm3x::{Engine, Store, Module, Linker};
//!
//! let engine = Engine::default();
//! let mut store = Store::new(&engine, ());
//! let module = Module::new(&engine, &wasm_bytes()).unwrap();
//! let linker = Linker::<()>::new(&engine);
//! let instance = linker.instantiate_and_start(&mut store, &module).unwrap();
//! let add = instance.get_typed_func::<(i32, i32), i32>(&store, "add").unwrap();
//! assert_eq!(add.call(&mut store, (2, 3)).unwrap(), 5);
//! # fn wasm_bytes() -> Vec<u8> { unimplemented!() }
//! ```
//!
//! # Differences from `wasmi`/`wasmtime` (Wasm3 limitations)
//!
//! - **Function lookup is runtime-global by name.** Wasm3 finds exported
//!   functions across all modules loaded into the runtime; there is no
//!   per-instance namespace and no lookup by index. This matches the common
//!   one-module-per-store usage.
//! - **No import/export enumeration.** Wasm3 does not expose a module's imports
//!   or exports, so there is no `Module::imports()`/`exports()`. Host functions
//!   are provided through a [`Linker`] and linked by name.
//! - **Host functions receive a [`Caller`] but cannot re-enter Wasm.** A host
//!   function gets a [`Caller<'_, T>`](Caller) for `&mut T` host-data and linear
//!   [`Memory`] access, but — unlike Wasmtime — it may not call back into Wasm:
//!   Wasm3's public call entry points run from the base of the runtime stack and
//!   would corrupt the suspended frame. Host functions also return at most one
//!   value (Wasm3's signature format encodes a single result); Wasm functions you
//!   *call* may be multi-value.
//! - **Light validation.** Wasm3 is not a fully validating runtime; treat
//!   [`Module::new`] validation as best-effort.
//! - **Single-threaded.** [`Engine`] and [`Store`] are neither [`Send`] nor
//!   [`Sync`].
//!
//! [Wasm3]: https://github.com/wasm3/wasm3
//! [`wasmi`]: https://docs.rs/wasmi
//! [`wasmtime`]: https://docs.rs/wasmtime
//! [`wasm3x-sys`]: https://docs.rs/wasm3x-sys

mod caller;
mod engine;
mod error;
mod func;
mod global;
mod instance;
mod linker;
mod memory;
mod module;
mod store;
mod trampoline;
mod value;

pub use self::caller::Caller;
pub use self::engine::{CompilationMode, Config, Engine};
pub use self::error::{Error, Result};
pub use self::func::{Func, IntoFunc, TypedFunc, WasmParams, WasmResults, WasmRet, WasmTy};
pub use self::global::Global;
pub use self::instance::Instance;
pub use self::linker::Linker;
pub use self::memory::Memory;
pub use self::module::Module;
pub use self::store::{AsContext, AsContextMut, Store, StoreContext, StoreContextMut};
pub use self::value::{FuncType, GlobalType, Mutability, Val, ValType};