Expand description
§xwasmi
This library allows WebAssembly modules to be loaded in binary format and their functions invoked.
§Introduction
WebAssembly (xwasm) is a safe, portable and compact format that is designed for efficient execution.
Wasm code is distributed in the form of modules that contains definitions of:
- functions,
- global variables,
- linear memory instances and
- tables.
Each of these definitions can be imported and exported.
In addition to these definitions, modules can define initialization data for their memory or tables. This initialization data can take the
form of segments, copied to given offsets. They can also define a start
function that is automatically executed when the module is loaded.
§Loading and Validation
Before execution, a module must be validated. This process checks that the module is well-formed and makes only allowed operations.
A valid module can’t access memory outside its sandbox, can’t cause stack underflows and can only call functions with correct signatures.
§Instantiation
In order to execute code from a xwasm module, it must be instantiated. Instantiation includes the following steps:
- Creating an empty module instance.
- Resolving the definition instances for each declared import in the module.
- Instantiating definitions declared in the module (e.g. allocate global variables, allocate linear memory, etc.).
- Initializing memory and table contents by copying segments into them.
- Executing the
start
function, if any.
After these steps, the module instance is ready to execute functions.
§Execution
It only is allowed to call functions which are exported by the module. Functions can either return a result or trap (e.g. there can’t be linking error in the middle of the function execution). This property is ensured by the validation process.
§Examples
extern crate xwasmi;
extern crate wabt;
use xwasmi::{ModuleInstance, ImportsBuilder, NopExternals, RuntimeValue};
fn main() {
// Parse WAT (WebAssembly Text format) into xwasm bytecode.
let xwasm_binary: Vec<u8> =
wabt::wat2xwasm(
r#"
(module
(func (export "test") (result i32)
i32.const 1337
)
)
"#,
)
.expect("failed to parse wat");
// Load xwasm binary and prepare it for instantiation.
let module = xwasmi::Module::from_buffer(&xwasm_binary)
.expect("failed to load xwasm");
// Instantiate a module with empty imports and
// assert that there is no `start` function.
let instance =
ModuleInstance::new(
&module,
&ImportsBuilder::default()
)
.expect("failed to instantiate xwasm module")
.assert_no_start();
// Finally, invoke the exported function "test" with no parameters
// and empty external function executor.
assert_eq!(
instance.invoke_export(
"test",
&[],
&mut NopExternals,
).expect("failed to execute export"),
Some(RuntimeValue::I32(1337)),
);
}
Modules§
- WebAssembly-specific sizes and units.
Structs§
- Runtime representation of a function.
- A resumable invocation handle. This struct is returned by
FuncInstance::invoke_resumable
. - Reference to a function (See
FuncInstance
for details). - Description of a global variable.
- Runtime representation of a global variable (or
global
for short). - Reference to a global variable (See
GlobalInstance
for details). - Convenience builder of
ImportResolver
. - Description of a linear memory.
- Runtime representation of a linear memory (or
memory
for short). - Reference to a memory (See
MemoryInstance
for details). - Deserialized module prepared for instantiation.
- A module instance is the runtime representation of a module.
- Reference to a
ModuleInstance
. - Implementation of
Externals
that just traps oninvoke_index
. - Mostly instantiated
ModuleRef
. - Wrapper around slice of
RuntimeValue
for using it as an argument list conveniently. - Signature of a function.
- Description of a table.
- Runtime representation of a table.
- Reference to a table (See
TableInstance
for details). - Error type which can be thrown by xwasm code or by host environment.
Enums§
- Internal interpreter error.
- An external value is the runtime representation of an entity that can be imported or exported.
- A resumable invocation error.
- Runtime representation of a value.
- Error type which can be thrown by xwasm code or by host environment.
- Error for
LittleEndianConvert
- Type of a value.
Constants§
- Size of a page of linear memory - 64KiB.
Traits§
- Trait that allows to implement host functions.
- Trait for creating value from a
RuntimeValue
. - Trait that allows the host to return custom error.
- Resolver of a module’s dependencies.
- Convert from and to little endian.
- Version of
ImportResolver
specialized for a single module.