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