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