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}