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}