Expand description
Wasmer-runtime is a library that makes embedding WebAssembly in your application easy, efficient, and safe.
§How to use Wasmer-Runtime
The easiest way is to use the instantiate
function to create an Instance
.
Then you can use call
or func
and then call
to call an exported function safely.
§Here’s an example:
Given this WebAssembly:
(module
(type $t0 (func (param i32) (result i32)))
(func $add_one (export "add_one") (type $t0) (param $p0 i32) (result i32)
get_local $p0
i32.const 1
i32.add))
compiled into wasm bytecode, we can call the exported “add_one” function:
ⓘ
static WASM: &'static [u8] = &[
// The module above compiled to bytecode goes here.
// ...
];
use wasmer_runtime::{
instantiate,
Value,
imports,
error,
Func,
};
fn main() -> error::Result<()> {
// We're not importing anything, so make an empty import object.
let import_object = imports! {};
let mut instance = instantiate(WASM, &import_object)?;
let add_one: Func<i32, i32> = instance.exports.get("add_one")?;
let value = add_one.call(42)?;
assert_eq!(value, 43);
Ok(())
}
§Additional Notes:
wasmer-runtime
is built to support multiple compiler backends.
Currently, we support the Singlepass, Cranelift, and LLVM compilers
with the wasmer-singlepass-backend
, wasmer-clif-backend
, and
wasmer-llvm-backend crates, respectively.
You can specify the compiler you wish to use with the compile_with
function or use the default with the [compile
] function.
Modules§
- cache
- The cache module provides the common data structures used by compiler backends to allow serializing compiled wasm code to a binary format. The binary format can be persisted, and loaded to allow skipping compilation and fast startup.
- error
- The error module contains the data structures and helper functions used to implement errors that are produced and returned from the wasmer runtime.
- memory
- The memory module contains the implementation data structures and helper functions used to manipulate and access wasm memory.
- types
- Types used in the Wasm runtime and conversion functions.
- units
- Various unit types.
- wasm
- Various types exposed by the Wasmer Runtime.
Macros§
- func
- Helper macro to create a new
Func
object using the provided function pointer. - imports
- Generate an
ImportObject
safely.
Structs§
- Array
- The
Array
marker type. This type can be used likeWasmPtr<T, Array>
to get access to methods - Code
Version - A
CodeVersion
is a container for a unit of generated code for a module. - Compiler
Config - Configuration data for the compiler
- Ctx
- The context of the currently running WebAssembly instance.
- DynFunc
- A representation of an exported WebAssembly function.
- Features
- Controls which experimental features will be enabled. Features usually have a corresponding WebAssembly proposal.
- Func
- Represents a function that can be used by WebAssembly.
- Global
- A handle to a Wasm Global
- Import
Object - All of the import data used when instantiating.
- Instance
- An instantiated WebAssembly module.
- Item
- The
Item
marker type. This is the default and does not usually need to be specified. - Memory
- A shared or unshared wasm linear memory.
- Middleware
Chain - A container for a chain of middlewares.
- Module
- A compiled WebAssembly module.
- Streaming
Compiler - A streaming compiler which is designed to generated code for a module based on a stream of wasm parser events.
- Table
- Container with a descriptor and a reference to a table storage.
- WasmPtr
- A zero-cost type that represents a pointer to something in Wasm linear memory.
Enums§
- Backend
- Enum used to select which compiler should be used to generate code.
- Exception
Code - The code of an exception.
- Export
- Kind of WebAssembly export.
- Value
- Represents a WebAssembly value.
Constants§
- VERSION
- The current version of this crate.
Traits§
- Compiler
- Like
Namespace - This trait represents objects that act as a namespace for imports. For example, an
Instance
orImportObject
could be considered namespaces that could provide imports to an instance.
Functions§
- compile_
with - Compile a
Module
using the provided compiler from WebAssembly binary code. This function is useful if it is necessary to a compile a module before it can be instantiated and must be used if you wish to use a different backend from the default. - compile_
with_ config_ with - The same as
compile_with_config
but takes aCompiler
for the purpose of changing the backend. - compiler_
for_ backend - Get the
Compiler
as a trait object for the givenBackend
. ReturnsOption
because support for the requestedCompiler
may not be enabled by feature flags. - pop_
code_ version - Pops a
CodeVersion
from the current code versions. - push_
code_ version - Pushes a new
CodeVersion
to the current code versions. - validate
- Perform validation as defined by the
WebAssembly specification. Returns
true
if validation succeeded,false
if validation failed.