radix_wasmi/
lib.rs

1//! The `wasmi` virtual machine definitions.
2//!
3//! These closely mirror the WebAssembly specification definitions.
4//! The overall structure is heavily inspired by the `wasmtime` virtual
5//! machine architecture.
6//!
7//! # Example
8//!
9//! The following example shows a "Hello, World!"-like example of creating
10//! a Wasm module from some initial `.wat` contents, defining a simple host
11//! function and calling the exported Wasm function.
12//!
13//! The example was inspired by
14//! [Wasmtime's API example](https://docs.rs/wasmtime/0.39.1/wasmtime/).
15//!
16//! ```
17//! use anyhow::{anyhow, Result};
18//! use wasmi::*;
19//!
20//! fn main() -> Result<()> {
21//!     // First step is to create the Wasm execution engine with some config.
22//!     // In this example we are using the default configuration.
23//!     let engine = Engine::default();
24//!     let wat = r#"
25//!         (module
26//!             (import "host" "hello" (func $host_hello (param i32)))
27//!             (func (export "hello")
28//!                 (call $host_hello (i32.const 3))
29//!             )
30//!         )
31//!     "#;
32//!     // Wasmi does not yet support parsing `.wat` so we have to convert
33//!     // out `.wat` into `.wasm` before we compile and validate it.
34//!     let wasm = wat::parse_str(&wat)?;
35//!     let module = Module::new(&engine, &mut &wasm[..])?;
36//!
37//!     // All Wasm objects operate within the context of a `Store`.
38//!     // Each `Store` has a type parameter to store host-specific data,
39//!     // which in this case we are using `42` for.
40//!     type HostState = u32;
41//!     let mut store = Store::new(&engine, 42);
42//!     let host_hello = Func::wrap(&mut store, |caller: Caller<'_, HostState>, param: i32| {
43//!         println!("Got {param} from WebAssembly");
44//!         println!("My host state is: {}", caller.data());
45//!     });
46//!
47//!     // In order to create Wasm module instances and link their imports
48//!     // and exports we require a `Linker`.
49//!     let mut linker = <Linker<HostState>>::new();
50//!     // Instantiation of a Wasm module requires defining its imports and then
51//!     // afterwards we can fetch exports by name, as well as asserting the
52//!     // type signature of the function with `get_typed_func`.
53//!     //
54//!     // Also before using an instance created this way we need to start it.
55//!     linker.define("host", "hello", host_hello)?;
56//!     let instance = linker
57//!         .instantiate(&mut store, &module)?
58//!         .start(&mut store)?;
59//!     let hello = instance.get_typed_func::<(), ()>(&store, "hello")?;
60//!
61//!     // And finally we can call the wasm!
62//!     hello.call(&mut store, ())?;
63//!
64//!     Ok(())
65//! }
66//! ```
67
68#![cfg_attr(not(feature = "std"), no_std)]
69#![warn(
70    clippy::cast_lossless,
71    clippy::missing_errors_doc,
72    clippy::used_underscore_binding,
73    clippy::redundant_closure_for_method_calls,
74    clippy::type_repetition_in_bounds,
75    clippy::inconsistent_struct_constructor,
76    clippy::default_trait_access,
77    clippy::items_after_statements
78)]
79#![recursion_limit = "550"]
80
81#[cfg(not(feature = "std"))]
82#[macro_use]
83extern crate alloc;
84#[cfg(feature = "std")]
85extern crate std as alloc;
86
87#[macro_use]
88mod foreach_tuple;
89
90mod engine;
91mod error;
92mod external;
93mod func;
94mod func_type;
95mod global;
96mod instance;
97mod linker;
98mod memory;
99mod module;
100mod store;
101mod table;
102
103/// Definitions from the `wasmi_core` crate.
104#[doc(inline)]
105pub use wasmi_core as core;
106
107/// Defines some errors that may occur upon interaction with `wasmi`.
108pub mod errors {
109    pub use super::{
110        func::FuncError,
111        global::GlobalError,
112        linker::LinkerError,
113        memory::MemoryError,
114        module::{InstantiationError, ModuleError},
115        table::TableError,
116    };
117}
118
119pub use self::{
120    engine::{
121        Config,
122        Engine,
123        ResumableCall,
124        ResumableInvocation,
125        StackLimits,
126        TypedResumableCall,
127        TypedResumableInvocation,
128    },
129    error::Error,
130    external::{Extern, ExternType},
131    func::{
132        Caller,
133        Func,
134        IntoFunc,
135        TypedFunc,
136        WasmParams,
137        WasmResults,
138        WasmRet,
139        WasmType,
140        WasmTypeList,
141    },
142    func_type::FuncType,
143    global::{Global, GlobalType, Mutability},
144    instance::{Export, ExportsIter, Instance},
145    linker::Linker,
146    memory::{Memory, MemoryType},
147    module::{
148        ExportType,
149        ImportType,
150        InstancePre,
151        Module,
152        ModuleExportsIter,
153        ModuleImportsIter,
154        Read,
155    },
156    store::{AsContext, AsContextMut, Store, StoreContext, StoreContextMut},
157    table::{Table, TableType},
158};
159use self::{
160    func::{FuncEntity, FuncIdx},
161    global::{GlobalEntity, GlobalIdx},
162    instance::{InstanceEntity, InstanceEntityBuilder, InstanceIdx},
163    memory::{MemoryEntity, MemoryIdx},
164    store::{StoreInner, Stored},
165    table::{TableEntity, TableIdx},
166};
radix_wasmi/lib.rs

radix_wasmi/
lib.rs
