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}