Struct Module

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

Newtype wrapper around wasmtime::Module.

Implementations

impl Module

pub fn new(inner: Module) -> Self

Create a wasm_runtime_layer::Module-compatible Module from a wasmtime::Module.

pub fn into_inner(self) -> Module

Consume a Module to obtain the inner wasmtime::Module.

Methods from Deref<Target = Module>

pub fn serialize(&self) -> Result<Vec<u8>, Error>

Serializes this module to a vector of bytes.

This function is similar to the Engine::precompile_module method where it produces an artifact of Wasmtime which is suitable to later pass into Module::deserialize. If a module is never instantiated then it’s recommended to use Engine::precompile_module instead of this method, but if a module is both instantiated and serialized then this method can be useful to get the serialized version without compiling twice.

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

Returns identifier/name that this Module has. This name is used in traps/backtrace details.

Note that most LLVM/clang/Rust-produced modules do not have a name associated with them, but other wasm tooling can be used to inject or add a name.

Examples

let module = Module::new(&engine, "(module $foo)")?;
assert_eq!(module.name(), Some("foo"));

let module = Module::new(&engine, "(module)")?;
assert_eq!(module.name(), None);

pub fn imports<'module>(&'module self) -> impl ExactSizeIterator + 'module

Returns the list of imports that this Module has and must be satisfied.

This function returns the list of imports that the wasm module has, but only the types of each import. The type of each import is used to typecheck the Instance::new method’s imports argument. The arguments to that function must match up 1-to-1 with the entries in the array returned here.

The imports returned reflect the order of the imports in the wasm module itself, and note that no form of deduplication happens.

Examples

Modules with no imports return an empty list here:

let module = Module::new(&engine, "(module)")?;
assert_eq!(module.imports().len(), 0);

and modules with imports will have a non-empty list:

let wat = r#"
    (module
        (import "host" "foo" (func))
    )
"#;
let module = Module::new(&engine, wat)?;
assert_eq!(module.imports().len(), 1);
let import = module.imports().next().unwrap();
assert_eq!(import.module(), "host");
assert_eq!(import.name(), "foo");
match import.ty() {
    ExternType::Func(_) => { /* ... */ }
    _ => panic!("unexpected import type!"),
}

pub fn exports<'module>(&'module self) -> impl ExactSizeIterator + 'module

Returns the list of exports that this Module has and will be available after instantiation.

This function will return the type of each item that will be returned from Instance::exports. Each entry in this list corresponds 1-to-1 with that list, and the entries here will indicate the name of the export along with the type of the export.

Examples

Modules might not have any exports:

let module = Module::new(&engine, "(module)")?;
assert!(module.exports().next().is_none());

When the exports are not empty, you can inspect each export:

let wat = r#"
    (module
        (func (export "foo"))
        (memory (export "memory") 1)
    )
"#;
let module = Module::new(&engine, wat)?;
assert_eq!(module.exports().len(), 2);

let mut exports = module.exports();
let foo = exports.next().unwrap();
assert_eq!(foo.name(), "foo");
match foo.ty() {
    ExternType::Func(_) => { /* ... */ }
    _ => panic!("unexpected export type!"),
}

let memory = exports.next().unwrap();
assert_eq!(memory.name(), "memory");
match memory.ty() {
    ExternType::Memory(_) => { /* ... */ }
    _ => panic!("unexpected export type!"),
}

pub fn get_export(&self, name: &str) -> Option<ExternType>

Looks up an export in this Module by name.

This function will return the type of an export with the given name.

Examples

There may be no export with that name:

let module = Module::new(&engine, "(module)")?;
assert!(module.get_export("foo").is_none());

When there is an export with that name, it is returned:

let wat = r#"
    (module
        (func (export "foo"))
        (memory (export "memory") 1)
    )
"#;
let module = Module::new(&engine, wat)?;
let foo = module.get_export("foo");
assert!(foo.is_some());

let foo = foo.unwrap();
match foo {
    ExternType::Func(_) => { /* ... */ }
    _ => panic!("unexpected export type!"),
}

pub fn get_export_index(&self, name: &str) -> Option<ModuleExport>

Looks up an export in this Module by name to get its index.

This function will return the index of an export with the given name. This can be useful to avoid the cost of looking up the export by name multiple times. Instead the ModuleExport can be stored and used to look up the export on the Instance later.

pub fn engine(&self) -> &Engine

Returns the Engine that this Module was compiled by.

pub fn resources_required(&self) -> ResourcesRequired

Returns a summary of the resources required to instantiate this Module.

Potential uses of the returned information:

• Determining whether your pooling allocator configuration supports instantiating this module.

• Deciding how many of which Module you want to instantiate within a fixed amount of resources, e.g. determining whether to create 5 instances of module X or 10 instances of module Y.

Example

use wasmtime::{Config, Engine, Module};

let mut config = Config::new();
config.wasm_multi_memory(true);
let engine = Engine::new(&config)?;

let module = Module::new(&engine, r#"
    (module
        ;; Import a memory. Doesn't count towards required resources.
        (import "a" "b" (memory 10))
        ;; Define two local memories. These count towards the required
        ;; resources.
        (memory 1)
        (memory 6)
    )
"#)?;

let resources = module.resources_required();

// Instantiating the module will require allocating two memories, and
// the maximum initial memory size is six Wasm pages.
assert_eq!(resources.num_memories, 2);
assert_eq!(resources.max_initial_memory_size, Some(6));

// The module doesn't need any tables.
assert_eq!(resources.num_tables, 0);
assert_eq!(resources.max_initial_table_size, None);

pub fn image_range(&self) -> Range<*const u8>

Returns the range of bytes in memory where this module’s compilation image resides.

The compilation image for a module contains executable code, data, debug information, etc. This is roughly the same as the Module::serialize but not the exact same.

The range of memory reported here is exposed to allow low-level manipulation of the memory in platform-specific manners such as using mlock to force the contents to be paged in immediately or keep them paged in after they’re loaded.

It is not safe to modify the memory in this range, nor is it safe to modify the protections of memory in this range.

pub fn initialize_copy_on_write_image(&self) -> Result<(), Error>

Force initialization of copy-on-write images to happen here-and-now instead of when they’re requested during first instantiation.

When copy-on-write memory initialization is enabled then Wasmtime will lazily create the initialization image for a module. This method can be used to explicitly dictate when this initialization happens.

Note that this largely only matters on Linux when memfd is used. Otherwise the copy-on-write image typically comes from disk and in that situation the creation of the image is trivial as the image is always sourced from disk. On Linux, though, when memfd is used a memfd is created and the initialization image is written to it.

Also note that this method is not required to be called, it’s available as a performance optimization if required but is otherwise handled automatically.

pub fn address_map<'a>( &'a self, ) -> Option<impl Iterator<Item = (usize, Option<u32>)> + 'a>

Get the map from .text section offsets to Wasm binary offsets for this module.

Each entry is a (.text section offset, Wasm binary offset) pair.

Entries are yielded in order of .text section offset.

Some entries are missing a Wasm binary offset. This is for code that is not associated with any single location in the Wasm binary, or for when source information was optimized away.

Not every module has an address map, since address map generation can be turned off on Config.

There is not an entry for every .text section offset. Every offset after an entry’s offset, but before the next entry’s offset, is considered to map to the same Wasm binary offset as the original entry. For example, the address map will not contain the following sequence of entries:

[
    // ...
    (10, Some(42)),
    (11, Some(42)),
    (12, Some(42)),
    (13, Some(43)),
    // ...
]

Instead, it will drop the entries for offsets 11 and 12 since they are the same as the entry for offset 10:

[
    // ...
    (10, Some(42)),
    (13, Some(43)),
    // ...
]

pub fn text(&self) -> &[u8]

Get this module’s code object’s .text section, containing its compiled executable code.

pub fn functions<'a>(&'a self) -> impl ExactSizeIterator + 'a

Get information about functions in this module’s .text section: their index, name, and offset+length.

Results are yielded in a ModuleFunction struct.

Trait Implementations

impl AsMut<Module> for Module

fn as_mut(&mut self) -> &mut Module

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<Module> for Module

fn as_mut(&mut self) -> &mut Module

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<Module> for Module

fn as_ref(&self) -> &Module

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Module> for Module

fn as_ref(&self) -> &Module

Converts this type into a shared reference of the (usually inferred) input type.

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

type Target = Module

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Module

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl From<Module> for Module

fn from(inner: Module) -> Self

Converts to this type from the input type.

impl From<Module> for Module

fn from(wrapper: Module) -> Self

Converts to this type from the input type.

impl RefCast for Module

type From = Module

fn ref_cast(_from: &Self::From) -> &Self

fn ref_cast_mut(_from: &mut Self::From) -> &mut Self

impl WasmModule<Engine> for Module

fn new(engine: &Engine, bytes: &[u8]) -> Result<Self>

Creates a new module from the given byte slice.

fn exports(&self) -> Box<dyn Iterator<Item = ExportType<'_>> + '_>

Gets the export types of the module.

fn get_export(&self, name: &str) -> Option<ExternType>

Gets the export type of the given name, if any, from this module.

fn imports(&self) -> Box<dyn Iterator<Item = ImportType<'_>> + '_>

Gets the import types of the module.