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}