pub struct Linker<T> { /* private fields */ }
Expand description
A type used to instantiate Component
s.
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>
impl<T> Linker<T>
sourcepub fn new(engine: &Engine) -> Linker<T>
pub fn new(engine: &Engine) -> Linker<T>
Creates a new linker for the Engine
specified with no items defined
within it.
sourcepub fn allow_shadowing(&mut self, allow: bool) -> &mut Self
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.
sourcepub fn root(&mut self) -> LinkerInstance<'_, T>
pub fn root(&mut self) -> LinkerInstance<'_, T>
Returns the “root instance” of this linker, used to define names into the root namespace.
sourcepub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>>
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.
sourcepub fn substituted_component_type(
&self,
component: &Component,
) -> Result<Component>
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
.
sourcepub fn instantiate_pre(&self, component: &Component) -> Result<InstancePre<T>>
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.
sourcepub fn instantiate(
&self,
store: impl AsContextMut<Data = T>,
component: &Component,
) -> Result<Instance>
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.
sourcepub async fn instantiate_async(
&self,
store: impl AsContextMut<Data = T>,
component: &Component,
) -> Result<Instance>where
T: Send,
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.
sourcepub fn define_unknown_imports_as_traps(
&mut self,
component: &Component,
) -> Result<()>
pub fn define_unknown_imports_as_traps( &mut self, component: &Component, ) -> Result<()>
Trait Implementations§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
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 moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
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