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