Struct wasmer::Module

pub struct Module { /* fields omitted */ }

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(store: &Store, 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)?;

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

Creates a new WebAssembly module from a file path.

pub fn from_binary(store: &Store, binary: &[u8]) -> Result<Self, CompileError>

Creates a new WebAssembly module from a 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(
    store: &Store,
    binary: &[u8]
) -> Result<Self, CompileError>

Creates a new WebAssembly module skipping any kind of validation.

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(store: &Store, 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<Vec<u8>, SerializeError>

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

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(
    store: &Store,
    bytes: &[u8]
) -> Result<Self, DeserializeError>

Deserializes a serialized Module binary into a Module.

Note: the module has to be serialized before with the 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 method is unsafe.

Usage

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

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

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

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

Safety

Please check Module::deserialize.

Usage

let module = Module::deserialize_from_file(&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 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<'a>(
    &'a self
) -> ImportsIterator<impl Iterator<Item = ImportType> + 'a>

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<'a>(
    &'a self
) -> ExportsIterator<impl Iterator<Item = ExportType> + 'a>

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 = Arc<[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.

pub fn store(&self) -> &Store

Returns the Store where the Instance belongs.

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 MemoryUsage for Module

fn size_of_val(&self, visited: &mut dyn MemoryUsageTracker) -> usize

Returns the size of the referenced value in bytes.