Struct wasmtime::Linker

pub struct Linker { /* fields omitted */ }

Structure used to link wasm modules/instances together.

This structure is used to assist in instantiating a Module. A Linker is a way of performing name resolution to make instantiating a module easier (as opposed to calling Instance::new). Linker is a name-based resolver where names are dynamically defined and then used to instantiate a Module. The goal of a Linker is to have a one-argument method, Linker::instantiate, which takes a Module and produces an Instance. This method will automatically select all the right imports for the Module to be instantiated, and will otherwise return an error if an import isn't satisfied.

Name Resolution

As mentioned previously, Linker is a form of name resolver. It will be using the string-based names of imports on a module to attempt to select a matching item to hook up to it. This name resolution has two-levels of namespaces, a module level and a name level. Each item is defined within a module and then has its own name. This basically follows the wasm standard for modularization.

Names in a Linker can be defined twice, but only for different signatures of items. This means that every item defined in a Linker has a unique name/type pair. For example you can define two functions with the module name foo and item name bar, so long as they have different function signatures. Currently duplicate memories and tables are not allowed, only one-per-name is allowed.

Note that allowing duplicates by shadowing the previous definition can be controlled with the Linker::allow_shadowing method as well.

Methods

impl Linker

pub fn new(store: &Store) -> Linker

Creates a new Linker.

This function will create a new Linker which is ready to start linking modules. All items defined in this linker and produced by this linker will be connected with store and must come from the same store.

Examples

use wasmtime::{Linker, Store};

let store = Store::default();
let mut linker = Linker::new(&store);
// ...

pub fn allow_shadowing(&mut self, allow: bool) -> &mut Linker

Configures whether this Linker will shadow previous duplicate definitions of the same signature.

By default a Linker will disallow duplicate definitions of the same signature. This method, however, can be used to instead allow duplicates and have the latest definition take precedence when linking modules.

Examples

let mut linker = Linker::new(&store);
linker.func("", "", || {})?;

// by default, duplicates are disallowed
assert!(linker.func("", "", || {}).is_err());

// but shadowing can be configured to be allowed as well
linker.allow_shadowing(true);
linker.func("", "", || {})?;

pub fn define(
    &mut self,
    module: &str,
    name: &str,
    item: impl Into<Extern>
) -> Result<&mut Self>

Defines a new item in this Linker.

This method will add a new definition, by name, to this instance of Linker. The module and name provided are what to name the item.

Errors

Returns an error if the module and name already identify an item of the same type as the item provided and if shadowing is disallowed. For more information see the documentation on Linker.

Also returns an error if item comes from a different store than this Linker was created with.

Examples

let mut linker = Linker::new(&store);
let ty = GlobalType::new(ValType::I32, Mutability::Const);
let global = Global::new(&store, ty, Val::I32(0x1234))?;
linker.define("host", "offset", global)?;

let wat = r#"
    (module
        (import "host" "offset" (global i32))
        (memory 1)
        (data (global.get 0) "foo")
    )
"#;
let module = Module::new(&store, wat)?;
linker.instantiate(&module)?;

pub fn func<Params, Args>(
    &mut self,
    module: &str,
    name: &str,
    func: impl IntoFunc<Params, Args>
) -> Result<&mut Self>

Convenience wrapper to define a function import.

This method is a convenience wrapper around Linker::define which internally delegates to Func::wrap.

Errors

Returns an error if the module and name already identify an item of the same type as the item provided and if shadowing is disallowed. For more information see the documentation on Linker.

Examples

let mut linker = Linker::new(&store);
linker.func("host", "double", |x: i32| x * 2)?;
linker.func("host", "log_i32", |x: i32| println!("{}", x))?;
linker.func("host", "log_str", |caller: Caller, ptr: i32, len: i32| {
    // ...
})?;

let wat = r#"
    (module
        (import "host" "double" (func (param i32) (result i32)))
        (import "host" "log_i32" (func (param i32)))
        (import "host" "log_str" (func (param i32 i32)))
    )
"#;
let module = Module::new(&store, wat)?;
linker.instantiate(&module)?;

pub fn instance(
    &mut self,
    module_name: &str,
    instance: &Instance
) -> Result<&mut Self>

Convenience wrapper to define an entire Instance in this linker.

This function is a convenience wrapper around Linker::define which will define all exports on instance into this linker. The module name for each export is module_name, and the name for each export is the name in the instance itself.

Errors

Returns an error if the any item is redefined twice in this linker (for example the same module_name was already defined) and shadowing is disallowed, or if instance comes from a different Store than this Linker originally was created with.

Examples

let mut linker = Linker::new(&store);

// Instantiate a small instance...
let wat = r#"(module (func (export "run") ))"#;
let module = Module::new(&store, wat)?;
let instance = linker.instantiate(&module)?;

// ... and inform the linker that the name of this instance is
// `instance1`. This defines the `instance1::run` name for our next
// module to use.
linker.instance("instance1", &instance)?;

let wat = r#"
    (module
        (import "instance1" "run" (func $instance1_run))
        (func (export "run")
            call $instance1_run
        )
    )
"#;
let module = Module::new(&store, wat)?;
let instance = linker.instantiate(&module)?;

pub fn instantiate(&self, module: &Module) -> Result<Instance>

Attempts to instantiate the module provided.

This method will attempt to assemble a list of imports that correspond to the imports required by the Module provided. This list of imports is then passed to Instance::new to continue the instantiation process.

Each import of module will be looked up in this Linker and must have previously been defined. If it was previously defined with an incorrect signature or if it was not prevoiusly defined then an error will be returned because the import can not be satisfied.

Errors

This method can fail because an import may not be found, or because instantiation itself may fail. For information on instantiation failures see Instance::new.

Examples

let mut linker = Linker::new(&store);
linker.func("host", "double", |x: i32| x * 2)?;

let wat = r#"
    (module
        (import "host" "double" (func (param i32) (result i32)))
    )
"#;
let module = Module::new(&store, wat)?;
linker.instantiate(&module)?;

pub fn store(&self) -> &Store

Returns the Store that this linker is connected to.