Struct Linker

pub struct Linker<T> { /* private fields */ }

Available on crate features runtime and component-model only.

A type used to instantiate Components.

This type is used to both link components together as well as supply host functionality to components. Values are defined in a Linker by their import name and then components are instantiated with a Linker using the names provided for name resolution of the component’s imports.

Names and Semver

Names defined in a Linker correspond to import names in the Component Model. Names in the Component Model are allowed to be semver-qualified, for example:

• wasi:cli/stdout@0.2.0
• wasi:http/types@0.2.0-rc-2023-10-25
• my:custom/plugin@1.0.0-pre.2

These version strings are taken into account when looking up names within a Linker. You’re allowed to define any number of versions within a Linker still, for example you can define a:b/c@0.2.0, a:b/c@0.2.1, and a:b/c@0.3.0 all at the same time.

Specifically though when names are looked up within a linker, for example during instantiation, semver-compatible names are automatically consulted. This means that if you define a:b/c@0.2.1 in a Linker but a component imports a:b/c@0.2.0 then that import will resolve to the 0.2.1 version.

This lookup behavior relies on hosts being well-behaved when using Semver, specifically that interfaces once defined are never changed. This reflects how Semver works at the Component Model layer, and it’s assumed that if versions are present then hosts are respecting this.

Note that this behavior goes the other direction, too. If a component imports a:b/c@0.2.1 and the host has provided a:b/c@0.2.0 then that will also resolve correctly. This is because if an API was defined at 0.2.0 and 0.2.1 then it must be the same API.

This behavior is intended to make it easier for hosts to upgrade WASI and for guests to upgrade WASI. So long as the actual “meat” of the functionality is defined then it should align correctly and components can be instantiated.

Implementations

impl<T> Linker<T>

pub fn new(engine: &Engine) -> Linker<T>

Creates a new linker for the Engine specified with no items defined within it.

pub fn engine(&self) -> &Engine

Returns the Engine this is connected to.

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

Configures whether or not name-shadowing is allowed.

By default name shadowing is not allowed and it’s an error to redefine the same name within a linker.

pub fn root(&mut self) -> LinkerInstance<'_, T>

Returns the “root instance” of this linker, used to define names into the root namespace.

pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>>

Returns a builder for the named instance specified.

Errors

Returns an error if name is already defined within the linker.

pub fn substituted_component_type( &self, component: &Component, ) -> Result<Component>

Returns the types::Component corresponding to component with resource types imported by it replaced using imports present in Self.

pub fn instantiate_pre(&self, component: &Component) -> Result<InstancePre<T>>

Performs a “pre-instantiation” to resolve the imports of the Component specified with the items defined within this linker.

This method will perform as much work as possible short of actually instantiating an instance. Internally this will use the names defined within this linker to satisfy the imports of the Component provided. Additionally this will perform type-checks against the component’s imports against all items defined within this linker.

Note that unlike internally in components where subtyping at the interface-types layer is supported this is not supported here. Items defined in this linker must match the component’s imports precisely.

Errors

Returns an error if this linker doesn’t define a name that the component imports or if a name defined doesn’t match the type of the item imported by the component provided.

pub fn instantiate( &self, store: impl AsContextMut<Data = T>, component: &Component, ) -> Result<Instance>

Instantiates the Component provided into the store specified.

This function will use the items defined within this Linker to satisfy the imports of the Component provided as necessary. For more information about this see Linker::instantiate_pre as well.

Errors

Returns an error if this Linker doesn’t define an import that component requires or if it is of the wrong type. Additionally this can return an error if something goes wrong during instantiation such as a runtime trap or a runtime limit being exceeded.

pub async fn instantiate_async( &self, store: impl AsContextMut<Data = T>, component: &Component, ) -> Result<Instance>

where T: Send,

Available on crate feature async only.

Instantiates the Component provided into the store specified.

This is exactly like Linker::instantiate except for async stores.

Errors

Returns an error if this Linker doesn’t define an import that component requires or if it is of the wrong type. Additionally this can return an error if something goes wrong during instantiation such as a runtime trap or a runtime limit being exceeded.

pub fn define_unknown_imports_as_traps( &mut self, component: &Component, ) -> Result<()>

Implement any imports of the given Component with a function which traps.

By default a Linker will error when unknown imports are encountered when instantiating a Component. This changes this behavior from an instant error to a trap that will happen if the import is called.

Trait Implementations

impl<T> Clone for Linker<T>

fn clone(&self) -> Linker<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.