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