wasmtime/runtime/
instance.rs

1use crate::linker::{Definition, DefinitionType};
2use crate::prelude::*;
3use crate::runtime::vm::{
4    self, Imports, ModuleRuntimeInfo, VMFuncRef, VMFunctionImport, VMGlobalImport, VMMemoryImport,
5    VMTableImport, VMTagImport,
6};
7use crate::store::{AllocateInstanceKind, InstanceId, StoreInstanceId, StoreOpaque};
8use crate::types::matching;
9use crate::{
10    AsContextMut, Engine, Export, Extern, Func, Global, Memory, Module, ModuleExport, SharedMemory,
11    StoreContext, StoreContextMut, Table, Tag, TypedFunc,
12};
13use alloc::sync::Arc;
14use core::ptr::NonNull;
15use wasmparser::WasmFeatures;
16use wasmtime_environ::{
17    EntityIndex, EntityType, FuncIndex, GlobalIndex, MemoryIndex, PrimaryMap, TableIndex, TagIndex,
18    TypeTrace,
19};
20
21/// An instantiated WebAssembly module.
22///
23/// This type represents the instantiation of a [`Module`]. Once instantiated
24/// you can access the [`exports`](Instance::exports) which are of type
25/// [`Extern`] and provide the ability to call functions, set globals, read
26/// memory, etc. When interacting with any wasm code you'll want to make an
27/// [`Instance`] to call any code or execute anything.
28///
29/// Instances are owned by a [`Store`](crate::Store) which is passed in at
30/// creation time. It's recommended to create instances with
31/// [`Linker::instantiate`](crate::Linker::instantiate) or similar
32/// [`Linker`](crate::Linker) methods, but a more low-level constructor is also
33/// available as [`Instance::new`].
34#[derive(Copy, Clone, Debug)]
35#[repr(C)]
36pub struct Instance {
37    id: StoreInstanceId,
38}
39
40// Double-check that the C representation in `instance.h` matches our in-Rust
41// representation here in terms of size/alignment/etc.
42const _: () = {
43    #[repr(C)]
44    struct C(u64, usize);
45    assert!(core::mem::size_of::<C>() == core::mem::size_of::<Instance>());
46    assert!(core::mem::align_of::<C>() == core::mem::align_of::<Instance>());
47    assert!(core::mem::offset_of!(Instance, id) == 0);
48};
49
50impl Instance {
51    /// Creates a new [`Instance`] from the previously compiled [`Module`] and
52    /// list of `imports` specified.
53    ///
54    /// This method instantiates the `module` provided with the `imports`,
55    /// following the procedure in the [core specification][inst] to
56    /// instantiate. Instantiation can fail for a number of reasons (many
57    /// specified below), but if successful the `start` function will be
58    /// automatically run (if specified in the `module`) and then the
59    /// [`Instance`] will be returned.
60    ///
61    /// Per the WebAssembly spec, instantiation includes running the module's
62    /// start function, if it has one (not to be confused with the `_start`
63    /// function, which is not run).
64    ///
65    /// Note that this is a low-level function that just performs an
66    /// instantiation. See the [`Linker`](crate::Linker) struct for an API which
67    /// provides a convenient way to link imports and provides automatic Command
68    /// and Reactor behavior.
69    ///
70    /// ## Providing Imports
71    ///
72    /// The entries in the list of `imports` are intended to correspond 1:1
73    /// with the list of imports returned by [`Module::imports`]. Before
74    /// calling [`Instance::new`] you'll want to inspect the return value of
75    /// [`Module::imports`] and, for each import type, create an [`Extern`]
76    /// which corresponds to that type.  These [`Extern`] values are all then
77    /// collected into a list and passed to this function.
78    ///
79    /// Note that this function is intentionally relatively low level. For an
80    /// easier time passing imports by doing name-based resolution it's
81    /// recommended to instead use the [`Linker`](crate::Linker) type.
82    ///
83    /// ## Errors
84    ///
85    /// This function can fail for a number of reasons, including, but not
86    /// limited to:
87    ///
88    /// * The number of `imports` provided doesn't match the number of imports
89    ///   returned by the `module`'s [`Module::imports`] method.
90    /// * The type of any [`Extern`] doesn't match the corresponding
91    ///   [`ExternType`] entry that it maps to.
92    /// * The `start` function in the instance, if present, traps.
93    /// * Module/instance resource limits are exceeded.
94    ///
95    /// When instantiation fails it's recommended to inspect the return value to
96    /// see why it failed, or bubble it upwards. If you'd like to specifically
97    /// check for trap errors, you can use `error.downcast::<Trap>()`. For more
98    /// about error handling see the [`Trap`] documentation.
99    ///
100    /// [`Trap`]: crate::Trap
101    ///
102    /// # Panics
103    ///
104    /// This function will panic if called with a store associated with a
105    /// [`asynchronous config`](crate::Config::async_support). This function
106    /// will also panic if any [`Extern`] supplied is not owned by `store`.
107    ///
108    /// [inst]: https://webassembly.github.io/spec/core/exec/modules.html#exec-instantiation
109    /// [`ExternType`]: crate::ExternType
110    pub fn new(
111        mut store: impl AsContextMut,
112        module: &Module,
113        imports: &[Extern],
114    ) -> Result<Instance> {
115        let mut store = store.as_context_mut();
116        let imports = Instance::typecheck_externs(store.0, module, imports)?;
117        // Note that the unsafety here should be satisfied by the call to
118        // `typecheck_externs` above which satisfies the condition that all
119        // the imports are valid for this module.
120        unsafe { Instance::new_started(&mut store, module, imports.as_ref()) }
121    }
122
123    /// Same as [`Instance::new`], except for usage in [asynchronous stores].
124    ///
125    /// For more details about this function see the documentation on
126    /// [`Instance::new`]. The only difference between these two methods is that
127    /// this one will asynchronously invoke the wasm start function in case it
128    /// calls any imported function which is an asynchronous host function (e.g.
129    /// created with [`Func::new_async`](crate::Func::new_async).
130    ///
131    /// # Panics
132    ///
133    /// This function will panic if called with a store associated with a
134    /// [`synchronous config`](crate::Config::new). This is only compatible with
135    /// stores associated with an [`asynchronous
136    /// config`](crate::Config::async_support).
137    ///
138    /// This function will also panic, like [`Instance::new`], if any [`Extern`]
139    /// specified does not belong to `store`.
140    #[cfg(feature = "async")]
141    pub async fn new_async(
142        mut store: impl AsContextMut<Data: Send>,
143        module: &Module,
144        imports: &[Extern],
145    ) -> Result<Instance> {
146        let mut store = store.as_context_mut();
147        let imports = Instance::typecheck_externs(store.0, module, imports)?;
148        // See `new` for notes on this unsafety
149        unsafe { Instance::new_started_async(&mut store, module, imports.as_ref()).await }
150    }
151
152    fn typecheck_externs(
153        store: &mut StoreOpaque,
154        module: &Module,
155        imports: &[Extern],
156    ) -> Result<OwnedImports> {
157        for import in imports {
158            if !import.comes_from_same_store(store) {
159                bail!("cross-`Store` instantiation is not currently supported");
160            }
161        }
162
163        typecheck(module, imports, |cx, ty, item| {
164            let item = DefinitionType::from(store, item);
165            cx.definition(ty, &item)
166        })?;
167
168        // When pushing functions into `OwnedImports` it's required that their
169        // `wasm_call` fields are all filled out. This `module` is guaranteed
170        // to have any trampolines necessary for functions so register the
171        // module with the store and then attempt to fill out any outstanding
172        // holes.
173        //
174        // Note that under normal operation this shouldn't do much as the list
175        // of funcs-with-holes should generally be empty. As a result the
176        // process of filling this out is not super optimized at this point.
177        store.modules_mut().register_module(module);
178        let (funcrefs, modules) = store.func_refs_and_modules();
179        funcrefs.fill(modules);
180
181        let mut owned_imports = OwnedImports::new(module);
182        for import in imports {
183            owned_imports.push(import, store);
184        }
185        Ok(owned_imports)
186    }
187
188    /// Internal function to create an instance and run the start function.
189    ///
190    /// This function's unsafety is the same as `Instance::new_raw`.
191    pub(crate) unsafe fn new_started<T>(
192        store: &mut StoreContextMut<'_, T>,
193        module: &Module,
194        imports: Imports<'_>,
195    ) -> Result<Instance> {
196        assert!(
197            !store.0.async_support(),
198            "must use async instantiation when async support is enabled",
199        );
200        Self::new_started_impl(store, module, imports)
201    }
202
203    /// Internal function to create an instance and run the start function.
204    ///
205    /// ONLY CALL THIS IF YOU HAVE ALREADY CHECKED FOR ASYNCNESS AND HANDLED
206    /// THE FIBER NONSENSE
207    pub(crate) unsafe fn new_started_impl<T>(
208        store: &mut StoreContextMut<'_, T>,
209        module: &Module,
210        imports: Imports<'_>,
211    ) -> Result<Instance> {
212        let (instance, start) = Instance::new_raw(store.0, module, imports)?;
213        if let Some(start) = start {
214            instance.start_raw(store, start)?;
215        }
216        Ok(instance)
217    }
218
219    /// Internal function to create an instance and run the start function.
220    ///
221    /// This function's unsafety is the same as `Instance::new_raw`.
222    #[cfg(feature = "async")]
223    async unsafe fn new_started_async<T>(
224        store: &mut StoreContextMut<'_, T>,
225        module: &Module,
226        imports: Imports<'_>,
227    ) -> Result<Instance>
228    where
229        T: Send + 'static,
230    {
231        assert!(
232            store.0.async_support(),
233            "must use sync instantiation when async support is disabled",
234        );
235
236        store
237            .on_fiber(|store| Self::new_started_impl(store, module, imports))
238            .await?
239    }
240
241    /// Internal function to create an instance which doesn't have its `start`
242    /// function run yet.
243    ///
244    /// This is not intended to be exposed from Wasmtime, it's intended to
245    /// refactor out common code from `new_started` and `new_started_async`.
246    ///
247    /// Note that this step needs to be run on a fiber in async mode even
248    /// though it doesn't do any blocking work because an async resource
249    /// limiter may need to yield.
250    ///
251    /// # Unsafety
252    ///
253    /// This method is unsafe because it does not type-check the `imports`
254    /// provided. The `imports` provided must be suitable for the module
255    /// provided as well.
256    unsafe fn new_raw(
257        store: &mut StoreOpaque,
258        module: &Module,
259        imports: Imports<'_>,
260    ) -> Result<(Instance, Option<FuncIndex>)> {
261        if !Engine::same(store.engine(), module.engine()) {
262            bail!("cross-`Engine` instantiation is not currently supported");
263        }
264        store.bump_resource_counts(module)?;
265
266        // Allocate the GC heap, if necessary.
267        if module.env_module().needs_gc_heap {
268            let _ = store.gc_store_mut()?;
269        }
270
271        let compiled_module = module.compiled_module();
272
273        // Register the module just before instantiation to ensure we keep the module
274        // properly referenced while in use by the store.
275        let module_id = store.modules_mut().register_module(module);
276
277        // The first thing we do is issue an instance allocation request
278        // to the instance allocator. This, on success, will give us an
279        // instance handle.
280        let id = store.allocate_instance(
281            AllocateInstanceKind::Module(module_id),
282            &ModuleRuntimeInfo::Module(module.clone()),
283            imports,
284        )?;
285
286        // Additionally, before we start doing fallible instantiation, we
287        // do one more step which is to insert an `InstanceData`
288        // corresponding to this instance. This `InstanceData` can be used
289        // via `Caller::get_export` if our instance's state "leaks" into
290        // other instances, even if we don't return successfully from this
291        // function.
292        //
293        // We don't actually load all exports from the instance at this
294        // time, instead preferring to lazily load them as they're demanded.
295        // For module/instance exports, though, those aren't actually
296        // stored in the instance handle so we need to immediately handle
297        // those here.
298        let instance = Instance::from_wasmtime(id, store);
299
300        // Now that we've recorded all information we need to about this
301        // instance within a `Store` we can start performing fallible
302        // initialization. Note that we still defer the `start` function to
303        // later since that may need to run asynchronously.
304        //
305        // If this returns an error (or if the start function traps) then
306        // any other initialization which may have succeeded which placed
307        // items from this instance into other instances should be ok when
308        // those items are loaded and run we'll have all the metadata to
309        // look at them.
310        let bulk_memory = store
311            .engine()
312            .features()
313            .contains(WasmFeatures::BULK_MEMORY);
314
315        vm::initialize_instance(store, id, compiled_module.module(), bulk_memory)?;
316
317        Ok((instance, compiled_module.module().start_func))
318    }
319
320    pub(crate) fn from_wasmtime(id: InstanceId, store: &mut StoreOpaque) -> Instance {
321        Instance {
322            id: StoreInstanceId::new(store.id(), id),
323        }
324    }
325
326    fn start_raw<T>(&self, store: &mut StoreContextMut<'_, T>, start: FuncIndex) -> Result<()> {
327        // If a start function is present, invoke it. Make sure we use all the
328        // trap-handling configuration in `store` as well.
329        let mut instance = self.id.get_mut(store.0);
330        let f = instance.as_mut().get_exported_func(start);
331        let caller_vmctx = instance.vmctx();
332        unsafe {
333            super::func::invoke_wasm_and_catch_traps(store, |_default_caller, vm| {
334                VMFuncRef::array_call(f.func_ref, vm, caller_vmctx, NonNull::from(&mut []))
335            })?;
336        }
337        Ok(())
338    }
339
340    /// Get this instance's module.
341    pub fn module<'a, T: 'static>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a Module {
342        self._module(store.into().0)
343    }
344
345    fn _module<'a>(&self, store: &'a StoreOpaque) -> &'a Module {
346        store.module_for_instance(self.id).unwrap()
347    }
348
349    /// Returns the list of exported items from this [`Instance`].
350    ///
351    /// # Panics
352    ///
353    /// Panics if `store` does not own this instance.
354    pub fn exports<'a, T: 'static>(
355        &'a self,
356        store: impl Into<StoreContextMut<'a, T>>,
357    ) -> impl ExactSizeIterator<Item = Export<'a>> + 'a {
358        self._exports(store.into().0)
359    }
360
361    fn _exports<'a>(
362        &'a self,
363        store: &'a mut StoreOpaque,
364    ) -> impl ExactSizeIterator<Item = Export<'a>> + 'a {
365        let module = store[self.id].env_module().clone();
366        let mut items = Vec::new();
367        for (_name, entity) in module.exports.iter() {
368            items.push(self._get_export(store, *entity));
369        }
370        store[self.id]
371            .env_module()
372            .exports
373            .iter()
374            .zip(items)
375            .map(|((name, _), item)| Export::new(name, item))
376    }
377
378    /// Looks up an exported [`Extern`] value by name.
379    ///
380    /// This method will search the module for an export named `name` and return
381    /// the value, if found.
382    ///
383    /// Returns `None` if there was no export named `name`.
384    ///
385    /// # Panics
386    ///
387    /// Panics if `store` does not own this instance.
388    ///
389    /// # Why does `get_export` take a mutable context?
390    ///
391    /// This method requires a mutable context because an instance's exports are
392    /// lazily populated, and we cache them as they are accessed. This makes
393    /// instantiating a module faster, but also means this method requires a
394    /// mutable context.
395    pub fn get_export(&self, mut store: impl AsContextMut, name: &str) -> Option<Extern> {
396        let store = store.as_context_mut().0;
397        let entity = *store[self.id].env_module().exports.get(name)?;
398        Some(self._get_export(store, entity))
399    }
400
401    /// Looks up an exported [`Extern`] value by a [`ModuleExport`] value.
402    ///
403    /// This is similar to [`Instance::get_export`] but uses a [`ModuleExport`] value to avoid
404    /// string lookups where possible. [`ModuleExport`]s can be obtained by calling
405    /// [`Module::get_export_index`] on the [`Module`] that this instance was instantiated with.
406    ///
407    /// This method will search the module for an export with a matching entity index and return
408    /// the value, if found.
409    ///
410    /// Returns `None` if there was no export with a matching entity index.
411    /// # Panics
412    ///
413    /// Panics if `store` does not own this instance.
414    pub fn get_module_export(
415        &self,
416        mut store: impl AsContextMut,
417        export: &ModuleExport,
418    ) -> Option<Extern> {
419        let store = store.as_context_mut().0;
420
421        // Verify the `ModuleExport` matches the module used in this instance.
422        if self._module(store).id() != export.module {
423            return None;
424        }
425
426        Some(self._get_export(store, export.entity))
427    }
428
429    fn _get_export(&self, store: &mut StoreOpaque, entity: EntityIndex) -> Extern {
430        let export = self.id.get_mut(store).get_export_by_index_mut(entity);
431        unsafe { Extern::from_wasmtime_export(export, store) }
432    }
433
434    /// Looks up an exported [`Func`] value by name.
435    ///
436    /// Returns `None` if there was no export named `name`, or if there was but
437    /// it wasn't a function.
438    ///
439    /// # Panics
440    ///
441    /// Panics if `store` does not own this instance.
442    pub fn get_func(&self, store: impl AsContextMut, name: &str) -> Option<Func> {
443        self.get_export(store, name)?.into_func()
444    }
445
446    /// Looks up an exported [`Func`] value by name and with its type.
447    ///
448    /// This function is a convenience wrapper over [`Instance::get_func`] and
449    /// [`Func::typed`]. For more information see the linked documentation.
450    ///
451    /// Returns an error if `name` isn't a function export or if the export's
452    /// type did not match `Params` or `Results`
453    ///
454    /// # Panics
455    ///
456    /// Panics if `store` does not own this instance.
457    pub fn get_typed_func<Params, Results>(
458        &self,
459        mut store: impl AsContextMut,
460        name: &str,
461    ) -> Result<TypedFunc<Params, Results>>
462    where
463        Params: crate::WasmParams,
464        Results: crate::WasmResults,
465    {
466        let f = self
467            .get_export(store.as_context_mut(), name)
468            .and_then(|f| f.into_func())
469            .ok_or_else(|| anyhow!("failed to find function export `{}`", name))?;
470        Ok(f.typed::<Params, Results>(store)
471            .with_context(|| format!("failed to convert function `{name}` to given type"))?)
472    }
473
474    /// Looks up an exported [`Table`] value by name.
475    ///
476    /// Returns `None` if there was no export named `name`, or if there was but
477    /// it wasn't a table.
478    ///
479    /// # Panics
480    ///
481    /// Panics if `store` does not own this instance.
482    pub fn get_table(&self, store: impl AsContextMut, name: &str) -> Option<Table> {
483        self.get_export(store, name)?.into_table()
484    }
485
486    /// Looks up an exported [`Memory`] value by name.
487    ///
488    /// Returns `None` if there was no export named `name`, or if there was but
489    /// it wasn't a memory.
490    ///
491    /// # Panics
492    ///
493    /// Panics if `store` does not own this instance.
494    pub fn get_memory(&self, store: impl AsContextMut, name: &str) -> Option<Memory> {
495        self.get_export(store, name)?.into_memory()
496    }
497
498    /// Looks up an exported [`SharedMemory`] value by name.
499    ///
500    /// Returns `None` if there was no export named `name`, or if there was but
501    /// it wasn't a shared memory.
502    ///
503    /// # Panics
504    ///
505    /// Panics if `store` does not own this instance.
506    pub fn get_shared_memory(
507        &self,
508        mut store: impl AsContextMut,
509        name: &str,
510    ) -> Option<SharedMemory> {
511        let mut store = store.as_context_mut();
512        self.get_export(&mut store, name)?.into_shared_memory()
513    }
514
515    /// Looks up an exported [`Global`] value by name.
516    ///
517    /// Returns `None` if there was no export named `name`, or if there was but
518    /// it wasn't a global.
519    ///
520    /// # Panics
521    ///
522    /// Panics if `store` does not own this instance.
523    pub fn get_global(&self, store: impl AsContextMut, name: &str) -> Option<Global> {
524        self.get_export(store, name)?.into_global()
525    }
526
527    /// Looks up a tag [`Tag`] by name.
528    ///
529    /// Returns `None` if there was no export named `name`, or if there was but
530    /// it wasn't a tag.
531    ///
532    /// # Panics
533    ///
534    /// Panics if `store` does not own this instance.
535    pub fn get_tag(&self, store: impl AsContextMut, name: &str) -> Option<Tag> {
536        self.get_export(store, name)?.into_tag()
537    }
538
539    #[cfg(feature = "component-model")]
540    pub(crate) fn id(&self) -> InstanceId {
541        self.id.instance()
542    }
543
544    /// Get all globals within this instance.
545    ///
546    /// Returns both import and defined globals.
547    ///
548    /// Returns both exported and non-exported globals.
549    ///
550    /// Gives access to the full globals space.
551    #[cfg(feature = "coredump")]
552    pub(crate) fn all_globals<'a>(
553        &'a self,
554        store: &'a mut StoreOpaque,
555    ) -> impl ExactSizeIterator<Item = (GlobalIndex, Global)> + 'a {
556        store[self.id]
557            .all_globals()
558            .collect::<Vec<_>>()
559            .into_iter()
560            .map(|(i, g)| (i, unsafe { Global::from_wasmtime_global(g, store) }))
561    }
562
563    /// Get all memories within this instance.
564    ///
565    /// Returns both import and defined memories.
566    ///
567    /// Returns both exported and non-exported memories.
568    ///
569    /// Gives access to the full memories space.
570    #[cfg(feature = "coredump")]
571    pub(crate) fn all_memories<'a>(
572        &'a self,
573        store: &'a mut StoreOpaque,
574    ) -> impl ExactSizeIterator<Item = (MemoryIndex, Memory)> + 'a {
575        store[self.id]
576            .all_memories()
577            .collect::<Vec<_>>()
578            .into_iter()
579            .map(|(i, m)| (i, unsafe { Memory::from_wasmtime_memory(m, store) }))
580    }
581}
582
583pub(crate) struct OwnedImports {
584    functions: PrimaryMap<FuncIndex, VMFunctionImport>,
585    tables: PrimaryMap<TableIndex, VMTableImport>,
586    memories: PrimaryMap<MemoryIndex, VMMemoryImport>,
587    globals: PrimaryMap<GlobalIndex, VMGlobalImport>,
588    tags: PrimaryMap<TagIndex, VMTagImport>,
589}
590
591impl OwnedImports {
592    fn new(module: &Module) -> OwnedImports {
593        let mut ret = OwnedImports::empty();
594        ret.reserve(module);
595        return ret;
596    }
597
598    pub(crate) fn empty() -> OwnedImports {
599        OwnedImports {
600            functions: PrimaryMap::new(),
601            tables: PrimaryMap::new(),
602            memories: PrimaryMap::new(),
603            globals: PrimaryMap::new(),
604            tags: PrimaryMap::new(),
605        }
606    }
607
608    pub(crate) fn reserve(&mut self, module: &Module) {
609        let raw = module.compiled_module().module();
610        self.functions.reserve(raw.num_imported_funcs);
611        self.tables.reserve(raw.num_imported_tables);
612        self.memories.reserve(raw.num_imported_memories);
613        self.globals.reserve(raw.num_imported_globals);
614        self.tags.reserve(raw.num_imported_tags);
615    }
616
617    #[cfg(feature = "component-model")]
618    pub(crate) fn clear(&mut self) {
619        self.functions.clear();
620        self.tables.clear();
621        self.memories.clear();
622        self.globals.clear();
623        self.tags.clear();
624    }
625
626    fn push(&mut self, item: &Extern, store: &mut StoreOpaque) {
627        match item {
628            Extern::Func(i) => {
629                self.functions.push(i.vmimport(store));
630            }
631            Extern::Global(i) => {
632                self.globals.push(i.vmimport(store));
633            }
634            Extern::Table(i) => {
635                self.tables.push(i.vmimport(store));
636            }
637            Extern::Memory(i) => {
638                self.memories.push(i.vmimport(store));
639            }
640            Extern::SharedMemory(i) => {
641                self.memories.push(i.vmimport(store));
642            }
643            Extern::Tag(i) => {
644                self.tags.push(i.vmimport(store));
645            }
646        }
647    }
648
649    /// Note that this is unsafe as the validity of `item` is not verified and
650    /// it contains a bunch of raw pointers.
651    #[cfg(feature = "component-model")]
652    pub(crate) unsafe fn push_export(&mut self, item: &crate::runtime::vm::Export) {
653        match item {
654            crate::runtime::vm::Export::Function(f) => {
655                let f = f.func_ref.as_ref();
656                self.functions.push(VMFunctionImport {
657                    wasm_call: f.wasm_call.unwrap(),
658                    array_call: f.array_call,
659                    vmctx: f.vmctx,
660                });
661            }
662            crate::runtime::vm::Export::Global(g) => {
663                self.globals.push(g.vmimport());
664            }
665            crate::runtime::vm::Export::Table(t) => {
666                self.tables.push(VMTableImport {
667                    from: t.definition.into(),
668                    vmctx: t.vmctx.into(),
669                    index: t.index,
670                });
671            }
672            crate::runtime::vm::Export::Memory(m) => {
673                self.memories.push(VMMemoryImport {
674                    from: m.definition.into(),
675                    vmctx: m.vmctx.into(),
676                    index: m.index,
677                });
678            }
679            crate::runtime::vm::Export::Tag(t) => {
680                self.tags.push(VMTagImport {
681                    from: t.definition.into(),
682                    vmctx: t.vmctx.into(),
683                    index: t.index,
684                });
685            }
686        }
687    }
688
689    pub(crate) fn as_ref(&self) -> Imports<'_> {
690        Imports {
691            tables: self.tables.values().as_slice(),
692            globals: self.globals.values().as_slice(),
693            memories: self.memories.values().as_slice(),
694            functions: self.functions.values().as_slice(),
695            tags: self.tags.values().as_slice(),
696        }
697    }
698}
699
700/// An instance, pre-instantiation, that is ready to be instantiated.
701///
702/// This structure represents an instance *just before* it was instantiated,
703/// after all type-checking and imports have been resolved. The only thing left
704/// to do for this instance is to actually run the process of instantiation.
705///
706/// Note that an `InstancePre` may not be tied to any particular [`Store`] if
707/// none of the imports it closed over are tied to any particular [`Store`].
708///
709/// This structure is created through the [`Linker::instantiate_pre`] method,
710/// which also has some more information and examples.
711///
712/// [`Store`]: crate::Store
713/// [`Linker::instantiate_pre`]: crate::Linker::instantiate_pre
714pub struct InstancePre<T> {
715    module: Module,
716
717    /// The items which this `InstancePre` use to instantiate the `module`
718    /// provided, passed to `Instance::new_started` after inserting them into a
719    /// `Store`.
720    ///
721    /// Note that this is stored as an `Arc<[T]>` to quickly move a strong
722    /// reference to everything internally into a `Store<T>` without having to
723    /// clone each individual item.
724    items: Arc<[Definition]>,
725
726    /// A count of `Definition::HostFunc` entries in `items` above to
727    /// preallocate space in a `Store` up front for all entries to be inserted.
728    host_funcs: usize,
729
730    /// The `VMFuncRef`s for the functions in `items` that do not
731    /// have a `wasm_call` trampoline. We pre-allocate and pre-patch these
732    /// `VMFuncRef`s so that we don't have to do it at
733    /// instantiation time.
734    ///
735    /// This is an `Arc<[T]>` for the same reason as `items`.
736    func_refs: Arc<[VMFuncRef]>,
737
738    _marker: core::marker::PhantomData<fn() -> T>,
739}
740
741/// InstancePre's clone does not require T: Clone
742impl<T> Clone for InstancePre<T> {
743    fn clone(&self) -> Self {
744        Self {
745            module: self.module.clone(),
746            items: self.items.clone(),
747            host_funcs: self.host_funcs,
748            func_refs: self.func_refs.clone(),
749            _marker: self._marker,
750        }
751    }
752}
753
754impl<T: 'static> InstancePre<T> {
755    /// Creates a new `InstancePre` which type-checks the `items` provided and
756    /// on success is ready to instantiate a new instance.
757    ///
758    /// # Unsafety
759    ///
760    /// This method is unsafe as the `T` of the `InstancePre<T>` is not
761    /// guaranteed to be the same as the `T` within the `Store`, the caller must
762    /// verify that.
763    pub(crate) unsafe fn new(module: &Module, items: Vec<Definition>) -> Result<InstancePre<T>> {
764        typecheck(module, &items, |cx, ty, item| cx.definition(ty, &item.ty()))?;
765
766        let mut func_refs = vec![];
767        let mut host_funcs = 0;
768        for item in &items {
769            match item {
770                Definition::Extern(_, _) => {}
771                Definition::HostFunc(f) => {
772                    host_funcs += 1;
773                    if f.func_ref().wasm_call.is_none() {
774                        // `f` needs its `VMFuncRef::wasm_call` patched with a
775                        // Wasm-to-native trampoline.
776                        debug_assert!(matches!(f.host_ctx(), crate::HostContext::Array(_)));
777                        func_refs.push(VMFuncRef {
778                            wasm_call: module
779                                .wasm_to_array_trampoline(f.sig_index())
780                                .map(|f| f.into()),
781                            ..*f.func_ref()
782                        });
783                    }
784                }
785            }
786        }
787
788        Ok(InstancePre {
789            module: module.clone(),
790            items: items.into(),
791            host_funcs,
792            func_refs: func_refs.into(),
793            _marker: core::marker::PhantomData,
794        })
795    }
796
797    /// Returns a reference to the module that this [`InstancePre`] will be
798    /// instantiating.
799    pub fn module(&self) -> &Module {
800        &self.module
801    }
802
803    /// Instantiates this instance, creating a new instance within the provided
804    /// `store`.
805    ///
806    /// This function will run the actual process of instantiation to
807    /// completion. This will use all of the previously-closed-over items as
808    /// imports to instantiate the module that this was originally created with.
809    ///
810    /// For more information about instantiation see [`Instance::new`].
811    ///
812    /// # Panics
813    ///
814    /// Panics if any import closed over by this [`InstancePre`] isn't owned by
815    /// `store`, or if `store` has async support enabled. Additionally this
816    /// function will panic if the `store` provided comes from a different
817    /// [`Engine`] than the [`InstancePre`] originally came from.
818    pub fn instantiate(&self, mut store: impl AsContextMut<Data = T>) -> Result<Instance> {
819        let mut store = store.as_context_mut();
820        let imports = pre_instantiate_raw(
821            &mut store.0,
822            &self.module,
823            &self.items,
824            self.host_funcs,
825            &self.func_refs,
826        )?;
827
828        // This unsafety should be handled by the type-checking performed by the
829        // constructor of `InstancePre` to assert that all the imports we're passing
830        // in match the module we're instantiating.
831        unsafe { Instance::new_started(&mut store, &self.module, imports.as_ref()) }
832    }
833
834    /// Creates a new instance, running the start function asynchronously
835    /// instead of inline.
836    ///
837    /// For more information about asynchronous instantiation see the
838    /// documentation on [`Instance::new_async`].
839    ///
840    /// # Panics
841    ///
842    /// Panics if any import closed over by this [`InstancePre`] isn't owned by
843    /// `store`, or if `store` does not have async support enabled.
844    #[cfg(feature = "async")]
845    pub async fn instantiate_async(
846        &self,
847        mut store: impl AsContextMut<Data: Send>,
848    ) -> Result<Instance> {
849        let mut store = store.as_context_mut();
850        let imports = pre_instantiate_raw(
851            &mut store.0,
852            &self.module,
853            &self.items,
854            self.host_funcs,
855            &self.func_refs,
856        )?;
857
858        // This unsafety should be handled by the type-checking performed by the
859        // constructor of `InstancePre` to assert that all the imports we're passing
860        // in match the module we're instantiating.
861        unsafe { Instance::new_started_async(&mut store, &self.module, imports.as_ref()).await }
862    }
863}
864
865/// Helper function shared between
866/// `InstancePre::{instantiate,instantiate_async}`
867///
868/// This is an out-of-line function to avoid the generic on `InstancePre` and
869/// get this compiled into the `wasmtime` crate to avoid having it monomorphized
870/// elsewhere.
871fn pre_instantiate_raw(
872    store: &mut StoreOpaque,
873    module: &Module,
874    items: &Arc<[Definition]>,
875    host_funcs: usize,
876    func_refs: &Arc<[VMFuncRef]>,
877) -> Result<OwnedImports> {
878    // Register this module and use it to fill out any funcref wasm_call holes
879    // we can. For more comments on this see `typecheck_externs`.
880    store.modules_mut().register_module(module);
881    let (funcrefs, modules) = store.func_refs_and_modules();
882    funcrefs.fill(modules);
883
884    if host_funcs > 0 {
885        // Any linker-defined function of the `Definition::HostFunc` variant
886        // will insert a function into the store automatically as part of
887        // instantiation, so reserve space here to make insertion more efficient
888        // as it won't have to realloc during the instantiation.
889        funcrefs.reserve_storage(host_funcs);
890
891        // The usage of `to_extern_store_rooted` requires that the items are
892        // rooted via another means, which happens here by cloning the list of
893        // items into the store once. This avoids cloning each individual item
894        // below.
895        funcrefs.push_instance_pre_definitions(items.clone());
896        funcrefs.push_instance_pre_func_refs(func_refs.clone());
897    }
898
899    let mut func_refs = func_refs.iter().map(|f| NonNull::from(f));
900    let mut imports = OwnedImports::new(module);
901    for import in items.iter() {
902        if !import.comes_from_same_store(store) {
903            bail!("cross-`Store` instantiation is not currently supported");
904        }
905        // This unsafety should be encapsulated in the constructor of
906        // `InstancePre` where the `T` of the original item should match the
907        // `T` of the store. Additionally the rooting necessary has happened
908        // above.
909        let item = match import {
910            Definition::Extern(e, _) => e.clone(),
911            Definition::HostFunc(func) => unsafe {
912                func.to_func_store_rooted(
913                    store,
914                    if func.func_ref().wasm_call.is_none() {
915                        Some(func_refs.next().unwrap())
916                    } else {
917                        None
918                    },
919                )
920                .into()
921            },
922        };
923        imports.push(&item, store);
924    }
925
926    Ok(imports)
927}
928
929fn typecheck<I>(
930    module: &Module,
931    import_args: &[I],
932    check: impl Fn(&matching::MatchCx<'_>, &EntityType, &I) -> Result<()>,
933) -> Result<()> {
934    let env_module = module.compiled_module().module();
935    let expected_len = env_module.imports().count();
936    let actual_len = import_args.len();
937    if expected_len != actual_len {
938        bail!("expected {expected_len} imports, found {actual_len}");
939    }
940    let cx = matching::MatchCx::new(module.engine());
941    for ((name, field, expected_ty), actual) in env_module.imports().zip(import_args) {
942        debug_assert!(expected_ty.is_canonicalized_for_runtime_usage());
943        check(&cx, &expected_ty, actual)
944            .with_context(|| format!("incompatible import type for `{name}::{field}`"))?;
945    }
946    Ok(())
947}