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