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