Struct Module

pub struct Module(/* private fields */);

A WebAssembly Module contains stateless WebAssembly code that has already been compiled and can be instantiated multiple times.

Cloning a module

Cloning a module is cheap: it does a shallow copy of the compiled contents rather than a deep copy.

Implementations

impl Module

pub fn new( engine: &impl AsEngineRef, bytes: impl AsRef<[u8]>, ) -> Result<Self, CompileError>

Creates a new WebAssembly Module given the configuration in the store.

If the provided bytes are not WebAssembly-like (start with b"\0asm"), and the “wat” feature is enabled for this crate, this function will try to to convert the bytes assuming they correspond to the WebAssembly text format.

Security

Before the code is compiled, it will be validated using the store features.

Errors

Creating a WebAssembly module from bytecode can result in a CompileError since this operation requires to transorm the Wasm bytecode into code the machine can easily execute.

Example

Reading from a WAT file.

use wasmer::*;
let wat = "(module)";
let module = Module::new(&store, wat)?;

Reading from bytes:

use wasmer::*;
// The following is the same as:
// (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)
// )
let bytes: Vec<u8> = vec![
    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x01, 0x06, 0x01, 0x60,
    0x01, 0x7f, 0x01, 0x7f, 0x03, 0x02, 0x01, 0x00, 0x07, 0x0b, 0x01, 0x07,
    0x61, 0x64, 0x64, 0x5f, 0x6f, 0x6e, 0x65, 0x00, 0x00, 0x0a, 0x09, 0x01,
    0x07, 0x00, 0x20, 0x00, 0x41, 0x01, 0x6a, 0x0b, 0x00, 0x1a, 0x04, 0x6e,
    0x61, 0x6d, 0x65, 0x01, 0x0a, 0x01, 0x00, 0x07, 0x61, 0x64, 0x64, 0x5f,
    0x6f, 0x6e, 0x65, 0x02, 0x07, 0x01, 0x00, 0x01, 0x00, 0x02, 0x70, 0x30,
];
let module = Module::new(&store, bytes)?;

Example of loading a module using just an Engine and no Store

let module = Module::from_file(&engine, "path/to/foo.wasm");

pub fn from_file( engine: &impl AsEngineRef, file: impl AsRef<Path>, ) -> Result<Self, IoCompileError>

Creates a new WebAssembly module from a file path.

pub fn from_binary( engine: &impl AsEngineRef, binary: &[u8], ) -> Result<Self, CompileError>

Creates a new WebAssembly module from a Wasm binary.

Opposed to Module::new, this function is not compatible with the WebAssembly text format (if the “wat” feature is enabled for this crate).

pub unsafe fn from_binary_unchecked( engine: &impl AsEngineRef, binary: &[u8], ) -> Result<Self, CompileError>

Creates a new WebAssembly module from a Wasm binary, skipping any kind of validation on the WebAssembly file.

Safety

This can speed up compilation time a bit, but it should be only used in environments where the WebAssembly modules are trusted and validated beforehand.

pub fn validate( engine: &impl AsEngineRef, binary: &[u8], ) -> Result<(), CompileError>

Validates a new WebAssembly Module given the configuration in the Store.

This validation is normally pretty fast and checks the enabled WebAssembly features in the Store Engine to assure deterministic validation of the Module.

pub fn serialize(&self) -> Result<Bytes, SerializeError>

Serializes a module into a binary representation that the Engine can later process via Module::deserialize.

Important

This function will return a custom binary format that will be different than the wasm binary format, but faster to load in Native hosts.

Usage

let serialized = module.serialize()?;

pub fn serialize_to_file( &self, path: impl AsRef<Path>, ) -> Result<(), SerializeError>

Serializes a module into a file that the Engine can later process via Module::deserialize_from_file.

Usage

module.serialize_to_file("path/to/foo.so")?;

pub unsafe fn deserialize_unchecked( engine: &impl AsEngineRef, bytes: impl IntoBytes, ) -> Result<Self, DeserializeError>

Deserializes a serialized module binary into a Module.

Note: You should usually prefer the safer Module::deserialize.

Important

This function only accepts a custom binary format, which will be different than the wasm binary format and may change among Wasmer versions. (it should be the result of the serialization of a Module via the Module::serialize method.).

Safety

This function is inherently unsafe as the provided bytes:

1. Are going to be deserialized directly into Rust objects.
2. Contains the function assembly bodies and, if intercepted, a malicious actor could inject code into executable memory.

And as such, the deserialize_unchecked method is unsafe.

Usage

let module = Module::deserialize_unchecked(&store, serialized_data)?;

pub unsafe fn deserialize( engine: &impl AsEngineRef, bytes: impl IntoBytes, ) -> Result<Self, DeserializeError>

Deserializes a serialized Module binary into a Module.

Important

This function only accepts a custom binary format, which will be different than the wasm binary format and may change among Wasmer versions. (it should be the result of the serialization of a Module via the Module::serialize method.).

Usage

let module = Module::deserialize(&store, serialized_data)?;

Safety

This function is inherently unsafe, because it loads executable code into memory. The loaded bytes must be trusted to contain a valid artifact previously built with Self::serialize.

pub unsafe fn deserialize_from_file( engine: &impl AsEngineRef, path: impl AsRef<Path>, ) -> Result<Self, DeserializeError>

Deserializes a serialized Module located in a Path into a Module.

Note: the module has to be serialized before with the serialize method.

Usage

let module = Module::deserialize_from_file(&store, path)?;

Safety

See Self::deserialize.

pub unsafe fn deserialize_from_file_unchecked( engine: &impl AsEngineRef, path: impl AsRef<Path>, ) -> Result<Self, DeserializeError>

Deserializes a serialized Module located in a Path into a Module.

Note: the module has to be serialized before with the serialize method.

You should usually prefer the safer Module::deserialize_from_file.

Safety

Please check Module::deserialize_unchecked.

Usage

let module = Module::deserialize_from_file_unchecked(&store, path)?;

pub fn name(&self) -> Option<&str>

Returns the name of the current module.

This name is normally set in the WebAssembly bytecode by some compilers, but can be also overwritten using the Module::set_name method.

Example

let wat = "(module $moduleName)";
let module = Module::new(&store, wat)?;
assert_eq!(module.name(), Some("moduleName"));

pub fn set_name(&mut self, name: &str) -> bool

Sets the name of the current module. This is normally useful for stacktraces and debugging.

It will return true if the module name was changed successfully, and return false otherwise (in case the module is cloned or already instantiated).

Example

let wat = "(module)";
let mut module = Module::new(&store, wat)?;
assert_eq!(module.name(), None);
module.set_name("foo");
assert_eq!(module.name(), Some("foo"));

pub fn imports(&self) -> ImportsIterator<impl Iterator<Item = ImportType> + '_>

Returns an iterator over the imported types in the Module.

The order of the imports is guaranteed to be the same as in the WebAssembly bytecode.

Example

let wat = r#"(module
    (import "host" "func1" (func))
    (import "host" "func2" (func))
)"#;
let module = Module::new(&store, wat)?;
for import in module.imports() {
    assert_eq!(import.module(), "host");
    assert!(import.name().contains("func"));
    import.ty();
}

pub fn exports(&self) -> ExportsIterator<impl Iterator<Item = ExportType> + '_>

Returns an iterator over the exported types in the Module.

The order of the exports is guaranteed to be the same as in the WebAssembly bytecode.

Example

let wat = r#"(module
    (func (export "namedfunc"))
    (memory (export "namedmemory") 1)
)"#;
let module = Module::new(&store, wat)?;
for export_ in module.exports() {
    assert!(export_.name().contains("named"));
    export_.ty();
}

pub fn custom_sections<'a>( &'a self, name: &'a str, ) -> impl Iterator<Item = Box<[u8]>> + 'a

Get the custom sections of the module given a name.

Important

Following the WebAssembly spec, one name can have multiple custom sections. That’s why an iterator (rather than one element) is returned.

Trait Implementations

impl Clone for Module

fn clone(&self) -> Module

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Module

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Module

fn eq(&self, other: &Module) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Module

impl StructuralPartialEq for Module