wasmtime/runtime/component/component.rs
1use crate::component::InstanceExportLookup;
2use crate::component::matching::InstanceType;
3use crate::component::types;
4use crate::prelude::*;
5#[cfg(feature = "std")]
6use crate::runtime::vm::open_file_for_mmap;
7use crate::runtime::vm::{CompiledModuleId, VMArrayCallFunction, VMFuncRef, VMWasmCallFunction};
8use crate::{
9 Engine, Module, ResourcesRequired, code::CodeObject, code_memory::CodeMemory,
10 type_registry::TypeCollection,
11};
12use crate::{FuncType, ValType};
13use alloc::sync::Arc;
14use core::ops::Range;
15use core::ptr::NonNull;
16#[cfg(feature = "std")]
17use std::path::Path;
18use wasmtime_environ::component::{
19 CompiledComponentInfo, ComponentArtifacts, ComponentTypes, CoreDef, Export, ExportIndex,
20 GlobalInitializer, InstantiateModule, NameMapNoIntern, OptionsIndex, StaticModuleIndex,
21 TrampolineIndex, TypeComponentIndex, TypeFuncIndex, VMComponentOffsets,
22};
23use wasmtime_environ::{Abi, CompiledFunctionsTable, FuncKey, TypeTrace};
24use wasmtime_environ::{FunctionLoc, HostPtr, ObjectKind, PrimaryMap};
25
26/// A compiled WebAssembly Component.
27///
28/// This structure represents a compiled component that is ready to be
29/// instantiated. This owns a region of virtual memory which contains executable
30/// code compiled from a WebAssembly binary originally. This is the analog of
31/// [`Module`](crate::Module) in the component embedding API.
32///
33/// A [`Component`] can be turned into an
34/// [`Instance`](crate::component::Instance) through a
35/// [`Linker`](crate::component::Linker). [`Component`]s are safe to share
36/// across threads. The compilation model of a component is the same as that of
37/// [a module](crate::Module) which is to say:
38///
39/// * Compilation happens synchronously during [`Component::new`].
40/// * The result of compilation can be saved into storage with
41/// [`Component::serialize`].
42/// * A previously compiled artifact can be parsed with
43/// [`Component::deserialize`].
44/// * No compilation happens at runtime for a component — everything is done
45/// by the time [`Component::new`] returns.
46///
47/// ## Components and `Clone`
48///
49/// Using `clone` on a `Component` is a cheap operation. It will not create an
50/// entirely new component, but rather just a new reference to the existing
51/// component. In other words it's a shallow copy, not a deep copy.
52///
53/// ## Examples
54///
55/// For example usage see the documentation of [`Module`](crate::Module) as
56/// [`Component`] has the same high-level API.
57#[derive(Clone)]
58pub struct Component {
59 inner: Arc<ComponentInner>,
60}
61
62struct ComponentInner {
63 /// Unique id for this component within this process.
64 ///
65 /// Note that this is repurposing ids for modules intentionally as there
66 /// shouldn't be an issue overlapping them.
67 id: CompiledModuleId,
68
69 /// The engine that this component belongs to.
70 engine: Engine,
71
72 /// Component type index
73 ty: TypeComponentIndex,
74
75 /// Core wasm modules that the component defined internally, indexed by the
76 /// compile-time-assigned `ModuleUpvarIndex`.
77 static_modules: PrimaryMap<StaticModuleIndex, Module>,
78
79 /// Code-related information such as the compiled artifact, type
80 /// information, etc.
81 ///
82 /// Note that the `Arc` here is used to share this allocation with internal
83 /// modules.
84 code: Arc<CodeObject>,
85
86 /// Metadata produced during compilation.
87 info: CompiledComponentInfo,
88
89 /// The index of compiled functions and their locations in the text section
90 /// for this component.
91 index: Arc<CompiledFunctionsTable>,
92
93 /// A cached handle to the `wasmtime::FuncType` for the canonical ABI's
94 /// `realloc`, to avoid the need to look up types in the registry and take
95 /// locks when calling `realloc` via `TypedFunc::call_raw`.
96 realloc_func_type: Arc<FuncType>,
97}
98
99pub(crate) struct AllCallFuncPointers {
100 pub wasm_call: NonNull<VMWasmCallFunction>,
101 pub array_call: NonNull<VMArrayCallFunction>,
102}
103
104impl Component {
105 /// Compiles a new WebAssembly component from the in-memory list of bytes
106 /// provided.
107 ///
108 /// The `bytes` provided can either be the binary or text format of a
109 /// [WebAssembly component]. Note that the text format requires the `wat`
110 /// feature of this crate to be enabled. This API does not support
111 /// streaming compilation.
112 ///
113 /// This function will synchronously validate the entire component,
114 /// including all core modules, and then compile all components, modules,
115 /// etc., found within the provided bytes.
116 ///
117 /// [WebAssembly component]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Binary.md
118 ///
119 /// # Errors
120 ///
121 /// This function may fail and return an error. Errors may include
122 /// situations such as:
123 ///
124 /// * The binary provided could not be decoded because it's not a valid
125 /// WebAssembly binary
126 /// * The WebAssembly binary may not validate (e.g. contains type errors)
127 /// * Implementation-specific limits were exceeded with a valid binary (for
128 /// example too many locals)
129 /// * The wasm binary may use features that are not enabled in the
130 /// configuration of `engine`
131 /// * If the `wat` feature is enabled and the input is text, then it may be
132 /// rejected if it fails to parse.
133 ///
134 /// The error returned should contain full information about why compilation
135 /// failed.
136 ///
137 /// # Examples
138 ///
139 /// The `new` function can be invoked with a in-memory array of bytes:
140 ///
141 /// ```no_run
142 /// # use wasmtime::*;
143 /// # use wasmtime::component::Component;
144 /// # fn main() -> anyhow::Result<()> {
145 /// # let engine = Engine::default();
146 /// # let wasm_bytes: Vec<u8> = Vec::new();
147 /// let component = Component::new(&engine, &wasm_bytes)?;
148 /// # Ok(())
149 /// # }
150 /// ```
151 ///
152 /// Or you can also pass in a string to be parsed as the wasm text
153 /// format:
154 ///
155 /// ```
156 /// # use wasmtime::*;
157 /// # use wasmtime::component::Component;
158 /// # fn main() -> anyhow::Result<()> {
159 /// # let engine = Engine::default();
160 /// let component = Component::new(&engine, "(component (core module))")?;
161 /// # Ok(())
162 /// # }
163 #[cfg(any(feature = "cranelift", feature = "winch"))]
164 pub fn new(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Component> {
165 crate::CodeBuilder::new(engine)
166 .wasm_binary_or_text(bytes.as_ref(), None)?
167 .compile_component()
168 }
169
170 /// Compiles a new WebAssembly component from a wasm file on disk pointed
171 /// to by `file`.
172 ///
173 /// This is a convenience function for reading the contents of `file` on
174 /// disk and then calling [`Component::new`].
175 #[cfg(all(feature = "std", any(feature = "cranelift", feature = "winch")))]
176 pub fn from_file(engine: &Engine, file: impl AsRef<Path>) -> Result<Component> {
177 crate::CodeBuilder::new(engine)
178 .wasm_binary_or_text_file(file.as_ref())?
179 .compile_component()
180 }
181
182 /// Compiles a new WebAssembly component from the in-memory wasm image
183 /// provided.
184 ///
185 /// This function is the same as [`Component::new`] except that it does not
186 /// accept the text format of WebAssembly. Even if the `wat` feature
187 /// is enabled an error will be returned here if `binary` is the text
188 /// format.
189 ///
190 /// For more information on semantics and errors see [`Component::new`].
191 #[cfg(any(feature = "cranelift", feature = "winch"))]
192 pub fn from_binary(engine: &Engine, binary: &[u8]) -> Result<Component> {
193 crate::CodeBuilder::new(engine)
194 .wasm_binary(binary, None)?
195 .compile_component()
196 }
197
198 /// Same as [`Module::deserialize`], but for components.
199 ///
200 /// Note that the bytes referenced here must contain contents previously
201 /// produced by [`Engine::precompile_component`] or
202 /// [`Component::serialize`].
203 ///
204 /// For more information see the [`Module::deserialize`] method.
205 ///
206 /// # Unsafety
207 ///
208 /// The unsafety of this method is the same as that of the
209 /// [`Module::deserialize`] method.
210 ///
211 /// [`Module::deserialize`]: crate::Module::deserialize
212 pub unsafe fn deserialize(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Component> {
213 let code = engine.load_code_bytes(bytes.as_ref(), ObjectKind::Component)?;
214 Component::from_parts(engine, code, None)
215 }
216
217 /// Same as [`Module::deserialize_raw`], but for components.
218 ///
219 /// See [`Component::deserialize`] for additional information; this method
220 /// works identically except that it will not create a copy of the provided
221 /// memory but will use it directly.
222 ///
223 /// # Unsafety
224 ///
225 /// All of the safety notes from [`Component::deserialize`] apply here as well
226 /// with the additional constraint that the code memory provide by `memory`
227 /// lives for as long as the module and is nevery externally modified for
228 /// the lifetime of the deserialized module.
229 pub unsafe fn deserialize_raw(engine: &Engine, memory: NonNull<[u8]>) -> Result<Component> {
230 // SAFETY: the contract required by `load_code_raw` is the same as this
231 // function.
232 let code = unsafe { engine.load_code_raw(memory, ObjectKind::Component)? };
233 Component::from_parts(engine, code, None)
234 }
235
236 /// Same as [`Module::deserialize_file`], but for components.
237 ///
238 /// Note that the file referenced here must contain contents previously
239 /// produced by [`Engine::precompile_component`] or
240 /// [`Component::serialize`].
241 ///
242 /// For more information see the [`Module::deserialize_file`] method.
243 ///
244 /// # Unsafety
245 ///
246 /// The unsafety of this method is the same as that of the
247 /// [`Module::deserialize_file`] method.
248 ///
249 /// [`Module::deserialize_file`]: crate::Module::deserialize_file
250 #[cfg(feature = "std")]
251 pub unsafe fn deserialize_file(engine: &Engine, path: impl AsRef<Path>) -> Result<Component> {
252 let file = open_file_for_mmap(path.as_ref())?;
253 let code = engine
254 .load_code_file(file, ObjectKind::Component)
255 .with_context(|| format!("failed to load code for: {}", path.as_ref().display()))?;
256 Component::from_parts(engine, code, None)
257 }
258
259 /// Returns the type of this component as a [`types::Component`].
260 ///
261 /// This method enables runtime introspection of the type of a component
262 /// before instantiation, if necessary.
263 ///
264 /// ## Component types and Resources
265 ///
266 /// An important point to note here is that the precise type of imports and
267 /// exports of a component change when it is instantiated with respect to
268 /// resources. For example a [`Component`] represents an un-instantiated
269 /// component meaning that its imported resources are represented as abstract
270 /// resource types. These abstract types are not equal to any other
271 /// component's types.
272 ///
273 /// For example:
274 ///
275 /// ```
276 /// # use wasmtime::Engine;
277 /// # use wasmtime::component::Component;
278 /// # use wasmtime::component::types::ComponentItem;
279 /// # fn main() -> wasmtime::Result<()> {
280 /// # let engine = Engine::default();
281 /// let a = Component::new(&engine, r#"
282 /// (component (import "x" (type (sub resource))))
283 /// "#)?;
284 /// let b = Component::new(&engine, r#"
285 /// (component (import "x" (type (sub resource))))
286 /// "#)?;
287 ///
288 /// let (_, a_ty) = a.component_type().imports(&engine).next().unwrap();
289 /// let (_, b_ty) = b.component_type().imports(&engine).next().unwrap();
290 ///
291 /// let a_ty = match a_ty {
292 /// ComponentItem::Resource(ty) => ty,
293 /// _ => unreachable!(),
294 /// };
295 /// let b_ty = match b_ty {
296 /// ComponentItem::Resource(ty) => ty,
297 /// _ => unreachable!(),
298 /// };
299 /// assert!(a_ty != b_ty);
300 /// # Ok(())
301 /// # }
302 /// ```
303 ///
304 /// Additionally, however, these abstract types are "substituted" during
305 /// instantiation meaning that a component type will appear to have changed
306 /// once it is instantiated.
307 ///
308 /// ```
309 /// # use wasmtime::{Engine, Store};
310 /// # use wasmtime::component::{Component, Linker, ResourceType};
311 /// # use wasmtime::component::types::ComponentItem;
312 /// # fn main() -> wasmtime::Result<()> {
313 /// # let engine = Engine::default();
314 /// // Here this component imports a resource and then exports it as-is
315 /// // which means that the export is equal to the import.
316 /// let a = Component::new(&engine, r#"
317 /// (component
318 /// (import "x" (type $x (sub resource)))
319 /// (export "x" (type $x))
320 /// )
321 /// "#)?;
322 ///
323 /// let (_, import) = a.component_type().imports(&engine).next().unwrap();
324 /// let (_, export) = a.component_type().exports(&engine).next().unwrap();
325 ///
326 /// let import = match import {
327 /// ComponentItem::Resource(ty) => ty,
328 /// _ => unreachable!(),
329 /// };
330 /// let export = match export {
331 /// ComponentItem::Resource(ty) => ty,
332 /// _ => unreachable!(),
333 /// };
334 /// assert_eq!(import, export);
335 ///
336 /// // However after instantiation the resource type "changes"
337 /// let mut store = Store::new(&engine, ());
338 /// let mut linker = Linker::new(&engine);
339 /// linker.root().resource("x", ResourceType::host::<()>(), |_, _| Ok(()))?;
340 /// let instance = linker.instantiate(&mut store, &a)?;
341 /// let instance_ty = instance.get_resource(&mut store, "x").unwrap();
342 ///
343 /// // Here `instance_ty` is not the same as either `import` or `export`,
344 /// // but it is equal to what we provided as an import.
345 /// assert!(instance_ty != import);
346 /// assert!(instance_ty != export);
347 /// assert!(instance_ty == ResourceType::host::<()>());
348 /// # Ok(())
349 /// # }
350 /// ```
351 ///
352 /// Finally, each instantiation of an exported resource from a component is
353 /// considered "fresh" for all instantiations meaning that different
354 /// instantiations will have different exported resource types:
355 ///
356 /// ```
357 /// # use wasmtime::{Engine, Store};
358 /// # use wasmtime::component::{Component, Linker};
359 /// # fn main() -> wasmtime::Result<()> {
360 /// # let engine = Engine::default();
361 /// let a = Component::new(&engine, r#"
362 /// (component
363 /// (type $x (resource (rep i32)))
364 /// (export "x" (type $x))
365 /// )
366 /// "#)?;
367 ///
368 /// let mut store = Store::new(&engine, ());
369 /// let linker = Linker::new(&engine);
370 /// let instance1 = linker.instantiate(&mut store, &a)?;
371 /// let instance2 = linker.instantiate(&mut store, &a)?;
372 ///
373 /// let x1 = instance1.get_resource(&mut store, "x").unwrap();
374 /// let x2 = instance2.get_resource(&mut store, "x").unwrap();
375 ///
376 /// // Despite these two resources being the same export of the same
377 /// // component they come from two different instances meaning that their
378 /// // types will be unique.
379 /// assert!(x1 != x2);
380 /// # Ok(())
381 /// # }
382 /// ```
383 pub fn component_type(&self) -> types::Component {
384 self.with_uninstantiated_instance_type(|ty| types::Component::from(self.inner.ty, ty))
385 }
386
387 fn with_uninstantiated_instance_type<R>(&self, f: impl FnOnce(&InstanceType<'_>) -> R) -> R {
388 let resources = Arc::new(PrimaryMap::new());
389 f(&InstanceType {
390 types: self.types(),
391 resources: &resources,
392 })
393 }
394
395 /// Final assembly step for a component from its in-memory representation.
396 ///
397 /// If the `artifacts` are specified as `None` here then they will be
398 /// deserialized from `code_memory`.
399 pub(crate) fn from_parts(
400 engine: &Engine,
401 code_memory: Arc<CodeMemory>,
402 artifacts: Option<ComponentArtifacts>,
403 ) -> Result<Component> {
404 let ComponentArtifacts {
405 ty,
406 info,
407 table: index,
408 mut types,
409 mut static_modules,
410 } = match artifacts {
411 Some(artifacts) => artifacts,
412 None => postcard::from_bytes(code_memory.wasmtime_info())?,
413 };
414 let index = Arc::new(index);
415
416 // Validate that the component can be used with the current instance
417 // allocator.
418 engine.allocator().validate_component(
419 &info.component,
420 &VMComponentOffsets::new(HostPtr, &info.component),
421 &|module_index| &static_modules[module_index].module,
422 )?;
423
424 // Create a signature registration with the `Engine` for all trampolines
425 // and core wasm types found within this component, both for the
426 // component and for all included core wasm modules.
427 let signatures = engine.register_and_canonicalize_types(
428 types.module_types_mut(),
429 static_modules.iter_mut().map(|(_, m)| &mut m.module),
430 );
431 types.canonicalize_for_runtime_usage(&mut |idx| signatures.shared_type(idx).unwrap());
432
433 // Assemble the `CodeObject` artifact which is shared by all core wasm
434 // modules as well as the final component.
435 let types = Arc::new(types);
436 let code = Arc::new(CodeObject::new(code_memory, signatures, types.into()));
437
438 // Convert all information about static core wasm modules into actual
439 // `Module` instances by converting each `CompiledModuleInfo`, the
440 // `types` type information, and the code memory to a runtime object.
441 let static_modules = static_modules
442 .into_iter()
443 .map(|(_, info)| {
444 Module::from_parts_raw(engine, code.clone(), info, index.clone(), false)
445 })
446 .collect::<Result<_>>()?;
447
448 let realloc_func_type = Arc::new(FuncType::new(
449 engine,
450 [ValType::I32, ValType::I32, ValType::I32, ValType::I32],
451 [ValType::I32],
452 ));
453
454 Ok(Component {
455 inner: Arc::new(ComponentInner {
456 id: CompiledModuleId::new(),
457 engine: engine.clone(),
458 ty,
459 static_modules,
460 code,
461 info,
462 index,
463 realloc_func_type,
464 }),
465 })
466 }
467
468 pub(crate) fn ty(&self) -> TypeComponentIndex {
469 self.inner.ty
470 }
471
472 pub(crate) fn env_component(&self) -> &wasmtime_environ::component::Component {
473 &self.inner.info.component
474 }
475
476 pub(crate) fn static_module(&self, idx: StaticModuleIndex) -> &Module {
477 &self.inner.static_modules[idx]
478 }
479
480 #[cfg(feature = "profiling")]
481 pub(crate) fn static_modules(&self) -> impl Iterator<Item = &Module> {
482 self.inner.static_modules.values()
483 }
484
485 #[inline]
486 pub(crate) fn types(&self) -> &Arc<ComponentTypes> {
487 match self.inner.code.types() {
488 crate::code::Types::Component(types) => types,
489 // The only creator of a `Component` is itself which uses the other
490 // variant, so this shouldn't be possible.
491 crate::code::Types::Module(_) => unreachable!(),
492 }
493 }
494
495 pub(crate) fn signatures(&self) -> &TypeCollection {
496 self.inner.code.signatures()
497 }
498
499 pub(crate) fn text(&self) -> &[u8] {
500 self.inner.code.code_memory().text()
501 }
502
503 pub(crate) fn trampoline_ptrs(&self, index: TrampolineIndex) -> AllCallFuncPointers {
504 let wasm_call = self
505 .inner
506 .index
507 .func_loc(FuncKey::ComponentTrampoline(Abi::Wasm, index))
508 .unwrap();
509 let array_call = self
510 .inner
511 .index
512 .func_loc(FuncKey::ComponentTrampoline(Abi::Array, index))
513 .unwrap();
514 AllCallFuncPointers {
515 wasm_call: self.func(wasm_call).cast(),
516 array_call: self.func(array_call).cast(),
517 }
518 }
519
520 fn func(&self, loc: &FunctionLoc) -> NonNull<u8> {
521 let text = self.text();
522 let trampoline = &text[loc.start as usize..][..loc.length as usize];
523 NonNull::from(trampoline).cast()
524 }
525
526 pub(crate) fn code_object(&self) -> &Arc<CodeObject> {
527 &self.inner.code
528 }
529
530 /// Same as [`Module::serialize`], except for a component.
531 ///
532 /// Note that the artifact produced here must be passed to
533 /// [`Component::deserialize`] and is not compatible for use with
534 /// [`Module`].
535 ///
536 /// [`Module::serialize`]: crate::Module::serialize
537 /// [`Module`]: crate::Module
538 pub fn serialize(&self) -> Result<Vec<u8>> {
539 Ok(self.code_object().code_memory().mmap().to_vec())
540 }
541
542 /// Creates a new `VMFuncRef` with all fields filled out for the destructor
543 /// specified.
544 ///
545 /// The `dtor`'s own `VMFuncRef` won't have `wasm_call` filled out but this
546 /// component may have `resource_drop_wasm_to_native_trampoline` filled out
547 /// if necessary in which case it's filled in here.
548 pub(crate) fn resource_drop_func_ref(&self, dtor: &crate::func::HostFunc) -> VMFuncRef {
549 // Host functions never have their `wasm_call` filled in at this time.
550 assert!(dtor.func_ref().wasm_call.is_none());
551
552 // Note that if `resource_drop_wasm_to_native_trampoline` is not present
553 // then this can't be called by the component, so it's ok to leave it
554 // blank.
555 let wasm_call = self
556 .inner
557 .index
558 .func_loc(FuncKey::ResourceDropTrampoline)
559 .map(|loc| self.func(loc).cast().into());
560
561 VMFuncRef {
562 wasm_call,
563 ..*dtor.func_ref()
564 }
565 }
566
567 /// Returns a summary of the resources required to instantiate this
568 /// [`Component`][crate::component::Component].
569 ///
570 /// Note that when a component imports and instantiates another component or
571 /// core module, we cannot determine ahead of time how many resources
572 /// instantiating this component will require, and therefore this method
573 /// will return `None` in these scenarios.
574 ///
575 /// Potential uses of the returned information:
576 ///
577 /// * Determining whether your pooling allocator configuration supports
578 /// instantiating this component.
579 ///
580 /// * Deciding how many of which `Component` you want to instantiate within
581 /// a fixed amount of resources, e.g. determining whether to create 5
582 /// instances of component X or 10 instances of component Y.
583 ///
584 /// # Example
585 ///
586 /// ```
587 /// # fn main() -> wasmtime::Result<()> {
588 /// use wasmtime::{Config, Engine, component::Component};
589 ///
590 /// let mut config = Config::new();
591 /// config.wasm_multi_memory(true);
592 /// config.wasm_component_model(true);
593 /// let engine = Engine::new(&config)?;
594 ///
595 /// let component = Component::new(&engine, &r#"
596 /// (component
597 /// ;; Define a core module that uses two memories.
598 /// (core module $m
599 /// (memory 1)
600 /// (memory 6)
601 /// )
602 ///
603 /// ;; Instantiate that core module three times.
604 /// (core instance $i1 (instantiate (module $m)))
605 /// (core instance $i2 (instantiate (module $m)))
606 /// (core instance $i3 (instantiate (module $m)))
607 /// )
608 /// "#)?;
609 ///
610 /// let resources = component.resources_required()
611 /// .expect("this component does not import any core modules or instances");
612 ///
613 /// // Instantiating the component will require allocating two memories per
614 /// // core instance, and there are three instances, so six total memories.
615 /// assert_eq!(resources.num_memories, 6);
616 /// assert_eq!(resources.max_initial_memory_size, Some(6));
617 ///
618 /// // The component doesn't need any tables.
619 /// assert_eq!(resources.num_tables, 0);
620 /// assert_eq!(resources.max_initial_table_size, None);
621 /// # Ok(()) }
622 /// ```
623 pub fn resources_required(&self) -> Option<ResourcesRequired> {
624 let mut resources = ResourcesRequired {
625 num_memories: 0,
626 max_initial_memory_size: None,
627 num_tables: 0,
628 max_initial_table_size: None,
629 };
630 for init in &self.env_component().initializers {
631 match init {
632 GlobalInitializer::InstantiateModule(inst) => match inst {
633 InstantiateModule::Static(index, _) => {
634 let module = self.static_module(*index);
635 resources.add(&module.resources_required());
636 }
637 InstantiateModule::Import(_, _) => {
638 // We can't statically determine the resources required
639 // to instantiate this component.
640 return None;
641 }
642 },
643 GlobalInitializer::LowerImport { .. }
644 | GlobalInitializer::ExtractMemory(_)
645 | GlobalInitializer::ExtractTable(_)
646 | GlobalInitializer::ExtractRealloc(_)
647 | GlobalInitializer::ExtractCallback(_)
648 | GlobalInitializer::ExtractPostReturn(_)
649 | GlobalInitializer::Resource(_) => {}
650 }
651 }
652 Some(resources)
653 }
654
655 /// Returns the range, in the host's address space, that this module's
656 /// compiled code resides at.
657 ///
658 /// For more information see
659 /// [`Module::image_range`](crate::Module::image_range).
660 pub fn image_range(&self) -> Range<*const u8> {
661 self.inner.code.code_memory().mmap().image_range()
662 }
663
664 /// Force initialization of copy-on-write images to happen here-and-now
665 /// instead of when they're requested during first instantiation.
666 ///
667 /// When [copy-on-write memory
668 /// initialization](crate::Config::memory_init_cow) is enabled then Wasmtime
669 /// will lazily create the initialization image for a component. This method
670 /// can be used to explicitly dictate when this initialization happens.
671 ///
672 /// Note that this largely only matters on Linux when memfd is used.
673 /// Otherwise the copy-on-write image typically comes from disk and in that
674 /// situation the creation of the image is trivial as the image is always
675 /// sourced from disk. On Linux, though, when memfd is used a memfd is
676 /// created and the initialization image is written to it.
677 ///
678 /// Also note that this method is not required to be called, it's available
679 /// as a performance optimization if required but is otherwise handled
680 /// automatically.
681 pub fn initialize_copy_on_write_image(&self) -> Result<()> {
682 for (_, module) in self.inner.static_modules.iter() {
683 module.initialize_copy_on_write_image()?;
684 }
685 Ok(())
686 }
687
688 /// Looks up a specific export of this component by `name` optionally nested
689 /// within the `instance` provided.
690 ///
691 /// See related method [`Self::get_export`] for additional docs and
692 /// examples.
693 ///
694 /// This method is primarily used to acquire a [`ComponentExportIndex`]
695 /// which can be used with [`Instance`](crate::component::Instance) when
696 /// looking up exports. Export lookup with [`ComponentExportIndex`] can
697 /// skip string lookups at runtime and instead use a more efficient
698 /// index-based lookup.
699 ///
700 /// This method only returns the [`ComponentExportIndex`]. If you need the
701 /// corresponding [`types::ComponentItem`], use the related function
702 /// [`Self::get_export`].
703 ///
704 ///
705 /// [`Instance`](crate::component::Instance) has a corresponding method
706 /// [`Instance::get_export_index`](crate::component::Instance::get_export_index).
707 pub fn get_export_index(
708 &self,
709 instance: Option<&ComponentExportIndex>,
710 name: &str,
711 ) -> Option<ComponentExportIndex> {
712 let index = self.lookup_export_index(instance, name)?;
713 Some(ComponentExportIndex {
714 id: self.inner.id,
715 index,
716 })
717 }
718
719 /// Looks up a specific export of this component by `name` optionally nested
720 /// within the `instance` provided.
721 ///
722 /// This method is primarily used to acquire a [`ComponentExportIndex`]
723 /// which can be used with [`Instance`](crate::component::Instance) when
724 /// looking up exports. Export lookup with [`ComponentExportIndex`] can
725 /// skip string lookups at runtime and instead use a more efficient
726 /// index-based lookup.
727 ///
728 /// This method takes a few arguments:
729 ///
730 /// * `engine` - the engine that was used to compile this component.
731 /// * `instance` - an optional "parent instance" for the export being looked
732 /// up. If this is `None` then the export is looked up on the root of the
733 /// component itself, and otherwise the export is looked up on the
734 /// `instance` specified. Note that `instance` must have come from a
735 /// previous invocation of this method.
736 /// * `name` - the name of the export that's being looked up.
737 ///
738 /// If the export is located then two values are returned: a
739 /// [`types::ComponentItem`] which enables introspection about the type of
740 /// the export and a [`ComponentExportIndex`]. The index returned notably
741 /// implements the [`InstanceExportLookup`] trait which enables using it
742 /// with [`Instance::get_func`](crate::component::Instance::get_func) for
743 /// example.
744 ///
745 /// The returned [`types::ComponentItem`] is more expensive to calculate
746 /// than the [`ComponentExportIndex`]. If you only consume the
747 /// [`ComponentExportIndex`], use the related method
748 /// [`Self::get_export_index`] instead.
749 ///
750 /// [`Instance`](crate::component::Instance) has a corresponding method
751 /// [`Instance::get_export`](crate::component::Instance::get_export).
752 ///
753 /// # Examples
754 ///
755 /// ```
756 /// use wasmtime::{Engine, Store};
757 /// use wasmtime::component::{Component, Linker};
758 /// use wasmtime::component::types::ComponentItem;
759 ///
760 /// # fn main() -> wasmtime::Result<()> {
761 /// let engine = Engine::default();
762 /// let component = Component::new(
763 /// &engine,
764 /// r#"
765 /// (component
766 /// (core module $m
767 /// (func (export "f"))
768 /// )
769 /// (core instance $i (instantiate $m))
770 /// (func (export "f")
771 /// (canon lift (core func $i "f")))
772 /// )
773 /// "#,
774 /// )?;
775 ///
776 /// // Perform a lookup of the function "f" before instantiaton.
777 /// let (ty, export) = component.get_export(None, "f").unwrap();
778 /// assert!(matches!(ty, ComponentItem::ComponentFunc(_)));
779 ///
780 /// // After instantiation use `export` to lookup the function in question
781 /// // which notably does not do a string lookup at runtime.
782 /// let mut store = Store::new(&engine, ());
783 /// let instance = Linker::new(&engine).instantiate(&mut store, &component)?;
784 /// let func = instance.get_typed_func::<(), ()>(&mut store, &export)?;
785 /// // ...
786 /// # Ok(())
787 /// # }
788 /// ```
789 pub fn get_export(
790 &self,
791 instance: Option<&ComponentExportIndex>,
792 name: &str,
793 ) -> Option<(types::ComponentItem, ComponentExportIndex)> {
794 let info = self.env_component();
795 let index = self.lookup_export_index(instance, name)?;
796 let item = self.with_uninstantiated_instance_type(|instance| {
797 types::ComponentItem::from_export(
798 &self.inner.engine,
799 &info.export_items[index],
800 instance,
801 )
802 });
803 Some((
804 item,
805 ComponentExportIndex {
806 id: self.inner.id,
807 index,
808 },
809 ))
810 }
811
812 pub(crate) fn lookup_export_index(
813 &self,
814 instance: Option<&ComponentExportIndex>,
815 name: &str,
816 ) -> Option<ExportIndex> {
817 let info = self.env_component();
818 let exports = match instance {
819 Some(idx) => {
820 if idx.id != self.inner.id {
821 return None;
822 }
823 match &info.export_items[idx.index] {
824 Export::Instance { exports, .. } => exports,
825 _ => return None,
826 }
827 }
828 None => &info.exports,
829 };
830 exports.get(name, &NameMapNoIntern).copied()
831 }
832
833 pub(crate) fn id(&self) -> CompiledModuleId {
834 self.inner.id
835 }
836
837 /// Returns the [`Engine`] that this [`Component`] was compiled by.
838 pub fn engine(&self) -> &Engine {
839 &self.inner.engine
840 }
841
842 pub(crate) fn realloc_func_ty(&self) -> &Arc<FuncType> {
843 &self.inner.realloc_func_type
844 }
845
846 /// Returns the `Export::LiftedFunction` metadata associated with `export`.
847 ///
848 /// # Panics
849 ///
850 /// Panics if `export` is out of bounds or if it isn't a `LiftedFunction`.
851 pub(crate) fn export_lifted_function(
852 &self,
853 export: ExportIndex,
854 ) -> (TypeFuncIndex, &CoreDef, OptionsIndex) {
855 let component = self.env_component();
856 match &component.export_items[export] {
857 Export::LiftedFunction { ty, func, options } => (*ty, func, *options),
858 _ => unreachable!(),
859 }
860 }
861}
862
863/// A value which represents a known export of a component.
864///
865/// This is the return value of [`Component::get_export`] and implements the
866/// [`InstanceExportLookup`] trait to work with lookups like
867/// [`Instance::get_func`](crate::component::Instance::get_func).
868#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
869pub struct ComponentExportIndex {
870 pub(crate) id: CompiledModuleId,
871 pub(crate) index: ExportIndex,
872}
873
874impl InstanceExportLookup for ComponentExportIndex {
875 fn lookup(&self, component: &Component) -> Option<ExportIndex> {
876 if component.inner.id == self.id {
877 Some(self.index)
878 } else {
879 None
880 }
881 }
882}
883
884#[cfg(test)]
885mod tests {
886 use crate::component::Component;
887 use crate::{Config, Engine};
888 use wasmtime_environ::MemoryInitialization;
889
890 #[test]
891 fn cow_on_by_default() {
892 let mut config = Config::new();
893 config.wasm_component_model(true);
894 let engine = Engine::new(&config).unwrap();
895 let component = Component::new(
896 &engine,
897 r#"
898 (component
899 (core module
900 (memory 1)
901 (data (i32.const 100) "abcd")
902 )
903 )
904 "#,
905 )
906 .unwrap();
907
908 for (_, module) in component.inner.static_modules.iter() {
909 let init = &module.env_module().memory_initialization;
910 assert!(matches!(init, MemoryInitialization::Static { .. }));
911 }
912 }
913}