wasmtime/runtime/
module.rs

1use crate::prelude::*;
2#[cfg(feature = "std")]
3use crate::runtime::vm::open_file_for_mmap;
4use crate::runtime::vm::{CompiledModuleId, MmapVec, ModuleMemoryImages, VMWasmCallFunction};
5use crate::sync::OnceLock;
6use crate::{
7    Engine,
8    code::CodeObject,
9    code_memory::CodeMemory,
10    instantiate::CompiledModule,
11    resources::ResourcesRequired,
12    types::{ExportType, ExternType, ImportType},
13};
14use alloc::sync::Arc;
15use core::fmt;
16use core::ops::Range;
17use core::ptr::NonNull;
18#[cfg(feature = "std")]
19use std::{fs::File, path::Path};
20use wasmparser::{Parser, ValidPayload, Validator};
21#[cfg(feature = "debug")]
22use wasmtime_environ::FrameTable;
23use wasmtime_environ::{
24    CompiledFunctionsTable, CompiledModuleInfo, EntityIndex, HostPtr, ModuleTypes, ObjectKind,
25    TypeTrace, VMOffsets, VMSharedTypeIndex,
26};
27#[cfg(feature = "gc")]
28use wasmtime_unwinder::ExceptionTable;
29mod registry;
30
31pub use registry::*;
32
33/// A compiled WebAssembly module, ready to be instantiated.
34///
35/// A `Module` is a compiled in-memory representation of an input WebAssembly
36/// binary. A `Module` is then used to create an [`Instance`](crate::Instance)
37/// through an instantiation process. You cannot call functions or fetch
38/// globals, for example, on a `Module` because it's purely a code
39/// representation. Instead you'll need to create an
40/// [`Instance`](crate::Instance) to interact with the wasm module.
41///
42/// A `Module` can be created by compiling WebAssembly code through APIs such as
43/// [`Module::new`]. This would be a JIT-style use case where code is compiled
44/// just before it's used. Alternatively a `Module` can be compiled in one
45/// process and [`Module::serialize`] can be used to save it to storage. A later
46/// call to [`Module::deserialize`] will quickly load the module to execute and
47/// does not need to compile any code, representing a more AOT-style use case.
48///
49/// Currently a `Module` does not implement any form of tiering or dynamic
50/// optimization of compiled code. Creation of a `Module` via [`Module::new`] or
51/// related APIs will perform the entire compilation step synchronously. When
52/// finished no further compilation will happen at runtime or later during
53/// execution of WebAssembly instances for example.
54///
55/// Compilation of WebAssembly by default goes through Cranelift and is
56/// recommended to be done once-per-module. The same WebAssembly binary need not
57/// be compiled multiple times and can instead used an embedder-cached result of
58/// the first call.
59///
60/// `Module` is thread-safe and safe to share across threads.
61///
62/// ## Modules and `Clone`
63///
64/// Using `clone` on a `Module` is a cheap operation. It will not create an
65/// entirely new module, but rather just a new reference to the existing module.
66/// In other words it's a shallow copy, not a deep copy.
67///
68/// ## Examples
69///
70/// There are a number of ways you can create a `Module`, for example pulling
71/// the bytes from a number of locations. One example is loading a module from
72/// the filesystem:
73///
74/// ```no_run
75/// # use wasmtime::*;
76/// # fn main() -> anyhow::Result<()> {
77/// let engine = Engine::default();
78/// let module = Module::from_file(&engine, "path/to/foo.wasm")?;
79/// # Ok(())
80/// # }
81/// ```
82///
83/// You can also load the wasm text format if more convenient too:
84///
85/// ```no_run
86/// # use wasmtime::*;
87/// # fn main() -> anyhow::Result<()> {
88/// let engine = Engine::default();
89/// // Now we're using the WebAssembly text extension: `.wat`!
90/// let module = Module::from_file(&engine, "path/to/foo.wat")?;
91/// # Ok(())
92/// # }
93/// ```
94///
95/// And if you've already got the bytes in-memory you can use the
96/// [`Module::new`] constructor:
97///
98/// ```no_run
99/// # use wasmtime::*;
100/// # fn main() -> anyhow::Result<()> {
101/// let engine = Engine::default();
102/// # let wasm_bytes: Vec<u8> = Vec::new();
103/// let module = Module::new(&engine, &wasm_bytes)?;
104///
105/// // It also works with the text format!
106/// let module = Module::new(&engine, "(module (func))")?;
107/// # Ok(())
108/// # }
109/// ```
110///
111/// Serializing and deserializing a module looks like:
112///
113/// ```no_run
114/// # use wasmtime::*;
115/// # fn main() -> anyhow::Result<()> {
116/// let engine = Engine::default();
117/// # let wasm_bytes: Vec<u8> = Vec::new();
118/// let module = Module::new(&engine, &wasm_bytes)?;
119/// let module_bytes = module.serialize()?;
120///
121/// // ... can save `module_bytes` to disk or other storage ...
122///
123/// // recreate the module from the serialized bytes. For the `unsafe` bits
124/// // see the documentation of `deserialize`.
125/// let module = unsafe { Module::deserialize(&engine, &module_bytes)? };
126/// # Ok(())
127/// # }
128/// ```
129///
130/// [`Config`]: crate::Config
131#[derive(Clone)]
132pub struct Module {
133    inner: Arc<ModuleInner>,
134}
135
136struct ModuleInner {
137    engine: Engine,
138    /// The compiled artifacts for this module that will be instantiated and
139    /// executed.
140    module: CompiledModule,
141
142    /// Runtime information such as the underlying mmap, type information, etc.
143    ///
144    /// Note that this `Arc` is used to share information between compiled
145    /// modules within a component. For bare core wasm modules created with
146    /// `Module::new`, for example, this is a uniquely owned `Arc`.
147    code: Arc<CodeObject>,
148
149    /// A set of initialization images for memories, if any.
150    ///
151    /// Note that this is behind a `OnceCell` to lazily create this image. On
152    /// Linux where `memfd_create` may be used to create the backing memory
153    /// image this is a pretty expensive operation, so by deferring it this
154    /// improves memory usage for modules that are created but may not ever be
155    /// instantiated.
156    memory_images: OnceLock<Option<ModuleMemoryImages>>,
157
158    /// Flag indicating whether this module can be serialized or not.
159    #[cfg(any(feature = "cranelift", feature = "winch"))]
160    serializable: bool,
161
162    /// Runtime offset information for `VMContext`.
163    offsets: VMOffsets<HostPtr>,
164}
165
166impl fmt::Debug for Module {
167    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
168        f.debug_struct("Module")
169            .field("name", &self.name())
170            .finish_non_exhaustive()
171    }
172}
173
174impl fmt::Debug for ModuleInner {
175    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
176        f.debug_struct("ModuleInner")
177            .field("name", &self.module.module().name.as_ref())
178            .finish_non_exhaustive()
179    }
180}
181
182impl Module {
183    /// Creates a new WebAssembly `Module` from the given in-memory `bytes`.
184    ///
185    /// The `bytes` provided must be in one of the following formats:
186    ///
187    /// * A [binary-encoded][binary] WebAssembly module. This is always supported.
188    /// * A [text-encoded][text] instance of the WebAssembly text format.
189    ///   This is only supported when the `wat` feature of this crate is enabled.
190    ///   If this is supplied then the text format will be parsed before validation.
191    ///   Note that the `wat` feature is enabled by default.
192    ///
193    /// The data for the wasm module must be loaded in-memory if it's present
194    /// elsewhere, for example on disk. This requires that the entire binary is
195    /// loaded into memory all at once, this API does not support streaming
196    /// compilation of a module.
197    ///
198    /// The WebAssembly binary will be decoded and validated. It will also be
199    /// compiled according to the configuration of the provided `engine`.
200    ///
201    /// # Errors
202    ///
203    /// This function may fail and return an error. Errors may include
204    /// situations such as:
205    ///
206    /// * The binary provided could not be decoded because it's not a valid
207    ///   WebAssembly binary
208    /// * The WebAssembly binary may not validate (e.g. contains type errors)
209    /// * Implementation-specific limits were exceeded with a valid binary (for
210    ///   example too many locals)
211    /// * The wasm binary may use features that are not enabled in the
212    ///   configuration of `engine`
213    /// * If the `wat` feature is enabled and the input is text, then it may be
214    ///   rejected if it fails to parse.
215    ///
216    /// The error returned should contain full information about why module
217    /// creation failed if one is returned.
218    ///
219    /// [binary]: https://webassembly.github.io/spec/core/binary/index.html
220    /// [text]: https://webassembly.github.io/spec/core/text/index.html
221    ///
222    /// # Examples
223    ///
224    /// The `new` function can be invoked with a in-memory array of bytes:
225    ///
226    /// ```no_run
227    /// # use wasmtime::*;
228    /// # fn main() -> anyhow::Result<()> {
229    /// # let engine = Engine::default();
230    /// # let wasm_bytes: Vec<u8> = Vec::new();
231    /// let module = Module::new(&engine, &wasm_bytes)?;
232    /// # Ok(())
233    /// # }
234    /// ```
235    ///
236    /// Or you can also pass in a string to be parsed as the wasm text
237    /// format:
238    ///
239    /// ```
240    /// # use wasmtime::*;
241    /// # fn main() -> anyhow::Result<()> {
242    /// # let engine = Engine::default();
243    /// let module = Module::new(&engine, "(module (func))")?;
244    /// # Ok(())
245    /// # }
246    /// ```
247    #[cfg(any(feature = "cranelift", feature = "winch"))]
248    pub fn new(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Module> {
249        crate::CodeBuilder::new(engine)
250            .wasm_binary_or_text(bytes.as_ref(), None)?
251            .compile_module()
252    }
253
254    /// Creates a new WebAssembly `Module` from the contents of the given
255    /// `file` on disk.
256    ///
257    /// This is a convenience function that will read the `file` provided and
258    /// pass the bytes to the [`Module::new`] function. For more information
259    /// see [`Module::new`]
260    ///
261    /// # Examples
262    ///
263    /// ```no_run
264    /// # use wasmtime::*;
265    /// # fn main() -> anyhow::Result<()> {
266    /// let engine = Engine::default();
267    /// let module = Module::from_file(&engine, "./path/to/foo.wasm")?;
268    /// # Ok(())
269    /// # }
270    /// ```
271    ///
272    /// The `.wat` text format is also supported:
273    ///
274    /// ```no_run
275    /// # use wasmtime::*;
276    /// # fn main() -> anyhow::Result<()> {
277    /// # let engine = Engine::default();
278    /// let module = Module::from_file(&engine, "./path/to/foo.wat")?;
279    /// # Ok(())
280    /// # }
281    /// ```
282    #[cfg(all(feature = "std", any(feature = "cranelift", feature = "winch")))]
283    pub fn from_file(engine: &Engine, file: impl AsRef<Path>) -> Result<Module> {
284        crate::CodeBuilder::new(engine)
285            .wasm_binary_or_text_file(file.as_ref())?
286            .compile_module()
287    }
288
289    /// Creates a new WebAssembly `Module` from the given in-memory `binary`
290    /// data.
291    ///
292    /// This is similar to [`Module::new`] except that it requires that the
293    /// `binary` input is a WebAssembly binary, the text format is not supported
294    /// by this function. It's generally recommended to use [`Module::new`], but
295    /// if it's required to not support the text format this function can be
296    /// used instead.
297    ///
298    /// # Examples
299    ///
300    /// ```
301    /// # use wasmtime::*;
302    /// # fn main() -> anyhow::Result<()> {
303    /// # let engine = Engine::default();
304    /// let wasm = b"\0asm\x01\0\0\0";
305    /// let module = Module::from_binary(&engine, wasm)?;
306    /// # Ok(())
307    /// # }
308    /// ```
309    ///
310    /// Note that the text format is **not** accepted by this function:
311    ///
312    /// ```
313    /// # use wasmtime::*;
314    /// # fn main() -> anyhow::Result<()> {
315    /// # let engine = Engine::default();
316    /// assert!(Module::from_binary(&engine, b"(module)").is_err());
317    /// # Ok(())
318    /// # }
319    /// ```
320    #[cfg(any(feature = "cranelift", feature = "winch"))]
321    pub fn from_binary(engine: &Engine, binary: &[u8]) -> Result<Module> {
322        crate::CodeBuilder::new(engine)
323            .wasm_binary(binary, None)?
324            .compile_module()
325    }
326
327    /// Creates a new WebAssembly `Module` from the contents of the given `file`
328    /// on disk, but with assumptions that the file is from a trusted source.
329    /// The file should be a binary- or text-format WebAssembly module, or a
330    /// precompiled artifact generated by the same version of Wasmtime.
331    ///
332    /// # Unsafety
333    ///
334    /// All of the reasons that [`deserialize`] is `unsafe` apply to this
335    /// function as well. Arbitrary data loaded from a file may trick Wasmtime
336    /// into arbitrary code execution since the contents of the file are not
337    /// validated to be a valid precompiled module.
338    ///
339    /// [`deserialize`]: Module::deserialize
340    ///
341    /// Additionally though this function is also `unsafe` because the file
342    /// referenced must remain unchanged and a valid precompiled module for the
343    /// entire lifetime of the [`Module`] returned. Any changes to the file on
344    /// disk may change future instantiations of the module to be incorrect.
345    /// This is because the file is mapped into memory and lazily loaded pages
346    /// reflect the current state of the file, not necessarily the original
347    /// state of the file.
348    #[cfg(all(feature = "std", any(feature = "cranelift", feature = "winch")))]
349    pub unsafe fn from_trusted_file(engine: &Engine, file: impl AsRef<Path>) -> Result<Module> {
350        let open_file = open_file_for_mmap(file.as_ref())?;
351        let mmap = crate::runtime::vm::MmapVec::from_file(open_file)?;
352        if &mmap[0..4] == b"\x7fELF" {
353            let code = engine.load_code(mmap, ObjectKind::Module)?;
354            return Module::from_parts(engine, code, None);
355        }
356
357        crate::CodeBuilder::new(engine)
358            .wasm_binary_or_text(&mmap[..], Some(file.as_ref()))?
359            .compile_module()
360    }
361
362    /// Deserializes an in-memory compiled module previously created with
363    /// [`Module::serialize`] or [`Engine::precompile_module`].
364    ///
365    /// This function will deserialize the binary blobs emitted by
366    /// [`Module::serialize`] and [`Engine::precompile_module`] back into an
367    /// in-memory [`Module`] that's ready to be instantiated.
368    ///
369    /// Note that the [`Module::deserialize_file`] method is more optimized than
370    /// this function, so if the serialized module is already present in a file
371    /// it's recommended to use that method instead.
372    ///
373    /// # Unsafety
374    ///
375    /// This function is marked as `unsafe` because if fed invalid input or used
376    /// improperly this could lead to memory safety vulnerabilities. This method
377    /// should not, for example, be exposed to arbitrary user input.
378    ///
379    /// The structure of the binary blob read here is only lightly validated
380    /// internally in `wasmtime`. This is intended to be an efficient
381    /// "rehydration" for a [`Module`] which has very few runtime checks beyond
382    /// deserialization. Arbitrary input could, for example, replace valid
383    /// compiled code with any other valid compiled code, meaning that this can
384    /// trivially be used to execute arbitrary code otherwise.
385    ///
386    /// For these reasons this function is `unsafe`. This function is only
387    /// designed to receive the previous input from [`Module::serialize`] and
388    /// [`Engine::precompile_module`]. If the exact output of those functions
389    /// (unmodified) is passed to this function then calls to this function can
390    /// be considered safe. It is the caller's responsibility to provide the
391    /// guarantee that only previously-serialized bytes are being passed in
392    /// here.
393    ///
394    /// Note that this function is designed to be safe receiving output from
395    /// *any* compiled version of `wasmtime` itself. This means that it is safe
396    /// to feed output from older versions of Wasmtime into this function, in
397    /// addition to newer versions of wasmtime (from the future!). These inputs
398    /// will deterministically and safely produce an `Err`. This function only
399    /// successfully accepts inputs from the same version of `wasmtime`, but the
400    /// safety guarantee only applies to externally-defined blobs of bytes, not
401    /// those defined by any version of wasmtime. (this means that if you cache
402    /// blobs across versions of wasmtime you can be safely guaranteed that
403    /// future versions of wasmtime will reject old cache entries).
404    pub unsafe fn deserialize(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Module> {
405        let code = engine.load_code_bytes(bytes.as_ref(), ObjectKind::Module)?;
406        Module::from_parts(engine, code, None)
407    }
408
409    /// In-place deserialization of an in-memory compiled module previously
410    /// created with [`Module::serialize`] or [`Engine::precompile_module`].
411    ///
412    /// See [`Self::deserialize`] for additional information; this method
413    /// works identically except that it will not create a copy of the provided
414    /// memory but will use it directly.
415    ///
416    /// # Unsafety
417    ///
418    /// All of the safety notes from [`Self::deserialize`] apply here as well
419    /// with the additional constraint that the code memory provide by `memory`
420    /// lives for as long as the module and is nevery externally modified for
421    /// the lifetime of the deserialized module.
422    pub unsafe fn deserialize_raw(engine: &Engine, memory: NonNull<[u8]>) -> Result<Module> {
423        // SAFETY: the contract required by `load_code_raw` is the same as this
424        // function.
425        let code = unsafe { engine.load_code_raw(memory, ObjectKind::Module)? };
426        Module::from_parts(engine, code, None)
427    }
428
429    /// Same as [`deserialize`], except that the contents of `path` are read to
430    /// deserialize into a [`Module`].
431    ///
432    /// This method is provided because it can be faster than [`deserialize`]
433    /// since the data doesn't need to be copied around, but rather the module
434    /// can be used directly from an mmap'd view of the file provided.
435    ///
436    /// [`deserialize`]: Module::deserialize
437    ///
438    /// # Unsafety
439    ///
440    /// All of the reasons that [`deserialize`] is `unsafe` applies to this
441    /// function as well. Arbitrary data loaded from a file may trick Wasmtime
442    /// into arbitrary code execution since the contents of the file are not
443    /// validated to be a valid precompiled module.
444    ///
445    /// Additionally though this function is also `unsafe` because the file
446    /// referenced must remain unchanged and a valid precompiled module for the
447    /// entire lifetime of the [`Module`] returned. Any changes to the file on
448    /// disk may change future instantiations of the module to be incorrect.
449    /// This is because the file is mapped into memory and lazily loaded pages
450    /// reflect the current state of the file, not necessarily the original
451    /// state of the file.
452    #[cfg(feature = "std")]
453    pub unsafe fn deserialize_file(engine: &Engine, path: impl AsRef<Path>) -> Result<Module> {
454        let file = open_file_for_mmap(path.as_ref())?;
455        // SAFETY: the contract of `deserialize_open_file` is the samea s this
456        // function.
457        unsafe {
458            Self::deserialize_open_file(engine, file)
459                .with_context(|| format!("failed deserialization for: {}", path.as_ref().display()))
460        }
461    }
462
463    /// Same as [`deserialize_file`], except that it takes an open `File`
464    /// instead of a path.
465    ///
466    /// This method is provided because it can be used instead of
467    /// [`deserialize_file`] in situations where `wasmtime` is running with
468    /// limited file system permissions. In that case a process
469    /// with file system access can pass already opened files to `wasmtime`.
470    ///
471    /// [`deserialize_file`]: Module::deserialize_file
472    ///
473    /// Note that the corresponding will be mapped as private writeable
474    /// (copy-on-write) and executable. For `windows` this means the file needs
475    /// to be opened with at least `FILE_GENERIC_READ | FILE_GENERIC_EXECUTE`
476    /// [`access_mode`].
477    ///
478    /// [`access_mode`]: https://doc.rust-lang.org/std/os/windows/fs/trait.OpenOptionsExt.html#tymethod.access_mode
479    ///
480    /// # Unsafety
481    ///
482    /// All of the reasons that [`deserialize_file`] is `unsafe` applies to this
483    /// function as well.
484    #[cfg(feature = "std")]
485    pub unsafe fn deserialize_open_file(engine: &Engine, file: File) -> Result<Module> {
486        let code = engine.load_code_file(file, ObjectKind::Module)?;
487        Module::from_parts(engine, code, None)
488    }
489
490    /// Entrypoint for creating a `Module` for all above functions, both
491    /// of the AOT and jit-compiled categories.
492    ///
493    /// In all cases the compilation artifact, `code_memory`, is provided here.
494    /// The `info_and_types` argument is `None` when a module is being
495    /// deserialized from a precompiled artifact or it's `Some` if it was just
496    /// compiled and the values are already available.
497    pub(crate) fn from_parts(
498        engine: &Engine,
499        code_memory: Arc<CodeMemory>,
500        info_and_types: Option<(CompiledModuleInfo, CompiledFunctionsTable, ModuleTypes)>,
501    ) -> Result<Self> {
502        // Acquire this module's metadata and type information, deserializing
503        // it from the provided artifact if it wasn't otherwise provided
504        // already.
505        let (mut info, index, mut types) = match info_and_types {
506            Some((info, index, types)) => (info, index, types),
507            None => postcard::from_bytes(code_memory.wasmtime_info())?,
508        };
509
510        // Register function type signatures into the engine for the lifetime
511        // of the `Module` that will be returned. This notably also builds up
512        // maps for trampolines to be used for this module when inserted into
513        // stores.
514        //
515        // Note that the unsafety here should be ok since the `trampolines`
516        // field should only point to valid trampoline function pointers
517        // within the text section.
518        let signatures =
519            engine.register_and_canonicalize_types(&mut types, core::iter::once(&mut info.module));
520
521        // Package up all our data into a `CodeObject` and delegate to the final
522        // step of module compilation.
523        let code = Arc::new(CodeObject::new(code_memory, signatures, types.into()));
524        let index = Arc::new(index);
525        Module::from_parts_raw(engine, code, info, index, true)
526    }
527
528    pub(crate) fn from_parts_raw(
529        engine: &Engine,
530        code: Arc<CodeObject>,
531        info: CompiledModuleInfo,
532        index: Arc<CompiledFunctionsTable>,
533        serializable: bool,
534    ) -> Result<Self> {
535        let module = CompiledModule::from_artifacts(
536            code.code_memory().clone(),
537            info,
538            index,
539            engine.profiler(),
540        )?;
541
542        // Validate the module can be used with the current instance allocator.
543        let offsets = VMOffsets::new(HostPtr, module.module());
544        engine
545            .allocator()
546            .validate_module(module.module(), &offsets)?;
547
548        let _ = serializable;
549
550        Ok(Self {
551            inner: Arc::new(ModuleInner {
552                engine: engine.clone(),
553                code,
554                memory_images: OnceLock::new(),
555                module,
556                #[cfg(any(feature = "cranelift", feature = "winch"))]
557                serializable,
558                offsets,
559            }),
560        })
561    }
562
563    /// Validates `binary` input data as a WebAssembly binary given the
564    /// configuration in `engine`.
565    ///
566    /// This function will perform a speedy validation of the `binary` input
567    /// WebAssembly module (which is in [binary form][binary], the text format
568    /// is not accepted by this function) and return either `Ok` or `Err`
569    /// depending on the results of validation. The `engine` argument indicates
570    /// configuration for WebAssembly features, for example, which are used to
571    /// indicate what should be valid and what shouldn't be.
572    ///
573    /// Validation automatically happens as part of [`Module::new`].
574    ///
575    /// # Errors
576    ///
577    /// If validation fails for any reason (type check error, usage of a feature
578    /// that wasn't enabled, etc) then an error with a description of the
579    /// validation issue will be returned.
580    ///
581    /// [binary]: https://webassembly.github.io/spec/core/binary/index.html
582    pub fn validate(engine: &Engine, binary: &[u8]) -> Result<()> {
583        let mut validator = Validator::new_with_features(engine.features());
584
585        let mut functions = Vec::new();
586        for payload in Parser::new(0).parse_all(binary) {
587            let payload = payload?;
588            if let ValidPayload::Func(a, b) = validator.payload(&payload)? {
589                functions.push((a, b));
590            }
591            if let wasmparser::Payload::Version { encoding, .. } = &payload {
592                if let wasmparser::Encoding::Component = encoding {
593                    bail!("component passed to module validation");
594                }
595            }
596        }
597
598        engine.run_maybe_parallel(functions, |(validator, body)| {
599            // FIXME: it would be best here to use a rayon-specific parallel
600            // iterator that maintains state-per-thread to share the function
601            // validator allocations (`Default::default` here) across multiple
602            // functions.
603            validator.into_validator(Default::default()).validate(&body)
604        })?;
605        Ok(())
606    }
607
608    /// Serializes this module to a vector of bytes.
609    ///
610    /// This function is similar to the [`Engine::precompile_module`] method
611    /// where it produces an artifact of Wasmtime which is suitable to later
612    /// pass into [`Module::deserialize`]. If a module is never instantiated
613    /// then it's recommended to use [`Engine::precompile_module`] instead of
614    /// this method, but if a module is both instantiated and serialized then
615    /// this method can be useful to get the serialized version without
616    /// compiling twice.
617    #[cfg(any(feature = "cranelift", feature = "winch"))]
618    pub fn serialize(&self) -> Result<Vec<u8>> {
619        // The current representation of compiled modules within a compiled
620        // component means that it cannot be serialized. The mmap returned here
621        // is the mmap for the entire component and while it contains all
622        // necessary data to deserialize this particular module it's all
623        // embedded within component-specific information.
624        //
625        // It's not the hardest thing in the world to support this but it's
626        // expected that there's not much of a use case at this time. In theory
627        // all that needs to be done is to edit the `.wasmtime.info` section
628        // to contains this module's metadata instead of the metadata for the
629        // whole component. The metadata itself is fairly trivially
630        // recreateable here it's more that there's no easy one-off API for
631        // editing the sections of an ELF object to use here.
632        //
633        // Overall for now this simply always returns an error in this
634        // situation. If you're reading this and feel that the situation should
635        // be different please feel free to open an issue.
636        if !self.inner.serializable {
637            bail!("cannot serialize a module exported from a component");
638        }
639        Ok(self.compiled_module().mmap().to_vec())
640    }
641
642    pub(crate) fn compiled_module(&self) -> &CompiledModule {
643        &self.inner.module
644    }
645
646    pub(crate) fn code_object(&self) -> &Arc<CodeObject> {
647        &self.inner.code
648    }
649
650    pub(crate) fn env_module(&self) -> &Arc<wasmtime_environ::Module> {
651        self.compiled_module().module()
652    }
653
654    pub(crate) fn types(&self) -> &ModuleTypes {
655        self.inner.code.module_types()
656    }
657
658    #[cfg(any(feature = "component-model", feature = "gc-drc"))]
659    pub(crate) fn signatures(&self) -> &crate::type_registry::TypeCollection {
660        self.inner.code.signatures()
661    }
662
663    /// Returns identifier/name that this [`Module`] has. This name
664    /// is used in traps/backtrace details.
665    ///
666    /// Note that most LLVM/clang/Rust-produced modules do not have a name
667    /// associated with them, but other wasm tooling can be used to inject or
668    /// add a name.
669    ///
670    /// # Examples
671    ///
672    /// ```
673    /// # use wasmtime::*;
674    /// # fn main() -> anyhow::Result<()> {
675    /// # let engine = Engine::default();
676    /// let module = Module::new(&engine, "(module $foo)")?;
677    /// assert_eq!(module.name(), Some("foo"));
678    ///
679    /// let module = Module::new(&engine, "(module)")?;
680    /// assert_eq!(module.name(), None);
681    ///
682    /// # Ok(())
683    /// # }
684    /// ```
685    pub fn name(&self) -> Option<&str> {
686        self.compiled_module().module().name.as_deref()
687    }
688
689    /// Returns the list of imports that this [`Module`] has and must be
690    /// satisfied.
691    ///
692    /// This function returns the list of imports that the wasm module has, but
693    /// only the types of each import. The type of each import is used to
694    /// typecheck the [`Instance::new`](crate::Instance::new) method's `imports`
695    /// argument. The arguments to that function must match up 1-to-1 with the
696    /// entries in the array returned here.
697    ///
698    /// The imports returned reflect the order of the imports in the wasm module
699    /// itself, and note that no form of deduplication happens.
700    ///
701    /// # Examples
702    ///
703    /// Modules with no imports return an empty list here:
704    ///
705    /// ```
706    /// # use wasmtime::*;
707    /// # fn main() -> anyhow::Result<()> {
708    /// # let engine = Engine::default();
709    /// let module = Module::new(&engine, "(module)")?;
710    /// assert_eq!(module.imports().len(), 0);
711    /// # Ok(())
712    /// # }
713    /// ```
714    ///
715    /// and modules with imports will have a non-empty list:
716    ///
717    /// ```
718    /// # use wasmtime::*;
719    /// # fn main() -> anyhow::Result<()> {
720    /// # let engine = Engine::default();
721    /// let wat = r#"
722    ///     (module
723    ///         (import "host" "foo" (func))
724    ///     )
725    /// "#;
726    /// let module = Module::new(&engine, wat)?;
727    /// assert_eq!(module.imports().len(), 1);
728    /// let import = module.imports().next().unwrap();
729    /// assert_eq!(import.module(), "host");
730    /// assert_eq!(import.name(), "foo");
731    /// match import.ty() {
732    ///     ExternType::Func(_) => { /* ... */ }
733    ///     _ => panic!("unexpected import type!"),
734    /// }
735    /// # Ok(())
736    /// # }
737    /// ```
738    pub fn imports<'module>(
739        &'module self,
740    ) -> impl ExactSizeIterator<Item = ImportType<'module>> + 'module {
741        let module = self.compiled_module().module();
742        let types = self.types();
743        let engine = self.engine();
744        module
745            .imports()
746            .map(move |(imp_mod, imp_field, ty)| {
747                debug_assert!(ty.is_canonicalized_for_runtime_usage());
748                ImportType::new(imp_mod, imp_field, ty, types, engine)
749            })
750            .collect::<Vec<_>>()
751            .into_iter()
752    }
753
754    /// Returns the list of exports that this [`Module`] has and will be
755    /// available after instantiation.
756    ///
757    /// This function will return the type of each item that will be returned
758    /// from [`Instance::exports`](crate::Instance::exports). Each entry in this
759    /// list corresponds 1-to-1 with that list, and the entries here will
760    /// indicate the name of the export along with the type of the export.
761    ///
762    /// # Examples
763    ///
764    /// Modules might not have any exports:
765    ///
766    /// ```
767    /// # use wasmtime::*;
768    /// # fn main() -> anyhow::Result<()> {
769    /// # let engine = Engine::default();
770    /// let module = Module::new(&engine, "(module)")?;
771    /// assert!(module.exports().next().is_none());
772    /// # Ok(())
773    /// # }
774    /// ```
775    ///
776    /// When the exports are not empty, you can inspect each export:
777    ///
778    /// ```
779    /// # use wasmtime::*;
780    /// # fn main() -> anyhow::Result<()> {
781    /// # let engine = Engine::default();
782    /// let wat = r#"
783    ///     (module
784    ///         (func (export "foo"))
785    ///         (memory (export "memory") 1)
786    ///     )
787    /// "#;
788    /// let module = Module::new(&engine, wat)?;
789    /// assert_eq!(module.exports().len(), 2);
790    ///
791    /// let mut exports = module.exports();
792    /// let foo = exports.next().unwrap();
793    /// assert_eq!(foo.name(), "foo");
794    /// match foo.ty() {
795    ///     ExternType::Func(_) => { /* ... */ }
796    ///     _ => panic!("unexpected export type!"),
797    /// }
798    ///
799    /// let memory = exports.next().unwrap();
800    /// assert_eq!(memory.name(), "memory");
801    /// match memory.ty() {
802    ///     ExternType::Memory(_) => { /* ... */ }
803    ///     _ => panic!("unexpected export type!"),
804    /// }
805    /// # Ok(())
806    /// # }
807    /// ```
808    pub fn exports<'module>(
809        &'module self,
810    ) -> impl ExactSizeIterator<Item = ExportType<'module>> + 'module {
811        let module = self.compiled_module().module();
812        let types = self.types();
813        let engine = self.engine();
814        module.exports.iter().map(move |(name, entity_index)| {
815            ExportType::new(name, module.type_of(*entity_index), types, engine)
816        })
817    }
818
819    /// Looks up an export in this [`Module`] by name.
820    ///
821    /// This function will return the type of an export with the given name.
822    ///
823    /// # Examples
824    ///
825    /// There may be no export with that name:
826    ///
827    /// ```
828    /// # use wasmtime::*;
829    /// # fn main() -> anyhow::Result<()> {
830    /// # let engine = Engine::default();
831    /// let module = Module::new(&engine, "(module)")?;
832    /// assert!(module.get_export("foo").is_none());
833    /// # Ok(())
834    /// # }
835    /// ```
836    ///
837    /// When there is an export with that name, it is returned:
838    ///
839    /// ```
840    /// # use wasmtime::*;
841    /// # fn main() -> anyhow::Result<()> {
842    /// # let engine = Engine::default();
843    /// let wat = r#"
844    ///     (module
845    ///         (func (export "foo"))
846    ///         (memory (export "memory") 1)
847    ///     )
848    /// "#;
849    /// let module = Module::new(&engine, wat)?;
850    /// let foo = module.get_export("foo");
851    /// assert!(foo.is_some());
852    ///
853    /// let foo = foo.unwrap();
854    /// match foo {
855    ///     ExternType::Func(_) => { /* ... */ }
856    ///     _ => panic!("unexpected export type!"),
857    /// }
858    ///
859    /// # Ok(())
860    /// # }
861    /// ```
862    pub fn get_export(&self, name: &str) -> Option<ExternType> {
863        let module = self.compiled_module().module();
864        let entity_index = module.exports.get(name)?;
865        Some(ExternType::from_wasmtime(
866            self.engine(),
867            self.types(),
868            &module.type_of(*entity_index),
869        ))
870    }
871
872    /// Looks up an export in this [`Module`] by name to get its index.
873    ///
874    /// This function will return the index of an export with the given name. This can be useful
875    /// to avoid the cost of looking up the export by name multiple times. Instead the
876    /// [`ModuleExport`] can be stored and used to look up the export on the
877    /// [`Instance`](crate::Instance) later.
878    pub fn get_export_index(&self, name: &str) -> Option<ModuleExport> {
879        let compiled_module = self.compiled_module();
880        let module = compiled_module.module();
881        let entity = *module.exports.get(name)?;
882        Some(ModuleExport {
883            module: self.id(),
884            entity,
885        })
886    }
887
888    /// Returns the [`Engine`] that this [`Module`] was compiled by.
889    pub fn engine(&self) -> &Engine {
890        &self.inner.engine
891    }
892
893    /// Returns a summary of the resources required to instantiate this
894    /// [`Module`].
895    ///
896    /// Potential uses of the returned information:
897    ///
898    /// * Determining whether your pooling allocator configuration supports
899    ///   instantiating this module.
900    ///
901    /// * Deciding how many of which `Module` you want to instantiate within a
902    ///   fixed amount of resources, e.g. determining whether to create 5
903    ///   instances of module X or 10 instances of module Y.
904    ///
905    /// # Example
906    ///
907    /// ```
908    /// # fn main() -> wasmtime::Result<()> {
909    /// use wasmtime::{Config, Engine, Module};
910    ///
911    /// let mut config = Config::new();
912    /// config.wasm_multi_memory(true);
913    /// let engine = Engine::new(&config)?;
914    ///
915    /// let module = Module::new(&engine, r#"
916    ///     (module
917    ///         ;; Import a memory. Doesn't count towards required resources.
918    ///         (import "a" "b" (memory 10))
919    ///         ;; Define two local memories. These count towards the required
920    ///         ;; resources.
921    ///         (memory 1)
922    ///         (memory 6)
923    ///     )
924    /// "#)?;
925    ///
926    /// let resources = module.resources_required();
927    ///
928    /// // Instantiating the module will require allocating two memories, and
929    /// // the maximum initial memory size is six Wasm pages.
930    /// assert_eq!(resources.num_memories, 2);
931    /// assert_eq!(resources.max_initial_memory_size, Some(6));
932    ///
933    /// // The module doesn't need any tables.
934    /// assert_eq!(resources.num_tables, 0);
935    /// assert_eq!(resources.max_initial_table_size, None);
936    /// # Ok(()) }
937    /// ```
938    pub fn resources_required(&self) -> ResourcesRequired {
939        let em = self.env_module();
940        let num_memories = u32::try_from(em.num_defined_memories()).unwrap();
941        let max_initial_memory_size = em
942            .memories
943            .values()
944            .skip(em.num_imported_memories)
945            .map(|memory| memory.limits.min)
946            .max();
947        let num_tables = u32::try_from(em.num_defined_tables()).unwrap();
948        let max_initial_table_size = em
949            .tables
950            .values()
951            .skip(em.num_imported_tables)
952            .map(|table| table.limits.min)
953            .max();
954        ResourcesRequired {
955            num_memories,
956            max_initial_memory_size,
957            num_tables,
958            max_initial_table_size,
959        }
960    }
961
962    /// Returns the range of bytes in memory where this module's compilation
963    /// image resides.
964    ///
965    /// The compilation image for a module contains executable code, data, debug
966    /// information, etc. This is roughly the same as the `Module::serialize`
967    /// but not the exact same.
968    ///
969    /// The range of memory reported here is exposed to allow low-level
970    /// manipulation of the memory in platform-specific manners such as using
971    /// `mlock` to force the contents to be paged in immediately or keep them
972    /// paged in after they're loaded.
973    ///
974    /// It is not safe to modify the memory in this range, nor is it safe to
975    /// modify the protections of memory in this range.
976    pub fn image_range(&self) -> Range<*const u8> {
977        self.compiled_module().mmap().image_range()
978    }
979
980    /// Force initialization of copy-on-write images to happen here-and-now
981    /// instead of when they're requested during first instantiation.
982    ///
983    /// When [copy-on-write memory
984    /// initialization](crate::Config::memory_init_cow) is enabled then Wasmtime
985    /// will lazily create the initialization image for a module. This method
986    /// can be used to explicitly dictate when this initialization happens.
987    ///
988    /// Note that this largely only matters on Linux when memfd is used.
989    /// Otherwise the copy-on-write image typically comes from disk and in that
990    /// situation the creation of the image is trivial as the image is always
991    /// sourced from disk. On Linux, though, when memfd is used a memfd is
992    /// created and the initialization image is written to it.
993    ///
994    /// Also note that this method is not required to be called, it's available
995    /// as a performance optimization if required but is otherwise handled
996    /// automatically.
997    pub fn initialize_copy_on_write_image(&self) -> Result<()> {
998        self.memory_images()?;
999        Ok(())
1000    }
1001
1002    /// Get the map from `.text` section offsets to Wasm binary offsets for this
1003    /// module.
1004    ///
1005    /// Each entry is a (`.text` section offset, Wasm binary offset) pair.
1006    ///
1007    /// Entries are yielded in order of `.text` section offset.
1008    ///
1009    /// Some entries are missing a Wasm binary offset. This is for code that is
1010    /// not associated with any single location in the Wasm binary, or for when
1011    /// source information was optimized away.
1012    ///
1013    /// Not every module has an address map, since address map generation can be
1014    /// turned off on `Config`.
1015    ///
1016    /// There is not an entry for every `.text` section offset. Every offset
1017    /// after an entry's offset, but before the next entry's offset, is
1018    /// considered to map to the same Wasm binary offset as the original
1019    /// entry. For example, the address map will not contain the following
1020    /// sequence of entries:
1021    ///
1022    /// ```ignore
1023    /// [
1024    ///     // ...
1025    ///     (10, Some(42)),
1026    ///     (11, Some(42)),
1027    ///     (12, Some(42)),
1028    ///     (13, Some(43)),
1029    ///     // ...
1030    /// ]
1031    /// ```
1032    ///
1033    /// Instead, it will drop the entries for offsets `11` and `12` since they
1034    /// are the same as the entry for offset `10`:
1035    ///
1036    /// ```ignore
1037    /// [
1038    ///     // ...
1039    ///     (10, Some(42)),
1040    ///     (13, Some(43)),
1041    ///     // ...
1042    /// ]
1043    /// ```
1044    pub fn address_map<'a>(&'a self) -> Option<impl Iterator<Item = (usize, Option<u32>)> + 'a> {
1045        Some(
1046            wasmtime_environ::iterate_address_map(
1047                self.code_object().code_memory().address_map_data(),
1048            )?
1049            .map(|(offset, file_pos)| (offset as usize, file_pos.file_offset())),
1050        )
1051    }
1052
1053    /// Get this module's code object's `.text` section, containing its compiled
1054    /// executable code.
1055    pub fn text(&self) -> &[u8] {
1056        self.code_object().code_memory().text()
1057    }
1058
1059    /// Get information about functions in this module's `.text` section: their
1060    /// index, name, and offset+length.
1061    ///
1062    /// Results are yielded in a ModuleFunction struct.
1063    pub fn functions<'a>(&'a self) -> impl ExactSizeIterator<Item = ModuleFunction> + 'a {
1064        let module = self.compiled_module();
1065        module.finished_functions().map(|(idx, _)| {
1066            let loc = module.func_loc(idx);
1067            let idx = module.module().func_index(idx);
1068            ModuleFunction {
1069                index: idx,
1070                name: module.func_name(idx).map(|n| n.to_string()),
1071                offset: loc.start as usize,
1072                len: loc.length as usize,
1073            }
1074        })
1075    }
1076
1077    pub(crate) fn id(&self) -> CompiledModuleId {
1078        self.inner.module.unique_id()
1079    }
1080
1081    pub(crate) fn offsets(&self) -> &VMOffsets<HostPtr> {
1082        &self.inner.offsets
1083    }
1084
1085    /// Return the address, in memory, of the trampoline that allows Wasm to
1086    /// call a array function of the given signature.
1087    pub(crate) fn wasm_to_array_trampoline(
1088        &self,
1089        signature: VMSharedTypeIndex,
1090    ) -> Option<NonNull<VMWasmCallFunction>> {
1091        log::trace!("Looking up trampoline for {signature:?}");
1092        let trampoline_shared_ty = self.inner.engine.signatures().trampoline_type(signature);
1093        let trampoline_module_ty = self
1094            .inner
1095            .code
1096            .signatures()
1097            .trampoline_type(trampoline_shared_ty)?;
1098        debug_assert!(
1099            self.inner
1100                .engine
1101                .signatures()
1102                .borrow(
1103                    self.inner
1104                        .code
1105                        .signatures()
1106                        .shared_type(trampoline_module_ty)
1107                        .unwrap()
1108                )
1109                .unwrap()
1110                .unwrap_func()
1111                .is_trampoline_type()
1112        );
1113
1114        let ptr = self
1115            .compiled_module()
1116            .wasm_to_array_trampoline(trampoline_module_ty)
1117            .expect("always have a trampoline for the trampoline type")
1118            .as_ptr()
1119            .cast::<VMWasmCallFunction>()
1120            .cast_mut();
1121        Some(NonNull::new(ptr).unwrap())
1122    }
1123
1124    pub(crate) fn memory_images(&self) -> Result<Option<&ModuleMemoryImages>> {
1125        let images = self
1126            .inner
1127            .memory_images
1128            .get_or_try_init(|| memory_images(&self.inner))?
1129            .as_ref();
1130        Ok(images)
1131    }
1132
1133    /// Get the text offset (relative PC) for a given absolute PC in
1134    /// this module.
1135    #[cfg(any(feature = "gc", feature = "debug"))]
1136    pub(crate) fn text_offset(&self, pc: usize) -> u32 {
1137        u32::try_from(pc - self.inner.module.text().as_ptr() as usize).unwrap()
1138    }
1139
1140    /// Lookup the stack map at a program counter value.
1141    #[cfg(feature = "gc")]
1142    pub(crate) fn lookup_stack_map(&self, pc: usize) -> Option<wasmtime_environ::StackMap<'_>> {
1143        let text_offset = self.text_offset(pc);
1144        let info = self.inner.code.code_memory().stack_map_data();
1145        wasmtime_environ::StackMap::lookup(text_offset, info)
1146    }
1147
1148    /// Obtain an exception-table parser on this module's exception metadata.
1149    #[cfg(feature = "gc")]
1150    pub(crate) fn exception_table<'a>(&'a self) -> ExceptionTable<'a> {
1151        ExceptionTable::parse(self.inner.code.code_memory().exception_tables())
1152            .expect("Exception tables were validated on module load")
1153    }
1154
1155    /// Obtain a frame-table parser on this module's frame state slot
1156    /// (debug instrumentation) metadata.
1157    #[cfg(feature = "debug")]
1158    pub(crate) fn frame_table<'a>(&'a self) -> Option<FrameTable<'a>> {
1159        let data = self.inner.code.code_memory().frame_tables();
1160        if data.is_empty() {
1161            None
1162        } else {
1163            Some(FrameTable::parse(data).expect("Frame tables were validated on module load"))
1164        }
1165    }
1166}
1167
1168/// Describes a function for a given module.
1169pub struct ModuleFunction {
1170    pub index: wasmtime_environ::FuncIndex,
1171    pub name: Option<String>,
1172    pub offset: usize,
1173    pub len: usize,
1174}
1175
1176impl Drop for ModuleInner {
1177    fn drop(&mut self) {
1178        // When a `Module` is being dropped that means that it's no longer
1179        // present in any `Store` and it's additionally not longer held by any
1180        // embedder. Take this opportunity to purge any lingering instantiations
1181        // within a pooling instance allocator, if applicable.
1182        self.engine
1183            .allocator()
1184            .purge_module(self.module.unique_id());
1185    }
1186}
1187
1188/// Describes the location of an export in a module.
1189#[derive(Copy, Clone)]
1190pub struct ModuleExport {
1191    /// The module that this export is defined in.
1192    pub(crate) module: CompiledModuleId,
1193    /// A raw index into the wasm module.
1194    pub(crate) entity: EntityIndex,
1195}
1196
1197fn _assert_send_sync() {
1198    fn _assert<T: Send + Sync>() {}
1199    _assert::<Module>();
1200}
1201
1202/// Helper method to construct a `ModuleMemoryImages` for an associated
1203/// `CompiledModule`.
1204fn memory_images(inner: &Arc<ModuleInner>) -> Result<Option<ModuleMemoryImages>> {
1205    // If initialization via copy-on-write is explicitly disabled in
1206    // configuration then this path is skipped entirely.
1207    if !inner.engine.tunables().memory_init_cow {
1208        return Ok(None);
1209    }
1210
1211    // ... otherwise logic is delegated to the `ModuleMemoryImages::new`
1212    // constructor.
1213    ModuleMemoryImages::new(
1214        &inner.engine,
1215        inner.module.module(),
1216        inner.code.code_memory(),
1217    )
1218}
1219
1220impl crate::vm::ModuleMemoryImageSource for CodeMemory {
1221    fn wasm_data(&self) -> &[u8] {
1222        <Self>::wasm_data(self)
1223    }
1224
1225    fn mmap(&self) -> Option<&MmapVec> {
1226        Some(<Self>::mmap(self))
1227    }
1228}
1229
1230#[cfg(test)]
1231mod tests {
1232    use crate::{Engine, Module};
1233    use wasmtime_environ::MemoryInitialization;
1234
1235    #[test]
1236    fn cow_on_by_default() {
1237        let engine = Engine::default();
1238        let module = Module::new(
1239            &engine,
1240            r#"
1241                (module
1242                    (memory 1)
1243                    (data (i32.const 100) "abcd")
1244                )
1245            "#,
1246        )
1247        .unwrap();
1248
1249        let init = &module.env_module().memory_initialization;
1250        assert!(matches!(init, MemoryInitialization::Static { .. }));
1251    }
1252}