Module wasmtime::component

source ·
Expand description

§Embedding API for the Component Model

This module contains the embedding API for the Component Model in Wasmtime. This module requires the component-model feature to be enabled, which is enabled by default. The embedding API here is mirrored after the core wasm embedding API at the crate root and is intended to have the same look-and-feel while handling concepts of the component model.

The component model is a broad topic which can’t be explained here fully, so it’s recommended to read over individual items’ documentation to see more about the capabilities of the embedding API. At a high-level, however, perhaps the most interesting items in this module are:

  • Component - a compiled component ready to be instantiated. Similar to a Module for core wasm.

  • Linker - a component-style location for defining host functions. This is not the same as wasmtime::Linker for core wasm modules.

  • bindgen! - a macro to generate Rust bindings for a WIT world. This maps all WIT types into Rust automatically and generates traits for embedders to implement.

Embedders of the component model will typically start by defining their API in WIT. This describes what will be available to guests and what needs to be provided to the embedder by the guest. This world that was created is then fed into bindgen! to generate types and traits for the embedder to use. The embedder then implements these traits, adds functionality via the generated add_to_linker method (see bindgen! for more info), and then instantiates/executes a component.

It’s recommended to read over the documentation for the Component Model to get an overview about how to build components from various languages.

§Example Usage

Imagine you have the following WIT package definition in a file called world.wit along with a component (my_component.wasm) that targets my-world:

package component:my-package;

world my-world {
    import name: func() -> string;
    export greet: func() -> string;
}

You can instantiate and call the component like so:

fn main() -> wasmtime::Result<()> {
    // Instantiate the engine and store
    let engine = wasmtime::Engine::default();
    let mut store = wasmtime::Store::new(&engine, ());

    // Load the component from disk
    let bytes = std::fs::read("my_component.wasm")?;
    let component = wasmtime::component::Component::new(&engine, bytes)?;

    // Configure the linker
    let mut linker = wasmtime::component::Linker::new(&engine);
    // The component expects one import `name` that
    // takes no params and returns a string
    linker
        .root()
        .func_wrap("name", |_store, _params: ()| {
            Ok((String::from("Alice"),))
        })?;

    // Instantiate the component
    let instance = linker.instantiate(&mut store, &component)?;

    // Call the `greet` function
    let func = instance.get_func(&mut store, "greet").expect("greet export not found");
    let mut result = [wasmtime::component::Val::String("".into())];
    func.call(&mut store, &[], &mut result)?;

    // This should print out `Greeting: [String("Hello, Alice!")]`
    println!("Greeting: {:?}", result);

    Ok(())
}

Manually configuring the linker and calling untyped component exports is a bit tedious and error prone. The bindgen! macro can be used to generate bindings eliminating much of this boilerplate.

See the docs for bindgen! for more information on how to use it.

Modules§

  • types
    This module defines the Type type, representing the dynamic form of a component interface type.

Macros§

Structs§

  • Component
    A compiled WebAssembly Component.
  • ComponentExportIndex
    A value which represents a known export of a component.
  • Func
    A WebAssembly component function which can be called.
  • Instance
    An instantiated component.
  • InstancePre
    A “pre-instantiated” Instance which has all of its arguments already supplied and is ready to instantiate.
  • Linker
    A type used to instantiate Components.
  • LinkerInstance
    Structure representing an “instance” being defined within a linker.
  • Resource
    A host-defined resource in the component model.
  • ResourceAny
    Representation of a resource in the component model, either a guest-defined or a host-defined resource.
  • ResourceTable
    The ResourceTable type maps a Resource<T> to its T.
  • ResourceType
    Representation of a resource type in the component model.
  • TypedFunc
    A statically-typed version of Func which takes Params as input and returns Return.
  • WasmList
    Representation of a list of values that are owned by a WebAssembly instance.
  • WasmStr
    Representation of a string located in linear memory in a WebAssembly instance.

Enums§

  • ResourceTableError
    Errors returned by operations on ResourceTable
  • Type
    Represents a component model interface type
  • Val
    Represents possible runtime values which a component function can either consume or produce

Traits§

  • ComponentNamedList
    A trait representing a static list of named types that can be passed to or returned from a TypedFunc.
  • ComponentType
    A trait representing types which can be passed to and read from components with the canonical ABI.
  • InstanceExportLookup
    Trait used to lookup the export of a component instance.
  • Lift
    Host types which can be created from the canonical ABI.
  • Lower
    Host types which can be passed to WebAssembly components.

Derive Macros§