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