wasmtime/
engine.rs

1use crate::Config;
2use crate::prelude::*;
3#[cfg(feature = "runtime")]
4pub use crate::runtime::code_memory::CustomCodeMemory;
5#[cfg(feature = "runtime")]
6use crate::runtime::type_registry::TypeRegistry;
7#[cfg(feature = "runtime")]
8use crate::runtime::vm::GcRuntime;
9use alloc::sync::Arc;
10use core::ptr::NonNull;
11#[cfg(target_has_atomic = "64")]
12use core::sync::atomic::{AtomicU64, Ordering};
13#[cfg(any(feature = "cranelift", feature = "winch"))]
14use object::write::{Object, StandardSegment};
15#[cfg(feature = "std")]
16use std::{fs::File, path::Path};
17use wasmparser::WasmFeatures;
18use wasmtime_environ::{FlagValue, ObjectKind, TripleExt, Tunables};
19
20mod serialization;
21
22/// An `Engine` which is a global context for compilation and management of wasm
23/// modules.
24///
25/// An engine can be safely shared across threads and is a cheap cloneable
26/// handle to the actual engine. The engine itself will be deallocated once all
27/// references to it have gone away.
28///
29/// Engines store global configuration preferences such as compilation settings,
30/// enabled features, etc. You'll likely only need at most one of these for a
31/// program.
32///
33/// ## Engines and `Clone`
34///
35/// Using `clone` on an `Engine` is a cheap operation. It will not create an
36/// entirely new engine, but rather just a new reference to the existing engine.
37/// In other words it's a shallow copy, not a deep copy.
38///
39/// ## Engines and `Default`
40///
41/// You can create an engine with default configuration settings using
42/// `Engine::default()`. Be sure to consult the documentation of [`Config`] for
43/// default settings.
44#[derive(Clone)]
45pub struct Engine {
46    inner: Arc<EngineInner>,
47}
48
49struct EngineInner {
50    config: Config,
51    features: WasmFeatures,
52    tunables: Tunables,
53    #[cfg(any(feature = "cranelift", feature = "winch"))]
54    compiler: Box<dyn wasmtime_environ::Compiler>,
55    #[cfg(feature = "runtime")]
56    allocator: Box<dyn crate::runtime::vm::InstanceAllocator + Send + Sync>,
57    #[cfg(feature = "runtime")]
58    gc_runtime: Option<Arc<dyn GcRuntime>>,
59    #[cfg(feature = "runtime")]
60    profiler: Box<dyn crate::profiling_agent::ProfilingAgent>,
61    #[cfg(feature = "runtime")]
62    signatures: TypeRegistry,
63    #[cfg(all(feature = "runtime", target_has_atomic = "64"))]
64    epoch: AtomicU64,
65
66    /// One-time check of whether the compiler's settings, if present, are
67    /// compatible with the native host.
68    compatible_with_native_host: crate::sync::OnceLock<Result<(), String>>,
69}
70
71impl core::fmt::Debug for Engine {
72    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
73        f.debug_tuple("Engine")
74            .field(&Arc::as_ptr(&self.inner))
75            .finish()
76    }
77}
78
79impl Default for Engine {
80    fn default() -> Engine {
81        Engine::new(&Config::default()).unwrap()
82    }
83}
84
85impl Engine {
86    /// Creates a new [`Engine`] with the specified compilation and
87    /// configuration settings.
88    ///
89    /// # Errors
90    ///
91    /// This method can fail if the `config` is invalid or some
92    /// configurations are incompatible.
93    ///
94    /// For example, feature `reference_types` will need to set
95    /// the compiler setting `unwind_info` to `true`, but explicitly
96    /// disable these two compiler settings will cause errors.
97    pub fn new(config: &Config) -> Result<Engine> {
98        let config = config.clone();
99        let (mut tunables, features) = config.validate()?;
100
101        #[cfg(feature = "runtime")]
102        if tunables.signals_based_traps {
103            // Ensure that crate::runtime::vm's signal handlers are
104            // configured. This is the per-program initialization required for
105            // handling traps, such as configuring signals, vectored exception
106            // handlers, etc.
107            #[cfg(has_native_signals)]
108            crate::runtime::vm::init_traps(config.macos_use_mach_ports);
109            if !cfg!(miri) {
110                #[cfg(all(has_host_compiler_backend, feature = "debug-builtins"))]
111                crate::runtime::vm::debug_builtins::init();
112            }
113        }
114
115        #[cfg(any(feature = "cranelift", feature = "winch"))]
116        let (config, compiler) = config.build_compiler(&mut tunables, features)?;
117        #[cfg(not(any(feature = "cranelift", feature = "winch")))]
118        let _ = &mut tunables;
119
120        Ok(Engine {
121            inner: Arc::new(EngineInner {
122                #[cfg(any(feature = "cranelift", feature = "winch"))]
123                compiler,
124                #[cfg(feature = "runtime")]
125                allocator: {
126                    let allocator = config.build_allocator(&tunables)?;
127                    #[cfg(feature = "gc")]
128                    {
129                        let mem_ty = tunables.gc_heap_memory_type();
130                        allocator.validate_memory(&mem_ty).context(
131                            "instance allocator cannot support configured GC heap memory",
132                        )?;
133                    }
134                    allocator
135                },
136                #[cfg(feature = "runtime")]
137                gc_runtime: config.build_gc_runtime()?,
138                #[cfg(feature = "runtime")]
139                profiler: config.build_profiler()?,
140                #[cfg(feature = "runtime")]
141                signatures: TypeRegistry::new(),
142                #[cfg(all(feature = "runtime", target_has_atomic = "64"))]
143                epoch: AtomicU64::new(0),
144                compatible_with_native_host: Default::default(),
145                config,
146                tunables,
147                features,
148            }),
149        })
150    }
151
152    /// Returns the configuration settings that this engine is using.
153    #[inline]
154    pub fn config(&self) -> &Config {
155        &self.inner.config
156    }
157
158    #[inline]
159    pub(crate) fn features(&self) -> WasmFeatures {
160        self.inner.features
161    }
162
163    pub(crate) fn run_maybe_parallel<
164        A: Send,
165        B: Send,
166        E: Send,
167        F: Fn(A) -> Result<B, E> + Send + Sync,
168    >(
169        &self,
170        input: Vec<A>,
171        f: F,
172    ) -> Result<Vec<B>, E> {
173        if self.config().parallel_compilation {
174            #[cfg(feature = "parallel-compilation")]
175            {
176                use rayon::prelude::*;
177                // If we collect into Result<Vec<B>, E> directly, the returned error is not
178                // deterministic, because any error could be returned early. So we first materialize
179                // all results in order and then return the first error deterministically, or Ok(_).
180                return input
181                    .into_par_iter()
182                    .map(|a| f(a))
183                    .collect::<Vec<Result<B, E>>>()
184                    .into_iter()
185                    .collect::<Result<Vec<B>, E>>();
186            }
187        }
188
189        // In case the parallel-compilation feature is disabled or the parallel_compilation config
190        // was turned off dynamically fallback to the non-parallel version.
191        input
192            .into_iter()
193            .map(|a| f(a))
194            .collect::<Result<Vec<B>, E>>()
195    }
196
197    #[cfg(any(feature = "cranelift", feature = "winch"))]
198    pub(crate) fn run_maybe_parallel_mut<
199        T: Send,
200        E: Send,
201        F: Fn(&mut T) -> Result<(), E> + Send + Sync,
202    >(
203        &self,
204        input: &mut [T],
205        f: F,
206    ) -> Result<(), E> {
207        if self.config().parallel_compilation {
208            #[cfg(feature = "parallel-compilation")]
209            {
210                use rayon::prelude::*;
211                // If we collect into `Result<(), E>` directly, the returned
212                // error is not deterministic, because any error could be
213                // returned early. So we first materialize all results in order
214                // and then return the first error deterministically, or
215                // `Ok(_)`.
216                return input
217                    .into_par_iter()
218                    .map(|a| f(a))
219                    .collect::<Vec<Result<(), E>>>()
220                    .into_iter()
221                    .collect::<Result<(), E>>();
222            }
223        }
224
225        // In case the parallel-compilation feature is disabled or the
226        // parallel_compilation config was turned off dynamically fallback to
227        // the non-parallel version.
228        input.into_iter().map(|a| f(a)).collect::<Result<(), E>>()
229    }
230
231    /// Take a weak reference to this engine.
232    pub fn weak(&self) -> EngineWeak {
233        EngineWeak {
234            inner: Arc::downgrade(&self.inner),
235        }
236    }
237
238    #[inline]
239    pub(crate) fn tunables(&self) -> &Tunables {
240        &self.inner.tunables
241    }
242
243    /// Returns whether the engine `a` and `b` refer to the same configuration.
244    #[inline]
245    pub fn same(a: &Engine, b: &Engine) -> bool {
246        Arc::ptr_eq(&a.inner, &b.inner)
247    }
248
249    /// Returns whether the engine is configured to support async functions.
250    #[cfg(feature = "async")]
251    #[inline]
252    pub fn is_async(&self) -> bool {
253        self.config().async_support
254    }
255
256    /// Detects whether the bytes provided are a precompiled object produced by
257    /// Wasmtime.
258    ///
259    /// This function will inspect the header of `bytes` to determine if it
260    /// looks like a precompiled core wasm module or a precompiled component.
261    /// This does not validate the full structure or guarantee that
262    /// deserialization will succeed, instead it helps higher-levels of the
263    /// stack make a decision about what to do next when presented with the
264    /// `bytes` as an input module.
265    ///
266    /// If the `bytes` looks like a precompiled object previously produced by
267    /// [`Module::serialize`](crate::Module::serialize),
268    /// [`Component::serialize`](crate::component::Component::serialize),
269    /// [`Engine::precompile_module`], or [`Engine::precompile_component`], then
270    /// this will return `Some(...)` indicating so. Otherwise `None` is
271    /// returned.
272    pub fn detect_precompiled(bytes: &[u8]) -> Option<Precompiled> {
273        serialization::detect_precompiled_bytes(bytes)
274    }
275
276    /// Like [`Engine::detect_precompiled`], but performs the detection on a file.
277    #[cfg(feature = "std")]
278    pub fn detect_precompiled_file(path: impl AsRef<Path>) -> Result<Option<Precompiled>> {
279        serialization::detect_precompiled_file(path)
280    }
281
282    /// Returns the target triple which this engine is compiling code for
283    /// and/or running code for.
284    pub(crate) fn target(&self) -> target_lexicon::Triple {
285        return self.config().compiler_target();
286    }
287
288    /// Verify that this engine's configuration is compatible with loading
289    /// modules onto the native host platform.
290    ///
291    /// This method is used as part of `Module::new` to ensure that this
292    /// engine can indeed load modules for the configured compiler (if any).
293    /// Note that if cranelift is disabled this trivially returns `Ok` because
294    /// loaded serialized modules are checked separately.
295    pub(crate) fn check_compatible_with_native_host(&self) -> Result<()> {
296        self.inner
297            .compatible_with_native_host
298            .get_or_init(|| self._check_compatible_with_native_host())
299            .clone()
300            .map_err(anyhow::Error::msg)
301    }
302
303    fn _check_compatible_with_native_host(&self) -> Result<(), String> {
304        use target_lexicon::Triple;
305
306        let host = Triple::host();
307        let target = self.config().compiler_target();
308
309        let target_matches_host = || {
310            // If the host target and target triple match, then it's valid
311            // to run results of compilation on this host.
312            if host == target {
313                return true;
314            }
315
316            // If there's a mismatch and the target is a compatible pulley
317            // target, then that's also ok to run.
318            if cfg!(feature = "pulley")
319                && target.is_pulley()
320                && target.pointer_width() == host.pointer_width()
321                && target.endianness() == host.endianness()
322            {
323                return true;
324            }
325
326            // ... otherwise everything else is considered not a match.
327            false
328        };
329
330        if !target_matches_host() {
331            return Err(format!(
332                "target '{target}' specified in the configuration does not match the host"
333            ));
334        }
335
336        #[cfg(any(feature = "cranelift", feature = "winch"))]
337        {
338            let compiler = self.compiler();
339            // Also double-check all compiler settings
340            for (key, value) in compiler.flags().iter() {
341                self.check_compatible_with_shared_flag(key, value)?;
342            }
343            for (key, value) in compiler.isa_flags().iter() {
344                self.check_compatible_with_isa_flag(key, value)?;
345            }
346        }
347
348        // Double-check that this configuration isn't requesting capabilities
349        // that this build of Wasmtime doesn't support.
350        if !cfg!(has_native_signals) && self.tunables().signals_based_traps {
351            return Err("signals-based-traps disabled at compile time -- cannot be enabled".into());
352        }
353        if !cfg!(has_virtual_memory) && self.tunables().memory_init_cow {
354            return Err("virtual memory disabled at compile time -- cannot enable CoW".into());
355        }
356        if !cfg!(target_has_atomic = "64") && self.tunables().epoch_interruption {
357            return Err("epochs currently require 64-bit atomics".into());
358        }
359
360        // Double-check that the host's float ABI matches Cranelift's float ABI.
361        // See `Config::x86_float_abi_ok` for some more
362        // information.
363        if target == target_lexicon::triple!("x86_64-unknown-none")
364            && self.config().x86_float_abi_ok != Some(true)
365        {
366            return Err("\
367the x86_64-unknown-none target by default uses a soft-float ABI that is \
368incompatible with Cranelift and Wasmtime -- use \
369`Config::x86_float_abi_ok` to disable this check and see more \
370information about this check\
371"
372            .into());
373        }
374
375        Ok(())
376    }
377
378    /// Checks to see whether the "shared flag", something enabled for
379    /// individual compilers, is compatible with the native host platform.
380    ///
381    /// This is used both when validating an engine's compilation settings are
382    /// compatible with the host as well as when deserializing modules from
383    /// disk to ensure they're compatible with the current host.
384    ///
385    /// Note that most of the settings here are not configured by users that
386    /// often. While theoretically possible via `Config` methods the more
387    /// interesting flags are the ISA ones below. Typically the values here
388    /// represent global configuration for wasm features. Settings here
389    /// currently rely on the compiler informing us of all settings, including
390    /// those disabled. Settings then fall in a few buckets:
391    ///
392    /// * Some settings must be enabled, such as `preserve_frame_pointers`.
393    /// * Some settings must have a particular value, such as
394    ///   `libcall_call_conv`.
395    /// * Some settings do not matter as to their value, such as `opt_level`.
396    pub(crate) fn check_compatible_with_shared_flag(
397        &self,
398        flag: &str,
399        value: &FlagValue,
400    ) -> Result<(), String> {
401        let target = self.target();
402        let ok = match flag {
403            // These settings must all have be enabled, since their value
404            // can affect the way the generated code performs or behaves at
405            // runtime.
406            "libcall_call_conv" => *value == FlagValue::Enum("isa_default"),
407            "preserve_frame_pointers" => *value == FlagValue::Bool(true),
408            "enable_probestack" => *value == FlagValue::Bool(true),
409            "probestack_strategy" => *value == FlagValue::Enum("inline"),
410            "enable_multi_ret_implicit_sret" => *value == FlagValue::Bool(true),
411
412            // Features wasmtime doesn't use should all be disabled, since
413            // otherwise if they are enabled it could change the behavior of
414            // generated code.
415            "enable_llvm_abi_extensions" => *value == FlagValue::Bool(false),
416            "enable_pinned_reg" => *value == FlagValue::Bool(false),
417            "use_colocated_libcalls" => *value == FlagValue::Bool(false),
418            "use_pinned_reg_as_heap_base" => *value == FlagValue::Bool(false),
419
420            // Windows requires unwind info as part of its ABI.
421            "unwind_info" => {
422                if target.operating_system == target_lexicon::OperatingSystem::Windows {
423                    *value == FlagValue::Bool(true)
424                } else {
425                    return Ok(())
426                }
427            }
428
429            // stack switch model must match the current OS
430            "stack_switch_model" => {
431                if self.features().contains(WasmFeatures::STACK_SWITCHING) {
432                    use target_lexicon::OperatingSystem;
433                    let expected =
434                    match target.operating_system  {
435                        OperatingSystem::Windows => "update_windows_tib",
436                        OperatingSystem::Linux
437                        | OperatingSystem::MacOSX(_)
438                        | OperatingSystem::Darwin(_)  => "basic",
439                        _ => { return Err(String::from("stack-switching feature not supported on this platform")); }
440                    };
441                    *value == FlagValue::Enum(expected)
442                } else {
443                    return Ok(())
444                }
445            }
446
447            // These settings don't affect the interface or functionality of
448            // the module itself, so their configuration values shouldn't
449            // matter.
450            "enable_heap_access_spectre_mitigation"
451            | "enable_table_access_spectre_mitigation"
452            | "enable_nan_canonicalization"
453            | "enable_float"
454            | "enable_verifier"
455            | "enable_pcc"
456            | "regalloc_checker"
457            | "regalloc_verbose_logs"
458            | "regalloc_algorithm"
459            | "is_pic"
460            | "bb_padding_log2_minus_one"
461            | "log2_min_function_alignment"
462            | "machine_code_cfg_info"
463            | "tls_model" // wasmtime doesn't use tls right now
464            | "opt_level" // opt level doesn't change semantics
465            | "enable_alias_analysis" // alias analysis-based opts don't change semantics
466            | "probestack_size_log2" // probestack above asserted disabled
467            | "regalloc" // shouldn't change semantics
468            | "enable_incremental_compilation_cache_checks" // shouldn't change semantics
469            | "enable_atomics" => return Ok(()),
470
471            // Everything else is unknown and needs to be added somewhere to
472            // this list if encountered.
473            _ => {
474                return Err(format!("unknown shared setting {flag:?} configured to {value:?}"))
475            }
476        };
477
478        if !ok {
479            return Err(format!(
480                "setting {flag:?} is configured to {value:?} which is not supported",
481            ));
482        }
483        Ok(())
484    }
485
486    /// Same as `check_compatible_with_native_host` except used for ISA-specific
487    /// flags. This is used to test whether a configured ISA flag is indeed
488    /// available on the host platform itself.
489    pub(crate) fn check_compatible_with_isa_flag(
490        &self,
491        flag: &str,
492        value: &FlagValue,
493    ) -> Result<(), String> {
494        match value {
495            // ISA flags are used for things like CPU features, so if they're
496            // disabled then it's compatible with the native host.
497            FlagValue::Bool(false) => return Ok(()),
498
499            // Fall through below where we test at runtime that features are
500            // available.
501            FlagValue::Bool(true) => {}
502
503            // Pulley's pointer_width must match the host.
504            FlagValue::Enum("pointer32") => {
505                return if cfg!(target_pointer_width = "32") {
506                    Ok(())
507                } else {
508                    Err("wrong host pointer width".to_string())
509                };
510            }
511            FlagValue::Enum("pointer64") => {
512                return if cfg!(target_pointer_width = "64") {
513                    Ok(())
514                } else {
515                    Err("wrong host pointer width".to_string())
516                };
517            }
518
519            // Only `bool` values are supported right now, other settings would
520            // need more support here.
521            _ => {
522                return Err(format!(
523                    "isa-specific feature {flag:?} configured to unknown value {value:?}"
524                ));
525            }
526        }
527
528        let host_feature = match flag {
529            // aarch64 features to detect
530            "has_lse" => "lse",
531            "has_pauth" => "paca",
532            "has_fp16" => "fp16",
533
534            // aarch64 features which don't need detection
535            // No effect on its own.
536            "sign_return_address_all" => return Ok(()),
537            // The pointer authentication instructions act as a `NOP` when
538            // unsupported, so it is safe to enable them.
539            "sign_return_address" => return Ok(()),
540            // No effect on its own.
541            "sign_return_address_with_bkey" => return Ok(()),
542            // The `BTI` instruction acts as a `NOP` when unsupported, so it
543            // is safe to enable it regardless of whether the host supports it
544            // or not.
545            "use_bti" => return Ok(()),
546
547            // s390x features to detect
548            "has_vxrs_ext2" => "vxrs_ext2",
549            "has_vxrs_ext3" => "vxrs_ext3",
550            "has_mie3" => "mie3",
551            "has_mie4" => "mie4",
552
553            // x64 features to detect
554            "has_cmpxchg16b" => "cmpxchg16b",
555            "has_sse3" => "sse3",
556            "has_ssse3" => "ssse3",
557            "has_sse41" => "sse4.1",
558            "has_sse42" => "sse4.2",
559            "has_popcnt" => "popcnt",
560            "has_avx" => "avx",
561            "has_avx2" => "avx2",
562            "has_fma" => "fma",
563            "has_bmi1" => "bmi1",
564            "has_bmi2" => "bmi2",
565            "has_avx512bitalg" => "avx512bitalg",
566            "has_avx512dq" => "avx512dq",
567            "has_avx512f" => "avx512f",
568            "has_avx512vl" => "avx512vl",
569            "has_avx512vbmi" => "avx512vbmi",
570            "has_lzcnt" => "lzcnt",
571
572            // pulley features
573            "big_endian" if cfg!(target_endian = "big") => return Ok(()),
574            "big_endian" if cfg!(target_endian = "little") => {
575                return Err("wrong host endianness".to_string());
576            }
577
578            _ => {
579                // FIXME: should enumerate risc-v features and plumb them
580                // through to the `detect_host_feature` function.
581                if cfg!(target_arch = "riscv64") && flag != "not_a_flag" {
582                    return Ok(());
583                }
584                return Err(format!(
585                    "don't know how to test for target-specific flag {flag:?} at runtime"
586                ));
587            }
588        };
589
590        let detect = match self.config().detect_host_feature {
591            Some(detect) => detect,
592            None => {
593                return Err(format!(
594                    "cannot determine if host feature {host_feature:?} is \
595                     available at runtime, configure a probing function with \
596                     `Config::detect_host_feature`"
597                ));
598            }
599        };
600
601        match detect(host_feature) {
602            Some(true) => Ok(()),
603            Some(false) => Err(format!(
604                "compilation setting {flag:?} is enabled, but not \
605                 available on the host",
606            )),
607            None => Err(format!(
608                "failed to detect if target-specific flag {host_feature:?} is \
609                 available at runtime (compile setting {flag:?})"
610            )),
611        }
612    }
613
614    /// Returns whether this [`Engine`] is configured to execute with Pulley,
615    /// Wasmtime's interpreter.
616    ///
617    /// Note that Pulley is the default for host platforms that do not have a
618    /// Cranelift backend to support them. For example at the time of this
619    /// writing 32-bit x86 is not supported in Cranelift so the
620    /// `i686-unknown-linux-gnu` target would by default return `true` here.
621    pub fn is_pulley(&self) -> bool {
622        self.target().is_pulley()
623    }
624}
625
626#[cfg(any(feature = "cranelift", feature = "winch"))]
627impl Engine {
628    pub(crate) fn compiler(&self) -> &dyn wasmtime_environ::Compiler {
629        &*self.inner.compiler
630    }
631
632    /// Ahead-of-time (AOT) compiles a WebAssembly module.
633    ///
634    /// The `bytes` provided must be in one of two formats:
635    ///
636    /// * A [binary-encoded][binary] WebAssembly module. This is always supported.
637    /// * A [text-encoded][text] instance of the WebAssembly text format.
638    ///   This is only supported when the `wat` feature of this crate is enabled.
639    ///   If this is supplied then the text format will be parsed before validation.
640    ///   Note that the `wat` feature is enabled by default.
641    ///
642    /// This method may be used to compile a module for use with a different target
643    /// host. The output of this method may be used with
644    /// [`Module::deserialize`](crate::Module::deserialize) on hosts compatible
645    /// with the [`Config`](crate::Config) associated with this [`Engine`].
646    ///
647    /// The output of this method is safe to send to another host machine for later
648    /// execution. As the output is already a compiled module, translation and code
649    /// generation will be skipped and this will improve the performance of constructing
650    /// a [`Module`](crate::Module) from the output of this method.
651    ///
652    /// [binary]: https://webassembly.github.io/spec/core/binary/index.html
653    /// [text]: https://webassembly.github.io/spec/core/text/index.html
654    pub fn precompile_module(&self, bytes: &[u8]) -> Result<Vec<u8>> {
655        crate::CodeBuilder::new(self)
656            .wasm_binary_or_text(bytes, None)?
657            .compile_module_serialized()
658    }
659
660    /// Same as [`Engine::precompile_module`] except for a
661    /// [`Component`](crate::component::Component)
662    #[cfg(feature = "component-model")]
663    pub fn precompile_component(&self, bytes: &[u8]) -> Result<Vec<u8>> {
664        crate::CodeBuilder::new(self)
665            .wasm_binary_or_text(bytes, None)?
666            .compile_component_serialized()
667    }
668
669    /// Produces a blob of bytes by serializing the `engine`'s configuration data to
670    /// be checked, perhaps in a different process, with the `check_compatible`
671    /// method below.
672    ///
673    /// The blob of bytes is inserted into the object file specified to become part
674    /// of the final compiled artifact.
675    pub(crate) fn append_compiler_info(&self, obj: &mut Object<'_>) {
676        serialization::append_compiler_info(self, obj, &serialization::Metadata::new(&self))
677    }
678
679    #[cfg(any(feature = "cranelift", feature = "winch"))]
680    pub(crate) fn append_bti(&self, obj: &mut Object<'_>) {
681        let section = obj.add_section(
682            obj.segment_name(StandardSegment::Data).to_vec(),
683            wasmtime_environ::obj::ELF_WASM_BTI.as_bytes().to_vec(),
684            object::SectionKind::ReadOnlyData,
685        );
686        let contents = if self.compiler().is_branch_protection_enabled() {
687            1
688        } else {
689            0
690        };
691        obj.append_section_data(section, &[contents], 1);
692    }
693}
694
695/// Return value from the [`Engine::detect_precompiled`] API.
696#[derive(PartialEq, Eq, Copy, Clone, Debug)]
697pub enum Precompiled {
698    /// The input bytes look like a precompiled core wasm module.
699    Module,
700    /// The input bytes look like a precompiled wasm component.
701    Component,
702}
703
704#[cfg(feature = "runtime")]
705impl Engine {
706    /// Eagerly initialize thread-local functionality shared by all [`Engine`]s.
707    ///
708    /// Wasmtime's implementation on some platforms may involve per-thread
709    /// setup that needs to happen whenever WebAssembly is invoked. This setup
710    /// can take on the order of a few hundred microseconds, whereas the
711    /// overhead of calling WebAssembly is otherwise on the order of a few
712    /// nanoseconds. This setup cost is paid once per-OS-thread. If your
713    /// application is sensitive to the latencies of WebAssembly function
714    /// calls, even those that happen first on a thread, then this function
715    /// can be used to improve the consistency of each call into WebAssembly
716    /// by explicitly frontloading the cost of the one-time setup per-thread.
717    ///
718    /// Note that this function is not required to be called in any embedding.
719    /// Wasmtime will automatically initialize thread-local-state as necessary
720    /// on calls into WebAssembly. This is provided for use cases where the
721    /// latency of WebAssembly calls are extra-important, which is not
722    /// necessarily true of all embeddings.
723    pub fn tls_eager_initialize() {
724        crate::runtime::vm::tls_eager_initialize();
725    }
726
727    /// Returns a [`PoolingAllocatorMetrics`](crate::PoolingAllocatorMetrics) if
728    /// this engine was configured with
729    /// [`InstanceAllocationStrategy::Pooling`](crate::InstanceAllocationStrategy::Pooling).
730    #[cfg(feature = "pooling-allocator")]
731    pub fn pooling_allocator_metrics(&self) -> Option<crate::vm::PoolingAllocatorMetrics> {
732        crate::runtime::vm::PoolingAllocatorMetrics::new(self)
733    }
734
735    pub(crate) fn allocator(&self) -> &dyn crate::runtime::vm::InstanceAllocator {
736        self.inner.allocator.as_ref()
737    }
738
739    pub(crate) fn gc_runtime(&self) -> Option<&Arc<dyn GcRuntime>> {
740        self.inner.gc_runtime.as_ref()
741    }
742
743    pub(crate) fn profiler(&self) -> &dyn crate::profiling_agent::ProfilingAgent {
744        self.inner.profiler.as_ref()
745    }
746
747    #[cfg(all(feature = "cache", any(feature = "cranelift", feature = "winch")))]
748    pub(crate) fn cache(&self) -> Option<&wasmtime_cache::Cache> {
749        self.config().cache.as_ref()
750    }
751
752    pub(crate) fn signatures(&self) -> &TypeRegistry {
753        &self.inner.signatures
754    }
755
756    #[cfg(feature = "runtime")]
757    pub(crate) fn custom_code_memory(&self) -> Option<&Arc<dyn CustomCodeMemory>> {
758        self.config().custom_code_memory.as_ref()
759    }
760
761    #[cfg(target_has_atomic = "64")]
762    pub(crate) fn epoch_counter(&self) -> &AtomicU64 {
763        &self.inner.epoch
764    }
765
766    #[cfg(target_has_atomic = "64")]
767    pub(crate) fn current_epoch(&self) -> u64 {
768        self.epoch_counter().load(Ordering::Relaxed)
769    }
770
771    /// Increments the epoch.
772    ///
773    /// When using epoch-based interruption, currently-executing Wasm
774    /// code within this engine will trap or yield "soon" when the
775    /// epoch deadline is reached or exceeded. (The configuration, and
776    /// the deadline, are set on the `Store`.) The intent of the
777    /// design is for this method to be called by the embedder at some
778    /// regular cadence, for example by a thread that wakes up at some
779    /// interval, or by a signal handler.
780    ///
781    /// See [`Config::epoch_interruption`](crate::Config::epoch_interruption)
782    /// for an introduction to epoch-based interruption and pointers
783    /// to the other relevant methods.
784    ///
785    /// When performing `increment_epoch` in a separate thread, consider using
786    /// [`Engine::weak`] to hold an [`EngineWeak`](crate::EngineWeak) and
787    /// performing [`EngineWeak::upgrade`](crate::EngineWeak::upgrade) on each
788    /// tick, so that the epoch ticking thread does not keep an [`Engine`] alive
789    /// longer than any of its consumers.
790    ///
791    /// ## Signal Safety
792    ///
793    /// This method is signal-safe: it does not make any syscalls, and
794    /// performs only an atomic increment to the epoch value in
795    /// memory.
796    #[cfg(target_has_atomic = "64")]
797    pub fn increment_epoch(&self) {
798        self.inner.epoch.fetch_add(1, Ordering::Relaxed);
799    }
800
801    /// Returns a [`std::hash::Hash`] that can be used to check precompiled WebAssembly compatibility.
802    ///
803    /// The outputs of [`Engine::precompile_module`] and [`Engine::precompile_component`]
804    /// are compatible with a different [`Engine`] instance only if the two engines use
805    /// compatible [`Config`]s. If this Hash matches between two [`Engine`]s then binaries
806    /// from one are guaranteed to deserialize in the other.
807    #[cfg(any(feature = "cranelift", feature = "winch"))]
808    pub fn precompile_compatibility_hash(&self) -> impl std::hash::Hash + '_ {
809        crate::compile::HashedEngineCompileEnv(self)
810    }
811
812    /// Returns the required alignment for a code image, if we
813    /// allocate in a way that is not a system `mmap()` that naturally
814    /// aligns it.
815    fn required_code_alignment(&self) -> usize {
816        self.custom_code_memory()
817            .map(|c| c.required_alignment())
818            .unwrap_or(1)
819    }
820
821    /// Loads a `CodeMemory` from the specified in-memory slice, copying it to a
822    /// uniquely owned mmap.
823    ///
824    /// The `expected` marker here is whether the bytes are expected to be a
825    /// precompiled module or a component.
826    pub(crate) fn load_code_bytes(
827        &self,
828        bytes: &[u8],
829        expected: ObjectKind,
830    ) -> Result<Arc<crate::CodeMemory>> {
831        self.load_code(
832            crate::runtime::vm::MmapVec::from_slice_with_alignment(
833                bytes,
834                self.required_code_alignment(),
835            )?,
836            expected,
837        )
838    }
839
840    /// Loads a `CodeMemory` from the specified memory region without copying
841    ///
842    /// The `expected` marker here is whether the bytes are expected to be
843    /// a precompiled module or a component.  The `memory` provided is expected
844    /// to be a serialized module (.cwasm) generated by `[Module::serialize]`
845    /// or [`Engine::precompile_module] or their `Component` counterparts
846    /// [`Component::serialize`] or `[Engine::precompile_component]`.
847    ///
848    /// The memory provided is guaranteed to only be immutably by the runtime.
849    ///
850    /// # Safety
851    ///
852    /// As there is no copy here, the runtime will be making direct readonly use
853    /// of the provided memory. As such, outside writes to this memory region
854    /// will result in undefined and likely very undesirable behavior.
855    pub(crate) unsafe fn load_code_raw(
856        &self,
857        memory: NonNull<[u8]>,
858        expected: ObjectKind,
859    ) -> Result<Arc<crate::CodeMemory>> {
860        // SAFETY: the contract of this function is the same as that of
861        // `from_raw`.
862        unsafe { self.load_code(crate::runtime::vm::MmapVec::from_raw(memory)?, expected) }
863    }
864
865    /// Like `load_code_bytes`, but creates a mmap from a file on disk.
866    #[cfg(feature = "std")]
867    pub(crate) fn load_code_file(
868        &self,
869        file: File,
870        expected: ObjectKind,
871    ) -> Result<Arc<crate::CodeMemory>> {
872        self.load_code(
873            crate::runtime::vm::MmapVec::from_file(file)
874                .with_context(|| "Failed to create file mapping".to_string())?,
875            expected,
876        )
877    }
878
879    pub(crate) fn load_code(
880        &self,
881        mmap: crate::runtime::vm::MmapVec,
882        expected: ObjectKind,
883    ) -> Result<Arc<crate::CodeMemory>> {
884        self.check_compatible_with_native_host()
885            .context("compilation settings are not compatible with the native host")?;
886
887        serialization::check_compatible(self, &mmap, expected)?;
888        let mut code = crate::CodeMemory::new(self, mmap)?;
889        code.publish()?;
890        Ok(Arc::new(code))
891    }
892
893    /// Unload process-related trap/signal handlers and destroy this engine.
894    ///
895    /// This method is not safe and is not widely applicable. It is not required
896    /// to be called and is intended for use cases such as unloading a dynamic
897    /// library from a process. It is difficult to invoke this method correctly
898    /// and it requires careful coordination to do so.
899    ///
900    /// # Panics
901    ///
902    /// This method will panic if this `Engine` handle is not the last remaining
903    /// engine handle.
904    ///
905    /// # Aborts
906    ///
907    /// This method will abort the process on some platforms in some situations
908    /// where unloading the handler cannot be performed and an unrecoverable
909    /// state is reached. For example on Unix platforms with signal handling
910    /// the process will be aborted if the current signal handlers are not
911    /// Wasmtime's.
912    ///
913    /// # Unsafety
914    ///
915    /// This method is not generally safe to call and has a number of
916    /// preconditions that must be met to even possibly be safe. Even with these
917    /// known preconditions met there may be other unknown invariants to uphold
918    /// as well.
919    ///
920    /// * There must be no other instances of `Engine` elsewhere in the process.
921    ///   Note that this isn't just copies of this `Engine` but it's any other
922    ///   `Engine` at all. This unloads global state that is used by all
923    ///   `Engine`s so this instance must be the last.
924    ///
925    /// * On Unix platforms no other signal handlers could have been installed
926    ///   for signals that Wasmtime catches. In this situation Wasmtime won't
927    ///   know how to restore signal handlers that Wasmtime possibly overwrote
928    ///   when Wasmtime was initially loaded. If possible initialize other
929    ///   libraries first and then initialize Wasmtime last (e.g. defer creating
930    ///   an `Engine`).
931    ///
932    /// * All existing threads which have used this DLL or copy of Wasmtime may
933    ///   no longer use this copy of Wasmtime. Per-thread state is not iterated
934    ///   and destroyed. Only future threads may use future instances of this
935    ///   Wasmtime itself.
936    ///
937    /// If other crashes are seen from using this method please feel free to
938    /// file an issue to update the documentation here with more preconditions
939    /// that must be met.
940    #[cfg(has_native_signals)]
941    pub unsafe fn unload_process_handlers(self) {
942        assert_eq!(Arc::weak_count(&self.inner), 0);
943        assert_eq!(Arc::strong_count(&self.inner), 1);
944
945        // SAFETY: the contract of this function is the same as `deinit_traps`.
946        #[cfg(not(miri))]
947        unsafe {
948            crate::runtime::vm::deinit_traps();
949        }
950    }
951}
952
953/// A weak reference to an [`Engine`].
954#[derive(Clone)]
955pub struct EngineWeak {
956    inner: alloc::sync::Weak<EngineInner>,
957}
958
959impl EngineWeak {
960    /// Upgrade this weak reference into an [`Engine`]. Returns `None` if
961    /// strong references (the [`Engine`] type itself) no longer exist.
962    pub fn upgrade(&self) -> Option<Engine> {
963        alloc::sync::Weak::upgrade(&self.inner).map(|inner| Engine { inner })
964    }
965}