Skip to main content

wasmtime/runtime/
instance.rs

1use crate::linker::{Definition, DefinitionType};
2use crate::prelude::*;
3use crate::runtime::vm::{
4    self, Imports, ModuleRuntimeInfo, UncaughtException, VMFuncRef, VMFunctionImport,
5    VMGlobalImport, VMMemoryImport, VMStore, VMTableImport, VMTagImport,
6};
7use crate::store::{
8    AllocateInstanceKind, Asyncness, InstanceId, StoreInstanceId, StoreOpaque, StoreResourceLimiter,
9};
10use crate::types::matching;
11use crate::{
12    AsContext, AsContextMut, Engine, Export, Extern, Func, Global, Memory, Module, ModuleExport,
13    SharedMemory, StoreContext, StoreContextMut, Table, Tag, TypedFunc,
14};
15use alloc::sync::Arc;
16use core::ptr::NonNull;
17use wasmtime_environ::{
18    EntityIndex, EntityType, FuncIndex, GlobalIndex, MemoryIndex, TableIndex, TagIndex, 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, PartialEq, Eq)]
35#[repr(C)]
36pub struct Instance {
37    pub(crate) 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    /// * The `store` provided requires the use of [`Instance::new_async`]
95    ///   instead, such as if epochs or fuel are configured.
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 any [`Extern`] supplied is not owned by
107    /// `store`.
108    ///
109    /// [inst]: https://webassembly.github.io/spec/core/exec/modules.html#exec-instantiation
110    /// [`ExternType`]: crate::ExternType
111    ///
112    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
113    /// memory allocation fails. See the `OutOfMemory` type's documentation for
114    /// details on Wasmtime's out-of-memory handling.
115    pub fn new(
116        mut store: impl AsContextMut,
117        module: &Module,
118        imports: &[Extern],
119    ) -> Result<Instance> {
120        let mut store = store.as_context_mut();
121        store.0.validate_sync_call()?;
122        let imports = Instance::typecheck_externs(store.0, module, imports)?;
123        // Note that the unsafety here should be satisfied by the call to
124        // `typecheck_externs` above which satisfies the condition that all
125        // the imports are valid for this module.
126        vm::assert_ready(unsafe {
127            Instance::new_started(&mut store, module, imports.as_ref(), Asyncness::No)
128        })
129    }
130
131    /// Same as [`Instance::new`], except for usage in [asynchronous stores].
132    ///
133    /// For more details about this function see the documentation on
134    /// [`Instance::new`]. The only difference between these two methods is that
135    /// this one will asynchronously invoke the wasm start function in case it
136    /// calls any imported function which is an asynchronous host function (e.g.
137    /// created with [`Func::new_async`](crate::Func::new_async).
138    ///
139    /// # Panics
140    ///
141    /// This function will 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, Module, Instance};
150    ///
151    /// #[tokio::main]
152    /// async fn main() -> Result<()> {
153    ///     let engine = Engine::default();
154    ///
155    ///     // For this example, a module with no imports is being used hence
156    ///     // the empty array to `Instance::new_async`.
157    ///     let module = Module::new(&engine, "(module)")?;
158    ///     let mut store = Store::new(&engine, ());
159    ///     let instance = Instance::new_async(&mut store, &module, &[]).await?;
160    ///
161    ///     // ... use `instance` and exports and such ...
162    ///
163    ///     Ok(())
164    /// }
165    /// ```
166    ///
167    /// Note, though, that the future returned from this function is only
168    /// `Send` if the store's own data is `Send` meaning that this does not
169    /// compile for example:
170    ///
171    /// ```compile_fail
172    /// use wasmtime::{Result, Store, Engine, Module, Instance};
173    /// use std::rc::Rc;
174    ///
175    /// #[tokio::main]
176    /// async fn main() -> Result<()> {
177    ///     let engine = Engine::default();
178    ///
179    ///     let module = Module::new(&engine, "(module)")?;
180    ///
181    ///     // Note that `Rc<()>` is NOT `Send`, which is what many future
182    ///     // runtimes require and below will cause a failure.
183    ///     let mut store = Store::new(&engine, Rc::new(()));
184    ///
185    ///     // Compile failure because `Store<Rc<()>>` is not `Send`
186    ///     assert_send(Instance::new_async(&mut store, &module, &[])).await?;
187    ///
188    ///     Ok(())
189    /// }
190    ///
191    /// fn assert_send<T: Send>(t: T) -> T { t }
192    /// ```
193    ///
194    /// # Errors
195    ///
196    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
197    /// memory allocation fails. See the `OutOfMemory` type's documentation for
198    /// details on Wasmtime's out-of-memory handling.
199    #[cfg(feature = "async")]
200    pub async fn new_async(
201        mut store: impl AsContextMut,
202        module: &Module,
203        imports: &[Extern],
204    ) -> Result<Instance> {
205        let mut store = store.as_context_mut();
206        let imports = Instance::typecheck_externs(store.0, module, imports)?;
207        // See `new` for notes on this unsafety
208        unsafe { Instance::new_started(&mut store, module, imports.as_ref(), Asyncness::Yes).await }
209    }
210
211    fn typecheck_externs(
212        store: &mut StoreOpaque,
213        module: &Module,
214        imports: &[Extern],
215    ) -> Result<OwnedImports> {
216        for import in imports {
217            if !import.comes_from_same_store(store) {
218                bail!("cross-`Store` instantiation is not currently supported");
219            }
220        }
221
222        typecheck(store.engine(), module, imports, |cx, ty, item| {
223            let item = DefinitionType::from(store, item);
224            cx.definition(ty, &item)
225        })?;
226
227        // When pushing functions into `OwnedImports` it's required that their
228        // `wasm_call` fields are all filled out. This `module` is guaranteed
229        // to have any trampolines necessary for functions so register the
230        // module with the store and then attempt to fill out any outstanding
231        // holes.
232        //
233        // Note that under normal operation this shouldn't do much as the list
234        // of funcs-with-holes should generally be empty. As a result the
235        // process of filling this out is not super optimized at this point.
236        let (modules, engine, breakpoints) = store.modules_and_engine_and_breakpoints_mut();
237        modules.register_module(module, engine, breakpoints)?;
238        let (funcrefs, modules) = store.func_refs_and_modules();
239        funcrefs.fill(modules);
240
241        let mut owned_imports = OwnedImports::new(module)?;
242        for import in imports {
243            owned_imports.push(import, store)?;
244        }
245        Ok(owned_imports)
246    }
247
248    /// Internal function to create an instance and run the start function.
249    ///
250    /// This function's unsafety is the same as `Instance::new_raw`.
251    pub(crate) async unsafe fn new_started<T>(
252        store: &mut StoreContextMut<'_, T>,
253        module: &Module,
254        imports: Imports<'_>,
255        asyncness: Asyncness,
256    ) -> Result<Instance> {
257        let (instance, needs_startup) = {
258            let (mut limiter, store) = store.0.resource_limiter_and_store_opaque();
259            // SAFETY: the safety contract of `new_raw` is the same as this
260            // function.
261            unsafe { Instance::new_raw(store, limiter.as_mut(), module, imports).await? }
262        };
263
264        // If this instance requires startup, which is a dynamic decision made
265        // at this point in conjunction with analysis at compile time, the
266        // instance gets started. Note that this isn't just the wasm start
267        // function itself, but it's finalization of initialization of this
268        // instance, for example for complicated global initialization
269        // expressions.
270        if needs_startup {
271            if asyncness == Asyncness::No {
272                instance.start_raw(store, UncaughtException::Propagate)?;
273            } else {
274                #[cfg(feature = "async")]
275                {
276                    store
277                        .on_fiber(|store| instance.start_raw(store, UncaughtException::Propagate))
278                        .await??;
279                }
280                #[cfg(not(feature = "async"))]
281                unreachable!();
282            }
283        }
284        Ok(instance)
285    }
286
287    /// Internal function to create an instance which doesn't have its `start`
288    /// function run yet.
289    ///
290    /// # Unsafety
291    ///
292    /// This method is unsafe because it does not type-check the `imports`
293    /// provided. The `imports` provided must be suitable for the module
294    /// provided as well.
295    pub(crate) async unsafe fn new_raw(
296        store: &mut StoreOpaque,
297        mut limiter: Option<&mut StoreResourceLimiter<'_>>,
298        module: &Module,
299        imports: Imports<'_>,
300    ) -> Result<(Instance, bool)> {
301        if !Engine::same(store.engine(), module.engine()) {
302            bail!("cross-`Engine` instantiation is not currently supported");
303        }
304        store.bump_resource_counts(module)?;
305
306        // Allocate the GC heap, if necessary.
307        if module.env_module().needs_gc_heap {
308            store.ensure_gc_store(limiter.as_deref_mut()).await?;
309        }
310
311        // Register the module just before instantiation to ensure we keep the module
312        // properly referenced while in use by the store.
313        let (modules, engine, breakpoints) = store.modules_and_engine_and_breakpoints_mut();
314        let module_id = modules.register_module(module, engine, breakpoints)?;
315
316        // The first thing we do is issue an instance allocation request
317        // to the instance allocator. This, on success, will give us an
318        // instance handle.
319        //
320        // SAFETY: this module, by construction, was already validated within
321        // the store.
322        let id = unsafe {
323            store
324                .allocate_instance(
325                    limiter.as_deref_mut(),
326                    AllocateInstanceKind::Module(module_id),
327                    &ModuleRuntimeInfo::Module(module.clone()),
328                    imports,
329                )
330                .await?
331        };
332
333        let instance = Instance::from_wasmtime(id, store);
334
335        let needs_startup = instance.id.get_mut(store).needs_startup();
336
337        // At this point the instance is created and stored within the store,
338        // but it's also not quite usable just yet. Initialization hasn't
339        // completed (e.g. active data/element segments) and the `start`
340        // function additionally has not yet been invoked. That's the
341        // responsibility of the caller to handle, however.
342        Ok((instance, needs_startup))
343    }
344
345    pub(crate) fn from_wasmtime(id: InstanceId, store: &StoreOpaque) -> Instance {
346        Instance {
347            id: StoreInstanceId::new(store.id(), id),
348        }
349    }
350
351    pub(crate) fn start_raw<T>(
352        &self,
353        store: &mut StoreContextMut<'_, T>,
354        uncaught_exception: UncaughtException,
355    ) -> Result<()> {
356        // If a start function is present, invoke it. Make sure we use all the
357        // trap-handling configuration in `store` as well.
358        let store_id = store.0.id();
359        let (mut instance, registry) = self.id.get_mut_and_module_registry(store.0);
360        // SAFETY: the `store_id` is the id of the store that owns this
361        // instance and any function stored within the instance.
362        let f = unsafe {
363            instance
364                .as_mut()
365                .get_startup_func(registry, store_id)
366                .expect("should have a startup function")
367        };
368        let caller_vmctx = instance.vmctx();
369        unsafe {
370            let funcref = f.vm_func_ref(store.0);
371            super::func::invoke_wasm_and_catch_traps(
372                store,
373                uncaught_exception,
374                |_default_caller, vm| {
375                    VMFuncRef::array_call(funcref, vm, caller_vmctx, NonNull::from(&mut []))
376                },
377            )?;
378        }
379        Ok(())
380    }
381
382    /// Get this instance's module.
383    pub fn module<'a, T: 'static>(&self, store: impl Into<StoreContext<'a, T>>) -> &'a Module {
384        self._module(store.into().0)
385    }
386
387    pub(crate) fn _module<'a>(&self, store: &'a StoreOpaque) -> &'a Module {
388        store.module_for_instance(self.id).unwrap()
389    }
390
391    /// Returns the list of exported items from this [`Instance`].
392    ///
393    /// # Panics
394    ///
395    /// Panics if `store` does not own this instance, or if memory allocation
396    /// fails.
397    pub fn exports<'a, T: 'static>(
398        &'a self,
399        store: impl Into<StoreContextMut<'a, T>>,
400    ) -> impl ExactSizeIterator<Item = Export<'a>> + 'a {
401        let store = store.into().0;
402        let store_id = store.id();
403        let engine = store.engine().clone();
404
405        let (instance, registry) = store.instance_and_module_registry_mut(self.id());
406        let (module, mut instance) = instance.module_and_self();
407        module.exports.iter().map(move |(name, entity)| {
408            // SAFETY: the `store_id` owns this instance and all exports
409            // contained within.
410            let export = unsafe {
411                instance
412                    .as_mut()
413                    .get_export_by_index_mut(registry, store_id, *entity)
414            };
415
416            let ext = Extern::from_wasmtime_export(export, &engine);
417            Export::new(&module.strings[name], ext)
418        })
419    }
420
421    /// Looks up an exported [`Extern`] value by name.
422    ///
423    /// This method will search the module for an export named `name` and return
424    /// the value, if found.
425    ///
426    /// Returns `None` if there was no export named `name`.
427    ///
428    /// # Panics
429    ///
430    /// Panics if `store` does not own this instance.
431    ///
432    /// # Why does `get_export` take a mutable context?
433    ///
434    /// This method requires a mutable context because an instance's exports are
435    /// lazily populated, and we cache them as they are accessed. This makes
436    /// instantiating a module faster, but also means this method requires a
437    /// mutable context.
438    pub fn get_export(&self, mut store: impl AsContextMut, name: &str) -> Option<Extern> {
439        let store = store.as_context_mut().0;
440        let module = store[self.id].env_module();
441        let name = module.strings.get_atom(name)?;
442        let entity = *module.exports.get(&name)?;
443        Some(self._get_export(store, entity))
444    }
445
446    /// Looks up an exported [`Extern`] value by a [`ModuleExport`] value.
447    ///
448    /// This is similar to [`Instance::get_export`] but uses a [`ModuleExport`] value to avoid
449    /// string lookups where possible. [`ModuleExport`]s can be obtained by calling
450    /// [`Module::get_export_index`] on the [`Module`] that this instance was instantiated with.
451    ///
452    /// This method will search the module for an export with a matching entity index and return
453    /// the value, if found.
454    ///
455    /// Returns `None` if there was no export with a matching entity index.
456    ///
457    /// # Panics
458    ///
459    /// Panics if `store` does not own this instance.
460    pub fn get_module_export(
461        &self,
462        mut store: impl AsContextMut,
463        export: &ModuleExport,
464    ) -> Option<Extern> {
465        let store = store.as_context_mut().0;
466
467        // Verify the `ModuleExport` matches the module used in this instance.
468        if store.module_for_instance(self.id)?.id() != export.module {
469            return None;
470        }
471
472        Some(self._get_export(store, export.entity))
473    }
474
475    /// Like `get_export`, for an export other than a function, which needs
476    /// only shared access to the store: function exports are populated
477    /// lazily.
478    fn get_data_export(&self, store: &StoreOpaque, name: &str) -> Option<Extern> {
479        let module = store[self.id].env_module();
480        let name = module.strings.get_atom(name)?;
481        let entity = *module.exports.get(&name)?;
482        let export = store[self.id].get_export_by_index(store.id(), entity)?;
483        Some(Extern::from_wasmtime_export(export, store.engine()))
484    }
485
486    fn _get_export(&self, store: &mut StoreOpaque, entity: EntityIndex) -> Extern {
487        let id = store.id();
488        // SAFETY: the store `id` owns this instance and all exports contained
489        // within.
490        let export = unsafe {
491            let (instance, registry) = self.id.get_mut_and_module_registry(store);
492            instance.get_export_by_index_mut(registry, id, entity)
493        };
494        Extern::from_wasmtime_export(export, store.engine())
495    }
496
497    /// Looks up an exported [`Func`] value by name.
498    ///
499    /// Returns `None` if there was no export named `name`, or if there was but
500    /// it wasn't a function.
501    ///
502    /// # Panics
503    ///
504    /// Panics if `store` does not own this instance.
505    pub fn get_func(&self, store: impl AsContextMut, name: &str) -> Option<Func> {
506        self.get_export(store, name)?.into_func()
507    }
508
509    /// Looks up an exported [`Func`] value by name and with its type.
510    ///
511    /// This function is a convenience wrapper over [`Instance::get_func`] and
512    /// [`Func::typed`]. For more information see the linked documentation.
513    ///
514    /// Returns an error if `name` isn't a function export or if the export's
515    /// type did not match `Params` or `Results`
516    ///
517    /// # Panics
518    ///
519    /// Panics if `store` does not own this instance.
520    ///
521    /// # Errors
522    ///
523    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
524    /// memory allocation fails. See the `OutOfMemory` type's documentation for
525    /// details on Wasmtime's out-of-memory handling.
526    pub fn get_typed_func<Params, Results>(
527        &self,
528        mut store: impl AsContextMut,
529        name: &str,
530    ) -> Result<TypedFunc<Params, Results>>
531    where
532        Params: crate::WasmParams,
533        Results: crate::WasmResults,
534    {
535        let f = self
536            .get_export(store.as_context_mut(), name)
537            .and_then(|f| f.into_func())
538            .ok_or_else(|| format_err!("failed to find function export `{name}`"))?;
539        Ok(f.typed::<Params, Results>(store)
540            .with_context(|| format!("failed to convert function `{name}` to given type"))?)
541    }
542
543    /// Looks up an exported [`Table`] value by name.
544    ///
545    /// Returns `None` if there was no export named `name`, or if there was but
546    /// it wasn't a table.
547    ///
548    /// # Panics
549    ///
550    /// Panics if `store` does not own this instance.
551    pub fn get_table(&self, store: impl AsContext, name: &str) -> Option<Table> {
552        self.get_data_export(store.as_context().0, name)?
553            .into_table()
554    }
555
556    /// Looks up an exported [`Memory`] value by name.
557    ///
558    /// Returns `None` if there was no export named `name`, or if there was but
559    /// it wasn't a memory.
560    ///
561    /// # Panics
562    ///
563    /// Panics if `store` does not own this instance.
564    pub fn get_memory(&self, store: impl AsContext, name: &str) -> Option<Memory> {
565        self.get_data_export(store.as_context().0, name)?
566            .into_memory()
567    }
568
569    /// Looks up an exported [`SharedMemory`] value by name.
570    ///
571    /// Returns `None` if there was no export named `name`, or if there was but
572    /// it wasn't a shared memory.
573    ///
574    /// # Panics
575    ///
576    /// Panics if `store` does not own this instance.
577    pub fn get_shared_memory(&self, store: impl AsContext, name: &str) -> Option<SharedMemory> {
578        self.get_data_export(store.as_context().0, name)?
579            .into_shared_memory()
580    }
581
582    /// Looks up an exported [`Global`] value by name.
583    ///
584    /// Returns `None` if there was no export named `name`, or if there was but
585    /// it wasn't a global.
586    ///
587    /// # Panics
588    ///
589    /// Panics if `store` does not own this instance.
590    pub fn get_global(&self, store: impl AsContext, name: &str) -> Option<Global> {
591        self.get_data_export(store.as_context().0, name)?
592            .into_global()
593    }
594
595    /// Looks up a tag [`Tag`] by name.
596    ///
597    /// Returns `None` if there was no export named `name`, or if there was but
598    /// it wasn't a tag.
599    ///
600    /// # Panics
601    ///
602    /// Panics if `store` does not own this instance.
603    pub fn get_tag(&self, store: impl AsContext, name: &str) -> Option<Tag> {
604        self.get_data_export(store.as_context().0, name)?.into_tag()
605    }
606
607    #[allow(
608        dead_code,
609        reason = "c-api crate does not yet support exnrefs and causes this method to be dead."
610    )]
611    pub(crate) fn id(&self) -> InstanceId {
612        self.id.instance()
613    }
614
615    /// Return a unique-within-Store index for this `Instance`.
616    ///
617    /// Allows distinguishing instance identities when introspecting
618    /// the `Store`, e.g. via debug APIs.
619    ///
620    /// This index will match the instance's position in the sequence
621    /// returned by `Store::debug_all_instances()`.
622    #[cfg(feature = "debug")]
623    pub fn debug_index_in_store(&self) -> u32 {
624        self.id.instance().as_u32()
625    }
626
627    /// Get all globals within this instance.
628    ///
629    /// Returns both import and defined globals.
630    ///
631    /// Returns both exported and non-exported globals.
632    ///
633    /// Gives access to the full globals space.
634    #[cfg(feature = "coredump")]
635    pub(crate) fn all_globals<'a>(
636        &'a self,
637        store: &'a mut StoreOpaque,
638    ) -> impl ExactSizeIterator<Item = (GlobalIndex, Global)> + 'a {
639        let store_id = store.id();
640        store[self.id].all_globals(store_id)
641    }
642
643    /// Get all memories within this instance.
644    ///
645    /// Returns both import and defined memories.
646    ///
647    /// Returns both exported and non-exported memories.
648    ///
649    /// Gives access to the full memories space.
650    #[cfg(feature = "coredump")]
651    pub(crate) fn all_memories<'a>(
652        &'a self,
653        store: &'a StoreOpaque,
654    ) -> impl ExactSizeIterator<Item = (MemoryIndex, vm::ExportMemory)> + 'a {
655        let store_id = store.id();
656        store[self.id].all_memories(store_id)
657    }
658}
659
660pub(crate) struct OwnedImports {
661    functions: TryPrimaryMap<FuncIndex, VMFunctionImport>,
662    tables: TryPrimaryMap<TableIndex, VMTableImport>,
663    memories: TryPrimaryMap<MemoryIndex, VMMemoryImport>,
664    globals: TryPrimaryMap<GlobalIndex, VMGlobalImport>,
665    tags: TryPrimaryMap<TagIndex, VMTagImport>,
666}
667
668impl OwnedImports {
669    fn new(module: &Module) -> Result<OwnedImports, OutOfMemory> {
670        let mut ret = OwnedImports::empty();
671        ret.reserve(module)?;
672        Ok(ret)
673    }
674
675    pub(crate) fn empty() -> OwnedImports {
676        OwnedImports {
677            functions: TryPrimaryMap::new(),
678            tables: TryPrimaryMap::new(),
679            memories: TryPrimaryMap::new(),
680            globals: TryPrimaryMap::new(),
681            tags: TryPrimaryMap::new(),
682        }
683    }
684
685    pub(crate) fn reserve(&mut self, module: &Module) -> Result<(), OutOfMemory> {
686        let raw = module.compiled_module().module();
687        self.functions.reserve(raw.num_imported_funcs)?;
688        self.tables.reserve(raw.num_imported_tables)?;
689        self.memories.reserve(raw.num_imported_memories)?;
690        self.globals.reserve(raw.num_imported_globals)?;
691        self.tags.reserve(raw.num_imported_tags)?;
692        Ok(())
693    }
694
695    #[cfg(feature = "component-model")]
696    pub(crate) fn clear(&mut self) {
697        self.functions.clear();
698        self.tables.clear();
699        self.memories.clear();
700        self.globals.clear();
701        self.tags.clear();
702    }
703
704    fn push(&mut self, item: &Extern, store: &mut StoreOpaque) -> Result<(), OutOfMemory> {
705        match item {
706            Extern::Func(i) => {
707                self.functions.push(i.vmimport(store))?;
708            }
709            Extern::Global(i) => {
710                self.globals.push(i.vmimport(store))?;
711            }
712            Extern::Table(i) => {
713                self.tables.push(i.vmimport(store))?;
714            }
715            Extern::Memory(i) => {
716                self.memories.push(i.vmimport(store))?;
717            }
718            Extern::SharedMemory(i) => {
719                self.memories.push(i.vmimport(store))?;
720            }
721            Extern::Tag(i) => {
722                self.tags.push(i.vmimport(store))?;
723            }
724        }
725        Ok(())
726    }
727
728    /// Note that this is unsafe as the validity of `item` is not verified and
729    /// it contains a bunch of raw pointers.
730    #[cfg(feature = "component-model")]
731    pub(crate) fn push_export(
732        &mut self,
733        store: &StoreOpaque,
734        item: &crate::runtime::vm::Export,
735    ) -> Result<(), OutOfMemory> {
736        match item {
737            crate::runtime::vm::Export::Function(f) => {
738                self.functions.push(f.vmimport(store))?;
739            }
740            crate::runtime::vm::Export::Global(g) => {
741                self.globals.push(g.vmimport(store))?;
742            }
743            crate::runtime::vm::Export::Table(t) => {
744                self.tables.push(t.vmimport(store))?;
745            }
746            crate::runtime::vm::Export::Memory(m) => {
747                self.memories.push(m.vmimport(store))?;
748            }
749            crate::runtime::vm::Export::SharedMemory(_, vmimport) => {
750                self.memories.push(*vmimport)?;
751            }
752            crate::runtime::vm::Export::Tag(t) => {
753                self.tags.push(t.vmimport(store))?;
754            }
755        }
756        Ok(())
757    }
758
759    pub(crate) fn as_ref(&self) -> Imports<'_> {
760        Imports {
761            tables: self.tables.values().as_slice(),
762            globals: self.globals.values().as_slice(),
763            memories: self.memories.values().as_slice(),
764            functions: self.functions.values().as_slice(),
765            tags: self.tags.values().as_slice(),
766        }
767    }
768}
769
770/// An instance, pre-instantiation, that is ready to be instantiated.
771///
772/// This structure represents an instance *just before* it was instantiated,
773/// after all type-checking and imports have been resolved. The only thing left
774/// to do for this instance is to actually run the process of instantiation.
775///
776/// Note that an `InstancePre` may not be tied to any particular [`Store`] if
777/// none of the imports it closed over are tied to any particular [`Store`].
778///
779/// This structure is created through the [`Linker::instantiate_pre`] method,
780/// which also has some more information and examples.
781///
782/// [`Store`]: crate::Store
783/// [`Linker::instantiate_pre`]: crate::Linker::instantiate_pre
784pub struct InstancePre<T> {
785    module: Module,
786
787    /// The items which this `InstancePre` use to instantiate the `module`
788    /// provided, passed to `Instance::new_started` after inserting them into a
789    /// `Store`.
790    ///
791    /// Note that this is stored as an `Arc` to quickly move a strong reference
792    /// to everything internally into a `Store<T>` without having to clone each
793    /// individual item.
794    items: Arc<TryVec<Definition>>,
795
796    /// A count of `Definition::HostFunc` entries in `items` above to
797    /// preallocate space in a `Store` up front for all entries to be inserted.
798    host_funcs: usize,
799
800    /// The `VMFuncRef`s for the functions in `items` that do not
801    /// have a `wasm_call` trampoline. We pre-allocate and pre-patch these
802    /// `VMFuncRef`s so that we don't have to do it at
803    /// instantiation time.
804    ///
805    /// This is an `Arc` for the same reason as `items`.
806    func_refs: Arc<TryVec<VMFuncRef>>,
807
808    /// Whether or not any import in `items` is flagged as needing async.
809    ///
810    /// This is used to update stores during instantiation as to whether they
811    /// require async entrypoints.
812    asyncness: Asyncness,
813
814    _marker: core::marker::PhantomData<fn() -> T>,
815}
816
817/// InstancePre's clone does not require T: Clone
818impl<T> Clone for InstancePre<T> {
819    fn clone(&self) -> Self {
820        Self {
821            module: self.module.clone(),
822            items: self.items.clone(),
823            host_funcs: self.host_funcs,
824            func_refs: self.func_refs.clone(),
825            asyncness: self.asyncness,
826            _marker: self._marker,
827        }
828    }
829}
830
831impl<T: 'static> InstancePre<T> {
832    /// Creates a new `InstancePre` which type-checks the `items` provided and
833    /// on success is ready to instantiate a new instance.
834    ///
835    /// `engine` is the engine that `items` belong to, and this returns an error
836    /// if that is not also `module`'s engine. This also returns an error if an
837    /// individual item within `items` reports an engine of its own that is not
838    /// `engine`, which happens when that item was taken from a store belonging
839    /// to a different engine than the linker it was defined in.
840    ///
841    /// # Unsafety
842    ///
843    /// This method is unsafe as the `T` of the `InstancePre<T>` is not
844    /// guaranteed to be the same as the `T` within the `Store`, the caller must
845    /// verify that.
846    pub(crate) unsafe fn new(
847        engine: &Engine,
848        module: &Module,
849        items: TryVec<Definition>,
850    ) -> Result<InstancePre<T>> {
851        typecheck(engine, module, &items, |cx, ty, item| {
852            cx.definition(ty, &item.ty())
853        })?;
854
855        let mut func_refs = TryVec::with_capacity(items.len())?;
856        let mut host_funcs = 0;
857        let mut asyncness = Asyncness::No;
858        for item in &items {
859            match item {
860                Definition::Extern { .. } => {}
861                Definition::HostFunc(f) => {
862                    host_funcs += 1;
863                    if f.func_ref().wasm_call.is_none() {
864                        func_refs.push(VMFuncRef {
865                            wasm_call: module
866                                .wasm_to_array_trampoline(f.sig_index())
867                                .map(|f| f.into()),
868                            ..*f.func_ref()
869                        })?;
870                    }
871                    asyncness = asyncness | f.asyncness();
872                }
873            }
874        }
875
876        Ok(InstancePre {
877            module: module.clone(),
878            items: try_new::<Arc<_>>(items)?,
879            host_funcs,
880            func_refs: try_new::<Arc<_>>(func_refs)?,
881            asyncness,
882            _marker: core::marker::PhantomData,
883        })
884    }
885
886    /// Returns a reference to the module that this [`InstancePre`] will be
887    /// instantiating.
888    pub fn module(&self) -> &Module {
889        &self.module
890    }
891
892    /// Instantiates this instance, creating a new instance within the provided
893    /// `store`.
894    ///
895    /// This function will run the actual process of instantiation to
896    /// completion. This will use all of the previously-closed-over items as
897    /// imports to instantiate the module that this was originally created with.
898    ///
899    /// For more information about instantiation see [`Instance::new`].
900    ///
901    /// # Panics
902    ///
903    /// Panics if any import closed over by this [`InstancePre`] isn't owned by
904    /// `store`, or if `store` has async support enabled. Additionally this
905    /// function will panic if the `store` provided comes from a different
906    /// [`Engine`] than the [`InstancePre`] originally came from.
907    ///
908    /// # Errors
909    ///
910    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
911    /// memory allocation fails. See the `OutOfMemory` type's documentation for
912    /// details on Wasmtime's out-of-memory handling.
913    pub fn instantiate(&self, mut store: impl AsContextMut<Data = T>) -> Result<Instance> {
914        let mut store = store.as_context_mut();
915        let imports = pre_instantiate_raw(
916            &mut store.0,
917            &self.module,
918            &self.items,
919            self.host_funcs,
920            &self.func_refs,
921            self.asyncness,
922        )?;
923
924        // Note that this is specifically done after `pre_instantiate_raw` to
925        // handle the case that if any imports in this `InstancePre` require
926        // async that it's flagged in the store by that point which will reject
927        // this instantiation to say "use `instantiate_async` instead".
928        store.0.validate_sync_call()?;
929
930        // This unsafety should be handled by the type-checking performed by the
931        // constructor of `InstancePre` to assert that all the imports we're passing
932        // in match the module we're instantiating.
933        vm::assert_ready(unsafe {
934            Instance::new_started(&mut store, &self.module, imports.as_ref(), Asyncness::No)
935        })
936    }
937
938    /// Creates a new instance, running the start function asynchronously
939    /// instead of inline.
940    ///
941    /// For more information about asynchronous instantiation see the
942    /// documentation on [`Instance::new_async`].
943    ///
944    /// # Panics
945    ///
946    /// Panics if any import closed over by this [`InstancePre`] isn't owned by
947    /// `store`, or if `store` does not have async support enabled.
948    ///
949    /// # Errors
950    ///
951    /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when
952    /// memory allocation fails. See the `OutOfMemory` type's documentation for
953    /// details on Wasmtime's out-of-memory handling.
954    #[cfg(feature = "async")]
955    pub async fn instantiate_async(
956        &self,
957        mut store: impl AsContextMut<Data = T>,
958    ) -> Result<Instance> {
959        let mut store = store.as_context_mut();
960        let imports = pre_instantiate_raw(
961            &mut store.0,
962            &self.module,
963            &self.items,
964            self.host_funcs,
965            &self.func_refs,
966            self.asyncness,
967        )?;
968
969        // This unsafety should be handled by the type-checking performed by the
970        // constructor of `InstancePre` to assert that all the imports we're passing
971        // in match the module we're instantiating.
972        unsafe {
973            Instance::new_started(&mut store, &self.module, imports.as_ref(), Asyncness::Yes).await
974        }
975    }
976}
977
978/// Helper function shared between
979/// `InstancePre::{instantiate,instantiate_async}`
980///
981/// This is an out-of-line function to avoid the generic on `InstancePre` and
982/// get this compiled into the `wasmtime` crate to avoid having it monomorphized
983/// elsewhere.
984fn pre_instantiate_raw(
985    store: &mut StoreOpaque,
986    module: &Module,
987    items: &Arc<TryVec<Definition>>,
988    host_funcs: usize,
989    func_refs: &Arc<TryVec<VMFuncRef>>,
990    asyncness: Asyncness,
991) -> Result<OwnedImports> {
992    // Register this module and use it to fill out any funcref wasm_call holes
993    // we can. For more comments on this see `typecheck_externs`.
994    let (modules, engine, breakpoints) = store.modules_and_engine_and_breakpoints_mut();
995    modules.register_module(module, engine, breakpoints)?;
996    let (funcrefs, modules) = store.func_refs_and_modules();
997    funcrefs.fill(modules);
998
999    if host_funcs > 0 {
1000        // Any linker-defined function of the `Definition::HostFunc` variant
1001        // will insert a function into the store automatically as part of
1002        // instantiation, so reserve space here to make insertion more efficient
1003        // as it won't have to realloc during the instantiation.
1004        funcrefs.reserve_storage(host_funcs)?;
1005
1006        // The usage of `to_extern_store_rooted` requires that the items are
1007        // rooted via another means, which happens here by cloning the list of
1008        // items into the store once. This avoids cloning each individual item
1009        // below.
1010        funcrefs.push_instance_pre_definitions(items.clone())?;
1011        funcrefs.push_instance_pre_func_refs(func_refs.clone())?;
1012    }
1013
1014    store.set_async_required(asyncness);
1015
1016    let mut func_refs = func_refs.iter().map(|f| NonNull::from(f));
1017    let mut imports = OwnedImports::new(module)?;
1018    for import in items.iter() {
1019        if !import.comes_from_same_store(store) {
1020            bail!("cross-`Store` instantiation is not currently supported");
1021        }
1022        // This unsafety should be encapsulated in the constructor of
1023        // `InstancePre` where the `T` of the original item should match the
1024        // `T` of the store. Additionally the rooting necessary has happened
1025        // above.
1026        let item = match import {
1027            Definition::Extern { item, .. } => item.clone(),
1028            Definition::HostFunc(func) => unsafe {
1029                func.to_func_store_rooted(
1030                    store,
1031                    if func.func_ref().wasm_call.is_none() {
1032                        Some(func_refs.next().unwrap())
1033                    } else {
1034                        None
1035                    },
1036                )
1037                .into()
1038            },
1039        };
1040        imports.push(&item, store)?;
1041    }
1042
1043    Ok(imports)
1044}
1045
1046/// An item that can be supplied as an import argument during instantiation.
1047///
1048/// # Safety
1049///
1050/// Implementations must return an associated engine if they own a handle to
1051/// one. Failure to do so may allow cross-`Engine` type confusion.
1052///
1053/// (Items that are just identifiers indexing into a store, for example
1054/// `Extern::Global(wasmtime::Global)`, do not have their own handle to an
1055/// engine. Their engine is the engine of the store they belong to, and it is
1056/// the store, not them, that holds an owning handle to the engine.)
1057unsafe trait ImportArg {
1058    fn engine(&self) -> Option<&Engine>;
1059}
1060
1061// SAFETY: `Extern::SharedMemory` is the only variant with an `Engine` handle.
1062unsafe impl ImportArg for Extern {
1063    fn engine(&self) -> Option<&Engine> {
1064        match self {
1065            Extern::SharedMemory(m) => Some(m.engine()),
1066            Extern::Func(_)
1067            | Extern::Global(_)
1068            | Extern::Table(_)
1069            | Extern::Memory(_)
1070            | Extern::Tag(_) => None,
1071        }
1072    }
1073}
1074
1075// SAFETY: `Definition::engine` is complete.
1076unsafe impl ImportArg for Definition {
1077    fn engine(&self) -> Option<&Engine> {
1078        Some(Definition::engine(self))
1079    }
1080}
1081
1082/// Type check the `import_args` against the imports that `module` declares.
1083///
1084/// `engine` is the engine that the `import_args` belong to. It must be the same
1085/// engine as `module`'s: entity types are compared by `VMSharedTypeIndex`, which
1086/// only means anything within the engine that assigned it, so checking one
1087/// engine's items against another engine's module would compare unrelated types
1088/// and consider them equal.
1089fn typecheck<I>(
1090    engine: &Engine,
1091    module: &Module,
1092    import_args: &[I],
1093    check: impl Fn(&matching::MatchCx<'_>, &EntityType, &I) -> Result<()>,
1094) -> Result<()>
1095where
1096    I: ImportArg,
1097{
1098    ensure!(
1099        Engine::same(engine, module.engine()),
1100        "cross-`Engine` instantiation is not currently supported"
1101    );
1102    let env_module = module.compiled_module().module();
1103    let expected_len = env_module.imports().count();
1104    let actual_len = import_args.len();
1105    if expected_len != actual_len {
1106        bail!("expected {expected_len} imports, found {actual_len}");
1107    }
1108    let cx = matching::MatchCx::new(module.engine());
1109    for ((name, field, expected_ty), actual) in env_module.imports().zip(import_args) {
1110        debug_assert!(expected_ty.is_canonicalized_for_runtime_usage());
1111        if let Some(actual_engine) = actual.engine() {
1112            ensure!(
1113                Engine::same(actual_engine, engine),
1114                "cross-`Engine` instantiation is not currently supported: \
1115                 the item provided for `{name}::{field}` belongs to a \
1116                 different engine than the module being instantiated"
1117            );
1118        }
1119        check(&cx, &expected_ty, actual)
1120            .with_context(|| format!("incompatible import type for `{name}::{field}`"))?;
1121    }
1122    Ok(())
1123}