wasmtime/runtime/component/

linker.rs

#[cfg(feature = "component-model-async")]
use crate::component::concurrent::Accessor;
use crate::component::func::HostFunc;
use crate::component::instance::RuntimeImport;
use crate::component::matching::{InstanceType, TypeChecker};
use crate::component::types;
use crate::component::{
    Component, ComponentNamedList, Instance, InstancePre, Lift, Lower, ResourceType, Val,
};
use crate::prelude::*;
use crate::{AsContextMut, Engine, Module, StoreContextMut};
use alloc::sync::Arc;
use core::marker;
#[cfg(feature = "component-model-async")]
use core::pin::Pin;
use wasmtime_environ::component::{NameMap, NameMapIntern};
use wasmtime_environ::{Atom, PrimaryMap, StringPool};

/// A type used to instantiate [`Component`]s.
///
/// This type is used to 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.
pub struct Linker<T: 'static> {
    engine: Engine,
    strings: StringPool,
    map: NameMap<Atom, Definition>,
    path: Vec<Atom>,
    allow_shadowing: bool,
    _marker: marker::PhantomData<fn() -> T>,
}

impl<T: 'static> Clone for Linker<T> {
    fn clone(&self) -> Linker<T> {
        Linker {
            engine: self.engine.clone(),
            strings: self.strings.clone_panic_on_oom(),
            map: self.map.clone_panic_on_oom(),
            path: self.path.clone(),
            allow_shadowing: self.allow_shadowing,
            _marker: self._marker,
        }
    }
}

/// Structure representing an "instance" being defined within a linker.
///
/// Instances do not need to be actual [`Instance`]s and instead are defined by
/// a "bag of named items", so each [`LinkerInstance`] can further define items
/// internally.
pub struct LinkerInstance<'a, T: 'static> {
    engine: &'a Engine,
    path: &'a mut Vec<Atom>,
    path_len: usize,
    strings: &'a mut StringPool,
    map: &'a mut NameMap<Atom, Definition>,
    allow_shadowing: bool,
    _marker: marker::PhantomData<fn() -> T>,
}

#[derive(Debug)]
pub(crate) enum Definition {
    Instance(NameMap<Atom, Definition>),
    Func(Arc<HostFunc>),
    Module(Module),
    Resource(ResourceType, Arc<crate::func::HostFunc>),
}

impl TryClone for Definition {
    fn try_clone(&self) -> Result<Self, OutOfMemory> {
        Ok(match self {
            Self::Instance(i) => Self::Instance(i.try_clone()?),
            Self::Func(f) => Self::Func(f.try_clone()?),
            Self::Module(m) => Self::Module(m.clone()),
            Self::Resource(r, f) => Self::Resource(*r, f.try_clone()?),
        })
    }
}

impl<T: 'static> Linker<T> {
    /// Creates a new linker for the [`Engine`] specified with no items defined
    /// within it.
    pub fn new(engine: &Engine) -> Linker<T> {
        Linker {
            engine: engine.clone(),
            strings: StringPool::default(),
            map: NameMap::default(),
            allow_shadowing: false,
            path: Vec::new(),
            _marker: marker::PhantomData,
        }
    }

    /// Returns the [`Engine`] this is connected to.
    pub fn engine(&self) -> &Engine {
        &self.engine
    }

    /// 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 allow_shadowing(&mut self, allow: bool) -> &mut Self {
        self.allow_shadowing = allow;
        self
    }

    /// Returns the "root instance" of this linker, used to define names into
    /// the root namespace.
    pub fn root(&mut self) -> LinkerInstance<'_, T> {
        LinkerInstance {
            engine: &self.engine,
            path: &mut self.path,
            path_len: 0,
            strings: &mut self.strings,
            map: &mut self.map,
            allow_shadowing: self.allow_shadowing,
            _marker: self._marker,
        }
    }

    /// Returns a builder for the named instance specified.
    ///
    /// # Errors
    ///
    /// Returns an error if `name` is already defined within the linker.
    pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>> {
        self.root().into_instance(name)
    }

    fn typecheck<'a>(&'a self, component: &'a Component) -> Result<TypeChecker<'a>> {
        let mut cx = TypeChecker {
            engine: &self.engine,
            types: component.types(),
            strings: &self.strings,
            imported_resources: try_new::<Arc<_>>(TryPrimaryMap::new())?,
        };

        // Walk over the component's list of import names and use that to look up
        // the definition within this linker that it corresponds to. When found
        // perform a typecheck against the component's expected type.
        let env_component = component.env_component();
        for (_idx, (name, ty)) in env_component.import_types.iter() {
            let import = self.map.get(name, &self.strings);
            cx.definition(&ty.ty, import).with_context(|| {
                format!(
                    "component imports {desc} `{name}`, but \
                     a matching implementation was not found in the linker",
                    desc = ty.ty.desc()
                )
            })?;
        }
        Ok(cx)
    }

    /// Returns the [`types::Component`] corresponding to `component` with resource
    /// types imported by it replaced using imports present in [`Self`].
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn substituted_component_type(&self, component: &Component) -> Result<types::Component> {
        let cx = self.typecheck(&component)?;
        Ok(types::Component::from(
            component.ty(),
            &InstanceType {
                types: cx.types,
                resources: Some(&cx.imported_resources),
            },
        ))
    }

    /// 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.
    ///
    /// Returns an error if `component` was not compiled by the same
    /// [`Engine`](crate::Engine) as this linker.
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn instantiate_pre(&self, component: &Component) -> Result<InstancePre<T>> {
        ensure!(
            Engine::same(&self.engine, component.engine()),
            "cross-`Engine` instantiation is not currently supported"
        );
        let cx = self.typecheck(&component)?;

        // A successful typecheck resolves all of the imported resources used by
        // this InstancePre. We keep a clone of this table in the InstancePre
        // so that we can construct an InstanceType for typechecking.
        let imported_resources = cx.imported_resources.clone();

        // Now that all imports are known to be defined and satisfied by this
        // linker a list of "flat" import items (aka no instances) is created
        // using the import map within the component created at
        // component-compile-time.
        let env_component = component.env_component();
        let mut imports = TryPrimaryMap::with_capacity(env_component.imports.len())?;
        for (idx, (import, names)) in env_component.imports.iter() {
            let (root, _) = &env_component.import_types[*import];

            // This is the flattening process where we go from a definition
            // optionally through a list of exported names to get to the final
            // item.
            let mut cur = self.map.get(root, &self.strings).unwrap();
            for name in names {
                cur = match cur {
                    Definition::Instance(map) => map.get(&name, &self.strings).unwrap(),
                    _ => unreachable!(),
                };
            }
            let import = match cur {
                Definition::Module(m) => RuntimeImport::Module(m.clone()),
                Definition::Func(f) => RuntimeImport::Func(f.clone()),
                Definition::Resource(t, dtor) => RuntimeImport::Resource {
                    ty: *t,
                    dtor: dtor.clone(),
                    dtor_funcref: component.resource_drop_func_ref(dtor),
                },

                // This is guaranteed by the compilation process that "leaf"
                // runtime imports are never instances.
                Definition::Instance(_) => unreachable!(),
            };
            let i = imports.push(import)?;
            assert_eq!(i, idx);
        }
        Ok(unsafe {
            InstancePre::new_unchecked(
                component.clone(),
                try_new::<Arc<_>>(PrimaryMap::from(imports))?,
                imported_resources,
            )
        })
    }

    /// 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.
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn instantiate(
        &self,
        mut store: impl AsContextMut<Data = T>,
        component: &Component,
    ) -> Result<Instance> {
        let store = store.as_context_mut();
        store.0.validate_sync_call()?;
        self.instantiate_pre(component)?.instantiate(store)
    }

    /// Instantiates the [`Component`] provided into the `store` specified.
    ///
    /// This is exactly like [`Linker::instantiate`] except for [asynchronous
    /// execution](crate#async).
    ///
    /// # 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.
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    #[cfg(feature = "async")]
    pub async fn instantiate_async(
        &self,
        store: impl AsContextMut<Data = T>,
        component: &Component,
    ) -> Result<Instance>
    where
        T: Send,
    {
        self.instantiate_pre(component)?
            .instantiate_async(store)
            .await
    }

    /// 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.
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn define_unknown_imports_as_traps(&mut self, component: &Component) -> Result<()> {
        self.define_unknown_imports(component, StubKind::Trap)
    }

    /// Implement any imports of the given [`Component`] with functions which
    /// ignore their arguments and return default values.
    ///
    /// By default a [`Linker`] will error when unknown imports are encountered
    /// when instantiating a [`Component`]. This changes that behavior from an
    /// instant error to returning defaults when the import is called. See
    /// [`Type::default_value`](crate::component::types::Type::default_value)
    /// for what each type defaults to.
    ///
    /// Values are built when the import is called, not here, as a handle's
    /// type depends on the instance it is flowing into.
    ///
    /// Not every result has a default: a `future`, `stream`, or
    /// `error-context`, or a guest-defined resource, has none. Such an import
    /// is still defined, but traps when called rather than preventing
    /// instantiation, so a component which never calls it can still be run.
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn define_unknown_imports_as_default_values(
        &mut self,
        _store: impl AsContextMut<Data = T>,
        component: &Component,
    ) -> Result<()> {
        self.define_unknown_imports(component, StubKind::DefaultValue)
    }

    /// Stub out all of `component`'s undefined imports.
    fn define_unknown_imports(&mut self, component: &Component, kind: StubKind) -> Result<()> {
        // Recursively stub out all imports of the component.
        use wasmtime_environ::component::{ComponentTypes, ResourceIndex, TypeDef};

        fn stub_item<T>(
            linker: &mut LinkerInstance<T>,
            resources: &mut TryEntitySet<ResourceIndex>,
            item_name: &str,
            item_def: &TypeDef,
            parent_instance: Option<&str>,
            types: &Arc<ComponentTypes>,
            kind: StubKind,
        ) -> Result<()> {
            // The first definition of a resource needs to be present, but all other future
            // references to the same resource are aliases of the original resource definition.
            // Once a resource is visited here all future hits on the same resource shouldn't
            // do anything else effectively. If item_name is already defined then we'll bail
            // out in the below matches!, and otherwise a stub will be inserted, so no matter
            // what the first resource is defined and all others will refer to that.
            if let TypeDef::Resource(ty) = item_def
                && !resources.insert(types[*ty].unwrap_concrete_ty())?
            {
                return Ok(());
            }

            // Skip if the item isn't an instance and has already been defined in the linker.
            if !matches!(item_def, TypeDef::ComponentInstance(_)) && linker.get(item_name).is_some()
            {
                return Ok(());
            }

            match item_def {
                TypeDef::ComponentFunc(_func_idx) => {
                    let fully_qualified_name = match parent_instance {
                        Some(parent) => {
                            let mut s = TryString::new();
                            s.push_str(parent)?;
                            s.push('#')?;
                            s.push_str(item_name)?;
                            s
                        }
                        None => {
                            let mut s = TryString::new();
                            s.push_str(item_name)?;
                            s
                        }
                    };

                    // An `async func`-typed import can never be satisfied by
                    // `func_new` (only a sync-typed import can) — see
                    // `typecheck_async`'s doc comment. Stub it with
                    // `func_new_concurrent` instead so unsatisfied async
                    // imports can be stubbed too, not just sync
                    // ones; if concurrency support isn't enabled there's no
                    // way to stub it here, so fall through to `func_new` and
                    // let instantiation fail with that same explanatory
                    // error.
                    #[cfg(feature = "component-model-async")]
                    if types[*_func_idx].async_ && linker.engine.tunables().concurrency_support {
                        linker.func_new_concurrent(&item_name, move |accessor, ty, params, results| {
                            let fully_qualified_name = fully_qualified_name.try_clone();
                            Box::pin(async move {
                                let fully_qualified_name = fully_qualified_name?;
                                match kind {
                                    StubKind::Trap => bail!(
                                        "unknown import: `{fully_qualified_name}` has not been defined"
                                    ),
                                    StubKind::DefaultValue => accessor
                                        .with(|store| fill_defaults(store, &ty, params, results))
                                        .with_context(|| {
                                            format_err!(
                                                "unknown import: `{fully_qualified_name}` has no \
                                                 default value"
                                            )
                                        }),
                                }
                            })
                        })?;
                        return Ok(());
                    }

                    linker.func_new(&item_name, move |store, ty, params, results| match kind {
                        StubKind::Trap => {
                            bail!("unknown import: `{fully_qualified_name}` has not been defined")
                        }
                        StubKind::DefaultValue => fill_defaults(store, &ty, params, results)
                            .with_context(|| {
                                format_err!(
                                    "unknown import: `{fully_qualified_name}` has no default value"
                                )
                            }),
                    })?;
                }
                TypeDef::ComponentInstance(i) => {
                    let instance = &types[*i];
                    let mut linker_instance = linker.instance(item_name)?;
                    for (export_name, export) in instance.exports.iter() {
                        stub_item(
                            &mut linker_instance,
                            resources,
                            export_name,
                            &export.ty,
                            Some(item_name),
                            types,
                            kind,
                        )?;
                    }
                }
                TypeDef::Resource(_) => {
                    let ty = crate::component::ResourceType::host::<()>();
                    linker.resource(item_name, ty, |_, _| Ok(()))?;
                }
                TypeDef::Component(_) | TypeDef::Module(_) => {
                    bail!(
                        "unable to define {} imports as {}",
                        item_def.desc(),
                        kind.desc()
                    )
                }
                _ => {}
            }
            Ok(())
        }

        let mut resources = TryEntitySet::new();

        for (_, (import_name, import_type)) in &component.env_component().import_types {
            stub_item(
                &mut self.root(),
                &mut resources,
                import_name,
                &import_type.ty,
                None,
                component.types(),
                kind,
            )?;
        }
        Ok(())
    }
}

/// Which flavor of stub `Linker::define_unknown_imports` installs.
#[derive(Copy, Clone)]
enum StubKind {
    /// Stubs trap when called.
    Trap,
    /// Stubs return default values; see
    /// `Linker::define_unknown_imports_as_default_values`.
    DefaultValue,
}

impl StubKind {
    /// A human readable description, for error messages.
    fn desc(&self) -> &'static str {
        match self {
            StubKind::Trap => "traps",
            StubKind::DefaultValue => "default values",
        }
    }
}

/// Drop every handle within `params`.
fn drop_params(mut store: impl AsContextMut, params: &[Val]) -> Result<()> {
    let mut store = store.as_context_mut();
    for param in params {
        drop_val(store.as_context_mut(), param)?;
    }
    Ok(())
}

/// Drop every handle within `val`.
fn drop_val<T>(mut store: StoreContextMut<'_, T>, val: &Val) -> Result<()> {
    match val {
        // Drop through the internal entry point rather than the public
        // `resource_drop`: this runs while servicing a guest call on a fiber,
        // where `resource_drop`'s `validate_sync_call` check would reject the
        // drop with "cannot do blocking `call` from an async context".
        Val::Resource(resource) => resource.resource_drop_in_guest_call(&mut store)?,

        // Without `component-model-async` these are uninhabited, so there is
        // nothing to close.
        #[cfg(feature = "component-model-async")]
        Val::Future(future) => future.clone().close(&mut store)?,
        #[cfg(feature = "component-model-async")]
        Val::Stream(stream) => stream.clone().close(&mut store)?,
        #[cfg(not(feature = "component-model-async"))]
        Val::Future(_) | Val::Stream(_) => {}

        Val::List(vals) | Val::Tuple(vals) | Val::FixedLengthList(vals) => {
            for val in vals {
                drop_val(store.as_context_mut(), val)?;
            }
        }
        Val::Record(fields) => {
            for (_, val) in fields {
                drop_val(store.as_context_mut(), val)?;
            }
        }
        Val::Map(entries) => {
            for (key, val) in entries {
                drop_val(store.as_context_mut(), key)?;
                drop_val(store.as_context_mut(), val)?;
            }
        }
        Val::Variant(_, Some(val)) | Val::Option(Some(val)) => {
            drop_val(store.as_context_mut(), val)?
        }
        Val::Result(Ok(Some(val)) | Err(Some(val))) => drop_val(store.as_context_mut(), val)?,

        // Lifting an `error-context` reads its representation without taking
        // ownership of a handle, so there is nothing to drop.
        Val::ErrorContext(_) => {}

        Val::Bool(_)
        | Val::S8(_)
        | Val::U8(_)
        | Val::S16(_)
        | Val::U16(_)
        | Val::S32(_)
        | Val::U32(_)
        | Val::S64(_)
        | Val::U64(_)
        | Val::Float32(_)
        | Val::Float64(_)
        | Val::Char(_)
        | Val::String(_)
        | Val::Enum(_)
        | Val::Flags(_)
        | Val::Variant(_, None)
        | Val::Option(None)
        | Val::Result(Ok(None) | Err(None)) => {}
    }
    Ok(())
}

/// Write a default value for each of `ty`'s results into `results`, after
/// disposing of `params`.
///
/// `ty` comes from the call itself rather than from the linker, so its `own`
/// and `borrow` types are those of the instance being called, which is what
/// makes the handles this produces pass the guest's type check.
fn fill_defaults(
    mut store: impl AsContextMut,
    ty: &types::ComponentFunc,
    params: &[Val],
    results: &mut [Val],
) -> Result<()> {
    drop_params(&mut store, params)?;
    for (slot, ty) in results.iter_mut().zip(ty.results()) {
        *slot = ty.default_value(&mut store)?;
    }
    Ok(())
}

impl<T: 'static> LinkerInstance<'_, T> {
    fn as_mut(&mut self) -> LinkerInstance<'_, T> {
        LinkerInstance {
            engine: self.engine,
            path: self.path,
            path_len: self.path_len,
            strings: self.strings,
            map: self.map,
            allow_shadowing: self.allow_shadowing,
            _marker: self._marker,
        }
    }

    /// Defines a new host-provided function into this [`LinkerInstance`].
    ///
    /// This method is used to give host functions to wasm components. The
    /// `func` provided will be callable from linked components with the type
    /// signature dictated by `Params` and `Return`. The `Params` is a tuple of
    /// types that will come from wasm and `Return` is a value coming from the
    /// host going back to wasm.
    ///
    /// Additionally the `func` takes a
    /// [`StoreContextMut`](crate::StoreContextMut) as its first parameter.
    ///
    /// Note that `func` must be an `Fn` and must also be `Send + Sync +
    /// 'static`. Shared state within a func is typically accessed with the `T`
    /// type parameter from [`Store<T>`](crate::Store) which is accessible
    /// through the leading [`StoreContextMut<'_, T>`](crate::StoreContextMut)
    /// argument which can be provided to the `func` given here.
    ///
    /// # Blocking / Async Behavior
    ///
    /// The host function `func` provided here is a blocking function from the
    /// perspective of WebAssembly. WebAssembly, and Rust, will be blocked until
    /// `func` completes.
    ///
    /// To define a function which is async on the host, but blocking to the
    /// guest, see the [`func_wrap_async`] method.
    ///
    /// [`func_wrap_async`]: LinkerInstance::func_wrap_async
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    //
    // TODO: needs more words and examples
    pub fn func_wrap<F, Params, Return>(&mut self, name: &str, func: F) -> Result<()>
    where
        F: Fn(StoreContextMut<T>, Params) -> Result<Return> + Send + Sync + 'static,
        Params: ComponentNamedList + Lift + 'static,
        Return: ComponentNamedList + Lower + 'static,
    {
        self.insert(name, Definition::Func(HostFunc::func_wrap(func)?))?;
        Ok(())
    }

    /// Defines a new host-provided async function into this [`LinkerInstance`].
    ///
    /// This function is similar to [`Self::func_wrap`] except it takes an async
    /// host function instead of a blocking host function. The `F` function here
    /// is intended to be:
    ///
    /// ```ignore
    /// F: AsyncFn(StoreContextMut<'_, T>, Params) -> Result<Return>
    /// ```
    ///
    /// however the returned future must be `Send` which is not possible to
    /// bound at this time. This will be switched to an async closure once Rust
    /// supports it.
    ///
    /// # Blocking / Async Behavior
    ///
    /// The function defined which WebAssembly calls will still appear as
    /// blocking from the perspective of WebAssembly itself. The host, however,
    /// can perform asynchronous operations without blocking the thread
    /// performing a call.
    ///
    /// When defining host functions with this function, WebAssembly is invoked
    /// on a separate stack within a Wasmtime-managed fiber (through the
    /// `call_async`-style of invocation). This means that if the future
    /// returned by `F` is not immediately ready then the fiber will be
    /// suspended to block WebAssembly but not the host. When the future
    /// becomes ready again the fiber will be resumed to continue execution
    /// within WebAssembly.
    ///
    /// [`func_wrap_async`]: LinkerInstance::func_wrap_async
    #[cfg(feature = "async")]
    pub fn func_wrap_async<Params, Return, F>(&mut self, name: &str, f: F) -> Result<()>
    where
        F: Fn(
                StoreContextMut<'_, T>,
                Params,
            ) -> Box<dyn Future<Output = Result<Return>> + Send + '_>
            + Send
            + Sync
            + 'static,
        Params: ComponentNamedList + Lift + 'static,
        Return: ComponentNamedList + Lower + 'static,
    {
        self.insert(name, Definition::Func(HostFunc::func_wrap_async(f)?))?;
        Ok(())
    }

    /// Defines a new host-provided async function into this [`LinkerInstance`].
    ///
    /// This function defines a host function available to call from
    /// WebAssembly. WebAssembly may additionally make multiple invocations of
    /// this function concurrently all at the same time. This function requires
    /// the [`Config::wasm_component_model_async`] feature to be enabled.
    ///
    /// The function `f` provided will be invoked when called by WebAssembly.
    /// WebAssembly components may then call `f` multiple times while previous
    /// invocations of `f` are already running. Additionally while `f` is
    /// running other host functions may be invoked.
    ///
    /// The `F` function here is intended to be:
    ///
    /// ```ignore
    /// F: AsyncFn(&Accessor<T>, Params) -> Result<Return>
    /// ```
    ///
    /// however the returned future must be `Send` which is not possible to
    /// bound at this time. This will be switched to an async closure once Rust
    /// supports it.
    ///
    /// The closure `f` is provided an [`Accessor`] which can be used to acquire
    /// temporary, blocking, access to a [`StoreContextMut`] (through
    /// [`Access`](crate::component::Access]). This models how a store is not
    /// available to `f` across `await` points but it is temporarily available
    /// while actively being polled.
    ///
    /// # Blocking / Async Behavior
    ///
    /// Unlike [`Self::func_wrap`] and [`Self::func_wrap_async`] this function
    /// is asynchronous even from the perspective of guest WebAssembly. This
    /// means that if `f` is not immediately resolved then the call from
    /// WebAssembly will still return immediately (assuming it was lowered with
    /// `async`). The closure `f` should not block the current thread and
    /// should only perform blocking via `async` meaning that `f` won't block
    /// either WebAssembly nor the host.
    ///
    /// Note that WebAssembly components can lower host functions both with and
    /// without `async`. That means that even if a host function is defined in
    /// the "concurrent" mode here a guest may still lower it synchronously. In
    /// this situation Wasmtime will manage blocking the guest while the closure
    /// `f` provided here completes. If a guest lowers this function with
    /// `async`, though, then no blocking will happen.
    ///
    /// [`Config::wasm_component_model_async`]: crate::Config::wasm_component_model_async
    /// [`func_wrap_async`]: LinkerInstance::func_wrap_async
    #[cfg(feature = "component-model-async")]
    pub fn func_wrap_concurrent<Params, Return, F>(&mut self, name: &str, f: F) -> Result<()>
    where
        T: 'static,
        F: Fn(&Accessor<T>, Params) -> Pin<Box<dyn Future<Output = Result<Return>> + Send + '_>>
            + Send
            + Sync
            + 'static,
        Params: ComponentNamedList + Lift + 'static,
        Return: ComponentNamedList + Lower + 'static,
    {
        if !self.engine.tunables().concurrency_support {
            bail!("concurrent host functions require `Config::concurrency_support`");
        }
        self.insert(name, Definition::Func(HostFunc::func_wrap_concurrent(f)?))?;
        Ok(())
    }

    /// Define a new host-provided function using dynamically typed values.
    ///
    /// The `name` provided is the name of the function to define and the
    /// `func` provided is the host-defined closure to invoke when this
    /// function is called.
    ///
    /// This function is the "dynamic" version of defining a host function as
    /// compared to [`LinkerInstance::func_wrap`]. With
    /// [`LinkerInstance::func_wrap`] a function's type is statically known but
    /// with this method the `func` argument's type isn't known ahead of time.
    /// That means that `func` can be by imported component so long as it's
    /// imported as a matching name.
    ///
    /// Type information will be available at execution time, however. For
    /// example when `func` is invoked the second argument, a `&[Val]` list,
    /// contains [`Val`] entries that say what type they are. Additionally the
    /// third argument, `&mut [Val]`, is the expected number of results. Note
    /// that the expected types of the results cannot be learned during the
    /// execution of `func`. Learning that would require runtime introspection
    /// of a component.
    ///
    /// Return values, stored in the third argument of `&mut [Val]`, are
    /// type-checked at runtime to ensure that they have the appropriate type.
    /// A trap will be raised if they do not have the right type.
    ///
    /// # Examples
    ///
    /// ```
    /// use wasmtime::{Store, Engine};
    /// use wasmtime::component::{Component, Linker, Val};
    ///
    /// # fn main() -> wasmtime::Result<()> {
    /// let engine = Engine::default();
    /// let component = Component::new(
    ///     &engine,
    ///     r#"
    ///         (component
    ///             (import "thunk" (func $thunk))
    ///             (import "is-even" (func $is-even (param "x" u32) (result bool)))
    ///
    ///             (core module $m
    ///                 (import "" "thunk" (func $thunk))
    ///                 (import "" "is-even" (func $is-even (param i32) (result i32)))
    ///
    ///                 (func (export "run")
    ///                     call $thunk
    ///
    ///                     (call $is-even (i32.const 1))
    ///                     if unreachable end
    ///
    ///                     (call $is-even (i32.const 2))
    ///                     i32.eqz
    ///                     if unreachable end
    ///                 )
    ///             )
    ///             (core func $thunk (canon lower (func $thunk)))
    ///             (core func $is-even (canon lower (func $is-even)))
    ///             (core instance $i (instantiate $m
    ///                 (with "" (instance
    ///                     (export "thunk" (func $thunk))
    ///                     (export "is-even" (func $is-even))
    ///                 ))
    ///             ))
    ///
    ///             (func (export "run") (canon lift (core func $i "run")))
    ///         )
    ///     "#,
    /// )?;
    ///
    /// let mut linker = Linker::<()>::new(&engine);
    ///
    /// // Sample function that takes no arguments.
    /// linker.root().func_new("thunk", |_store, _ty, params, results| {
    ///     assert!(params.is_empty());
    ///     assert!(results.is_empty());
    ///     println!("Look ma, host hands!");
    ///     Ok(())
    /// })?;
    ///
    /// // This function takes one argument and returns one result.
    /// linker.root().func_new("is-even", |_store, _ty, params, results| {
    ///     assert_eq!(params.len(), 1);
    ///     let param = match params[0] {
    ///         Val::U32(n) => n,
    ///         _ => panic!("unexpected type"),
    ///     };
    ///
    ///     assert_eq!(results.len(), 1);
    ///     results[0] = Val::Bool(param % 2 == 0);
    ///     Ok(())
    /// })?;
    ///
    /// let mut store = Store::new(&engine, ());
    /// let instance = linker.instantiate(&mut store, &component)?;
    /// let run = instance.get_typed_func::<(), ()>(&mut store, "run")?;
    /// run.call(&mut store, ())?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn func_new(
        &mut self,
        name: &str,
        func: impl Fn(StoreContextMut<'_, T>, types::ComponentFunc, &[Val], &mut [Val]) -> Result<()>
        + Send
        + Sync
        + 'static,
    ) -> Result<()> {
        self.insert(name, Definition::Func(HostFunc::func_new(func)?))?;
        Ok(())
    }

    /// Define a new host-provided async function using dynamic types.
    ///
    /// As [`Self::func_wrap_async`] is a dual of [`Self::func_wrap`], this
    /// function is the dual of [`Self::func_new`].
    ///
    /// For documentation on blocking behavior see [`Self::func_wrap_async`].
    #[cfg(feature = "async")]
    pub fn func_new_async<F>(&mut self, name: &str, func: F) -> Result<()>
    where
        F: for<'a> Fn(
                StoreContextMut<'a, T>,
                types::ComponentFunc,
                &'a [Val],
                &'a mut [Val],
            ) -> Box<dyn Future<Output = Result<()>> + Send + 'a>
            + Send
            + Sync
            + 'static,
    {
        self.insert(name, Definition::Func(HostFunc::func_new_async(func)?))?;
        Ok(())
    }

    /// Define a new host-provided async function using dynamic types.
    ///
    /// As [`Self::func_wrap_concurrent`] is a dual of [`Self::func_wrap`], this
    /// function is the dual of [`Self::func_new`].
    ///
    /// For documentation on async/blocking behavior see
    /// [`Self::func_wrap_concurrent`].
    #[cfg(feature = "component-model-async")]
    pub fn func_new_concurrent<F>(&mut self, name: &str, f: F) -> Result<()>
    where
        T: 'static,
        F: for<'a> Fn(
                &'a Accessor<T>,
                types::ComponentFunc,
                &'a [Val],
                &'a mut [Val],
            ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>
            + Send
            + Sync
            + 'static,
    {
        if !self.engine.tunables().concurrency_support {
            bail!("concurrent host functions require `Config::concurrency_support`");
        }
        self.insert(name, Definition::Func(HostFunc::func_new_concurrent(f)?))?;
        Ok(())
    }

    /// Defines a [`Module`] within this instance.
    ///
    /// This can be used to provide a core wasm [`Module`] as an import to a
    /// component. The [`Module`] provided is saved within the linker for the
    /// specified `name` in this instance.
    ///
    /// # Errors
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn module(&mut self, name: &str, module: &Module) -> Result<()> {
        self.insert(name, Definition::Module(module.clone()))?;
        Ok(())
    }

    /// Defines a new resource of a given [`ResourceType`] in this linker.
    ///
    /// This function is used to specify resources defined in the host.
    ///
    /// The `name` argument is the name to define the resource within this
    /// linker.
    ///
    /// The `dtor` provided is a destructor that will get invoked when an owned
    /// version of this resource is destroyed from the guest. Note that this
    /// destructor is not called when a host-owned resource is destroyed as it's
    /// assumed the host knows how to handle destroying its own resources.
    ///
    /// The `dtor` closure is provided the store state as the first argument
    /// along with the representation of the resource that was just destroyed.
    ///
    /// [`Resource<U>`]: crate::component::Resource
    ///
    /// # Errors
    ///
    /// The provided `dtor` closure returns an error if something goes wrong
    /// when a guest calls the `dtor` to drop a `Resource<T>` such as
    /// a runtime trap or a runtime limit being exceeded.
    ///
    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
    /// memory allocation fails. See the `OutOfMemory` type's documentation for
    /// details on Wasmtime's out-of-memory handling.
    pub fn resource(
        &mut self,
        name: &str,
        ty: ResourceType,
        dtor: impl Fn(StoreContextMut<'_, T>, u32) -> Result<()> + Send + Sync + 'static,
    ) -> Result<()> {
        let dtor = try_new::<Arc<_>>(crate::func::HostFunc::wrap(
            &self.engine,
            move |mut cx: crate::Caller<'_, T>, (param,): (u32,)| dtor(cx.as_context_mut(), param),
        )?)?;
        self.insert(name, Definition::Resource(ty, dtor))?;
        Ok(())
    }

    /// Identical to [`Self::resource`], except that it takes an async destructor.
    #[cfg(feature = "async")]
    pub fn resource_async<F>(&mut self, name: &str, ty: ResourceType, dtor: F) -> Result<()>
    where
        T: Send,
        F: Fn(StoreContextMut<'_, T>, u32) -> Box<dyn Future<Output = Result<()>> + Send + '_>
            + Send
            + Sync
            + 'static,
    {
        let dtor = try_new::<Arc<_>>(crate::func::HostFunc::wrap_async(
            &self.engine,
            move |cx: crate::Caller<'_, T>, (param,): (u32,)| dtor(cx.into(), param),
        )?)?;
        self.insert(name, Definition::Resource(ty, dtor))?;
        Ok(())
    }

    /// Identical to [`Self::resource`], except that it takes a concurrent destructor.
    #[cfg(feature = "component-model-async")]
    pub fn resource_concurrent<F>(&mut self, name: &str, ty: ResourceType, dtor: F) -> Result<()>
    where
        T: Send + 'static,
        F: Fn(&Accessor<T>, u32) -> Pin<Box<dyn Future<Output = Result<()>> + Send + '_>>
            + Send
            + Sync
            + 'static,
    {
        if !self.engine.tunables().concurrency_support {
            bail!("concurrent host functions require `Config::concurrency_support`");
        }
        // TODO: This isn't really concurrent -- it requires exclusive access to
        // the store for the duration of the call, preventing guest code from
        // running until it completes.  We should make it concurrent and clean
        // up the implementation to avoid using e.g. `Accessor::new` and
        // `tls::set` directly.
        let dtor = Arc::new(dtor);
        let dtor = Arc::new(crate::func::HostFunc::wrap_async(
            &self.engine,
            move |mut cx: crate::Caller<'_, T>, (param,): (u32,)| {
                let dtor = dtor.clone();
                Box::new(async move {
                    let mut store = cx.as_context_mut();
                    let accessor =
                        &Accessor::new(crate::store::StoreToken::new(store.as_context_mut()));
                    let mut future = core::pin::pin!(dtor(accessor, param));
                    core::future::poll_fn(|cx| {
                        crate::component::concurrent::tls::set(store.0, || future.as_mut().poll(cx))
                    })
                    .await
                })
            },
        )?);
        self.insert(name, Definition::Resource(ty, dtor))?;
        Ok(())
    }

    /// Defines a nested instance within this instance.
    ///
    /// This can be used to describe arbitrarily nested levels of instances
    /// within a linker to satisfy nested instance exports of components.
    pub fn instance(&mut self, name: &str) -> Result<LinkerInstance<'_, T>> {
        self.as_mut().into_instance(name)
    }

    /// Same as [`LinkerInstance::instance`] except with different lifetime
    /// parameters.
    pub fn into_instance(mut self, name: &str) -> Result<Self> {
        let atom = self.strings.intern(name)?;

        // If this item is already an instance then don't stomp over it with a
        // new empty instance (or fail due to shadowing being disallowed).
        // Instead continue through to below to explicitly allow re-opening an
        // instance multiple times over separate API calls.
        //
        // If this item isn't defined, or is defined as anything other than an
        // instance, however, the insert a fresh new instance and see what
        // happens as a result.
        match self.map.raw_get_mut(&atom) {
            Some(Definition::Instance(_)) => {}
            _ => {
                self.insert(name, Definition::Instance(NameMap::default()))?;
            }
        }
        self.map = match self.map.raw_get_mut(&atom) {
            Some(Definition::Instance(map)) => map,
            _ => unreachable!(),
        };
        self.path.truncate(self.path_len);
        self.path.push(atom);
        self.path_len += 1;
        Ok(self)
    }

    fn insert(&mut self, name: &str, item: Definition) -> Result<Atom> {
        self.map
            .insert(name, self.strings, self.allow_shadowing, item)
    }

    fn get(&self, name: &str) -> Option<&Definition> {
        self.map.get(name, self.strings)
    }
}