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