Struct wasmtime::component::Linker

source ·
pub struct Linker<T> { /* private fields */ }
Expand description

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§

source§

impl<T> Linker<T>

source

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

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

source

pub fn engine(&self) -> &Engine

Returns the Engine this is connected to.

source

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.

source

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

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

source

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.

source

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.

source

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.

source

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.

source

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

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.

source

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§

source§

impl<T> Clone for Linker<T>

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<T> Freeze for Linker<T>

§

impl<T> !RefUnwindSafe for Linker<T>

§

impl<T> Send for Linker<T>

§

impl<T> Sync for Linker<T>

§

impl<T> Unpin for Linker<T>

§

impl<T> !UnwindSafe for Linker<T>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
source§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.