Struct substrate_wasmtime::Module

pub struct Module { /* fields omitted */ }

A compiled WebAssembly module, ready to be instantiated.

A Module is a compiled in-memory representation of an input WebAssembly binary. A Module is then used to create an Instance through an instantiation process. You cannot call functions or fetch globals, for example, on a Module because it's purely a code representation. Instead you'll need to create an Instance to interact with the wasm module.

Modules and Clone

Using clone on a Module is a cheap operation. It will not create an entirely new module, but rather just a new reference to the existing module. In other words it's a shallow copy, not a deep copy.

Methods

impl Module

pub fn new(store: &Store, bytes: impl AsRef<[u8]>) -> Result<Module>

Creates a new WebAssembly Module from the given in-memory bytes.

The bytes provided must be in one of two formats:

• It can be a binary-encoded WebAssembly module. This is always supported.
• It may also be a text-encoded instance of the WebAssembly text format. This is only supported when the wat feature of this crate is enabled. If this is supplied then the text format will be parsed before validation. Note that the wat feature is enabled by default.

The data for the wasm module must be loaded in-memory if it's present elsewhere, for example on disk. This requires that the entire binary is loaded into memory all at once, this API does not support streaming compilation of a module.

The WebAssembly binary will be decoded and validated. It will also be compiled according to the configuration of the provided store and cached in this type.

The provided store is a global cache for compiled resources as well as configuration for what wasm features are enabled. It's recommended to share a store among modules if possible.

Errors

This function may fail and return an error. Errors may include situations such as:

• The binary provided could not be decoded because it's not a valid WebAssembly binary
• The WebAssembly binary may not validate (e.g. contains type errors)
• Implementation-specific limits were exceeded with a valid binary (for example too many locals)
• The wasm binary may use features that are not enabled in the configuration of store
• If the wat feature is enabled and the input is text, then it may be rejected if it fails to parse.

The error returned should contain full information about why module creation failed if one is returned.

pub fn new_with_name(
    store: &Store,
    bytes: impl AsRef<[u8]>,
    name: &str
) -> Result<Module>

Creates a new WebAssembly Module from the given in-memory binary data. The provided name will be used in traps/backtrace details.

See Module::new for other details.

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

Creates a new WebAssembly Module from the contents of the given file on disk.

This is a convenience function that will read the file provided and pass the bytes to the Module::new function. For more information see Module::new

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

Creates a new WebAssembly Module from the given in-memory binary data.

This is similar to Module::new except that it requires that the binary input is a WebAssembly binary, the text format is not supported by this function. It's generally recommended to use Module::new, but if it's required to not support the text format this function can be used instead.

pub unsafe fn from_binary_unchecked(
    store: &Store,
    binary: &[u8]
) -> Result<Module>

Creates a new WebAssembly Module from the given in-memory binary data, skipping validation and asserting that binary is a valid WebAssembly module.

This function is the same as Module::new except that it skips the call to Module::validate and it does not support the text format of WebAssembly. The WebAssembly binary is not validated for correctness and it is simply assumed as valid.

For more information about creation of a module and the store argument see the documentation of Module::new.

Unsafety

This function is unsafe due to the unchecked assumption that the input binary is valid. If the binary is not actually a valid wasm binary it may cause invalid machine code to get generated, cause panics, etc.

It is only safe to call this method if Module::validate succeeds on the same arguments passed to this function.

Errors

This function may fail for many of the same reasons as Module::new. While this assumes that the binary is valid it still needs to actually be somewhat valid for decoding purposes, and the basics of decoding can still fail.

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

Validates binary input data as a WebAssembly binary given the configuration in store.

This function will perform a speedy validation of the binary input WebAssembly module (which is in binary form, the text format is not accepted by this function) and return either Ok or Err depending on the results of validation. The store argument indicates configuration for WebAssembly features, for example, which are used to indicate what should be valid and what shouldn't be.

Validation automatically happens as part of Module::new, but is a requirement for [Module::new_unchecked] to be safe.

Errors

If validation fails for any reason (type check error, usage of a feature that wasn't enabled, etc) then an error with a description of the validation issue will be returned.

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

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

pub fn imports(&self) -> &[ImportType]

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

pub fn exports(&self) -> &[ExportType]

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

pub fn store(&self) -> &Store

Returns the Store that this Module was compiled into.

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.