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