wasmtime/runtime/component/
instance.rs

1use crate::component::func::HostFunc;
2use crate::component::matching::InstanceType;
3use crate::component::store::{ComponentInstanceId, StoreComponentInstanceId};
4use crate::component::{
5    Component, ComponentExportIndex, ComponentNamedList, Func, Lift, Lower, ResourceType,
6    TypedFunc, types::ComponentItem,
7};
8use crate::instance::OwnedImports;
9use crate::linker::DefinitionType;
10use crate::prelude::*;
11use crate::runtime::vm::component::{
12    CallContexts, ComponentInstance, ResourceTables, TypedResource, TypedResourceIndex,
13};
14use crate::runtime::vm::{self, VMFuncRef};
15use crate::store::StoreOpaque;
16use crate::{AsContext, AsContextMut, Engine, Module, StoreContextMut};
17use alloc::sync::Arc;
18use core::marker;
19use core::pin::Pin;
20use core::ptr::NonNull;
21use wasmtime_environ::{EngineOrModuleTypeIndex, component::*};
22use wasmtime_environ::{EntityIndex, EntityType, PrimaryMap};
23
24/// An instantiated component.
25///
26/// This type represents an instantiated [`Component`](super::Component).
27/// Instances have exports which can be accessed through functions such as
28/// [`Instance::get_func`] or [`Instance::get_export`]. Instances are owned by a
29/// [`Store`](crate::Store) and all methods require a handle to the store.
30///
31/// Component instances are created through
32/// [`Linker::instantiate`](super::Linker::instantiate) and its family of
33/// methods.
34///
35/// This type is similar to the core wasm version
36/// [`wasmtime::Instance`](crate::Instance) except that it represents an
37/// instantiated component instead of an instantiated module.
38#[derive(Copy, Clone, Debug)]
39#[repr(transparent)]
40pub struct Instance {
41    id: StoreComponentInstanceId,
42}
43
44// Double-check that the C representation in `component/instance.h` matches our
45// in-Rust representation here in terms of size/alignment/etc.
46const _: () = {
47    #[repr(C)]
48    struct C(u64, u32);
49    assert!(core::mem::size_of::<C>() == core::mem::size_of::<Instance>());
50    assert!(core::mem::align_of::<C>() == core::mem::align_of::<Instance>());
51    assert!(core::mem::offset_of!(Instance, id) == 0);
52};
53
54impl Instance {
55    /// Creates a raw `Instance` from the internal identifiers within the store.
56    pub(crate) fn from_wasmtime(store: &StoreOpaque, id: ComponentInstanceId) -> Instance {
57        Instance {
58            id: StoreComponentInstanceId::new(store.id(), id),
59        }
60    }
61
62    /// Looks up an exported function by name within this [`Instance`].
63    ///
64    /// The `store` argument provided must be the store that this instance
65    /// lives within and the `name` argument is the lookup key by which to find
66    /// the exported function. If the function is found then `Some` is returned
67    /// and otherwise `None` is returned.
68    ///
69    /// The `name` here can be a string such as `&str` or it can be a
70    /// [`ComponentExportIndex`] which is loaded prior from a [`Component`].
71    ///
72    /// # Panics
73    ///
74    /// Panics if `store` does not own this instance.
75    ///
76    /// # Examples
77    ///
78    /// Looking up a function which is exported from the root of a component:
79    ///
80    /// ```
81    /// use wasmtime::{Engine, Store};
82    /// use wasmtime::component::{Component, Linker};
83    ///
84    /// # fn main() -> wasmtime::Result<()> {
85    /// let engine = Engine::default();
86    /// let component = Component::new(
87    ///     &engine,
88    ///     r#"
89    ///         (component
90    ///             (core module $m
91    ///                 (func (export "f"))
92    ///             )
93    ///             (core instance $i (instantiate $m))
94    ///             (func (export "f")
95    ///                 (canon lift (core func $i "f")))
96    ///         )
97    ///     "#,
98    /// )?;
99    ///
100    /// // Look up the function by name
101    /// let mut store = Store::new(&engine, ());
102    /// let instance = Linker::new(&engine).instantiate(&mut store, &component)?;
103    /// let func = instance.get_func(&mut store, "f").unwrap();
104    ///
105    /// // The function can also be looked up by an index via a precomputed index.
106    /// let export = component.get_export_index(None, "f").unwrap();
107    /// let func = instance.get_func(&mut store, &export).unwrap();
108    /// # Ok(())
109    /// # }
110    /// ```
111    ///
112    /// Looking up a function which is exported from a nested instance:
113    ///
114    /// ```
115    /// use wasmtime::{Engine, Store};
116    /// use wasmtime::component::{Component, Linker};
117    ///
118    /// # fn main() -> wasmtime::Result<()> {
119    /// let engine = Engine::default();
120    /// let component = Component::new(
121    ///     &engine,
122    ///     r#"
123    ///         (component
124    ///             (core module $m
125    ///                 (func (export "f"))
126    ///             )
127    ///             (core instance $i (instantiate $m))
128    ///             (func $f
129    ///                 (canon lift (core func $i "f")))
130    ///
131    ///             (instance $i
132    ///                 (export "f" (func $f)))
133    ///             (export "i" (instance $i))
134    ///         )
135    ///     "#,
136    /// )?;
137    ///
138    /// // First look up the exported instance, then use that to lookup the
139    /// // exported function.
140    /// let instance_index = component.get_export_index(None, "i").unwrap();
141    /// let func_index = component.get_export_index(Some(&instance_index), "f").unwrap();
142    ///
143    /// // Then use `func_index` at runtime.
144    /// let mut store = Store::new(&engine, ());
145    /// let instance = Linker::new(&engine).instantiate(&mut store, &component)?;
146    /// let func = instance.get_func(&mut store, &func_index).unwrap();
147    ///
148    /// // Alternatively the `instance` can be used directly in conjunction with
149    /// // the `get_export_index` method.
150    /// let instance_index = instance.get_export_index(&mut store, None, "i").unwrap();
151    /// let func_index = instance.get_export_index(&mut store, Some(&instance_index), "f").unwrap();
152    /// let func = instance.get_func(&mut store, &func_index).unwrap();
153    /// # Ok(())
154    /// # }
155    /// ```
156    pub fn get_func(
157        &self,
158        mut store: impl AsContextMut,
159        name: impl InstanceExportLookup,
160    ) -> Option<Func> {
161        let store = store.as_context_mut().0;
162        let instance = self.id.get(store);
163        let component = instance.component();
164
165        // Validate that `name` exists within `self.`
166        let index = name.lookup(component)?;
167
168        // Validate that `index` is indeed a lifted function.
169        match &component.env_component().export_items[index] {
170            Export::LiftedFunction { .. } => {}
171            _ => return None,
172        }
173
174        // And package up the indices!
175        Some(Func::from_lifted_func(*self, index))
176    }
177
178    /// Looks up an exported [`Func`] value by name and with its type.
179    ///
180    /// This function is a convenience wrapper over [`Instance::get_func`] and
181    /// [`Func::typed`]. For more information see the linked documentation.
182    ///
183    /// Returns an error if `name` isn't a function export or if the export's
184    /// type did not match `Params` or `Results`
185    ///
186    /// # Panics
187    ///
188    /// Panics if `store` does not own this instance.
189    pub fn get_typed_func<Params, Results>(
190        &self,
191        mut store: impl AsContextMut,
192        name: impl InstanceExportLookup,
193    ) -> Result<TypedFunc<Params, Results>>
194    where
195        Params: ComponentNamedList + Lower,
196        Results: ComponentNamedList + Lift,
197    {
198        let f = self
199            .get_func(store.as_context_mut(), name)
200            .ok_or_else(|| anyhow!("failed to find function export"))?;
201        Ok(f.typed::<Params, Results>(store)
202            .with_context(|| format!("failed to convert function to given type"))?)
203    }
204
205    /// Looks up an exported module by name within this [`Instance`].
206    ///
207    /// The `store` argument provided must be the store that this instance
208    /// lives within and the `name` argument is the lookup key by which to find
209    /// the exported module. If the module is found then `Some` is returned
210    /// and otherwise `None` is returned.
211    ///
212    /// The `name` here can be a string such as `&str` or it can be a
213    /// [`ComponentExportIndex`] which is loaded prior from a [`Component`].
214    ///
215    /// For some examples see [`Instance::get_func`] for loading values from a
216    /// component.
217    ///
218    /// # Panics
219    ///
220    /// Panics if `store` does not own this instance.
221    pub fn get_module(
222        &self,
223        mut store: impl AsContextMut,
224        name: impl InstanceExportLookup,
225    ) -> Option<Module> {
226        let store = store.as_context_mut().0;
227        let (instance, export) = self.lookup_export(store, name)?;
228        match export {
229            Export::ModuleStatic { index, .. } => {
230                Some(instance.component().static_module(*index).clone())
231            }
232            Export::ModuleImport { import, .. } => match instance.runtime_import(*import) {
233                RuntimeImport::Module(m) => Some(m.clone()),
234                _ => unreachable!(),
235            },
236            _ => None,
237        }
238    }
239
240    /// Looks up an exported resource type by name within this [`Instance`].
241    ///
242    /// The `store` argument provided must be the store that this instance
243    /// lives within and the `name` argument is the lookup key by which to find
244    /// the exported resource. If the resource is found then `Some` is returned
245    /// and otherwise `None` is returned.
246    ///
247    /// The `name` here can be a string such as `&str` or it can be a
248    /// [`ComponentExportIndex`] which is loaded prior from a [`Component`].
249    ///
250    /// For some examples see [`Instance::get_func`] for loading values from a
251    /// component.
252    ///
253    /// # Panics
254    ///
255    /// Panics if `store` does not own this instance.
256    pub fn get_resource(
257        &self,
258        mut store: impl AsContextMut,
259        name: impl InstanceExportLookup,
260    ) -> Option<ResourceType> {
261        let store = store.as_context_mut().0;
262        let (instance, export) = self.lookup_export(store, name)?;
263        match export {
264            Export::Type(TypeDef::Resource(id)) => {
265                Some(InstanceType::new(instance).resource_type(*id))
266            }
267            Export::Type(_)
268            | Export::LiftedFunction { .. }
269            | Export::ModuleStatic { .. }
270            | Export::ModuleImport { .. }
271            | Export::Instance { .. } => None,
272        }
273    }
274
275    /// A methods similar to [`Component::get_export`] except for this
276    /// instance.
277    ///
278    /// This method will lookup the `name` provided within the `instance`
279    /// provided and return a [`ComponentItem`] describing the export,
280    /// and [`ComponentExportIndex`] which can be passed other `get_*`
281    /// functions like [`Instance::get_func`].
282    ///
283    /// The [`ComponentItem`] is more expensive to compute than the
284    /// [`ComponentExportIndex`]. If you are not consuming the
285    /// [`ComponentItem`], use [`Instance::get_export_index`] instead.
286    ///
287    /// # Panics
288    ///
289    /// Panics if `store` does not own this instance.
290    pub fn get_export(
291        &self,
292        mut store: impl AsContextMut,
293        instance: Option<&ComponentExportIndex>,
294        name: &str,
295    ) -> Option<(ComponentItem, ComponentExportIndex)> {
296        self._get_export(store.as_context_mut().0, instance, name)
297    }
298
299    fn _get_export(
300        &self,
301        store: &StoreOpaque,
302        instance: Option<&ComponentExportIndex>,
303        name: &str,
304    ) -> Option<(ComponentItem, ComponentExportIndex)> {
305        let data = self.id().get(store);
306        let component = data.component();
307        let index = component.lookup_export_index(instance, name)?;
308        let item = ComponentItem::from_export(
309            &store.engine(),
310            &component.env_component().export_items[index],
311            &InstanceType::new(data),
312        );
313        Some((
314            item,
315            ComponentExportIndex {
316                id: data.component().id(),
317                index,
318            },
319        ))
320    }
321
322    /// A methods similar to [`Component::get_export_index`] except for this
323    /// instance.
324    ///
325    /// This method will lookup the `name` provided within the `instance`
326    /// provided and return a [`ComponentExportIndex`] which can be passed
327    /// other `get_*` functions like [`Instance::get_func`].
328    ///
329    /// If you need the [`ComponentItem`] corresponding to this export, use
330    /// the [`Instance::get_export`] instead.
331    ///
332    /// # Panics
333    ///
334    /// Panics if `store` does not own this instance.
335    pub fn get_export_index(
336        &self,
337        mut store: impl AsContextMut,
338        instance: Option<&ComponentExportIndex>,
339        name: &str,
340    ) -> Option<ComponentExportIndex> {
341        let data = self.id().get(store.as_context_mut().0);
342        let index = data.component().lookup_export_index(instance, name)?;
343        Some(ComponentExportIndex {
344            id: data.component().id(),
345            index,
346        })
347    }
348
349    fn lookup_export<'a>(
350        &self,
351        store: &'a StoreOpaque,
352        name: impl InstanceExportLookup,
353    ) -> Option<(&'a ComponentInstance, &'a Export)> {
354        let data = self.id().get(store);
355        let index = name.lookup(data.component())?;
356        Some((data, &data.component().env_component().export_items[index]))
357    }
358
359    /// Returns the [`InstancePre`] that was used to create this instance.
360    pub fn instance_pre<T>(&self, store: impl AsContext<Data = T>) -> InstancePre<T> {
361        // This indexing operation asserts the Store owns the Instance.
362        // Therefore, the InstancePre<T> must match the Store<T>.
363        let data = self.id().get(store.as_context().0);
364
365        // SAFETY: calling this method safely here relies on matching the `T`
366        // in `InstancePre<T>` to the store itself, which is happening in the
367        // type signature just above by ensuring the store's data is `T` which
368        // matches the return value.
369        unsafe { data.instance_pre() }
370    }
371
372    pub(crate) fn id(&self) -> StoreComponentInstanceId {
373        self.id
374    }
375
376    /// Implementation of the `resource.new` intrinsic for `i32`
377    /// representations.
378    pub(crate) fn resource_new32(
379        self,
380        store: &mut StoreOpaque,
381        caller: RuntimeComponentInstanceIndex,
382        ty: TypeResourceTableIndex,
383        rep: u32,
384    ) -> Result<u32> {
385        self.id().get(store).check_may_leave(caller)?;
386        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
387        resource_tables(calls, instance).resource_new(TypedResource::Component { ty, rep })
388    }
389
390    /// Implementation of the `resource.rep` intrinsic for `i32`
391    /// representations.
392    pub(crate) fn resource_rep32(
393        self,
394        store: &mut StoreOpaque,
395        caller: RuntimeComponentInstanceIndex,
396        ty: TypeResourceTableIndex,
397        index: u32,
398    ) -> Result<u32> {
399        self.id().get(store).check_may_leave(caller)?;
400        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
401        resource_tables(calls, instance).resource_rep(TypedResourceIndex::Component { ty, index })
402    }
403
404    /// Implementation of the `resource.drop` intrinsic.
405    pub(crate) fn resource_drop(
406        self,
407        store: &mut StoreOpaque,
408        caller: RuntimeComponentInstanceIndex,
409        ty: TypeResourceTableIndex,
410        index: u32,
411    ) -> Result<Option<u32>> {
412        self.id().get(store).check_may_leave(caller)?;
413        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
414        resource_tables(calls, instance).resource_drop(TypedResourceIndex::Component { ty, index })
415    }
416
417    pub(crate) fn resource_transfer_own(
418        self,
419        store: &mut StoreOpaque,
420        index: u32,
421        src: TypeResourceTableIndex,
422        dst: TypeResourceTableIndex,
423    ) -> Result<u32> {
424        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
425        let mut tables = resource_tables(calls, instance);
426        let rep = tables.resource_lift_own(TypedResourceIndex::Component { ty: src, index })?;
427        tables.resource_lower_own(TypedResource::Component { ty: dst, rep })
428    }
429
430    pub(crate) fn resource_transfer_borrow(
431        self,
432        store: &mut StoreOpaque,
433        index: u32,
434        src: TypeResourceTableIndex,
435        dst: TypeResourceTableIndex,
436    ) -> Result<u32> {
437        let dst_owns_resource = self.id().get(store).resource_owned_by_own_instance(dst);
438        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
439        let mut tables = resource_tables(calls, instance);
440        let rep = tables.resource_lift_borrow(TypedResourceIndex::Component { ty: src, index })?;
441        // Implement `lower_borrow`'s special case here where if a borrow's
442        // resource type is owned by `dst` then the destination receives the
443        // representation directly rather than a handle to the representation.
444        //
445        // This can perhaps become a different libcall in the future to avoid
446        // this check at runtime since we know at compile time whether the
447        // destination type owns the resource, but that's left as a future
448        // refactoring if truly necessary.
449        if dst_owns_resource {
450            return Ok(rep);
451        }
452        tables.resource_lower_borrow(TypedResource::Component { ty: dst, rep })
453    }
454
455    pub(crate) fn resource_enter_call(self, store: &mut StoreOpaque) {
456        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
457        resource_tables(calls, instance).enter_call()
458    }
459
460    pub(crate) fn resource_exit_call(self, store: &mut StoreOpaque) -> Result<()> {
461        let (calls, _, _, instance) = store.component_resource_state_with_instance(self);
462        resource_tables(calls, instance).exit_call()
463    }
464
465    pub(crate) fn lookup_vmdef(&self, store: &mut StoreOpaque, def: &CoreDef) -> vm::Export {
466        lookup_vmdef(store, self.id.instance(), def)
467    }
468}
469
470/// Translates a `CoreDef`, a definition of a core wasm item, to an
471/// [`Export`] which is the runtime core wasm definition.
472pub(crate) fn lookup_vmdef(
473    store: &mut StoreOpaque,
474    id: ComponentInstanceId,
475    def: &CoreDef,
476) -> vm::Export {
477    match def {
478        CoreDef::Export(e) => lookup_vmexport(store, id, e),
479        CoreDef::Trampoline(idx) => {
480            let funcref = store
481                .store_data_mut()
482                .component_instance_mut(id)
483                .trampoline_func_ref(*idx);
484            // SAFETY: the `funcref` is owned by `store` and is valid within
485            // that store, so it's safe to create a `Func`.
486            vm::Export::Function(unsafe { crate::Func::from_vm_func_ref(store.id(), funcref) })
487        }
488        CoreDef::InstanceFlags(idx) => {
489            let id = StoreComponentInstanceId::new(store.id(), id);
490            vm::Export::Global(crate::Global::from_component_flags(id, *idx))
491        }
492    }
493}
494
495/// Translates a `CoreExport<T>`, an export of some core instance within
496/// this component, to the actual runtime definition of that item.
497pub(crate) fn lookup_vmexport<T>(
498    store: &mut StoreOpaque,
499    id: ComponentInstanceId,
500    item: &CoreExport<T>,
501) -> vm::Export
502where
503    T: Copy + Into<EntityIndex>,
504{
505    let store_id = store.id();
506    let id = store
507        .store_data_mut()
508        .component_instance_mut(id)
509        .instance(item.instance);
510    let instance = store.instance_mut(id);
511    let idx = match &item.item {
512        ExportItem::Index(idx) => (*idx).into(),
513
514        // FIXME: ideally at runtime we don't actually do any name lookups
515        // here. This will only happen when the host supplies an imported
516        // module so while the structure can't be known at compile time we
517        // do know at `InstancePre` time, for example, what all the host
518        // imports are. In theory we should be able to, as part of
519        // `InstancePre` construction, perform all name=>index mappings
520        // during that phase so the actual instantiation of an `InstancePre`
521        // skips all string lookups. This should probably only be
522        // investigated if this becomes a performance issue though.
523        ExportItem::Name(name) => instance.env_module().exports[name],
524    };
525    // SAFETY: the `store_id` owns this instance and all exports contained
526    // within.
527    unsafe { instance.get_export_by_index_mut(store_id, idx) }
528}
529
530fn resource_tables<'a>(
531    calls: &'a mut CallContexts,
532    instance: Pin<&'a mut ComponentInstance>,
533) -> ResourceTables<'a> {
534    ResourceTables {
535        host_table: None,
536        calls,
537        guest: Some(instance.guest_tables()),
538    }
539}
540
541/// Trait used to lookup the export of a component instance.
542///
543/// This trait is used as an implementation detail of [`Instance::get_func`]
544/// and related `get_*` methods. Notable implementors of this trait are:
545///
546/// * `str`
547/// * `String`
548/// * [`ComponentExportIndex`]
549///
550/// Note that this is intended to be a `wasmtime`-sealed trait so it shouldn't
551/// need to be implemented externally.
552pub trait InstanceExportLookup {
553    #[doc(hidden)]
554    fn lookup(&self, component: &Component) -> Option<ExportIndex>;
555}
556
557impl<T> InstanceExportLookup for &T
558where
559    T: InstanceExportLookup + ?Sized,
560{
561    fn lookup(&self, component: &Component) -> Option<ExportIndex> {
562        T::lookup(self, component)
563    }
564}
565
566impl InstanceExportLookup for str {
567    fn lookup(&self, component: &Component) -> Option<ExportIndex> {
568        component
569            .env_component()
570            .exports
571            .get(self, &NameMapNoIntern)
572            .copied()
573    }
574}
575
576impl InstanceExportLookup for String {
577    fn lookup(&self, component: &Component) -> Option<ExportIndex> {
578        str::lookup(self, component)
579    }
580}
581
582struct Instantiator<'a> {
583    component: &'a Component,
584    id: ComponentInstanceId,
585    core_imports: OwnedImports,
586    imports: &'a PrimaryMap<RuntimeImportIndex, RuntimeImport>,
587}
588
589pub(crate) enum RuntimeImport {
590    Func(Arc<HostFunc>),
591    Module(Module),
592    Resource {
593        ty: ResourceType,
594
595        // A strong reference to the host function that represents the
596        // destructor for this resource. At this time all resources here are
597        // host-defined resources. Note that this is itself never read because
598        // the funcref below points to it.
599        //
600        // Also note that the `Arc` here is used to support the same host
601        // function being used across multiple instances simultaneously. Or
602        // otherwise this makes `InstancePre::instantiate` possible to create
603        // separate instances all sharing the same host function.
604        _dtor: Arc<crate::func::HostFunc>,
605
606        // A raw function which is filled out (including `wasm_call`) which
607        // points to the internals of the `_dtor` field. This is read and
608        // possibly executed by wasm.
609        dtor_funcref: VMFuncRef,
610    },
611}
612
613pub type ImportedResources = PrimaryMap<ResourceIndex, ResourceType>;
614
615impl<'a> Instantiator<'a> {
616    fn new(
617        component: &'a Component,
618        store: &mut StoreOpaque,
619        imports: &'a Arc<PrimaryMap<RuntimeImportIndex, RuntimeImport>>,
620    ) -> Instantiator<'a> {
621        let env_component = component.env_component();
622        store.modules_mut().register_component(component);
623        let imported_resources: ImportedResources =
624            PrimaryMap::with_capacity(env_component.imported_resources.len());
625
626        let instance = ComponentInstance::new(
627            store.store_data().components.next_component_instance_id(),
628            component,
629            Arc::new(imported_resources),
630            imports,
631            store.traitobj(),
632        );
633        let id = store.store_data_mut().push_component_instance(instance);
634
635        Instantiator {
636            component,
637            imports,
638            core_imports: OwnedImports::empty(),
639            id,
640        }
641    }
642
643    async fn run<T>(&mut self, store: &mut StoreContextMut<'_, T>) -> Result<()> {
644        let env_component = self.component.env_component();
645
646        // Before all initializers are processed configure all destructors for
647        // host-defined resources. No initializer will correspond to these and
648        // it's required to happen before they're needed, so execute this first.
649        for (idx, import) in env_component.imported_resources.iter() {
650            let (ty, func_ref) = match &self.imports[*import] {
651                RuntimeImport::Resource {
652                    ty, dtor_funcref, ..
653                } => (*ty, NonNull::from(dtor_funcref)),
654                _ => unreachable!(),
655            };
656            let i = self.instance_resource_types_mut(store.0).push(ty);
657            assert_eq!(i, idx);
658            self.instance_mut(store.0)
659                .set_resource_destructor(idx, Some(func_ref));
660        }
661
662        // Next configure all `VMFuncRef`s for trampolines that this component
663        // will require. These functions won't actually get used until their
664        // associated state has been initialized through the global initializers
665        // below, but the funcrefs can all be configured here.
666        for (idx, sig) in env_component.trampolines.iter() {
667            let ptrs = self.component.trampoline_ptrs(idx);
668            let signature = match self.component.signatures().shared_type(*sig) {
669                Some(s) => s,
670                None => panic!("found unregistered signature: {sig:?}"),
671            };
672
673            self.instance_mut(store.0).set_trampoline(
674                idx,
675                ptrs.wasm_call,
676                ptrs.array_call,
677                signature,
678            );
679        }
680
681        for initializer in env_component.initializers.iter() {
682            match initializer {
683                GlobalInitializer::InstantiateModule(m) => {
684                    let module;
685                    let imports = match m {
686                        // Since upvars are statically know we know that the
687                        // `args` list is already in the right order.
688                        InstantiateModule::Static(idx, args) => {
689                            module = self.component.static_module(*idx);
690                            self.build_imports(store.0, module, args.iter())
691                        }
692
693                        // With imports, unlike upvars, we need to do runtime
694                        // lookups with strings to determine the order of the
695                        // imports since it's whatever the actual module
696                        // requires.
697                        //
698                        // FIXME: see the note in `ExportItem::Name` handling
699                        // above for how we ideally shouldn't do string lookup
700                        // here.
701                        InstantiateModule::Import(idx, args) => {
702                            module = match &self.imports[*idx] {
703                                RuntimeImport::Module(m) => m,
704                                _ => unreachable!(),
705                            };
706                            let args = module
707                                .imports()
708                                .map(|import| &args[import.module()][import.name()]);
709                            self.build_imports(store.0, module, args)
710                        }
711                    };
712
713                    // Note that the unsafety here should be ok because the
714                    // validity of the component means that type-checks have
715                    // already been performed. This means that the unsafety due
716                    // to imports having the wrong type should not happen here.
717                    //
718                    // Also note we are calling new_started_impl because we have
719                    // already checked for asyncness and are running on a fiber
720                    // if required.
721
722                    let i = unsafe {
723                        crate::Instance::new_started(store, module, imports.as_ref()).await?
724                    };
725                    self.instance_mut(store.0).push_instance_id(i.id());
726                }
727
728                GlobalInitializer::LowerImport { import, index } => {
729                    let func = match &self.imports[*import] {
730                        RuntimeImport::Func(func) => func,
731                        _ => unreachable!(),
732                    };
733                    self.instance_mut(store.0)
734                        .set_lowering(*index, func.lowering());
735                }
736
737                GlobalInitializer::ExtractTable(table) => self.extract_table(store.0, table),
738
739                GlobalInitializer::ExtractMemory(mem) => self.extract_memory(store.0, mem),
740
741                GlobalInitializer::ExtractRealloc(realloc) => {
742                    self.extract_realloc(store.0, realloc)
743                }
744
745                GlobalInitializer::ExtractCallback(callback) => {
746                    self.extract_callback(store.0, callback)
747                }
748
749                GlobalInitializer::ExtractPostReturn(post_return) => {
750                    self.extract_post_return(store.0, post_return)
751                }
752
753                GlobalInitializer::Resource(r) => self.resource(store.0, r),
754            }
755        }
756        Ok(())
757    }
758
759    fn resource(&mut self, store: &mut StoreOpaque, resource: &Resource) {
760        let dtor = resource
761            .dtor
762            .as_ref()
763            .map(|dtor| lookup_vmdef(store, self.id, dtor));
764        let dtor = dtor.map(|export| match export {
765            crate::runtime::vm::Export::Function(f) => f.vm_func_ref(store),
766            _ => unreachable!(),
767        });
768        let index = self
769            .component
770            .env_component()
771            .resource_index(resource.index);
772        let instance = self.instance(store);
773        let ty = ResourceType::guest(store.id(), instance, resource.index);
774        self.instance_mut(store)
775            .set_resource_destructor(index, dtor);
776        let i = self.instance_resource_types_mut(store).push(ty);
777        debug_assert_eq!(i, index);
778    }
779
780    fn extract_memory(&mut self, store: &mut StoreOpaque, memory: &ExtractMemory) {
781        let mem = match lookup_vmexport(store, self.id, &memory.export) {
782            crate::runtime::vm::Export::Memory { memory, .. } => memory,
783            _ => unreachable!(),
784        };
785        let import = mem.vmimport(store);
786        self.instance_mut(store)
787            .set_runtime_memory(memory.index, import.from.as_non_null());
788    }
789
790    fn extract_realloc(&mut self, store: &mut StoreOpaque, realloc: &ExtractRealloc) {
791        let func_ref = match lookup_vmdef(store, self.id, &realloc.def) {
792            crate::runtime::vm::Export::Function(f) => f.vm_func_ref(store),
793            _ => unreachable!(),
794        };
795        self.instance_mut(store)
796            .set_runtime_realloc(realloc.index, func_ref);
797    }
798
799    fn extract_callback(&mut self, store: &mut StoreOpaque, callback: &ExtractCallback) {
800        let func_ref = match lookup_vmdef(store, self.id, &callback.def) {
801            crate::runtime::vm::Export::Function(f) => f.vm_func_ref(store),
802            _ => unreachable!(),
803        };
804        self.instance_mut(store)
805            .set_runtime_callback(callback.index, func_ref);
806    }
807
808    fn extract_post_return(&mut self, store: &mut StoreOpaque, post_return: &ExtractPostReturn) {
809        let func_ref = match lookup_vmdef(store, self.id, &post_return.def) {
810            crate::runtime::vm::Export::Function(f) => f.vm_func_ref(store),
811            _ => unreachable!(),
812        };
813        self.instance_mut(store)
814            .set_runtime_post_return(post_return.index, func_ref);
815    }
816
817    fn extract_table(&mut self, store: &mut StoreOpaque, table: &ExtractTable) {
818        let export = match lookup_vmexport(store, self.id, &table.export) {
819            crate::runtime::vm::Export::Table(t) => t,
820            _ => unreachable!(),
821        };
822        let import = export.vmimport(store);
823        self.instance_mut(store)
824            .set_runtime_table(table.index, import);
825    }
826
827    fn build_imports<'b>(
828        &mut self,
829        store: &mut StoreOpaque,
830        module: &Module,
831        args: impl Iterator<Item = &'b CoreDef>,
832    ) -> &OwnedImports {
833        self.core_imports.clear();
834        self.core_imports.reserve(module);
835        let mut imports = module.compiled_module().module().imports();
836
837        for arg in args {
838            // The general idea of Wasmtime is that at runtime type-checks for
839            // core wasm instantiations internally within a component are
840            // unnecessary and superfluous. Naturally though mistakes may be
841            // made, so double-check this property of wasmtime in debug mode.
842
843            if cfg!(debug_assertions) {
844                let (imp_module, imp_name, expected) = imports.next().unwrap();
845                self.assert_type_matches(store, module, arg, imp_module, imp_name, expected);
846            }
847
848            // The unsafety here should be ok since the `export` is loaded
849            // directly from an instance which should only give us valid export
850            // items.
851            let export = lookup_vmdef(store, self.id, arg);
852            self.core_imports.push_export(store, &export);
853        }
854        debug_assert!(imports.next().is_none());
855
856        &self.core_imports
857    }
858
859    fn assert_type_matches(
860        &self,
861        store: &mut StoreOpaque,
862        module: &Module,
863        arg: &CoreDef,
864        imp_module: &str,
865        imp_name: &str,
866        expected: EntityType,
867    ) {
868        let export = lookup_vmdef(store, self.id, arg);
869
870        // If this value is a core wasm function then the type check is inlined
871        // here. This can otherwise fail `Extern::from_wasmtime_export` because
872        // there's no guarantee that there exists a trampoline for `f` so this
873        // can't fall through to the case below
874        if let crate::runtime::vm::Export::Function(f) = &export {
875            let expected = match expected.unwrap_func() {
876                EngineOrModuleTypeIndex::Engine(e) => Some(e),
877                EngineOrModuleTypeIndex::Module(m) => module.signatures().shared_type(m),
878                EngineOrModuleTypeIndex::RecGroup(_) => unreachable!(),
879            };
880            let actual = unsafe { f.vm_func_ref(store).as_ref().type_index };
881            assert_eq!(
882                expected,
883                Some(actual),
884                "type mismatch for import {imp_module:?} {imp_name:?}!!!\n\n\
885                 expected {:#?}\n\n\
886                 found {:#?}",
887                expected.and_then(|e| store.engine().signatures().borrow(e)),
888                store.engine().signatures().borrow(actual)
889            );
890            return;
891        }
892
893        let val = unsafe { crate::Extern::from_wasmtime_export(export, store) };
894        let ty = DefinitionType::from(store, &val);
895        crate::types::matching::MatchCx::new(module.engine())
896            .definition(&expected, &ty)
897            .expect("unexpected typecheck failure");
898    }
899
900    /// Convenience helper to return the `&ComponentInstance` that's being
901    /// instantiated.
902    fn instance<'b>(&self, store: &'b StoreOpaque) -> &'b ComponentInstance {
903        store.store_data().component_instance(self.id)
904    }
905
906    /// Same as [`Self::instance`], but for mutability.
907    fn instance_mut<'b>(&self, store: &'b mut StoreOpaque) -> Pin<&'b mut ComponentInstance> {
908        store.store_data_mut().component_instance_mut(self.id)
909    }
910
911    // NB: This method is only intended to be called during the instantiation
912    // process because the `Arc::get_mut` here is fallible and won't generally
913    // succeed once the instance has been handed to the embedder. Before that
914    // though it should be guaranteed that the single owning reference currently
915    // lives within the `ComponentInstance` that's being built.
916    fn instance_resource_types_mut<'b>(
917        &self,
918        store: &'b mut StoreOpaque,
919    ) -> &'b mut ImportedResources {
920        Arc::get_mut(self.instance_mut(store).resource_types_mut()).unwrap()
921    }
922}
923
924/// A "pre-instantiated" [`Instance`] which has all of its arguments already
925/// supplied and is ready to instantiate.
926///
927/// This structure represents an efficient form of instantiation where import
928/// type-checking and import lookup has all been resolved by the time that this
929/// type is created. This type is primarily created through the
930/// [`Linker::instantiate_pre`](crate::component::Linker::instantiate_pre)
931/// method.
932pub struct InstancePre<T: 'static> {
933    component: Component,
934    imports: Arc<PrimaryMap<RuntimeImportIndex, RuntimeImport>>,
935    resource_types: Arc<PrimaryMap<ResourceIndex, ResourceType>>,
936    _marker: marker::PhantomData<fn() -> T>,
937}
938
939// `InstancePre`'s clone does not require `T: Clone`
940impl<T: 'static> Clone for InstancePre<T> {
941    fn clone(&self) -> Self {
942        Self {
943            component: self.component.clone(),
944            imports: self.imports.clone(),
945            resource_types: self.resource_types.clone(),
946            _marker: self._marker,
947        }
948    }
949}
950
951impl<T: 'static> InstancePre<T> {
952    /// This function is `unsafe` since there's no guarantee that the
953    /// `RuntimeImport` items provided are guaranteed to work with the `T` of
954    /// the store.
955    ///
956    /// Additionally there is no static guarantee that the `imports` provided
957    /// satisfy the imports of the `component` provided.
958    pub(crate) unsafe fn new_unchecked(
959        component: Component,
960        imports: Arc<PrimaryMap<RuntimeImportIndex, RuntimeImport>>,
961        resource_types: Arc<PrimaryMap<ResourceIndex, ResourceType>>,
962    ) -> InstancePre<T> {
963        InstancePre {
964            component,
965            imports,
966            resource_types,
967            _marker: marker::PhantomData,
968        }
969    }
970
971    /// Returns the underlying component that will be instantiated.
972    pub fn component(&self) -> &Component {
973        &self.component
974    }
975
976    #[doc(hidden)]
977    /// Returns the type at which the underlying component will be
978    /// instantiated. This contains the instantiated type information which
979    /// was determined by the Linker.
980    pub fn instance_type(&self) -> InstanceType<'_> {
981        InstanceType {
982            types: &self.component.types(),
983            resources: &self.resource_types,
984        }
985    }
986
987    /// Returns the underlying engine.
988    pub fn engine(&self) -> &Engine {
989        self.component.engine()
990    }
991
992    /// Performs the instantiation process into the store specified.
993    //
994    // TODO: needs more docs
995    pub fn instantiate(&self, store: impl AsContextMut<Data = T>) -> Result<Instance> {
996        assert!(
997            !store.as_context().async_support(),
998            "must use async instantiation when async support is enabled"
999        );
1000        vm::assert_ready(self._instantiate(store))
1001    }
1002    /// Performs the instantiation process into the store specified.
1003    ///
1004    /// Exactly like [`Self::instantiate`] except for use on async stores.
1005    //
1006    // TODO: needs more docs
1007    #[cfg(feature = "async")]
1008    pub async fn instantiate_async(&self, store: impl AsContextMut<Data = T>) -> Result<Instance> {
1009        self._instantiate(store).await
1010    }
1011
1012    async fn _instantiate(&self, mut store: impl AsContextMut<Data = T>) -> Result<Instance> {
1013        let mut store = store.as_context_mut();
1014        store
1015            .engine()
1016            .allocator()
1017            .increment_component_instance_count()?;
1018        let mut instantiator = Instantiator::new(&self.component, store.0, &self.imports);
1019        instantiator.run(&mut store).await.map_err(|e| {
1020            store
1021                .engine()
1022                .allocator()
1023                .decrement_component_instance_count();
1024            e
1025        })?;
1026        let instance = Instance::from_wasmtime(store.0, instantiator.id);
1027        store.0.push_component_instance(instance);
1028        Ok(instance)
1029    }
1030}