wasmtime/config.rs
1use crate::Engine;
2use crate::prelude::*;
3use alloc::sync::Arc;
4use bitflags::Flags;
5use core::fmt;
6use core::num::{NonZeroU32, NonZeroUsize};
7use core::str::FromStr;
8#[cfg(any(feature = "cranelift", feature = "winch"))]
9use std::path::Path;
10pub use wasmparser::WasmFeatures;
11#[cfg(any(feature = "cranelift", feature = "winch"))]
12use wasmtime_environ::FlagValue;
13use wasmtime_environ::{ConfigTunables, OperatorCost, OperatorCostStrategy, TripleExt, Tunables};
14
15#[cfg(feature = "runtime")]
16use crate::memory::MemoryCreator;
17#[cfg(feature = "runtime")]
18use crate::profiling_agent::{self, ProfilingAgent};
19#[cfg(feature = "runtime")]
20use crate::runtime::vm::{GcRuntime, InstanceAllocator, OnDemandInstanceAllocator};
21
22#[cfg(feature = "async")]
23use crate::stack::{StackCreator, StackCreatorProxy};
24#[cfg(feature = "async")]
25use wasmtime_fiber::RuntimeFiberStackCreator;
26
27#[cfg(feature = "runtime")]
28pub use crate::runtime::code_memory::CustomCodeMemory;
29#[cfg(feature = "cache")]
30pub use wasmtime_cache::{Cache, CacheConfig};
31#[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
32pub use wasmtime_environ::CacheStore;
33pub use wasmtime_environ::Inlining;
34
35pub(crate) const DEFAULT_WASM_BACKTRACE_MAX_FRAMES: NonZeroUsize = NonZeroUsize::new(20).unwrap();
36
37/// Represents the module instance allocation strategy to use.
38#[derive(Clone)]
39#[non_exhaustive]
40pub enum InstanceAllocationStrategy {
41 /// The on-demand instance allocation strategy.
42 ///
43 /// Resources related to a module instance are allocated at instantiation time and
44 /// immediately deallocated when the `Store` referencing the instance is dropped.
45 ///
46 /// This is the default allocation strategy for Wasmtime.
47 OnDemand,
48 /// The pooling instance allocation strategy.
49 ///
50 /// A pool of resources is created in advance and module instantiation reuses resources
51 /// from the pool. Resources are returned to the pool when the `Store` referencing the instance
52 /// is dropped.
53 ///
54 /// When GC is enabled, the pooling allocator requires that the GC heap
55 /// configuration matches the linear memory configuration (i.e.,
56 /// `gc_heap_reservation` must equal `memory_reservation`, etc.). By
57 /// default, if no `gc_heap_*` tunables are explicitly configured, they
58 /// automatically inherit the `memory_*` values.
59 #[cfg(feature = "pooling-allocator")]
60 Pooling(PoolingAllocationConfig),
61}
62
63impl InstanceAllocationStrategy {
64 /// The default pooling instance allocation strategy.
65 #[cfg(feature = "pooling-allocator")]
66 pub fn pooling() -> Self {
67 Self::Pooling(Default::default())
68 }
69}
70
71impl Default for InstanceAllocationStrategy {
72 fn default() -> Self {
73 Self::OnDemand
74 }
75}
76
77#[cfg(feature = "pooling-allocator")]
78impl From<PoolingAllocationConfig> for InstanceAllocationStrategy {
79 fn from(cfg: PoolingAllocationConfig) -> InstanceAllocationStrategy {
80 InstanceAllocationStrategy::Pooling(cfg)
81 }
82}
83
84#[derive(Clone)]
85/// Configure the strategy used for versioning in serializing and deserializing [`crate::Module`].
86pub enum ModuleVersionStrategy {
87 /// Use the wasmtime crate's Cargo package version.
88 WasmtimeVersion,
89 /// Use a custom version string. Must be at most 255 bytes.
90 Custom(String),
91 /// Emit no version string in serialization, and accept all version strings in deserialization.
92 None,
93}
94
95impl Default for ModuleVersionStrategy {
96 fn default() -> Self {
97 ModuleVersionStrategy::WasmtimeVersion
98 }
99}
100
101impl core::hash::Hash for ModuleVersionStrategy {
102 fn hash<H: core::hash::Hasher>(&self, hasher: &mut H) {
103 match self {
104 Self::WasmtimeVersion => env!("CARGO_PKG_VERSION").hash(hasher),
105 Self::Custom(s) => s.hash(hasher),
106 Self::None => {}
107 };
108 }
109}
110
111impl ModuleVersionStrategy {
112 /// Get the string-encoding version of the module.
113 pub fn as_str(&self) -> &str {
114 match &self {
115 Self::WasmtimeVersion => env!("CARGO_PKG_VERSION_MAJOR"),
116 Self::Custom(c) => c,
117 Self::None => "",
118 }
119 }
120}
121
122/// Configuration for record/replay
123#[derive(Clone)]
124#[non_exhaustive]
125pub enum RRConfig {
126 #[cfg(feature = "rr")]
127 /// Recording on store is enabled
128 Recording,
129 #[cfg(feature = "rr")]
130 /// Replaying on store is enabled
131 Replaying,
132 /// No record/replay is enabled
133 None,
134}
135
136/// Global configuration options used to create an [`Engine`]
137/// and customize its behavior.
138///
139/// This structure exposed a builder-like interface and is primarily consumed by
140/// [`Engine::new()`].
141///
142/// The validation of `Config` is deferred until the engine is being built, thus
143/// a problematic config may cause [`Engine::new`] to fail.
144///
145/// # Defaults
146///
147/// The `Default` trait implementation and the return value from
148/// [`Config::new()`] are the same and represent the default set of
149/// configuration for an engine. The exact set of defaults will differ based on
150/// properties such as enabled Cargo features at compile time and the configured
151/// target (see [`Config::target`]). Configuration options document their
152/// default values and what the conditional value of the default is where
153/// applicable.
154#[derive(Clone)]
155pub struct Config {
156 #[cfg(any(feature = "cranelift", feature = "winch"))]
157 compiler_config: Option<CompilerConfig>,
158 target: Option<target_lexicon::Triple>,
159 #[cfg(feature = "gc")]
160 collector: Collector,
161 profiling_strategy: ProfilingStrategy,
162 tunables: ConfigTunables,
163
164 #[cfg(feature = "cache")]
165 pub(crate) cache: Option<Cache>,
166 #[cfg(feature = "runtime")]
167 pub(crate) mem_creator: Option<Arc<dyn MemoryCreator>>,
168 #[cfg(feature = "runtime")]
169 pub(crate) custom_code_memory: Option<Arc<dyn CustomCodeMemory>>,
170 pub(crate) allocation_strategy: InstanceAllocationStrategy,
171 pub(crate) max_wasm_stack: usize,
172 /// Explicitly enabled features via `Config::wasm_*` methods. This is a
173 /// signal that the embedder specifically wants something turned on
174 /// regardless of the defaults that Wasmtime might otherwise have enabled.
175 ///
176 /// Note that this, and `disabled_features` below, start as the empty set of
177 /// features to only track explicit user requests.
178 pub(crate) enabled_features: WasmFeatures,
179 /// Same as `enabled_features`, but for those that are explicitly disabled.
180 pub(crate) disabled_features: WasmFeatures,
181 pub(crate) wasm_backtrace_details_env_used: bool,
182 pub(crate) wasm_backtrace_max_frames: Option<NonZeroUsize>,
183 pub(crate) native_unwind_info: Option<bool>,
184 pub(crate) async_stack_size: usize,
185 pub(crate) async_stack_zeroing: bool,
186 #[cfg(feature = "async")]
187 pub(crate) stack_creator: Option<Arc<dyn RuntimeFiberStackCreator>>,
188 pub(crate) module_version: ModuleVersionStrategy,
189 pub(crate) parallel_compilation: bool,
190 pub(crate) memory_guaranteed_dense_image_size: u64,
191 pub(crate) force_memory_init_memfd: bool,
192 pub(crate) wmemcheck: bool,
193 #[cfg(feature = "coredump")]
194 pub(crate) coredump_on_trap: bool,
195 pub(crate) macos_use_mach_ports: bool,
196 pub(crate) detect_host_feature: Option<fn(&str) -> Option<bool>>,
197 pub(crate) x86_float_abi_ok: Option<bool>,
198 pub(crate) shared_memory: bool,
199 pub(crate) rr_config: RRConfig,
200}
201
202/// User-provided configuration for the compiler.
203#[cfg(any(feature = "cranelift", feature = "winch"))]
204#[derive(Debug, Clone)]
205struct CompilerConfig {
206 strategy: Option<Strategy>,
207 settings: crate::hash_map::HashMap<String, (String, UserSpecified)>,
208 flags: crate::hash_map::HashMap<String, UserSpecified>,
209 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
210 cache_store: Option<Arc<dyn CacheStore>>,
211 clif_dir: Option<std::path::PathBuf>,
212 wmemcheck: bool,
213}
214
215#[cfg(any(feature = "cranelift", feature = "winch"))]
216#[derive(Debug, Clone)]
217enum UserSpecified {
218 Yes,
219 No,
220}
221
222#[cfg(any(feature = "cranelift", feature = "winch"))]
223impl CompilerConfig {
224 fn new() -> Self {
225 Self {
226 strategy: Strategy::Auto.not_auto(),
227 settings: Default::default(),
228 flags: Default::default(),
229 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
230 cache_store: None,
231 clif_dir: None,
232 wmemcheck: false,
233 }
234 }
235
236 /// Ensures that the key is not set or equals to the given value.
237 /// If the key is not set, it will be set to the given value.
238 ///
239 /// # Returns
240 ///
241 /// Returns true if successfully set or already had the given setting
242 /// value, or false if the setting was explicitly set to something
243 /// else previously.
244 fn ensure_setting_unset_or_given(&mut self, k: &str, v: &str) -> bool {
245 if let Some((value, _)) = self.settings.get(k) {
246 if value != v {
247 return false;
248 }
249 } else {
250 self.settings
251 .insert(k.to_string(), (v.to_string(), UserSpecified::No));
252 }
253 true
254 }
255}
256
257#[cfg(any(feature = "cranelift", feature = "winch"))]
258impl Default for CompilerConfig {
259 fn default() -> Self {
260 Self::new()
261 }
262}
263
264impl Config {
265 /// Creates a new configuration object with the default configuration
266 /// specified.
267 pub fn new() -> Self {
268 let mut ret = Self {
269 tunables: ConfigTunables::default(),
270 #[cfg(any(feature = "cranelift", feature = "winch"))]
271 compiler_config: Some(CompilerConfig::default()),
272 target: None,
273 #[cfg(feature = "gc")]
274 collector: Collector::default(),
275 #[cfg(feature = "cache")]
276 cache: None,
277 profiling_strategy: ProfilingStrategy::None,
278 #[cfg(feature = "runtime")]
279 mem_creator: None,
280 #[cfg(feature = "runtime")]
281 custom_code_memory: None,
282 allocation_strategy: InstanceAllocationStrategy::OnDemand,
283 // 512k of stack -- note that this is chosen currently to not be too
284 // big, not be too small, and be a good default for most platforms.
285 // One platform of particular note is Windows where the stack size
286 // of the main thread seems to, by default, be smaller than that of
287 // Linux and macOS. This 512k value at least lets our current test
288 // suite pass on the main thread of Windows (using `--test-threads
289 // 1` forces this), or at least it passed when this change was
290 // committed.
291 max_wasm_stack: 512 * 1024,
292 wasm_backtrace_details_env_used: false,
293 wasm_backtrace_max_frames: Some(DEFAULT_WASM_BACKTRACE_MAX_FRAMES),
294 native_unwind_info: None,
295 enabled_features: WasmFeatures::empty(),
296 disabled_features: WasmFeatures::empty(),
297 async_stack_size: 2 << 20,
298 async_stack_zeroing: false,
299 #[cfg(feature = "async")]
300 stack_creator: None,
301 module_version: ModuleVersionStrategy::default(),
302 parallel_compilation: !cfg!(miri),
303 memory_guaranteed_dense_image_size: 16 << 20,
304 force_memory_init_memfd: false,
305 wmemcheck: false,
306 #[cfg(feature = "coredump")]
307 coredump_on_trap: false,
308 // Disable mach ports on miri since it doesn't emulate those APIs,
309 // and additionally disable it with ASAN by default because
310 // otherwise mach ports routes around signal handlers installed by
311 // ASAN.
312 macos_use_mach_ports: !cfg!(miri) && !cfg!(asan),
313 #[cfg(feature = "std")]
314 detect_host_feature: Some(detect_host_feature),
315 #[cfg(not(feature = "std"))]
316 detect_host_feature: None,
317 x86_float_abi_ok: None,
318 shared_memory: false,
319 rr_config: RRConfig::None,
320 };
321 ret.wasm_backtrace_details(WasmBacktraceDetails::Environment);
322 ret
323 }
324
325 #[cfg(any(feature = "cranelift", feature = "winch"))]
326 pub(crate) fn has_compiler(&self) -> bool {
327 self.compiler_config.is_some()
328 }
329
330 #[track_caller]
331 #[cfg(any(feature = "cranelift", feature = "winch"))]
332 fn compiler_config_mut(&mut self) -> &mut CompilerConfig {
333 self.compiler_config.as_mut().expect(
334 "cannot configure compiler settings for `Config`s \
335 created by `Config::without_compiler`",
336 )
337 }
338
339 /// Configure whether Wasm compilation is enabled.
340 ///
341 /// Disabling Wasm compilation will allow you to load and run
342 /// [pre-compiled][Engine::precompile_module] Wasm programs, but not
343 /// to compile and run new Wasm programs that have not already been
344 /// pre-compiled.
345 ///
346 /// Many compilation-related configuration methods will panic if compilation
347 /// has been disabled.
348 ///
349 /// Note that there are two ways to disable Wasm compilation:
350 ///
351 /// 1. Statically, by disabling the `"cranelift"` and `"winch"` cargo
352 /// features when building Wasmtime. These builds of Wasmtime will have
353 /// smaller code size, since they do not include any of the code to
354 /// compile Wasm.
355 ///
356 /// 2. Dynamically, by passing `false` to this method at run-time when
357 /// configuring Wasmtime. The Wasmtime binary will still include the code
358 /// for compiling Wasm, it just won't be executed, so code size is larger
359 /// than with the first approach.
360 ///
361 /// The static approach is better in most cases, however dynamically calling
362 /// `enable_compiler(false)` is useful whenever you create multiple
363 /// [`Engine`]s in the same process, some of which must be able to compile
364 /// Wasm and some of which should never do so. Tests are a common example of
365 /// such a situation, especially when there are multiple Rust binaries in
366 /// the same cargo workspace, and cargo's feature resolution enables the
367 /// `"cranelift"` or `"winch"` features across the whole workspace.
368 #[cfg(any(feature = "cranelift", feature = "winch"))]
369 pub fn enable_compiler(&mut self, enable: bool) -> &mut Self {
370 match (enable, &self.compiler_config) {
371 (true, Some(_)) | (false, None) => {}
372 (true, None) => {
373 self.compiler_config = Some(CompilerConfig::default());
374 }
375 (false, Some(_)) => {
376 self.compiler_config = None;
377 }
378 }
379 self
380 }
381
382 /// Configures the target platform of this [`Config`].
383 ///
384 /// This method is used to configure the output of compilation in an
385 /// [`Engine`]. This can be used, for example, to
386 /// cross-compile from one platform to another. By default, the host target
387 /// triple is used meaning compiled code is suitable to run on the host.
388 ///
389 /// Note that the [`Module`](crate::Module) type can only be created if the
390 /// target configured here matches the host. Otherwise if a cross-compile is
391 /// being performed where the host doesn't match the target then
392 /// [`Engine::precompile_module`] must be used instead.
393 ///
394 /// Target-specific flags (such as CPU features) will not be inferred by
395 /// default for the target when one is provided here. This means that this
396 /// can also be used, for example, with the host architecture to disable all
397 /// host-inferred feature flags. Configuring target-specific flags can be
398 /// done with [`Config::cranelift_flag_set`] and
399 /// [`Config::cranelift_flag_enable`].
400 ///
401 /// # Errors
402 ///
403 /// This method will error if the given target triple is not supported.
404 pub fn target(&mut self, target: &str) -> Result<&mut Self> {
405 self.target =
406 Some(target_lexicon::Triple::from_str(target).map_err(|e| crate::format_err!(e))?);
407
408 Ok(self)
409 }
410
411 /// Enables the incremental compilation cache in Cranelift, using the provided `CacheStore`
412 /// backend for storage.
413 ///
414 /// # Panics
415 ///
416 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
417 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
418 pub fn enable_incremental_compilation(
419 &mut self,
420 cache_store: Arc<dyn CacheStore>,
421 ) -> Result<&mut Self> {
422 self.compiler_config_mut().cache_store = Some(cache_store);
423 Ok(self)
424 }
425
426 #[doc(hidden)]
427 #[deprecated(note = "no longer has any effect")]
428 #[cfg(feature = "async")]
429 pub fn async_support(&mut self, _enable: bool) -> &mut Self {
430 self
431 }
432
433 /// Configures whether DWARF debug information will be emitted
434 /// during compilation for a native debugger on the Wasmtime
435 /// process to consume.
436 ///
437 /// Note that the `debug-builtins` compile-time Cargo feature must also be
438 /// enabled for native debuggers such as GDB or LLDB to be able to debug
439 /// guest WebAssembly programs.
440 ///
441 /// By default this option is `false`.
442 /// **Note** Enabling this option is not compatible with the Winch compiler.
443 pub fn debug_info(&mut self, enable: bool) -> &mut Self {
444 self.tunables.debug_native = Some(enable);
445 self
446 }
447
448 /// Whether or not symbols are located in generated compiled module
449 /// artifacts.
450 ///
451 /// Wasmtime's currently representation of compiled artifacts is an ELF
452 /// file. ELF files have symbol tables and such and this option enables
453 /// whether symbols are emitted for wasm functions. This utility can be
454 /// useful when profiling wasm modules (many profilers work with
455 /// ELF-in-memory by default without futher configuration), introspection of
456 /// a `*.cwasm` (e.g. the symbol table is what `wasmtime objdump` reads), or
457 /// just general binary analysis of the result ELF file. Large wasm modules
458 /// can have large symbol tables, however, and the symbols serve no purpose
459 /// at runtime meaning that they are pure overhead for minimal module as
460 /// well. This option can be used to disable these symbols which will reduce
461 /// the debuggability of modules but will also reduce their size.
462 ///
463 /// Note that the ELF file representation is considered an implementation
464 /// detail of Wasmtime and embedders should not rely on this format.
465 /// Wasmtime may change the format of artifacts in the future.
466 ///
467 /// This option is `true` by default.
468 ///
469 /// This option is required if [`Config::debug_info`] is enabled.
470 pub fn debug_symbols(&mut self, enable: bool) -> &mut Self {
471 self.tunables.debug_symbols = Some(enable);
472 self
473 }
474
475 /// Configures whether compiled guest code will be instrumented to
476 /// provide debugging at the Wasm VM level.
477 ///
478 /// This is required in order to enable a guest-level debugging
479 /// API that can precisely examine Wasm VM state and (eventually,
480 /// once it is complete) set breakpoints and watchpoints and step
481 /// through code.
482 ///
483 /// Without this enabled, debugging can only be done via a native
484 /// debugger operating on the compiled guest code (see
485 /// [`Config::debug_info`] and is "best-effort": we may be able to
486 /// recover some Wasm locals or operand stack values, but it is
487 /// not guaranteed, even when optimizations are disabled.
488 ///
489 /// When this is enabled, additional instrumentation is inserted
490 /// that directly tracks the Wasm VM state at every step. This has
491 /// some performance impact, but allows perfect debugging
492 /// fidelity.
493 ///
494 /// Breakpoints, watchpoints, and stepping are not yet supported,
495 /// but will be added in a future version of Wasmtime.
496 ///
497 /// This enables use of the [`crate::FrameHandle`] API which is
498 /// provided by [`crate::Caller::debug_exit_frames`] or
499 /// [`crate::Store::debug_exit_frames`].
500 ///
501 /// ***Note*** Enabling this option is not compatible with the
502 /// Winch compiler.
503 #[cfg(feature = "debug")]
504 pub fn guest_debug(&mut self, enable: bool) -> &mut Self {
505 self.tunables.debug_guest = Some(enable);
506 self
507 }
508
509 /// Configures whether [`WasmBacktrace`] will be present in the context of
510 /// errors returned from Wasmtime.
511 ///
512 /// This method is deprecated in favor of
513 /// [`Config::wasm_backtrace_max_frames`]. Calling `wasm_backtrace(false)`
514 /// is equivalent to `wasm_backtrace_max_frames(None)`, and
515 /// `wasm_backtrace(true)` will leave `wasm_backtrace_max_frames` unchanged
516 /// if the value is `Some` and will otherwise restore the default `Some`
517 /// value.
518 ///
519 /// [`WasmBacktrace`]: crate::WasmBacktrace
520 #[deprecated = "use `wasm_backtrace_max_frames` instead"]
521 pub fn wasm_backtrace(&mut self, enable: bool) -> &mut Self {
522 match (enable, self.wasm_backtrace_max_frames) {
523 (false, _) => self.wasm_backtrace_max_frames = None,
524 // Wasm backtraces were disabled; enable them with the
525 // default maximum number of frames to capture.
526 (true, None) => {
527 self.wasm_backtrace_max_frames = Some(DEFAULT_WASM_BACKTRACE_MAX_FRAMES)
528 }
529 // Wasm backtraces are already enabled; keep the existing
530 // max-frames configuration.
531 (true, Some(_)) => {}
532 }
533 self
534 }
535
536 /// Configures whether backtraces in `Trap` will parse debug info in the wasm file to
537 /// have filename/line number information.
538 ///
539 /// When enabled this will causes modules to retain debugging information
540 /// found in wasm binaries. This debug information will be used when a trap
541 /// happens to symbolicate each stack frame and attempt to print a
542 /// filename/line number for each wasm frame in the stack trace.
543 ///
544 /// By default this option is `WasmBacktraceDetails::Environment`, meaning
545 /// that wasm will read `WASMTIME_BACKTRACE_DETAILS` to indicate whether
546 /// details should be parsed. Note that the `std` feature of this crate must
547 /// be active to read environment variables, otherwise this is disabled by
548 /// default.
549 pub fn wasm_backtrace_details(&mut self, enable: WasmBacktraceDetails) -> &mut Self {
550 self.wasm_backtrace_details_env_used = false;
551 self.tunables.parse_wasm_debuginfo = match enable {
552 WasmBacktraceDetails::Enable => Some(true),
553 WasmBacktraceDetails::Disable => Some(false),
554 WasmBacktraceDetails::Environment => {
555 #[cfg(feature = "std")]
556 {
557 self.wasm_backtrace_details_env_used = true;
558 std::env::var("WASMTIME_BACKTRACE_DETAILS")
559 .map(|s| Some(s == "1"))
560 .unwrap_or(Some(false))
561 }
562 #[cfg(not(feature = "std"))]
563 {
564 Some(false)
565 }
566 }
567 };
568 self
569 }
570
571 /// Configures the maximum number of WebAssembly frames to collect in
572 /// backtraces.
573 ///
574 /// A backtrace may be collected whenever an error is returned from a host
575 /// function call through to WebAssembly or when WebAssembly itself hits a
576 /// trap condition, such as an out-of-bounds memory access. This flag
577 /// indicates, in these conditions, whether the backtrace is collected or
578 /// not and how many frames should be collected.
579 ///
580 /// Currently wasm backtraces are implemented through frame pointer walking.
581 /// This means that collecting a backtrace is expected to be a fast and
582 /// relatively cheap operation. Additionally backtrace collection is
583 /// suitable in concurrent environments since one thread capturing a
584 /// backtrace won't block other threads.
585 ///
586 /// Collected backtraces are attached via
587 /// [`Error::context`](crate::Error::context) to errors returned from host
588 /// functions. The [`WasmBacktrace`] type can be acquired via
589 /// [`Error::downcast_ref`](crate::Error::downcast_ref) to inspect the
590 /// backtrace. When this option is set to `None` then this context is never
591 /// applied to errors coming out of wasm.
592 ///
593 /// The default value is 20.
594 ///
595 /// [`WasmBacktrace`]: crate::WasmBacktrace
596 pub fn wasm_backtrace_max_frames(&mut self, limit: Option<NonZeroUsize>) -> &mut Self {
597 self.wasm_backtrace_max_frames = limit;
598 self
599 }
600
601 /// Configures whether to generate native unwind information
602 /// (e.g. `.eh_frame` on Linux).
603 ///
604 /// This configuration option only exists to help third-party stack
605 /// capturing mechanisms, such as the system's unwinder or the `backtrace`
606 /// crate, determine how to unwind through Wasm frames. It does not affect
607 /// whether Wasmtime can capture Wasm backtraces or not. The presence of
608 /// [`WasmBacktrace`] is controlled by the
609 /// [`Config::wasm_backtrace_max_frames`] option.
610 ///
611 /// Native unwind information is included:
612 /// - When targeting Windows, since the Windows ABI requires it.
613 /// - By default.
614 ///
615 /// Note that systems loading many modules may wish to disable this
616 /// configuration option instead of leaving it on-by-default. Some platforms
617 /// exhibit quadratic behavior when registering/unregistering unwinding
618 /// information which can greatly slow down the module loading/unloading
619 /// process.
620 ///
621 /// [`WasmBacktrace`]: crate::WasmBacktrace
622 pub fn native_unwind_info(&mut self, enable: bool) -> &mut Self {
623 self.native_unwind_info = Some(enable);
624 self
625 }
626
627 /// Configures whether execution of WebAssembly will "consume fuel" to
628 /// either halt or yield execution as desired.
629 ///
630 /// This can be used to deterministically prevent infinitely-executing
631 /// WebAssembly code by instrumenting generated code to consume fuel as it
632 /// executes. When fuel runs out a trap is raised, however [`Store`] can be
633 /// configured to yield execution periodically via
634 /// [`crate::Store::fuel_async_yield_interval`].
635 ///
636 /// Note that a [`Store`] starts with no fuel, so if you enable this option
637 /// you'll have to be sure to pour some fuel into [`Store`] before
638 /// executing some code.
639 ///
640 /// Fuel accounting is not precise when WebAssembly traps. Each call is
641 /// still bounded by the fuel in the [`Store`], but the amount of fuel
642 /// listed as being consumed when WebAssembly traps may not accurately
643 /// reflect the exact amount that was consumed. This tradeoff enables
644 /// Wasmtime to optimize fuel-consumption primarily while still ensuring
645 /// that non-trapping code is always bounded. Embedders which need precise
646 /// fuel consumption metrics should not reuse a [`Store`] after a trap and
647 /// should not rely on the precise value of [`Store::get_fuel`] in the event
648 /// of a trap.
649 ///
650 /// By default this option is `false`.
651 ///
652 /// [`Store`]: crate::Store
653 /// [`Store::get_fuel`]: crate::Store::get_fuel
654 pub fn consume_fuel(&mut self, enable: bool) -> &mut Self {
655 self.tunables.consume_fuel = Some(enable);
656 self
657 }
658
659 /// Configures the fuel cost of each WebAssembly operator.
660 ///
661 /// In addition to each operator's flat cost, [`OperatorCost::variable`]
662 /// configures per-byte, per-element, and per-page costs for operators whose
663 /// work depends on a runtime operand.
664 ///
665 /// These costs apply both to operators in function bodies and to operators
666 /// in constant expressions evaluated at instantiation time, such as global
667 /// initializers and element or data segment offsets.
668 ///
669 /// This is only relevant when [`Config::consume_fuel`] is enabled.
670 pub fn operator_cost(&mut self, cost: OperatorCost) -> &mut Self {
671 self.tunables.operator_cost = Some(OperatorCostStrategy::table(cost));
672 self
673 }
674
675 /// Enables epoch-based interruption.
676 ///
677 /// When executing code in async mode, we sometimes want to
678 /// implement a form of cooperative timeslicing: long-running Wasm
679 /// guest code should periodically yield to the executor
680 /// loop. This yielding could be implemented by using "fuel" (see
681 /// [`consume_fuel`](Config::consume_fuel)). However, fuel
682 /// instrumentation is somewhat expensive: it modifies the
683 /// compiled form of the Wasm code so that it maintains a precise
684 /// instruction count, frequently checking this count against the
685 /// remaining fuel. If one does not need this precise count or
686 /// deterministic interruptions and needs only a periodic
687 /// interrupt of some form, then It would be better to have a more
688 /// lightweight mechanism.
689 ///
690 /// Epoch-based interruption is that mechanism. There is a global
691 /// "epoch", which is a counter that divides time into arbitrary
692 /// periods (or epochs). This counter lives on the
693 /// [`Engine`] and can be incremented by calling
694 /// [`Engine::increment_epoch`].
695 /// Epoch-based instrumentation works by setting a "deadline
696 /// epoch". The compiled code knows the deadline, and at certain
697 /// points, checks the current epoch against that deadline. It
698 /// will yield if the deadline has been reached.
699 ///
700 /// The idea is that checking an infrequently-changing counter is
701 /// cheaper than counting and frequently storing a precise metric
702 /// (instructions executed) locally. The interruptions are not
703 /// deterministic, but if the embedder increments the epoch in a
704 /// periodic way (say, every regular timer tick by a thread or
705 /// signal handler), then we can ensure that all async code will
706 /// yield to the executor within a bounded time.
707 ///
708 /// The [`Store`](crate::Store) tracks the deadline, and controls
709 /// what happens when the deadline is reached during
710 /// execution. Several behaviors are possible:
711 ///
712 /// - Trap if code is executing when the epoch deadline is
713 /// met. See
714 /// [`Store::epoch_deadline_trap`](crate::Store::epoch_deadline_trap).
715 ///
716 /// - Call an arbitrary function. This function may chose to trap or
717 /// increment the epoch. See
718 /// [`Store::epoch_deadline_callback`](crate::Store::epoch_deadline_callback).
719 ///
720 /// - Yield to the executor loop, then resume when the future is
721 /// next polled. See
722 /// [`Store::epoch_deadline_async_yield_and_update`](crate::Store::epoch_deadline_async_yield_and_update).
723 ///
724 /// Trapping is the default. The yielding behaviour may be used for
725 /// the timeslicing behavior described above.
726 ///
727 /// This feature is available with or without async support.
728 /// However, without async support, the timeslicing behaviour is
729 /// not available. This means epoch-based interruption can only
730 /// serve as a simple external-interruption mechanism.
731 ///
732 /// An initial deadline must be set before executing code by calling
733 /// [`Store::set_epoch_deadline`](crate::Store::set_epoch_deadline). If this
734 /// deadline is not configured then wasm will immediately trap.
735 ///
736 /// ## Interaction with blocking host calls
737 ///
738 /// Epochs (and fuel) do not assist in handling WebAssembly code blocked in
739 /// a call to the host. For example if the WebAssembly function calls
740 /// `wasi:io/poll.poll` to sleep epochs will not assist in waking this up or
741 /// timing it out. Epochs intentionally only affect running WebAssembly code
742 /// itself and it's left to the embedder to determine how best to wake up
743 /// indefinitely blocking code in the host.
744 ///
745 /// The typical solution for this, however, is to use the `async` variant of
746 /// WASI host functions. This models computation as a Rust `Future` which
747 /// means that when blocking happens the future is only suspended and
748 /// control yields back to the main event loop. This gives the embedder the
749 /// opportunity to use `tokio::time::timeout` for example on a wasm
750 /// computation and have the desired effect of cancelling a blocking
751 /// operation when a timeout expires.
752 ///
753 /// ## Limitations with malicious guests
754 ///
755 /// Epochs are designed to handle malicious WebAssembly guests -- the
756 /// deadline check cannot be avoided by WebAssembly code. It is safe to use
757 /// epoch deadlines to limit the execution time of untrusted code.
758 ///
759 /// Note, though, that a current limitation to this is that
760 /// bulk-data-transfer instructions, such as `memory.copy`, only check the
761 /// epoch once at the start of the operation. These operations can take a
762 /// variable amount of time to complete based on how many bytes are being
763 /// copied. This means that the maximal time slice a guest might take is
764 /// the maximum of the epoch interval and the largest
765 /// memory-copy-style-instruction executed. The size of a copy is bounded
766 /// on the size of linear memory or GC heap size. In the limit, however, a
767 /// guest using a 64-bit linear memory with a 128GiB size could issue a
768 /// 128GiB `memory.copy` which would have no preemption within the
769 /// instruction itself. Hosts which need strict time limits for guests right
770 /// now are recommended to ensure that the store's allocated heap size
771 /// (linear memory + GC heap) are bounded with a
772 /// [`ResourceLimiter`](crate::ResourceLimiter).
773 ///
774 /// ## When to use fuel vs. epochs
775 ///
776 /// In general, epoch-based interruption results in faster
777 /// execution. This difference is sometimes significant: in some
778 /// measurements, up to 2-3x. This is because epoch-based
779 /// interruption does less work: it only watches for a global
780 /// rarely-changing counter to increment, rather than keeping a
781 /// local frequently-changing counter and comparing it to a
782 /// deadline.
783 ///
784 /// Fuel, in contrast, should be used when *deterministic*
785 /// yielding or trapping is needed. For example, if it is required
786 /// that the same function call with the same starting state will
787 /// always either complete or trap with an out-of-fuel error,
788 /// deterministically, then fuel with a fixed bound should be
789 /// used.
790 ///
791 /// **Note** Enabling this option is not compatible with the Winch compiler.
792 ///
793 /// # See Also
794 ///
795 /// - [`Store::set_epoch_deadline`](crate::Store::set_epoch_deadline)
796 /// - [`Store::epoch_deadline_trap`](crate::Store::epoch_deadline_trap)
797 /// - [`Store::epoch_deadline_callback`](crate::Store::epoch_deadline_callback)
798 /// - [`Store::epoch_deadline_async_yield_and_update`](crate::Store::epoch_deadline_async_yield_and_update)
799 pub fn epoch_interruption(&mut self, enable: bool) -> &mut Self {
800 self.tunables.epoch_interruption = Some(enable);
801 self
802 }
803
804 /// XXX: MMU interruption is not yet fully landed; this config flag, not yet
805 /// plumbed through to the CLI, serves as a feature flag that keeps its
806 /// landed portions from kicking in.
807 ///
808 /// Enables MMU-based interruption, a lower-overhead alternative to
809 /// [`Config::epoch_interruption`]. It uses memory-protection faults instead
810 /// of epoch deadline comparisons to prod a running Wasm guest to yield.
811 ///
812 /// # How it works
813 ///
814 /// Cranelift emits, at each loop backedge and function prologue, a load
815 /// from a per-store "interrupt page". To trigger an interruption, the
816 /// embedder marks that page as inaccessible; the resulting SIGSEGV is
817 /// caught by Wasmtime's signal handler, which distinguishes an
818 /// interrupt-check load from an actual crash by consulting a record of each
819 /// such load in the trap table. The signal handler then causes the active
820 /// fiber to yield.
821 ///
822 /// # Compared to `epoch_interruption`
823 ///
824 /// - Faster. Whereas epoch interruption needs to compare, branch, and keep
825 /// a deadline register coherent, MMU interruption does only a single
826 /// (dead) load from a per-store memory page. In the no-interruption case,
827 /// the load completes successfully, and overhead (versus doing nothing)
828 /// is 2.8% on the SpiderMonkey Sightglass benchmark, compared to 14.4%
829 /// for epoch interruption. Factoring in interruptions, the SpiderMonkey
830 /// Markdown-parsing workload, when run under `wasmtime serve`, shows a
831 /// 12% boost in throughput over epoch interruption and a 19% reduction in
832 /// p50 latency.
833 /// - Also non-deterministic. The same guidance in
834 /// [`Config::epoch_interruption`] about fuel vs. epochs applies here.
835 /// - Equally fine-grained. Checks for MMU interruption happen at the same
836 /// points in the compiled Wasm as checks for epoch interruption.
837 /// - Less flexible. Unlike epochs, there is, as of yet, no configurable
838 /// per-store interrupt behavior. When triggered, interruption always
839 /// causes the running fiber to yield; the `Store::epoch_deadline_*`
840 /// callbacks are not consulted.
841 ///
842 /// # Triggering an interruption
843 ///
844 /// Interruptions are triggered from outside the Wasm guest code by an
845 /// [`MmuInterrupter`](crate::MmuInterrupter), which hands each running
846 /// [`Store`] an interrupt page and protects it when that store is due to
847 /// yield. The [`Engine`] owns a single interrupter, shared by all its
848 /// stores. You must provide this interrupter using
849 /// [`Config::with_mmu_interrupter`] before running code.
850 /// [`TimingWheelInterrupter`](crate::TimingWheelInterrupter) is a good
851 /// default implementation; like the epoch counter, it does nothing until
852 /// you tick it.
853 ///
854 /// # Requirements
855 ///
856 /// - **Async.** Since MMU interruption always causes the fiber to yield,
857 /// wasmtime must be built with the `async` feature. Configuring an engine
858 /// with `mmu_interruption()` puts every [`Store`] derived from it into
859 /// async mode automatically.
860 /// - **Cranelift.** Winch does not support it.
861 /// - **Linux on x86_64 or aarch64 target.** Cross-compilation from other
862 /// hosts is fine.
863 /// - **Native signals**, because we depend on a signal handler.
864 /// - **Signals-based traps**, because signal-handler installation (in
865 /// [`Engine::new()`]) is currently gated on this. It should be possible
866 /// to remove this dependency, but the use cases are few, and threading
867 /// the value of `signals_based_traps` into the signal handler may be
868 /// nontrivial.
869 ///
870 /// # Errors
871 ///
872 /// Some requirements are validated after config time: some when an
873 /// [`Engine`] is instantiated (which calls [`Config::validate`] herein) and
874 /// others when code is loaded into the engine. Nothing panics; errors are
875 /// reported via return values.
876 #[doc(hidden)]
877 pub fn mmu_interruption(&mut self, enable: bool) -> &mut Self {
878 self.tunables.mmu_interruption = Some(enable);
879 self
880 }
881
882 /// Whether this build of Wasmtime can run code on this host with
883 /// [`Self::mmu_interruption`] enabled.
884 #[doc(hidden)]
885 pub fn is_mmu_interruption_runtime_available() -> bool {
886 cfg!(has_mmu_interruption_runtime)
887 }
888
889 /// XXX: For internal fuzzing and debugging use only!
890 #[doc(hidden)]
891 pub fn gc_zeal_alloc_counter(&mut self, counter: Option<NonZeroU32>) -> Result<&mut Self> {
892 #[cfg(not(gc_zeal))]
893 {
894 let _ = counter;
895 bail!(
896 "cannot set `gc_zeal_alloc_counter` because Wasmtime was not built with `cfg(gc_zeal)`"
897 );
898 }
899
900 #[cfg(gc_zeal)]
901 {
902 self.tunables.gc_zeal_alloc_counter = Some(counter);
903 Ok(self)
904 }
905 }
906
907 /// Configures the maximum amount of stack space available for
908 /// executing WebAssembly code.
909 ///
910 /// WebAssembly has well-defined semantics on stack overflow. This is
911 /// intended to be a knob which can help configure how much stack space
912 /// wasm execution is allowed to consume. Note that the number here is not
913 /// super-precise, but rather wasm will take at most "pretty close to this
914 /// much" stack space.
915 ///
916 /// If a wasm call (or series of nested wasm calls) take more stack space
917 /// than the `size` specified then a stack overflow trap will be raised.
918 ///
919 /// Caveat: this knob only limits the stack space consumed by wasm code.
920 /// More importantly, it does not ensure that this much stack space is
921 /// available on the calling thread stack. Exhausting the thread stack
922 /// typically leads to an **abort** of the process.
923 ///
924 /// Here are some examples of how that could happen:
925 ///
926 /// - Let's assume this option is set to 2 MiB and then a thread that has
927 /// a stack with 512 KiB left.
928 ///
929 /// If wasm code consumes more than 512 KiB then the process will be aborted.
930 ///
931 /// - Assuming the same conditions, but this time wasm code does not consume
932 /// any stack but calls into a host function. The host function consumes
933 /// more than 512 KiB of stack space. The process will be aborted.
934 ///
935 /// There's another gotcha related to recursive calling into wasm: the stack
936 /// space consumed by a host function is counted towards this limit. The
937 /// host functions are not prevented from consuming more than this limit.
938 /// However, if the host function that used more than this limit and called
939 /// back into wasm, then the execution will trap immediately because of
940 /// stack overflow.
941 ///
942 /// When the `async` feature is enabled, this value cannot exceed the
943 /// `async_stack_size` option. Be careful not to set this value too close
944 /// to `async_stack_size` as doing so may limit how much stack space
945 /// is available for host functions.
946 ///
947 /// By default this option is 512 KiB.
948 ///
949 /// # Errors
950 ///
951 /// The [`Engine::new`] method will fail if the `size` specified here is
952 /// either 0 or larger than the [`Config::async_stack_size`] configuration.
953 pub fn max_wasm_stack(&mut self, size: usize) -> &mut Self {
954 self.max_wasm_stack = size;
955 self
956 }
957
958 /// Configures the size of the stacks used for asynchronous execution.
959 ///
960 /// This setting configures the size of the stacks that are allocated for
961 /// asynchronous execution. The value cannot be less than `max_wasm_stack`.
962 ///
963 /// The amount of stack space guaranteed for host functions is
964 /// `async_stack_size - max_wasm_stack`, so take care not to set these two values
965 /// close to one another; doing so may cause host functions to overflow the
966 /// stack and abort the process.
967 ///
968 /// By default this option is 2 MiB.
969 ///
970 /// # Errors
971 ///
972 /// The [`Engine::new`] method will fail if the value for this option is
973 /// smaller than the [`Config::max_wasm_stack`] option.
974 pub fn async_stack_size(&mut self, size: usize) -> &mut Self {
975 self.async_stack_size = size;
976 self
977 }
978
979 /// Configures whether or not stacks used for async futures are zeroed
980 /// before (re)use.
981 ///
982 /// When the [`call_async`] variant of calling WebAssembly is used
983 /// then Wasmtime will create a separate runtime execution stack for each
984 /// future produced by [`call_async`]. By default upon allocation, depending
985 /// on the platform, these stacks might be filled with uninitialized
986 /// memory. This is safe and correct because, modulo bugs in Wasmtime,
987 /// compiled Wasm code will never read from a stack slot before it
988 /// initializes the stack slot.
989 ///
990 /// However, as a defense-in-depth mechanism, you may configure Wasmtime to
991 /// ensure that these stacks are zeroed before they are used. Notably, if
992 /// you are using the pooling allocator, stacks can be pooled and reused
993 /// across different Wasm guests; ensuring that stacks are zeroed can
994 /// prevent data leakage between Wasm guests even in the face of potential
995 /// read-of-stack-slot-before-initialization bugs in Wasmtime's compiler.
996 ///
997 /// Stack zeroing can be a costly operation in highly concurrent
998 /// environments due to modifications of the virtual address space requiring
999 /// process-wide synchronization. It can also be costly in `no-std`
1000 /// environments that must manually zero memory, and cannot rely on an OS
1001 /// and virtual memory to provide zeroed pages.
1002 ///
1003 /// This option defaults to `false`.
1004 ///
1005 /// [`call_async`]: crate::TypedFunc::call_async
1006 pub fn async_stack_zeroing(&mut self, enable: bool) -> &mut Self {
1007 self.async_stack_zeroing = enable;
1008 self
1009 }
1010
1011 /// Explicitly enables (and un-disables) a given set of [`WasmFeatures`].
1012 ///
1013 /// Note: this is a low-level method that does not necessarily imply that
1014 /// wasmtime _supports_ a feature. It should only be used to _disable_
1015 /// features that callers want to be rejected by the parser or _enable_
1016 /// features callers are certain that the current configuration of wasmtime
1017 /// supports.
1018 ///
1019 /// Feature validation is deferred until an engine is being built, thus by
1020 /// enabling features here a caller may cause
1021 /// [`Engine::new`] to fail later, if the feature
1022 /// configuration isn't supported.
1023 pub fn wasm_features(&mut self, flag: WasmFeatures, enable: bool) -> &mut Self {
1024 self.enabled_features.set(flag, enable);
1025 self.disabled_features.set(flag, !enable);
1026 self
1027 }
1028
1029 /// Configures whether the WebAssembly tail calls proposal will be enabled
1030 /// for compilation or not.
1031 ///
1032 /// The [WebAssembly tail calls proposal] introduces the `return_call` and
1033 /// `return_call_indirect` instructions. These instructions allow for Wasm
1034 /// programs to implement some recursive algorithms with *O(1)* stack space
1035 /// usage.
1036 ///
1037 /// This is `true` by default.
1038 ///
1039 /// [WebAssembly tail calls proposal]: https://github.com/WebAssembly/tail-call
1040 pub fn wasm_tail_call(&mut self, enable: bool) -> &mut Self {
1041 self.wasm_features(WasmFeatures::TAIL_CALL, enable);
1042 self
1043 }
1044
1045 /// Configures whether the WebAssembly [branch-hinting] proposal is enabled.
1046 ///
1047 /// When enabled, the `metadata.code.branch_hint` custom section is parsed
1048 /// and used to lay out cold code paths during compilation. The hints are
1049 /// advisory and never affect execution semantics.
1050 ///
1051 /// This is `false` by default until the proposal has been fuzzed.
1052 ///
1053 /// [branch-hinting]: https://github.com/WebAssembly/branch-hinting
1054 pub fn wasm_branch_hinting(&mut self, enable: bool) -> &mut Self {
1055 self.tunables.branch_hinting = Some(enable);
1056 self
1057 }
1058
1059 /// Configures whether the WebAssembly custom-page-sizes proposal will be
1060 /// enabled for compilation or not.
1061 ///
1062 /// The [WebAssembly custom-page-sizes proposal] allows a memory to
1063 /// customize its page sizes. By default, Wasm page sizes are 64KiB
1064 /// large. This proposal allows the memory to opt into smaller page sizes
1065 /// instead, allowing Wasm to run in environments with less than 64KiB RAM
1066 /// available, for example.
1067 ///
1068 /// Note that the page size is part of the memory's type, and because
1069 /// different memories may have different types, they may also have
1070 /// different page sizes.
1071 ///
1072 /// Currently the only valid page sizes are 64KiB (the default) and 1
1073 /// byte. Future extensions may relax this constraint and allow all powers
1074 /// of two.
1075 ///
1076 /// Support for this proposal is disabled by default.
1077 ///
1078 /// [WebAssembly custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
1079 pub fn wasm_custom_page_sizes(&mut self, enable: bool) -> &mut Self {
1080 self.wasm_features(WasmFeatures::CUSTOM_PAGE_SIZES, enable);
1081 self
1082 }
1083
1084 /// Configures whether the WebAssembly compact imports proposal is enabled.
1085 ///
1086 /// The [WebAssembly compact import section proposal]
1087 /// adds two compact encodings for imports:
1088 /// - A module name and a list of `(item name, type)` pairs
1089 /// - A module name, a type, and a list of item names
1090 ///
1091 /// This reduces redundant module and type listings, and can
1092 /// reduce WebAssembly file size, especially in files with many
1093 /// repeated imports.
1094 ///
1095 /// When enabled, compact imports are accepted in binary and text-format inputs.
1096 ///
1097 /// This feature is `false` by default.
1098 ///
1099 /// [WebAssembly compact import section proposal]: https://github.com/WebAssembly/compact-import-section
1100 pub fn wasm_compact_imports(&mut self, enable: bool) -> &mut Self {
1101 self.wasm_features(WasmFeatures::COMPACT_IMPORTS, enable);
1102 self
1103 }
1104
1105 /// Configures whether the WebAssembly [threads] proposal will be enabled
1106 /// for compilation.
1107 ///
1108 /// This feature gates items such as shared memories and atomic
1109 /// instructions. Note that the threads feature depends on the bulk memory
1110 /// feature, which is enabled by default. Additionally note that while the
1111 /// wasm feature is called "threads" it does not actually include the
1112 /// ability to spawn threads. Spawning threads is part of the [wasi-threads]
1113 /// proposal which is a separately gated feature in Wasmtime.
1114 ///
1115 /// Embeddings of Wasmtime are able to build their own custom threading
1116 /// scheme on top of the core wasm threads proposal, however.
1117 ///
1118 /// The default value for this option is whether the `threads`
1119 /// crate feature of Wasmtime is enabled or not. By default this crate
1120 /// feature is enabled.
1121 ///
1122 /// [threads]: https://github.com/webassembly/threads
1123 /// [wasi-threads]: https://github.com/webassembly/wasi-threads
1124 #[cfg(feature = "threads")]
1125 pub fn wasm_threads(&mut self, enable: bool) -> &mut Self {
1126 self.wasm_features(WasmFeatures::THREADS, enable);
1127 self
1128 }
1129
1130 /// Configures whether the [WebAssembly reference types proposal][proposal]
1131 /// will be enabled for compilation.
1132 ///
1133 /// This feature gates items such as the `externref` and `funcref` types as
1134 /// well as allowing a module to define multiple tables.
1135 ///
1136 /// Note that the reference types proposal depends on the bulk memory proposal.
1137 ///
1138 /// This feature is `true` by default.
1139 ///
1140 /// # Errors
1141 ///
1142 /// The validation of this feature are deferred until the engine is being built,
1143 /// and thus may cause [`Engine::new`] fail if the `bulk_memory` feature is disabled.
1144 ///
1145 /// [proposal]: https://github.com/webassembly/reference-types
1146 #[cfg(feature = "gc")]
1147 pub fn wasm_reference_types(&mut self, enable: bool) -> &mut Self {
1148 self.wasm_features(WasmFeatures::REFERENCE_TYPES, enable);
1149 self
1150 }
1151
1152 /// Configures whether the [WebAssembly function references
1153 /// proposal][proposal] will be enabled for compilation.
1154 ///
1155 /// This feature gates non-nullable reference types, function reference
1156 /// types, `call_ref`, `ref.func`, and non-nullable reference related
1157 /// instructions.
1158 ///
1159 /// Note that the function references proposal depends on the reference
1160 /// types proposal.
1161 ///
1162 /// This feature is `true` by default.
1163 ///
1164 /// [proposal]: https://github.com/WebAssembly/function-references
1165 #[cfg(feature = "gc")]
1166 pub fn wasm_function_references(&mut self, enable: bool) -> &mut Self {
1167 self.wasm_features(WasmFeatures::FUNCTION_REFERENCES, enable);
1168 self
1169 }
1170
1171 /// Configures whether the [WebAssembly wide-arithmetic][proposal] will be
1172 /// enabled for compilation.
1173 ///
1174 /// This feature is `true` by default.
1175 ///
1176 /// [proposal]: https://github.com/WebAssembly/wide-arithmetic
1177 pub fn wasm_wide_arithmetic(&mut self, enable: bool) -> &mut Self {
1178 self.wasm_features(WasmFeatures::WIDE_ARITHMETIC, enable);
1179 self
1180 }
1181
1182 /// Configures whether the [WebAssembly Garbage Collection
1183 /// proposal][proposal] will be enabled for compilation.
1184 ///
1185 /// This feature gates `struct` and `array` type definitions and references,
1186 /// the `i31ref` type, and all related instructions.
1187 ///
1188 /// Note that the function references proposal depends on the typed function
1189 /// references proposal.
1190 ///
1191 /// This feature is `true` by default.
1192 ///
1193 /// [proposal]: https://github.com/WebAssembly/gc
1194 pub fn wasm_gc(&mut self, enable: bool) -> &mut Self {
1195 self.wasm_features(WasmFeatures::GC, enable);
1196 self
1197 }
1198
1199 /// Configures whether the WebAssembly SIMD proposal will be
1200 /// enabled for compilation.
1201 ///
1202 /// The [WebAssembly SIMD proposal][proposal]. This feature gates items such
1203 /// as the `v128` type and all of its operators being in a module. Note that
1204 /// this does not enable the [relaxed simd proposal].
1205 ///
1206 /// **Note**
1207 ///
1208 /// On x86_64 platforms the base CPU feature requirement for SIMD
1209 /// is SSE2 for the Cranelift compiler and AVX for the Winch compiler.
1210 ///
1211 /// On riscv64 the Cranelift compiler requires the `has_v` (or
1212 /// `has_zvl128b`) setting for SIMD, which is not detected when
1213 /// [`Config::target`] is used. Without it creating an [`Engine`] fails
1214 /// unless this option and [`Config::wasm_relaxed_simd`] are disabled.
1215 ///
1216 /// This is `true` by default.
1217 ///
1218 /// [proposal]: https://github.com/webassembly/simd
1219 /// [relaxed simd proposal]: https://github.com/WebAssembly/relaxed-simd
1220 pub fn wasm_simd(&mut self, enable: bool) -> &mut Self {
1221 self.wasm_features(WasmFeatures::SIMD, enable);
1222 self
1223 }
1224
1225 /// Configures whether the WebAssembly Relaxed SIMD proposal will be
1226 /// enabled for compilation.
1227 ///
1228 /// The relaxed SIMD proposal adds new instructions to WebAssembly which,
1229 /// for some specific inputs, are allowed to produce different results on
1230 /// different hosts. More-or-less this proposal enables exposing
1231 /// platform-specific semantics of SIMD instructions in a controlled
1232 /// fashion to a WebAssembly program. From an embedder's perspective this
1233 /// means that WebAssembly programs may execute differently depending on
1234 /// whether the host is x86_64 or AArch64, for example.
1235 ///
1236 /// By default Wasmtime lowers relaxed SIMD instructions to the fastest
1237 /// lowering for the platform it's running on. This means that, by default,
1238 /// some relaxed SIMD instructions may have different results for the same
1239 /// inputs across x86_64 and AArch64. This behavior can be disabled through
1240 /// the [`Config::relaxed_simd_deterministic`] option which will force
1241 /// deterministic behavior across all platforms, as classified by the
1242 /// specification, at the cost of performance.
1243 ///
1244 /// On riscv64 the Cranelift compiler requires the `has_v` (or
1245 /// `has_zvl128b`) setting for relaxed SIMD. Without it creating an
1246 /// [`Engine`] fails unless this option is disabled.
1247 ///
1248 /// This is `true` by default.
1249 ///
1250 /// [proposal]: https://github.com/webassembly/relaxed-simd
1251 pub fn wasm_relaxed_simd(&mut self, enable: bool) -> &mut Self {
1252 self.wasm_features(WasmFeatures::RELAXED_SIMD, enable);
1253 self
1254 }
1255
1256 /// This option can be used to control the behavior of the [relaxed SIMD
1257 /// proposal's][proposal] instructions.
1258 ///
1259 /// The relaxed SIMD proposal introduces instructions that are allowed to
1260 /// have different behavior on different architectures, primarily to afford
1261 /// an efficient implementation on all architectures. This means, however,
1262 /// that the same module may execute differently on one host than another,
1263 /// which typically is not otherwise the case. This option is provided to
1264 /// force Wasmtime to generate deterministic code for all relaxed simd
1265 /// instructions, at the cost of performance, for all architectures. When
1266 /// this option is enabled then the deterministic behavior of all
1267 /// instructions in the relaxed SIMD proposal is selected.
1268 ///
1269 /// This is `false` by default.
1270 ///
1271 /// [proposal]: https://github.com/webassembly/relaxed-simd
1272 pub fn relaxed_simd_deterministic(&mut self, enable: bool) -> &mut Self {
1273 self.tunables.relaxed_simd_deterministic = Some(enable);
1274 self
1275 }
1276
1277 /// Configures whether the [WebAssembly bulk memory operations
1278 /// proposal][proposal] will be enabled for compilation.
1279 ///
1280 /// This feature gates items such as the `memory.copy` instruction, passive
1281 /// data/table segments, etc, being in a module.
1282 ///
1283 /// This is `true` by default.
1284 ///
1285 /// Feature `reference_types`, which is also `true` by default, requires
1286 /// this feature to be enabled. Thus disabling this feature must also disable
1287 /// `reference_types` as well using [`wasm_reference_types`](crate::Config::wasm_reference_types).
1288 ///
1289 /// # Errors
1290 ///
1291 /// Disabling this feature without disabling `reference_types` will cause
1292 /// [`Engine::new`] to fail.
1293 ///
1294 /// [proposal]: https://github.com/webassembly/bulk-memory-operations
1295 pub fn wasm_bulk_memory(&mut self, enable: bool) -> &mut Self {
1296 self.wasm_features(WasmFeatures::BULK_MEMORY, enable);
1297 self
1298 }
1299
1300 /// Configures whether the WebAssembly multi-value [proposal] will
1301 /// be enabled for compilation.
1302 ///
1303 /// This feature gates functions and blocks returning multiple values in a
1304 /// module, for example.
1305 ///
1306 /// This is `true` by default.
1307 ///
1308 /// [proposal]: https://github.com/webassembly/multi-value
1309 pub fn wasm_multi_value(&mut self, enable: bool) -> &mut Self {
1310 self.wasm_features(WasmFeatures::MULTI_VALUE, enable);
1311 self
1312 }
1313
1314 /// Configures whether the WebAssembly multi-memory [proposal] will
1315 /// be enabled for compilation.
1316 ///
1317 /// This feature gates modules having more than one linear memory
1318 /// declaration or import.
1319 ///
1320 /// This is `true` by default.
1321 ///
1322 /// [proposal]: https://github.com/webassembly/multi-memory
1323 pub fn wasm_multi_memory(&mut self, enable: bool) -> &mut Self {
1324 self.wasm_features(WasmFeatures::MULTI_MEMORY, enable);
1325 self
1326 }
1327
1328 /// Configures whether the WebAssembly memory64 [proposal] will
1329 /// be enabled for compilation.
1330 ///
1331 /// Note that this the upstream specification is not finalized and Wasmtime
1332 /// may also have bugs for this feature since it hasn't been exercised
1333 /// much.
1334 ///
1335 /// This is `false` by default.
1336 ///
1337 /// [proposal]: https://github.com/webassembly/memory64
1338 pub fn wasm_memory64(&mut self, enable: bool) -> &mut Self {
1339 self.wasm_features(WasmFeatures::MEMORY64, enable);
1340 self
1341 }
1342
1343 /// Configures whether the WebAssembly extended-const [proposal] will
1344 /// be enabled for compilation.
1345 ///
1346 /// This is `true` by default.
1347 ///
1348 /// [proposal]: https://github.com/webassembly/extended-const
1349 pub fn wasm_extended_const(&mut self, enable: bool) -> &mut Self {
1350 self.wasm_features(WasmFeatures::EXTENDED_CONST, enable);
1351 self
1352 }
1353
1354 /// Configures whether the [WebAssembly stack switching
1355 /// proposal][proposal] will be enabled for compilation.
1356 ///
1357 /// This feature gates the use of control tags.
1358 ///
1359 /// This feature depends on the `function_reference_types` and
1360 /// `exceptions` features.
1361 ///
1362 /// This feature is `false` by default.
1363 ///
1364 /// # Errors
1365 ///
1366 /// [proposal]: https://github.com/webassembly/stack-switching
1367 pub fn wasm_stack_switching(&mut self, enable: bool) -> &mut Self {
1368 self.wasm_features(WasmFeatures::STACK_SWITCHING, enable);
1369 self
1370 }
1371
1372 /// Configures whether the WebAssembly component-model [proposal] will
1373 /// be enabled for compilation.
1374 ///
1375 /// This flag can be used to blanket disable all components within Wasmtime.
1376 /// Otherwise usage of components requires statically using
1377 /// [`Component`](crate::component::Component) instead of
1378 /// [`Module`](crate::Module) for example anyway.
1379 ///
1380 /// The default value for this option is whether the `component-model`
1381 /// crate feature of Wasmtime is enabled or not. By default this crate
1382 /// feature is enabled.
1383 ///
1384 /// [proposal]: https://github.com/webassembly/component-model
1385 #[cfg(feature = "component-model")]
1386 pub fn wasm_component_model(&mut self, enable: bool) -> &mut Self {
1387 self.wasm_features(WasmFeatures::COMPONENT_MODEL, enable);
1388 self
1389 }
1390
1391 /// Configures whether components support the async ABI [proposal] for
1392 /// lifting and lowering functions, as well as `stream`, `future`, and
1393 /// `error-context` types.
1394 ///
1395 /// The default value for this option is whether the `component-model-async`
1396 /// crate feature of Wasmtime is enabled or not. By default this crate
1397 /// feature is enabled. This option is also disabled by default if
1398 /// [`Config::concurrency_support`] is disabled.
1399 ///
1400 /// [proposal]:
1401 /// https://github.com/WebAssembly/component-model/blob/main/design/mvp/Concurrency.md
1402 #[cfg(feature = "component-model-async")]
1403 pub fn wasm_component_model_async(&mut self, enable: bool) -> &mut Self {
1404 self.wasm_features(WasmFeatures::CM_ASYNC, enable);
1405 self
1406 }
1407
1408 /// This corresponds to the 🚝 emoji in the component model specification.
1409 ///
1410 /// Please note that Wasmtime's support for this feature is _very_
1411 /// incomplete.
1412 ///
1413 /// [proposal]:
1414 /// https://github.com/WebAssembly/component-model/blob/main/design/mvp/Concurrency.md
1415 #[cfg(feature = "component-model-async")]
1416 pub fn wasm_component_model_more_async_builtins(&mut self, enable: bool) -> &mut Self {
1417 self.wasm_features(WasmFeatures::CM_MORE_ASYNC_BUILTINS, enable);
1418 self
1419 }
1420
1421 /// This corresponds to the 🚟 emoji in the component model specification.
1422 ///
1423 /// Please note that Wasmtime's support for this feature is _very_
1424 /// incomplete.
1425 ///
1426 /// [proposal]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Concurrency.md
1427 #[cfg(feature = "component-model-async")]
1428 pub fn wasm_component_model_async_stackful(&mut self, enable: bool) -> &mut Self {
1429 self.wasm_features(WasmFeatures::CM_ASYNC_STACKFUL, enable);
1430 self
1431 }
1432
1433 /// This corresponds to the 🧵 emoji in the component model specification.
1434 ///
1435 /// Please note that Wasmtime's support for this feature is _very_
1436 /// incomplete.
1437 ///
1438 /// [proposal]:
1439 /// https://github.com/WebAssembly/component-model/pull/557
1440 #[cfg(feature = "component-model-async")]
1441 pub fn wasm_component_model_threading(&mut self, enable: bool) -> &mut Self {
1442 self.wasm_features(WasmFeatures::CM_THREADING, enable);
1443 self
1444 }
1445
1446 /// This corresponds to the 📝 emoji in the component model specification.
1447 ///
1448 /// Please note that Wasmtime's support for this feature is _very_
1449 /// incomplete.
1450 ///
1451 /// [proposal]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Concurrency.md
1452 #[cfg(feature = "component-model")]
1453 pub fn wasm_component_model_error_context(&mut self, enable: bool) -> &mut Self {
1454 self.wasm_features(WasmFeatures::CM_ERROR_CONTEXT, enable);
1455 self
1456 }
1457
1458 /// Configures whether the [GC extension to the component-model
1459 /// proposal][proposal] is enabled or not.
1460 ///
1461 /// This corresponds to the 🛸 emoji in the component model specification.
1462 ///
1463 /// Please note that Wasmtime's support for this feature is _very_
1464 /// incomplete.
1465 ///
1466 /// [proposal]: https://github.com/WebAssembly/component-model/issues/525
1467 #[cfg(feature = "component-model")]
1468 pub fn wasm_component_model_gc(&mut self, enable: bool) -> &mut Self {
1469 self.wasm_features(WasmFeatures::CM_GC, enable);
1470 self
1471 }
1472
1473 /// Configures whether the component model map type is enabled or not.
1474 ///
1475 /// This corresponds to the 🗺️ emoji in the component model specification
1476 /// and enables the `map<k, v>` type in WIT and the component binary
1477 /// format.
1478 ///
1479 /// This is `false` by default.
1480 #[cfg(feature = "component-model")]
1481 pub fn wasm_component_model_map(&mut self, enable: bool) -> &mut Self {
1482 self.wasm_features(WasmFeatures::CM_MAP, enable);
1483 self
1484 }
1485
1486 /// Configures whether the component model memory64 support is enabled
1487 ///
1488 /// This corresponds to the 🐘 emoji in the component model specification.
1489 ///
1490 /// Please note that Wasmtime's support for this feature is _very_
1491 /// incomplete.
1492 #[cfg(feature = "component-model")]
1493 pub fn wasm_component_model_memory64(&mut self, enable: bool) -> &mut Self {
1494 self.wasm_features(WasmFeatures::CM64, enable);
1495 self
1496 }
1497
1498 /// This corresponds to the 🔧 emoji in the component model specification.
1499 ///
1500 /// Please note that Wasmtime's support for this feature is _very_
1501 /// incomplete.
1502 #[cfg(feature = "component-model")]
1503 pub fn wasm_component_model_fixed_length_lists(&mut self, enable: bool) -> &mut Self {
1504 self.wasm_features(WasmFeatures::CM_FIXED_LENGTH_LISTS, enable);
1505 self
1506 }
1507
1508 /// Configures whether the component model `(implements "...")` and
1509 /// `(external-id "...")` name annotations are enabled.
1510 ///
1511 /// This corresponds to the 🏷️ emoji in the component model specification.
1512 ///
1513 /// Please note that Wasmtime's support for this feature is a work in
1514 /// progress.
1515 #[cfg(feature = "component-model")]
1516 pub fn wasm_component_model_implements(&mut self, enable: bool) -> &mut Self {
1517 self.wasm_features(WasmFeatures::CM_IMPLEMENTS, enable);
1518 self
1519 }
1520
1521 /// This corresponds to the 🔗 emoji in the component model specification.
1522 ///
1523 /// Please note that Wasmtime's support for this feature is a work in
1524 /// progress.
1525 #[cfg(feature = "component-model")]
1526 pub fn wasm_component_model_canonical_names(&mut self, enable: bool) -> &mut Self {
1527 self.wasm_features(WasmFeatures::CM_CANON_NAMES, enable);
1528 self
1529 }
1530
1531 /// This corresponds to the 📡 emoji in the component model specification.
1532 ///
1533 /// Please note that Wasmtime's support for this feature is a work in
1534 /// progress.
1535 #[cfg(feature = "component-model")]
1536 pub fn wasm_component_model_accessors(&mut self, enable: bool) -> &mut Self {
1537 self.wasm_features(WasmFeatures::CM_ACCESSORS, enable);
1538 self
1539 }
1540
1541 /// Configures whether the [Exception-handling proposal][proposal] is enabled or not.
1542 ///
1543 /// This is `true` by default, except when using [`Strategy::Winch`] where
1544 /// it defaults to `false`.
1545 ///
1546 /// [proposal]: https://github.com/WebAssembly/exception-handling
1547 #[cfg(feature = "gc")]
1548 pub fn wasm_exceptions(&mut self, enable: bool) -> &mut Self {
1549 self.wasm_features(WasmFeatures::EXCEPTIONS, enable);
1550 self
1551 }
1552
1553 #[doc(hidden)] // FIXME(#3427) - if/when implemented then un-hide this
1554 #[deprecated = "This configuration option only exists for internal \
1555 usage with the spec testsuite. It may be removed at \
1556 any time and without warning. Do not rely on it!"]
1557 pub fn wasm_legacy_exceptions(&mut self, enable: bool) -> &mut Self {
1558 self.wasm_features(WasmFeatures::LEGACY_EXCEPTIONS, enable);
1559 self
1560 }
1561
1562 /// Configures which compilation strategy will be used for wasm modules.
1563 ///
1564 /// This method can be used to configure which compiler is used for wasm
1565 /// modules, and for more documentation consult the [`Strategy`] enumeration
1566 /// and its documentation.
1567 ///
1568 /// The default value for this is `Strategy::Auto`.
1569 ///
1570 /// # Panics
1571 ///
1572 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1573 #[cfg(any(feature = "cranelift", feature = "winch"))]
1574 pub fn strategy(&mut self, strategy: Strategy) -> &mut Self {
1575 self.compiler_config_mut().strategy = strategy.not_auto();
1576 self
1577 }
1578
1579 /// Configures which garbage collector will be used for Wasm modules.
1580 ///
1581 /// This method can be used to configure which garbage collector
1582 /// implementation is used for Wasm modules. For more documentation, consult
1583 /// the [`Collector`] enumeration and its documentation.
1584 ///
1585 /// The default value for this is `Collector::Auto`.
1586 #[cfg(feature = "gc")]
1587 pub fn collector(&mut self, collector: Collector) -> &mut Self {
1588 self.collector = collector;
1589 self
1590 }
1591
1592 /// Configures the initial size, in bytes, of each store's GC heap.
1593 ///
1594 /// By default all GC heaps start out at 0 bytes in size and must grow
1595 /// upwards from there. Growth happens incrementally as GC pressure happens
1596 /// and memory runs out. The amount being grown by is additionally a
1597 /// heuristic of the size of the failed allocation. By providing an initial
1598 /// size of a store's GC heap embedders can more tightly control initial
1599 /// parameters to optimize workloads that might have a predictable pattern.
1600 /// For example if workloads frequently have less than a certain threshold
1601 /// of size then that could be configured as the initial size here to avoid
1602 /// growths happening over time.
1603 ///
1604 /// Note that like WebAssembly linear memories the GC heap does not start
1605 /// with committed memory equal to this size. Instead memory is reserved,
1606 /// but then lazily allocated by the OS on access. In other words it should
1607 /// be relatively cheap to increase this value to help amortize initial
1608 /// startup cost of wasm modules.
1609 ///
1610 /// The `bytes` size is rounded up to the GC heap's page size.
1611 ///
1612 /// This only configures the initially-allocated size of the GC heap; the
1613 /// heap can still grow beyond it on demand. It is separate from
1614 /// [`Config::gc_heap_reservation`], which configures the size of the
1615 /// virtual-memory reservation (and therefore how far the heap can grow
1616 /// in place).
1617 ///
1618 /// The default value for this is 0.
1619 pub fn gc_heap_initial_size(&mut self, bytes: u64) -> &mut Self {
1620 self.tunables.gc_heap_initial_size = Some(bytes);
1621 self
1622 }
1623
1624 /// Creates a default profiler based on the profiling strategy chosen.
1625 ///
1626 /// Profiler creation calls the type's default initializer where the purpose is
1627 /// really just to put in place the type used for profiling.
1628 ///
1629 /// Some [`ProfilingStrategy`] require specific platforms or particular feature
1630 /// to be enabled, such as `ProfilingStrategy::JitDump` requires the `jitdump`
1631 /// feature.
1632 ///
1633 /// # Errors
1634 ///
1635 /// The validation of this field is deferred until the engine is being built, and thus may
1636 /// cause [`Engine::new`] fail if the required feature is disabled, or the platform is not
1637 /// supported.
1638 pub fn profiler(&mut self, profile: ProfilingStrategy) -> &mut Self {
1639 self.profiling_strategy = profile;
1640 self
1641 }
1642
1643 /// Configures whether the debug verifier of Cranelift is enabled or not.
1644 ///
1645 /// When Cranelift is used as a code generation backend this will configure
1646 /// it to have the `enable_verifier` flag which will enable a number of debug
1647 /// checks inside of Cranelift. This is largely only useful for the
1648 /// developers of wasmtime itself.
1649 ///
1650 /// The default value for this is `false`
1651 ///
1652 /// # Panics
1653 ///
1654 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1655 #[cfg(any(feature = "cranelift", feature = "winch"))]
1656 pub fn cranelift_debug_verifier(&mut self, enable: bool) -> &mut Self {
1657 let val = if enable { "true" } else { "false" };
1658 self.compiler_config_mut().settings.insert(
1659 "enable_verifier".to_string(),
1660 (val.to_string(), UserSpecified::No),
1661 );
1662 self
1663 }
1664
1665 /// Configures whether extra debug checks are inserted into
1666 /// Wasmtime-generated code by Cranelift.
1667 ///
1668 /// The default value for this is `false`
1669 ///
1670 /// # Panics
1671 ///
1672 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1673 #[cfg(any(feature = "cranelift", feature = "winch"))]
1674 pub fn cranelift_wasmtime_debug_checks(&mut self, enable: bool) -> &mut Self {
1675 unsafe { self.cranelift_flag_set("wasmtime_debug_checks", &enable.to_string()) }
1676 }
1677
1678 /// Configures the Cranelift code generator optimization level.
1679 ///
1680 /// When the Cranelift code generator is used you can configure the
1681 /// optimization level used for generated code in a few various ways. For
1682 /// more information see the documentation of [`OptLevel`].
1683 ///
1684 /// The default value for this is `OptLevel::Speed`.
1685 ///
1686 /// # Panics
1687 ///
1688 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1689 #[cfg(any(feature = "cranelift", feature = "winch"))]
1690 pub fn cranelift_opt_level(&mut self, level: OptLevel) -> &mut Self {
1691 let val = match level {
1692 OptLevel::None => "none",
1693 OptLevel::Speed => "speed",
1694 OptLevel::SpeedAndSize => "speed_and_size",
1695 };
1696 self.compiler_config_mut().settings.insert(
1697 "opt_level".to_string(),
1698 (val.to_string(), UserSpecified::No),
1699 );
1700 self
1701 }
1702
1703 /// Configures the regalloc algorithm used by the Cranelift code generator.
1704 ///
1705 /// Cranelift can select any of several register allocator algorithms. Each
1706 /// of these algorithms generates correct code, but they represent different
1707 /// tradeoffs between compile speed (how expensive the compilation process
1708 /// is) and run-time speed (how fast the generated code runs).
1709 /// For more information see the documentation of [`RegallocAlgorithm`].
1710 ///
1711 /// The default value for this is `RegallocAlgorithm::Backtracking`.
1712 ///
1713 /// # Panics
1714 ///
1715 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1716 #[cfg(any(feature = "cranelift", feature = "winch"))]
1717 pub fn cranelift_regalloc_algorithm(&mut self, algo: RegallocAlgorithm) -> &mut Self {
1718 let val = match algo {
1719 RegallocAlgorithm::Backtracking => "backtracking",
1720 RegallocAlgorithm::SinglePass => "single_pass",
1721 };
1722 self.compiler_config_mut().settings.insert(
1723 "regalloc_algorithm".to_string(),
1724 (val.to_string(), UserSpecified::No),
1725 );
1726 self
1727 }
1728
1729 /// Configures whether Cranelift should perform a NaN-canonicalization pass.
1730 ///
1731 /// When Cranelift is used as a code generation backend this will configure
1732 /// it to replace NaNs with a single canonical value. This is useful for
1733 /// users requiring entirely deterministic WebAssembly computation. This is
1734 /// not required by the WebAssembly spec, so it is not enabled by default.
1735 ///
1736 /// Note that this option affects not only WebAssembly's `f32` and `f64`
1737 /// types but additionally the `v128` type. This option will cause
1738 /// operations using any of these types to have extra checks placed after
1739 /// them to normalize NaN values as needed.
1740 ///
1741 /// The default value for this is `false`
1742 ///
1743 /// # Panics
1744 ///
1745 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1746 #[cfg(any(feature = "cranelift", feature = "winch"))]
1747 pub fn cranelift_nan_canonicalization(&mut self, enable: bool) -> &mut Self {
1748 let val = if enable { "true" } else { "false" };
1749 self.compiler_config_mut().settings.insert(
1750 "enable_nan_canonicalization".to_string(),
1751 (val.to_string(), UserSpecified::No),
1752 );
1753 self
1754 }
1755
1756 /// Allows setting a Cranelift boolean flag or preset. This allows
1757 /// fine-tuning of Cranelift settings.
1758 ///
1759 /// Since Cranelift flags may be unstable, this method should not be considered to be stable
1760 /// either; other `Config` functions should be preferred for stability.
1761 ///
1762 /// # Safety
1763 ///
1764 /// This is marked as unsafe, because setting the wrong flag might break invariants,
1765 /// resulting in execution hazards.
1766 ///
1767 /// # Errors
1768 ///
1769 /// The validation of the flags are deferred until the engine is being built, and thus may
1770 /// cause [`Engine::new`] fail if the flag's name does not exist, or the value is not appropriate
1771 /// for the flag type.
1772 ///
1773 /// # Panics
1774 ///
1775 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1776 #[cfg(any(feature = "cranelift", feature = "winch"))]
1777 pub unsafe fn cranelift_flag_enable(&mut self, flag: &str) -> &mut Self {
1778 self.compiler_config_mut()
1779 .flags
1780 .insert(flag.to_string(), UserSpecified::Yes);
1781 self
1782 }
1783
1784 /// Allows settings another Cranelift flag defined by a flag name and value. This allows
1785 /// fine-tuning of Cranelift settings.
1786 ///
1787 /// Since Cranelift flags may be unstable, this method should not be considered to be stable
1788 /// either; other `Config` functions should be preferred for stability.
1789 ///
1790 /// # Safety
1791 ///
1792 /// This is marked as unsafe, because setting the wrong flag might break invariants,
1793 /// resulting in execution hazards.
1794 ///
1795 /// # Errors
1796 ///
1797 /// The validation of the flags are deferred until the engine is being built, and thus may
1798 /// cause [`Engine::new`] fail if the flag's name does not exist, or incompatible with other
1799 /// settings.
1800 ///
1801 /// For example, feature `wasm_backtrace` will set `unwind_info` to `true`, but if it's
1802 /// manually set to false then it will fail.
1803 ///
1804 /// # Panics
1805 ///
1806 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
1807 #[cfg(any(feature = "cranelift", feature = "winch"))]
1808 pub unsafe fn cranelift_flag_set(&mut self, name: &str, value: &str) -> &mut Self {
1809 self.compiler_config_mut()
1810 .settings
1811 .insert(name.to_string(), (value.to_string(), UserSpecified::Yes));
1812 self
1813 }
1814
1815 /// Set a custom [`Cache`].
1816 ///
1817 /// To load a cache configuration from a file, use [`Cache::from_file`]. Otherwise, you can
1818 /// create a new cache config using [`CacheConfig::new`] and passing that to [`Cache::new`].
1819 ///
1820 /// If you want to disable the cache, you can call this method with `None`.
1821 ///
1822 /// By default, new configs do not have caching enabled.
1823 /// Every call to [`Module::new(my_wasm)`][crate::Module::new] will recompile `my_wasm`,
1824 /// even when it is unchanged, unless an enabled `CacheConfig` is provided.
1825 ///
1826 /// This method is only available when the `cache` feature of this crate is
1827 /// enabled.
1828 ///
1829 /// [docs]: https://bytecodealliance.github.io/wasmtime/cli-cache.html
1830 #[cfg(feature = "cache")]
1831 pub fn cache(&mut self, cache: Option<Cache>) -> &mut Self {
1832 self.cache = cache;
1833 self
1834 }
1835
1836 /// Sets a custom memory creator.
1837 ///
1838 /// Custom memory creators are used when creating host `Memory` objects or when
1839 /// creating instance linear memories for the on-demand instance allocation strategy.
1840 #[cfg(feature = "runtime")]
1841 pub fn with_host_memory(&mut self, mem_creator: Arc<dyn MemoryCreator>) -> &mut Self {
1842 self.mem_creator = Some(mem_creator);
1843 self
1844 }
1845
1846 /// Sets a custom stack creator.
1847 ///
1848 /// Custom memory creators are used when creating creating async instance stacks for
1849 /// the on-demand instance allocation strategy.
1850 #[cfg(feature = "async")]
1851 pub fn with_host_stack(&mut self, stack_creator: Arc<dyn StackCreator>) -> &mut Self {
1852 self.stack_creator = Some(Arc::new(StackCreatorProxy(stack_creator)));
1853 self
1854 }
1855
1856 /// Sets a custom executable-memory publisher.
1857 ///
1858 /// Custom executable-memory publishers are hooks that allow
1859 /// Wasmtime to make certain regions of memory executable when
1860 /// loading precompiled modules or compiling new modules
1861 /// in-process. In most modern operating systems, memory allocated
1862 /// for heap usage is readable and writable by default but not
1863 /// executable. To jump to machine code stored in that memory, we
1864 /// need to make it executable. For security reasons, we usually
1865 /// also make it read-only at the same time, so the executing code
1866 /// can't be modified later.
1867 ///
1868 /// By default, Wasmtime will use the appropriate system calls on
1869 /// the host platform for this work. However, it also allows
1870 /// plugging in a custom implementation via this configuration
1871 /// option. This may be useful on custom or `no_std` platforms,
1872 /// for example, especially where virtual memory is not otherwise
1873 /// used by Wasmtime (no `signals-and-traps` feature).
1874 #[cfg(feature = "runtime")]
1875 pub fn with_custom_code_memory(
1876 &mut self,
1877 custom_code_memory: Option<Arc<dyn CustomCodeMemory>>,
1878 ) -> &mut Self {
1879 self.custom_code_memory = custom_code_memory;
1880 self
1881 }
1882
1883 /// Sets the instance allocation strategy to use.
1884 ///
1885 /// This is notably used in conjunction with
1886 /// [`InstanceAllocationStrategy::Pooling`] and [`PoolingAllocationConfig`].
1887 pub fn allocation_strategy(
1888 &mut self,
1889 strategy: impl Into<InstanceAllocationStrategy>,
1890 ) -> &mut Self {
1891 self.allocation_strategy = strategy.into();
1892 self
1893 }
1894
1895 /// Specifies the capacity of linear memories, in bytes, in their initial
1896 /// allocation.
1897 ///
1898 /// > Note: this value has important performance ramifications, be sure to
1899 /// > benchmark when setting this to a non-default value and read over this
1900 /// > documentation.
1901 ///
1902 /// This function will change the size of the initial memory allocation made
1903 /// for linear memories. This setting is only applicable when the initial
1904 /// size of a linear memory is below this threshold. Linear memories are
1905 /// allocated in the virtual address space of the host process with OS APIs
1906 /// such as `mmap` and this setting affects how large the allocation will
1907 /// be.
1908 ///
1909 /// ## Background: WebAssembly Linear Memories
1910 ///
1911 /// WebAssembly linear memories always start with a minimum size and can
1912 /// possibly grow up to a maximum size. The minimum size is always specified
1913 /// in a WebAssembly module itself and the maximum size can either be
1914 /// optionally specified in the module or inherently limited by the index
1915 /// type. For example for this module:
1916 ///
1917 /// ```wasm
1918 /// (module
1919 /// (memory $a 4)
1920 /// (memory $b 4096 4096 (pagesize 1))
1921 /// (memory $c i64 10)
1922 /// )
1923 /// ```
1924 ///
1925 /// * Memory `$a` initially allocates 4 WebAssembly pages (256KiB) and can
1926 /// grow up to 4GiB, the limit of the 32-bit index space.
1927 /// * Memory `$b` initially allocates 4096 WebAssembly pages, but in this
1928 /// case its page size is 1, so it's 4096 bytes. Memory can also grow no
1929 /// further meaning that it will always be 4096 bytes.
1930 /// * Memory `$c` is a 64-bit linear memory which starts with 640KiB of
1931 /// memory and can theoretically grow up to 2^64 bytes, although most
1932 /// hosts will run out of memory long before that.
1933 ///
1934 /// All operations on linear memories done by wasm are required to be
1935 /// in-bounds. Any access beyond the end of a linear memory is considered a
1936 /// trap.
1937 ///
1938 /// ## What this setting affects: Virtual Memory
1939 ///
1940 /// This setting is used to configure the behavior of the size of the linear
1941 /// memory allocation performed for each of these memories. For example the
1942 /// initial linear memory allocation looks like this:
1943 ///
1944 /// ```text
1945 /// memory_reservation
1946 /// |
1947 /// ◄─────────┴────────────────►
1948 /// ┌───────┬─────────┬──────────────────┬───────┐
1949 /// │ guard │ initial │ ... capacity ... │ guard │
1950 /// └───────┴─────────┴──────────────────┴───────┘
1951 /// ◄──┬──► ◄──┬──►
1952 /// │ │
1953 /// │ memory_guard_size
1954 /// │
1955 /// │
1956 /// memory_guard_size (if guard_before_linear_memory)
1957 /// ```
1958 ///
1959 /// Memory in the `initial` range is accessible to the instance and can be
1960 /// read/written by wasm code. Memory in the `guard` regions is never
1961 /// accessible to wasm code and memory in `capacity` is initially
1962 /// inaccessible but may become accessible through `memory.grow` instructions
1963 /// for example.
1964 ///
1965 /// This means that this setting is the size of the initial chunk of virtual
1966 /// memory that a linear memory may grow into.
1967 ///
1968 /// ## What this setting affects: Runtime Speed
1969 ///
1970 /// This is a performance-sensitive setting which is taken into account
1971 /// during the compilation process of a WebAssembly module. For example if a
1972 /// 32-bit WebAssembly linear memory has a `memory_reservation` size of 4GiB
1973 /// then bounds checks can be elided because `capacity` will be guaranteed
1974 /// to be unmapped for all addressable bytes that wasm can access (modulo a
1975 /// few details).
1976 ///
1977 /// If `memory_reservation` was something smaller like 256KiB then that
1978 /// would have a much smaller impact on virtual memory but the compile code
1979 /// would then need to have explicit bounds checks to ensure that
1980 /// loads/stores are in-bounds.
1981 ///
1982 /// The goal of this setting is to enable skipping bounds checks in most
1983 /// modules by default. Some situations which require explicit bounds checks
1984 /// though are:
1985 ///
1986 /// * When `memory_reservation` is smaller than the addressable size of the
1987 /// linear memory. For example if 64-bit linear memories always need
1988 /// bounds checks as they can address the entire virtual address spacce.
1989 /// For 32-bit linear memories a `memory_reservation` minimum size of 4GiB
1990 /// is required to elide bounds checks.
1991 ///
1992 /// * When linear memories have a page size of 1 then bounds checks are
1993 /// required. In this situation virtual memory can't be relied upon
1994 /// because that operates at the host page size granularity where wasm
1995 /// requires a per-byte level granularity.
1996 ///
1997 /// * Configuration settings such as [`Config::signals_based_traps`] can be
1998 /// used to disable the use of signal handlers and virtual memory so
1999 /// explicit bounds checks are required.
2000 ///
2001 /// * When [`Config::memory_guard_size`] is too small a bounds check may be
2002 /// required. For 32-bit wasm addresses are actually 33-bit effective
2003 /// addresses because loads/stores have a 32-bit static offset to add to
2004 /// the dynamic 32-bit address. If the static offset is larger than the
2005 /// size of the guard region then an explicit bounds check is required.
2006 ///
2007 /// ## What this setting affects: Memory Growth Behavior
2008 ///
2009 /// In addition to affecting bounds checks emitted in compiled code this
2010 /// setting also affects how WebAssembly linear memories are grown. The
2011 /// `memory.grow` instruction can be used to make a linear memory larger and
2012 /// this is also affected by APIs such as
2013 /// [`Memory::grow`](crate::Memory::grow).
2014 ///
2015 /// In these situations when the amount being grown is small enough to fit
2016 /// within the remaining capacity then the linear memory doesn't have to be
2017 /// moved at runtime. If the capacity runs out though then a new linear
2018 /// memory allocation must be made and the contents of linear memory is
2019 /// copied over.
2020 ///
2021 /// For example here's a situation where a copy happens:
2022 ///
2023 /// * The `memory_reservation` setting is configured to 128KiB.
2024 /// * A WebAssembly linear memory starts with a single 64KiB page.
2025 /// * This memory can be grown by one page to contain the full 128KiB of
2026 /// memory.
2027 /// * If grown by one more page, though, then a 192KiB allocation must be
2028 /// made and the previous 128KiB of contents are copied into the new
2029 /// allocation.
2030 ///
2031 /// This growth behavior can have a significant performance impact if lots
2032 /// of data needs to be copied on growth. Conversely if memory growth never
2033 /// needs to happen because the capacity will always be large enough then
2034 /// optimizations can be applied to cache the base pointer of linear memory.
2035 ///
2036 /// When memory is grown then the
2037 /// [`Config::memory_reservation_for_growth`] is used for the new
2038 /// memory allocation to have memory to grow into.
2039 ///
2040 /// When using the pooling allocator via [`PoolingAllocationConfig`] then
2041 /// memories are never allowed to move so requests for growth are instead
2042 /// rejected with an error.
2043 ///
2044 /// ## When this setting is not used
2045 ///
2046 /// This setting is ignored and unused when the initial size of linear
2047 /// memory is larger than this threshold. For example if this setting is set
2048 /// to 1MiB but a wasm module requires a 2MiB minimum allocation then this
2049 /// setting is ignored. In this situation the minimum size of memory will be
2050 /// allocated along with [`Config::memory_reservation_for_growth`]
2051 /// after it to grow into.
2052 ///
2053 /// That means that this value can be set to zero. That can be useful in
2054 /// benchmarking to see the overhead of bounds checks for example.
2055 /// Additionally it can be used to minimize the virtual memory allocated by
2056 /// Wasmtime.
2057 ///
2058 /// ## Default Value
2059 ///
2060 /// The default value for this property depends on the host platform. For
2061 /// 64-bit platforms there's lots of address space available, so the default
2062 /// configured here is 4GiB. When coupled with the default size of
2063 /// [`Config::memory_guard_size`] this means that 32-bit WebAssembly linear
2064 /// memories with 64KiB page sizes will skip almost all bounds checks by
2065 /// default.
2066 ///
2067 /// For 32-bit platforms this value defaults to 10MiB. This means that
2068 /// bounds checks will be required on 32-bit platforms.
2069 pub fn memory_reservation(&mut self, bytes: u64) -> &mut Self {
2070 self.tunables.memory_reservation = Some(bytes);
2071 self
2072 }
2073
2074 /// Indicates whether linear memories may relocate their base pointer at
2075 /// runtime.
2076 ///
2077 /// WebAssembly linear memories either have a maximum size that's explicitly
2078 /// listed in the type of a memory or inherently limited by the index type
2079 /// of the memory (e.g. 4GiB for 32-bit linear memories). Depending on how
2080 /// the linear memory is allocated (see [`Config::memory_reservation`]) it
2081 /// may be necessary to move the memory in the host's virtual address space
2082 /// during growth. This option controls whether this movement is allowed or
2083 /// not.
2084 ///
2085 /// An example of a linear memory needing to move is when
2086 /// [`Config::memory_reservation`] is 0 then a linear memory will be
2087 /// allocated as the minimum size of the memory plus
2088 /// [`Config::memory_reservation_for_growth`]. When memory grows beyond the
2089 /// reservation for growth then the memory needs to be relocated.
2090 ///
2091 /// When this option is set to `false` then it can have a number of impacts
2092 /// on how memories work at runtime:
2093 ///
2094 /// * Modules can be compiled with static knowledge the base pointer of
2095 /// linear memory never changes to enable optimizations such as
2096 /// loop invariant code motion (hoisting the base pointer out of a loop).
2097 ///
2098 /// * Memories cannot grow in excess of their original allocation. This
2099 /// means that [`Config::memory_reservation`] and
2100 /// [`Config::memory_reservation_for_growth`] may need tuning to ensure
2101 /// the memory configuration works at runtime.
2102 ///
2103 /// The default value for this option is `true`.
2104 pub fn memory_may_move(&mut self, enable: bool) -> &mut Self {
2105 self.tunables.memory_may_move = Some(enable);
2106 self
2107 }
2108
2109 /// Configures the size, in bytes, of the guard region used at the end of a
2110 /// linear memory's address space reservation.
2111 ///
2112 /// > Note: this value has important performance ramifications, be sure to
2113 /// > understand what this value does before tweaking it and benchmarking.
2114 ///
2115 /// This setting controls how many bytes are guaranteed to be unmapped after
2116 /// the virtual memory allocation of a linear memory. When
2117 /// combined with sufficiently large values of
2118 /// [`Config::memory_reservation`] (e.g. 4GiB for 32-bit linear memories)
2119 /// then a guard region can be used to eliminate bounds checks in generated
2120 /// code.
2121 ///
2122 /// This setting additionally can be used to help deduplicate bounds checks
2123 /// in code that otherwise requires bounds checks. For example with a 4KiB
2124 /// guard region then a 64-bit linear memory which accesses addresses `x+8`
2125 /// and `x+16` only needs to perform a single bounds check on `x`. If that
2126 /// bounds check passes then the offset is guaranteed to either reside in
2127 /// linear memory or the guard region, resulting in deterministic behavior
2128 /// either way.
2129 ///
2130 /// ## How big should the guard be?
2131 ///
2132 /// In general, like with configuring [`Config::memory_reservation`], you
2133 /// probably don't want to change this value from the defaults. Removing
2134 /// bounds checks is dependent on a number of factors where the size of the
2135 /// guard region is only one piece of the equation. Other factors include:
2136 ///
2137 /// * [`Config::memory_reservation`]
2138 /// * The index type of the linear memory (e.g. 32-bit or 64-bit)
2139 /// * The page size of the linear memory
2140 /// * Other settings such as [`Config::signals_based_traps`]
2141 ///
2142 /// Embeddings using virtual memory almost always want at least some guard
2143 /// region, but otherwise changes from the default should be profiled
2144 /// locally to see the performance impact.
2145 ///
2146 /// ## Default
2147 ///
2148 /// The default value for this property is 32MiB on 64-bit platforms. This
2149 /// allows eliminating almost all bounds checks on loads/stores with an
2150 /// immediate offset of less than 32MiB. On 32-bit platforms this defaults
2151 /// to 64KiB.
2152 pub fn memory_guard_size(&mut self, bytes: u64) -> &mut Self {
2153 self.tunables.memory_guard_size = Some(bytes);
2154 self
2155 }
2156
2157 /// Configures the size, in bytes, of the extra virtual memory space
2158 /// reserved after a linear memory is relocated.
2159 ///
2160 /// This setting is used in conjunction with [`Config::memory_reservation`]
2161 /// to configure what happens after a linear memory is relocated in the host
2162 /// address space. If the initial size of a linear memory exceeds
2163 /// [`Config::memory_reservation`] or if it grows beyond that size
2164 /// throughout its lifetime then this setting will be used.
2165 ///
2166 /// When a linear memory is relocated it will initially look like this:
2167 ///
2168 /// ```text
2169 /// memory.size
2170 /// │
2171 /// ◄──────┴─────►
2172 /// ┌───────┬──────────────┬───────┐
2173 /// │ guard │ accessible │ guard │
2174 /// └───────┴──────────────┴───────┘
2175 /// ◄──┬──►
2176 /// │
2177 /// memory_guard_size
2178 /// ```
2179 ///
2180 /// where `accessible` needs to be grown but there's no more memory to grow
2181 /// into. A new region of the virtual address space will be allocated that
2182 /// looks like this:
2183 ///
2184 /// ```text
2185 /// memory_reservation_for_growth
2186 /// │
2187 /// memory.size │
2188 /// │ │
2189 /// ◄──────┴─────► ◄─────────────┴───────────►
2190 /// ┌───────┬──────────────┬───────────────────────────┬───────┐
2191 /// │ guard │ accessible │ .. reserved for growth .. │ guard │
2192 /// └───────┴──────────────┴───────────────────────────┴───────┘
2193 /// ◄──┬──►
2194 /// │
2195 /// memory_guard_size
2196 /// ```
2197 ///
2198 /// This means that up to `memory_reservation_for_growth` bytes can be
2199 /// allocated again before the entire linear memory needs to be moved again
2200 /// when another `memory_reservation_for_growth` bytes will be appended to
2201 /// the size of the allocation.
2202 ///
2203 /// Note that this is a currently simple heuristic for optimizing the growth
2204 /// of dynamic memories, primarily implemented for the memory64 proposal
2205 /// where the maximum size of memory is larger than 4GiB. This setting is
2206 /// unlikely to be a one-size-fits-all style approach and if you're an
2207 /// embedder running into issues with growth and are interested in having
2208 /// other growth strategies available here please feel free to [open an
2209 /// issue on the Wasmtime repository][issue]!
2210 ///
2211 /// [issue]: https://github.com/bytecodealliance/wasmtime/issues/new
2212 ///
2213 /// ## Default
2214 ///
2215 /// For 64-bit platforms this defaults to 2GiB, and for 32-bit platforms
2216 /// this defaults to 1MiB.
2217 pub fn memory_reservation_for_growth(&mut self, bytes: u64) -> &mut Self {
2218 self.tunables.memory_reservation_for_growth = Some(bytes);
2219 self
2220 }
2221
2222 /// Configures the initial size, in bytes, to be allocated for GC heaps.
2223 ///
2224 /// This is similar to [`Config::memory_reservation`] but applies to the GC
2225 /// heap rather than to linear memories. See that method for more details
2226 /// on what "reservation" means and the implications of this setting.
2227 ///
2228 /// ## Default
2229 ///
2230 /// If none of the `gc_heap_*` tunables are explicitly configured, they
2231 /// default to the same values as their `memory_*` counterparts. Otherwise,
2232 /// the default value for this property depends on the host platform: for
2233 /// 64-bit platforms this defaults to 4GiB, and for 32-bit platforms this
2234 /// defaults to 10MiB.
2235 pub fn gc_heap_reservation(&mut self, bytes: u64) -> &mut Self {
2236 self.tunables.gc_heap_reservation = Some(bytes);
2237 self
2238 }
2239
2240 /// Configures the size, in bytes, of the guard page region for GC heaps.
2241 ///
2242 /// This is similar to [`Config::memory_guard_size`] but applies to the GC
2243 /// heap rather than to linear memories. See that method for more details on
2244 /// what guard pages are and the implications of this setting.
2245 ///
2246 /// ## Default
2247 ///
2248 /// If none of the `gc_heap_*` tunables are explicitly configured, they
2249 /// default to the same values as their `memory_*` counterparts. Otherwise,
2250 /// the default value for this property is 32MiB on 64-bit platforms and
2251 /// 64KiB on 32-bit platforms.
2252 pub fn gc_heap_guard_size(&mut self, bytes: u64) -> &mut Self {
2253 self.tunables.gc_heap_guard_size = Some(bytes);
2254 self
2255 }
2256
2257 /// Configures the size, in bytes, of the extra virtual memory space
2258 /// reserved after a GC heap is relocated.
2259 ///
2260 /// This is similar to [`Config::memory_reservation_for_growth`] but applies
2261 /// to the GC heap rather than to linear memories. See that method for more
2262 /// details.
2263 ///
2264 /// ## Default
2265 ///
2266 /// If none of the `gc_heap_*` tunables are explicitly configured, they
2267 /// default to the same values as their `memory_*` counterparts. Otherwise,
2268 /// for 64-bit platforms this defaults to 2GiB, and for 32-bit platforms
2269 /// this defaults to 1MiB.
2270 pub fn gc_heap_reservation_for_growth(&mut self, bytes: u64) -> &mut Self {
2271 self.tunables.gc_heap_reservation_for_growth = Some(bytes);
2272 self
2273 }
2274
2275 /// Indicates whether GC heaps are allowed to be reallocated after initial
2276 /// allocation at runtime.
2277 ///
2278 /// This is similar to [`Config::memory_may_move`] but applies to the GC
2279 /// heap rather than to linear memories. See that method for more details.
2280 ///
2281 /// ## Default
2282 ///
2283 /// If none of the `gc_heap_*` tunables are explicitly configured, they
2284 /// default to the same values as their `memory_*` counterparts. Otherwise,
2285 /// the default value for this option is `true`.
2286 pub fn gc_heap_may_move(&mut self, enable: bool) -> &mut Self {
2287 self.tunables.gc_heap_may_move = Some(enable);
2288 self
2289 }
2290
2291 /// Indicates whether a guard region is present before allocations of
2292 /// linear memory.
2293 ///
2294 /// Guard regions before linear memories are never used during normal
2295 /// operation of WebAssembly modules, even if they have out-of-bounds
2296 /// loads. The only purpose for a preceding guard region in linear memory
2297 /// is extra protection against possible bugs in code generators like
2298 /// Cranelift. This setting does not affect performance in any way, but will
2299 /// result in larger virtual memory reservations for linear memories (it
2300 /// won't actually ever use more memory, just use more of the address
2301 /// space).
2302 ///
2303 /// The size of the guard region before linear memory is the same as the
2304 /// guard size that comes after linear memory, which is configured by
2305 /// [`Config::memory_guard_size`].
2306 ///
2307 /// ## Default
2308 ///
2309 /// This value defaults to `true`.
2310 pub fn guard_before_linear_memory(&mut self, enable: bool) -> &mut Self {
2311 self.tunables.guard_before_linear_memory = Some(enable);
2312 self
2313 }
2314
2315 /// Indicates whether to initialize tables lazily, so that instantiation
2316 /// is fast but indirect calls are a little slower. If false, tables
2317 /// are initialized eagerly during instantiation from any active element
2318 /// segments that apply to them.
2319 ///
2320 /// **Note** Disabling this option is not compatible with the Winch compiler.
2321 ///
2322 /// ## Default
2323 ///
2324 /// This value defaults to `true`.
2325 pub fn table_lazy_init(&mut self, table_lazy_init: bool) -> &mut Self {
2326 self.tunables.table_lazy_init = Some(table_lazy_init);
2327 self
2328 }
2329
2330 /// Configure the version information used in serialized and deserialized [`crate::Module`]s.
2331 /// This effects the behavior of [`crate::Module::serialize()`], as well as
2332 /// [`crate::Module::deserialize()`] and related functions.
2333 ///
2334 /// The default strategy is to use the wasmtime crate's Cargo package version.
2335 pub fn module_version(&mut self, strategy: ModuleVersionStrategy) -> Result<&mut Self> {
2336 match strategy {
2337 // This case requires special precondition for assertion in SerializedModule::to_bytes
2338 ModuleVersionStrategy::Custom(ref v) => {
2339 if v.as_bytes().len() > 255 {
2340 bail!("custom module version cannot be more than 255 bytes: {v}");
2341 }
2342 }
2343 _ => {}
2344 }
2345 self.module_version = strategy;
2346 Ok(self)
2347 }
2348
2349 /// Configure whether wasmtime should compile a module using multiple
2350 /// threads.
2351 ///
2352 /// Disabling this will result in a single thread being used to compile
2353 /// the wasm bytecode.
2354 ///
2355 /// By default parallel compilation is enabled.
2356 #[cfg(feature = "parallel-compilation")]
2357 pub fn parallel_compilation(&mut self, parallel: bool) -> &mut Self {
2358 self.parallel_compilation = parallel;
2359 self
2360 }
2361
2362 /// Configures whether compiled artifacts will contain information to map
2363 /// native program addresses back to the original wasm module.
2364 ///
2365 /// This configuration option is `true` by default and, if enabled,
2366 /// generates the appropriate tables in compiled modules to map from native
2367 /// address back to wasm source addresses. This is used for displaying wasm
2368 /// program counters in backtraces as well as generating filenames/line
2369 /// numbers if so configured as well (and the original wasm module has DWARF
2370 /// debugging information present).
2371 pub fn generate_address_map(&mut self, generate: bool) -> &mut Self {
2372 self.tunables.generate_address_map = Some(generate);
2373 self
2374 }
2375
2376 /// Configures whether copy-on-write memory-mapped data is used to
2377 /// initialize a linear memory.
2378 ///
2379 /// Initializing linear memory via a copy-on-write mapping can drastically
2380 /// improve instantiation costs of a WebAssembly module because copying
2381 /// memory is deferred. Additionally if a page of memory is only ever read
2382 /// from WebAssembly and never written too then the same underlying page of
2383 /// data will be reused between all instantiations of a module meaning that
2384 /// if a module is instantiated many times this can lower the overall memory
2385 /// required needed to run that module.
2386 ///
2387 /// The main disadvantage of copy-on-write initialization, however, is that
2388 /// it may be possible for highly-parallel scenarios to be less scalable. If
2389 /// a page is read initially by a WebAssembly module then that page will be
2390 /// mapped to a read-only copy shared between all WebAssembly instances. If
2391 /// the same page is then written, however, then a private copy is created
2392 /// and swapped out from the read-only version. This also requires an [IPI],
2393 /// however, which can be a significant bottleneck in high-parallelism
2394 /// situations.
2395 ///
2396 /// This feature is only applicable when a WebAssembly module meets specific
2397 /// criteria to be initialized in this fashion, such as:
2398 ///
2399 /// * Only memories defined in the module can be initialized this way.
2400 /// * Data segments for memory must use statically known offsets.
2401 /// * Data segments for memory must all be in-bounds.
2402 ///
2403 /// Modules which do not meet these criteria will fall back to
2404 /// initialization of linear memory based on copying memory.
2405 ///
2406 /// This feature of Wasmtime is also platform-specific:
2407 ///
2408 /// * Linux - this feature is supported for all instances of [`Module`].
2409 /// Modules backed by an existing mmap (such as those created by
2410 /// [`Module::deserialize_file`]) will reuse that mmap to cow-initialize
2411 /// memory. Other instance of [`Module`] may use the `memfd_create`
2412 /// syscall to create an initialization image to `mmap`.
2413 /// * Unix (not Linux) - this feature is only supported when loading modules
2414 /// from a precompiled file via [`Module::deserialize_file`] where there
2415 /// is a file descriptor to use to map data into the process. Note that
2416 /// the module must have been compiled with this setting enabled as well.
2417 /// * Windows - there is no support for this feature at this time. Memory
2418 /// initialization will always copy bytes.
2419 ///
2420 /// By default this option is enabled.
2421 ///
2422 /// [`Module::deserialize_file`]: crate::Module::deserialize_file
2423 /// [`Module`]: crate::Module
2424 /// [IPI]: https://en.wikipedia.org/wiki/Inter-processor_interrupt
2425 pub fn memory_init_cow(&mut self, enable: bool) -> &mut Self {
2426 self.tunables.memory_init_cow = Some(enable);
2427 self
2428 }
2429
2430 /// A configuration option to force the usage of `memfd_create` on Linux to
2431 /// be used as the backing source for a module's initial memory image.
2432 ///
2433 /// When [`Config::memory_init_cow`] is enabled, which is enabled by
2434 /// default, module memory initialization images are taken from a module's
2435 /// original mmap if possible. If a precompiled module was loaded from disk
2436 /// this means that the disk's file is used as an mmap source for the
2437 /// initial linear memory contents. This option can be used to force, on
2438 /// Linux, that instead of using the original file on disk a new in-memory
2439 /// file is created with `memfd_create` to hold the contents of the initial
2440 /// image.
2441 ///
2442 /// This option can be used to avoid possibly loading the contents of memory
2443 /// from disk through a page fault. Instead with `memfd_create` the contents
2444 /// of memory are always in RAM, meaning that even page faults which
2445 /// initially populate a wasm linear memory will only work with RAM instead
2446 /// of ever hitting the disk that the original precompiled module is stored
2447 /// on.
2448 ///
2449 /// This option is disabled by default.
2450 pub fn force_memory_init_memfd(&mut self, enable: bool) -> &mut Self {
2451 self.force_memory_init_memfd = enable;
2452 self
2453 }
2454
2455 /// Configures whether or not a coredump should be generated and attached to
2456 /// the [`Error`](crate::Error) when a trap is raised.
2457 ///
2458 /// This option is disabled by default.
2459 #[cfg(feature = "coredump")]
2460 pub fn coredump_on_trap(&mut self, enable: bool) -> &mut Self {
2461 self.coredump_on_trap = enable;
2462 self
2463 }
2464
2465 /// Enables memory error checking for wasm programs.
2466 ///
2467 /// This option is disabled by default.
2468 ///
2469 /// # Panics
2470 ///
2471 /// Panics if this configuration's compiler was [disabled][Config::enable_compiler].
2472 #[cfg(any(feature = "cranelift", feature = "winch"))]
2473 pub fn wmemcheck(&mut self, enable: bool) -> &mut Self {
2474 self.wmemcheck = enable;
2475 self.compiler_config_mut().wmemcheck = enable;
2476 self
2477 }
2478
2479 /// Configures the "guaranteed dense image size" for copy-on-write
2480 /// initialized memories.
2481 ///
2482 /// When using the [`Config::memory_init_cow`] feature to initialize memory
2483 /// efficiently (which is enabled by default), compiled modules contain an
2484 /// image of the module's initial heap. If the module has a fairly sparse
2485 /// initial heap, with just a few data segments at very different offsets,
2486 /// this could result in a large region of zero bytes in the image. In
2487 /// other words, it's not very memory-efficient.
2488 ///
2489 /// We normally use a heuristic to avoid this: if less than half
2490 /// of the initialized range (first non-zero to last non-zero
2491 /// byte) of any memory in the module has pages with nonzero
2492 /// bytes, then we avoid creating a memory image for the entire module.
2493 ///
2494 /// However, if the embedder always needs the instantiation-time efficiency
2495 /// of copy-on-write initialization, and is otherwise carefully controlling
2496 /// parameters of the modules (for example, by limiting the maximum heap
2497 /// size of the modules), then it may be desirable to ensure a memory image
2498 /// is created even if this could go against the heuristic above. Thus, we
2499 /// add another condition: there is a size of initialized data region up to
2500 /// which we *always* allow a memory image. The embedder can set this to a
2501 /// known maximum heap size if they desire to always get the benefits of
2502 /// copy-on-write images.
2503 ///
2504 /// In the future we may implement a "best of both worlds"
2505 /// solution where we have a dense image up to some limit, and
2506 /// then support a sparse list of initializers beyond that; this
2507 /// would get most of the benefit of copy-on-write and pay the incremental
2508 /// cost of eager initialization only for those bits of memory
2509 /// that are out-of-bounds. However, for now, an embedder desiring
2510 /// fast instantiation should ensure that this setting is as large
2511 /// as the maximum module initial memory content size.
2512 ///
2513 /// By default this value is 16 MiB.
2514 pub fn memory_guaranteed_dense_image_size(&mut self, size_in_bytes: u64) -> &mut Self {
2515 self.memory_guaranteed_dense_image_size = size_in_bytes;
2516 self
2517 }
2518
2519 /// Whether to enable function inlining during compilation or not.
2520 ///
2521 /// This may result in faster execution at runtime, but adds additional
2522 /// compilation time. Inlining may also enlarge the size of compiled
2523 /// artifacts (for example, the size of the result of
2524 /// [`Engine::precompile_component`]).
2525 ///
2526 /// Inlining is not supported by all of Wasmtime's compilation strategies;
2527 /// currently, it only Cranelift supports it. This setting will be ignored
2528 /// when using a compilation strategy that does not support inlining, like
2529 /// Winch.
2530 ///
2531 /// The default value for this is `Inlining::No`.
2532 pub fn compiler_inlining(&mut self, inlining: Inlining) -> &mut Self {
2533 self.tunables.inlining = Some(inlining);
2534 self
2535 }
2536
2537 /// Returns the set of features that the currently selected compiler backend
2538 /// does not support at all and may panic on.
2539 ///
2540 /// Wasmtime strives to reject unknown modules or unsupported modules with
2541 /// first-class errors instead of panics. Not all compiler backends have the
2542 /// same level of feature support on all platforms as well. This method
2543 /// returns a set of features that the currently selected compiler
2544 /// configuration is known to not support and may panic on. This acts as a
2545 /// first-level filter on incoming wasm modules/configuration to fail-fast
2546 /// instead of panicking later on.
2547 ///
2548 /// Note that if a feature is not returned here it does not mean that the
2549 /// backend fully supports the proposal. Instead that means that the backend
2550 /// doesn't ever panic on the proposal, but errors during compilation may
2551 /// still be returned. This means that features listed here are definitely
2552 /// not supported at all, but features not listed here may still be
2553 /// partially supported. For example at the time of this writing the Winch
2554 /// backend partially supports simd so it's not listed here. Winch doesn't
2555 /// fully support simd but unimplemented instructions just return errors.
2556 fn compiler_panicking_wasm_features(&self) -> WasmFeatures {
2557 // First we compute the set of features that Wasmtime itself knows;
2558 // this is a sort of "maximal set" that we invert to create a set
2559 // of features we _definitely can't support_ because wasmtime
2560 // has never heard of them.
2561 let features_known_to_wasmtime = WasmFeatures::WASM3
2562 | WasmFeatures::COMPONENT_MODEL
2563 | WasmFeatures::CUSTOM_PAGE_SIZES
2564 | WasmFeatures::COMPACT_IMPORTS
2565 | WasmFeatures::STACK_SWITCHING
2566 | WasmFeatures::WIDE_ARITHMETIC
2567 | WasmFeatures::CM_ASYNC
2568 | WasmFeatures::CM_ASYNC_STACKFUL
2569 | WasmFeatures::CM_MORE_ASYNC_BUILTINS
2570 | WasmFeatures::CM_THREADING
2571 | WasmFeatures::CM_ERROR_CONTEXT
2572 | WasmFeatures::CM_GC
2573 | WasmFeatures::CM_MAP
2574 | WasmFeatures::CM64
2575 | WasmFeatures::CM_FIXED_LENGTH_LISTS
2576 | WasmFeatures::CM_IMPLEMENTS
2577 | WasmFeatures::CM_CANON_NAMES
2578 | WasmFeatures::CM_ACCESSORS;
2579
2580 let mut unsupported = !features_known_to_wasmtime;
2581
2582 match self.get_strategy() {
2583 None | Some(Strategy::Cranelift) => {
2584 // Pulley at this time fundamentally doesn't support the
2585 // `threads` proposal, notably shared memory, because Rust can't
2586 // safely implement loads/stores in the face of shared memory.
2587 // Stack switching is not implemented, either.
2588 if self.compiler_target().is_pulley() {
2589 unsupported |= WasmFeatures::THREADS;
2590 unsupported |= WasmFeatures::STACK_SWITCHING;
2591 }
2592
2593 use target_lexicon::*;
2594 match self.compiler_target() {
2595 Triple {
2596 architecture: Architecture::X86_64 | Architecture::X86_64h,
2597 operating_system:
2598 OperatingSystem::Linux
2599 | OperatingSystem::MacOSX(_)
2600 | OperatingSystem::Darwin(_),
2601 ..
2602 } => {
2603 // Stack switching supported on (non-Pulley) Cranelift.
2604 }
2605
2606 _ => {
2607 // On platforms other than x64 Unix-like, we don't
2608 // support stack switching.
2609 unsupported |= WasmFeatures::STACK_SWITCHING;
2610 }
2611 }
2612 }
2613 Some(Strategy::Winch) => {
2614 unsupported |= WasmFeatures::GC
2615 | WasmFeatures::FUNCTION_REFERENCES
2616 | WasmFeatures::RELAXED_SIMD
2617 | WasmFeatures::LEGACY_EXCEPTIONS
2618 | WasmFeatures::STACK_SWITCHING;
2619
2620 match self.compiler_target().architecture {
2621 target_lexicon::Architecture::Aarch64(_) => {
2622 unsupported |= WasmFeatures::THREADS;
2623 }
2624
2625 // Winch doesn't support other non-x64 architectures at this
2626 // time either but will return an first-class error for
2627 // them.
2628 _ => {}
2629 }
2630 }
2631 Some(Strategy::Auto) => unreachable!(),
2632 }
2633 unsupported
2634 }
2635
2636 fn get_strategy(&self) -> Option<Strategy> {
2637 #[cfg(any(feature = "cranelift", feature = "winch"))]
2638 return self.compiler_config.as_ref()?.strategy;
2639 #[cfg(not(any(feature = "cranelift", feature = "winch")))]
2640 return None;
2641 }
2642
2643 /// Calculates the set of features that are enabled for this `Config`.
2644 ///
2645 /// This is a bit of a subtle function which takes into account inputs such
2646 /// as the default set of features Wasmtime has enabled, the currently
2647 /// enabled compiler, the currently enabled target, compile-time crate
2648 /// features, and explicitly configured wasm proposals. This function does
2649 /// not return a fixed set of all proposals in all cases as it's a bit more
2650 /// nuanced than that.
2651 ///
2652 /// This method internally will start with an empty set of features to
2653 /// avoid being tied to wasmparser's defaults. Next Wasmtime's set of
2654 /// default features are added to this set, some of which are conditional
2655 /// depending on crate features. Finally explicitly requested features via
2656 /// `wasm_*` methods on `Config` are applied. Everything is then validated
2657 /// later in `Config::validate`.
2658 ///
2659 /// Note that the validation later on in `Config::validate` is a crucial
2660 /// step here. The returned features here might include features unsupported
2661 /// at compile time or unsupported by the selected compiler. In that case
2662 /// `Config::validate` will present a first-class error message indicating
2663 /// what's going on, and users should in theory be able to understand "ok
2664 /// yeah that's why I can't enable that feature here".
2665 fn features(&self) -> WasmFeatures {
2666 let mut features;
2667
2668 // Next add in all on-by-default features that Wasmtime has which are
2669 // subject to the criteria at
2670 // https://docs.wasmtime.dev/contributing-implementing-wasm-proposals.html
2671 // and https://docs.wasmtime.dev/stability-wasm-proposals.html.
2672 //
2673 // Features here are based on the currently selected compiler. Wasm
2674 // features generally are tightly intertwined with compiler support, and
2675 // just because we want to on-by-default support in one compiler doesn't
2676 // mean we want it for another. Additionally note that each compiler
2677 // here starts with a fixed, unchanging, set of wasm features (e.g.
2678 // `WASM2` or `WASM3`) which insulates this from `wasmparser`'s
2679 // defaults.
2680 //
2681 // Finally, `None` is possible here when compiler support isn't enabled
2682 // at all. In that situation just assume we're using Cranelift's feature
2683 // set.
2684 //
2685 // NB: if you add a feature to a compiler please double-check
2686 // https://docs.wasmtime.dev/stability-wasm-proposals.html
2687 // to ensure all requirements are met and/or update the documentation
2688 // there too.
2689 match self.get_strategy() {
2690 None | Some(Strategy::Cranelift) => {
2691 features = WasmFeatures::WASM3;
2692 features |= WasmFeatures::WIDE_ARITHMETIC;
2693
2694 // features |= WasmFeatures::YOUR_WASM_FEATURE;
2695 // ...
2696 }
2697 Some(Strategy::Winch) => {
2698 features = WasmFeatures::WASM2;
2699 features.remove(WasmFeatures::GC_TYPES);
2700 features |= WasmFeatures::EXTENDED_CONST;
2701 features |= WasmFeatures::MEMORY64;
2702 features |= WasmFeatures::MULTI_MEMORY;
2703 }
2704 Some(Strategy::Auto) => unreachable!(),
2705 }
2706
2707 // Next configure some features further based on compile-time features
2708 // of the wasmtime crate itself. For example if "gc" is disabled then
2709 // `GC_TYPES` are disabled (a wasmparser pseudo-feature) as well as
2710 // exceptions, but reference-types is still available (e.g. new
2711 // encodings/types/etc).
2712 if !cfg!(feature = "gc") {
2713 features.remove(WasmFeatures::GC_TYPES | WasmFeatures::EXCEPTIONS);
2714 }
2715 if !cfg!(feature = "threads") {
2716 features.remove(WasmFeatures::THREADS);
2717 }
2718
2719 // These features aren't included in the base sets above, so explicitly
2720 // enable/disable them there based on compiler features. Note that
2721 // these are pretty much exclusively runtime-related features so there's
2722 // no differentiation here between compilers.
2723 features.set(
2724 WasmFeatures::COMPONENT_MODEL,
2725 cfg!(feature = "component-model"),
2726 );
2727 features.set(
2728 WasmFeatures::CM_ASYNC,
2729 self.tunables
2730 .concurrency_support
2731 .unwrap_or(cfg!(feature = "component-model-async")),
2732 );
2733
2734 // Next disable any features which the current compiler/target do not
2735 // support. This handles cases where Winch, for example, doesn't
2736 // implement a feature yet but Cranelift does. Or maybe Cranelift only
2737 // supports one particular platform and not others. Things like that.
2738 features = features & !self.compiler_panicking_wasm_features();
2739
2740 // And, finally, process all explicitly enabled/disabled features on
2741 // behalf of the embedder's frobbing `Config::wasm_*`. These have the
2742 // highest priority since they were explicitly requested.
2743 debug_assert!((self.enabled_features & self.disabled_features).is_empty());
2744 features &= !self.disabled_features;
2745 features |= self.enabled_features;
2746
2747 features
2748 }
2749
2750 /// Returns the configured compiler target for this `Config`.
2751 pub(crate) fn compiler_target(&self) -> target_lexicon::Triple {
2752 // If a target is explicitly configured, always use that.
2753 if let Some(target) = self.target.clone() {
2754 return target;
2755 }
2756
2757 // If the `build.rs` script determined that this platform uses pulley by
2758 // default, then use Pulley.
2759 if cfg!(default_target_pulley) {
2760 return target_lexicon::Triple::pulley_host();
2761 }
2762
2763 // And at this point the target is for sure the host.
2764 target_lexicon::Triple::host()
2765 }
2766
2767 /// Returns `true` if any of the `gc_heap_*` tunables have been explicitly
2768 /// configured.
2769 fn any_gc_heap_tunables_configured(&self) -> bool {
2770 self.tunables.gc_heap_reservation.is_some()
2771 || self.tunables.gc_heap_guard_size.is_some()
2772 || self.tunables.gc_heap_reservation_for_growth.is_some()
2773 || self.tunables.gc_heap_may_move.is_some()
2774 }
2775
2776 pub(crate) fn validate(&self) -> Result<(Tunables, WasmFeatures)> {
2777 let features = self.features();
2778
2779 // First validate that the selected compiler backend and configuration
2780 // supports the set of `features` that are enabled. This will help
2781 // provide more first class errors instead of panics about unsupported
2782 // features and configurations.
2783 let unsupported = features & self.compiler_panicking_wasm_features();
2784 if !unsupported.is_empty() {
2785 for flag in WasmFeatures::FLAGS.iter() {
2786 if !unsupported.contains(*flag.value()) {
2787 continue;
2788 }
2789 bail!(
2790 "the wasm_{} feature is not supported on this compiler configuration",
2791 flag.name().to_lowercase()
2792 );
2793 }
2794
2795 panic!("should have returned an error by now")
2796 }
2797
2798 if self.max_wasm_stack > self.async_stack_size {
2799 bail!("max_wasm_stack size cannot exceed the async_stack_size");
2800 }
2801 if self.max_wasm_stack == 0 {
2802 bail!("max_wasm_stack size cannot be zero");
2803 }
2804 if !cfg!(feature = "wmemcheck") && self.wmemcheck {
2805 bail!("wmemcheck (memory checker) was requested but is not enabled in this build");
2806 }
2807
2808 if !cfg!(feature = "gc") && features.gc_types() {
2809 bail!("support for GC was disabled at compile time")
2810 }
2811
2812 if !cfg!(feature = "gc") && features.contains(WasmFeatures::EXCEPTIONS) {
2813 bail!("exceptions support requires garbage collection (GC) to be enabled in the build");
2814 }
2815
2816 match &self.rr_config {
2817 #[cfg(feature = "rr")]
2818 RRConfig::Recording | RRConfig::Replaying => {
2819 self.validate_rr_determinism_conflicts()?;
2820 }
2821 RRConfig::None => {}
2822 };
2823
2824 let mut tunables = Tunables::default_for_target(&self.compiler_target())?;
2825
2826 // Stack switching is emitted inline in compiled Wasm. In
2827 // ASan-enabled builds the compiler must arrange the
2828 // corresponding fiber switch handshake around every such
2829 // instruction. This defaults to how Wasmtime itself was built
2830 // but can be overridden with `Config::asan_compatible_code`.
2831 tunables.asan_stack_switching = cfg!(asan);
2832
2833 // By default this is enabled with the Cargo feature, and if the feature
2834 // is missing this is disabled.
2835 tunables.concurrency_support = cfg!(feature = "component-model-async");
2836
2837 #[cfg(feature = "rr")]
2838 {
2839 tunables.recording = matches!(self.rr_config, RRConfig::Recording);
2840 }
2841
2842 // If no target is explicitly specified then further refine `tunables`
2843 // for the configuration of this host depending on what platform
2844 // features were found available at compile time. This means that anyone
2845 // cross-compiling for a customized host will need to further refine
2846 // compilation options.
2847 if self.target.is_none() {
2848 // If this platform doesn't have native signals then change some
2849 // defaults to account for that. Note that VM guards are turned off
2850 // here because that's primarily a feature of eliding
2851 // bounds-checks.
2852 if !cfg!(has_native_signals) {
2853 tunables.signals_based_traps = cfg!(has_native_signals);
2854 tunables.memory_guard_size = 0;
2855 tunables.gc_heap_guard_size = 0;
2856 }
2857
2858 // When virtual memory is not available use slightly different
2859 // defaults for tunables to be more amenable to `MallocMemory`.
2860 // Note that these can still be overridden by config options.
2861 if !cfg!(has_virtual_memory) {
2862 tunables.memory_reservation = 0;
2863 tunables.memory_reservation_for_growth = 1 << 20; // 1MB
2864 tunables.memory_init_cow = false;
2865 tunables.gc_heap_reservation = 0;
2866 tunables.gc_heap_reservation_for_growth = 1 << 20; // 1MB
2867 }
2868 }
2869
2870 // If guest-debugging is enabled, we must disable
2871 // signals-based traps. Do this before we process the user's
2872 // provided tunables settings so we can detect a conflict with
2873 // an explicit request to use signals-based traps.
2874 #[cfg(feature = "debug")]
2875 if self.tunables.debug_guest == Some(true) {
2876 tunables.signals_based_traps = false;
2877 }
2878
2879 // Inlining currently falls over with the `stack_switch` instruction.
2880 #[cfg(any(feature = "cranelift", feature = "winch"))]
2881 if features.contains(WasmFeatures::STACK_SWITCHING) {
2882 if let Some(inlining) = self.tunables.inlining
2883 && inlining != Inlining::No
2884 {
2885 bail!("cannot enable compiler inlining when stack switching is enabled");
2886 }
2887 tunables.inlining = Inlining::No;
2888 }
2889
2890 self.tunables.configure(&mut tunables);
2891
2892 // Debuggers set watchpoints through linear memories' shadows.
2893 tunables.memory_watchpoints = tunables.debug_guest;
2894
2895 // If no GC heap tunables are explicitly configured, copy the memory
2896 // tunables' configured values so that GC heaps default to the same
2897 // configuration as linear memories.
2898 if !self.any_gc_heap_tunables_configured() {
2899 tunables.gc_heap_reservation = tunables.memory_reservation;
2900 tunables.gc_heap_guard_size = tunables.memory_guard_size;
2901 tunables.gc_heap_reservation_for_growth = tunables.memory_reservation_for_growth;
2902 tunables.gc_heap_may_move = tunables.memory_may_move;
2903 }
2904
2905 // Validate that the configuration of reservation/guards is sensible
2906 // enough to ever possibly actually get allocated. If this doesn't fit
2907 // in the target's address space then there's no hope.
2908 let guard_regions = if tunables.guard_before_linear_memory {
2909 2
2910 } else {
2911 1
2912 };
2913 let max_size = match self.compiler_target().pointer_width() {
2914 Ok(width) if width.bits() < 64 => (1 << width.bits()) - 1,
2915 _ => u64::MAX,
2916 };
2917 for (what, reservation, guard_size) in [
2918 (
2919 "memory",
2920 tunables.memory_reservation,
2921 tunables.memory_guard_size,
2922 ),
2923 (
2924 "gc_heap",
2925 tunables.gc_heap_reservation,
2926 tunables.gc_heap_guard_size,
2927 ),
2928 ] {
2929 if guard_size
2930 .checked_mul(guard_regions)
2931 .and_then(|g| g.checked_add(reservation))
2932 .is_none_or(|size| size > max_size)
2933 {
2934 bail!(
2935 "`{what}_reservation` ({reservation}) plus `{what}_guard_size` \
2936 ({guard_size}) overflows the target's address space"
2937 );
2938 }
2939 }
2940
2941 // If we're going to compile with winch, we must use the winch calling convention.
2942 #[cfg(any(feature = "cranelift", feature = "winch"))]
2943 {
2944 tunables.winch_callable = self
2945 .compiler_config
2946 .as_ref()
2947 .is_some_and(|c| c.strategy == Some(Strategy::Winch));
2948 }
2949
2950 tunables.collector = if features.gc_types() {
2951 #[cfg(feature = "gc")]
2952 {
2953 use wasmtime_environ::Collector as EnvCollector;
2954 Some(match self.collector.try_not_auto()? {
2955 Collector::DeferredReferenceCounting => EnvCollector::DeferredReferenceCounting,
2956 Collector::Null => EnvCollector::Null,
2957 Collector::Copying => EnvCollector::Copying,
2958 Collector::Auto => unreachable!(),
2959 })
2960 }
2961 #[cfg(not(feature = "gc"))]
2962 bail!("cannot use GC types: the `gc` feature was disabled at compile time")
2963 } else {
2964 None
2965 };
2966
2967 if tunables.debug_guest {
2968 ensure!(
2969 cfg!(feature = "debug"),
2970 "debug instrumentation support was disabled at compile time"
2971 );
2972 ensure!(
2973 !tunables.signals_based_traps,
2974 "cannot use signals-based traps with guest debugging enabled"
2975 );
2976 }
2977
2978 if tunables.mmu_interruption {
2979 // Only with signals-based traps can MMU interruption's signal
2980 // handler be installed (at engine creation time).
2981 ensure!(
2982 tunables.signals_based_traps,
2983 "MMU interruption requires signals-based traps"
2984 );
2985 }
2986 // Concurrency support is required for some component model features.
2987 let requires_concurrency = WasmFeatures::CM_ASYNC
2988 | WasmFeatures::CM_MORE_ASYNC_BUILTINS
2989 | WasmFeatures::CM_ASYNC_STACKFUL
2990 | WasmFeatures::CM_THREADING
2991 | WasmFeatures::CM_ERROR_CONTEXT;
2992 if tunables.concurrency_support && !cfg!(feature = "component-model-async") {
2993 bail!(
2994 "concurrency support was requested but was not \
2995 compiled into this build of Wasmtime"
2996 )
2997 }
2998 if !tunables.concurrency_support && features.intersects(requires_concurrency) {
2999 bail!(
3000 "concurrency support must be enabled to use the component \
3001 model async or threading features"
3002 )
3003 }
3004
3005 // Generated adapters between components will use `ref.func` in some
3006 // async-related situations so `component-model-async` requires
3007 // `reference-types`.
3008 if features.contains(WasmFeatures::CM_ASYNC)
3009 && !features.contains(WasmFeatures::REFERENCE_TYPES)
3010 {
3011 bail!("the component-model-async feature requires the wasm reference-types proposal");
3012 }
3013
3014 // If the pooling allocator is used and GC is enabled, check that
3015 // memories and the GC heap are configured identically, since the
3016 // pooling allocator can't support differently-configured heaps.
3017 #[cfg(feature = "pooling-allocator")]
3018 if matches!(
3019 &self.allocation_strategy,
3020 InstanceAllocationStrategy::Pooling(_)
3021 ) && tunables.collector.is_some()
3022 {
3023 if tunables.memory_reservation != tunables.gc_heap_reservation {
3024 bail!(
3025 "when using the pooling allocator with GC, `memory_reservation` ({}) \
3026 and `gc_heap_reservation` ({}) must be the same",
3027 tunables.memory_reservation,
3028 tunables.gc_heap_reservation,
3029 );
3030 }
3031 if tunables.memory_guard_size != tunables.gc_heap_guard_size {
3032 bail!(
3033 "when using the pooling allocator with GC, `memory_guard_size` ({}) \
3034 and `gc_heap_guard_size` ({}) must be the same",
3035 tunables.memory_guard_size,
3036 tunables.gc_heap_guard_size,
3037 );
3038 }
3039 if tunables.memory_reservation_for_growth != tunables.gc_heap_reservation_for_growth {
3040 bail!(
3041 "when using the pooling allocator with GC, \
3042 `memory_reservation_for_growth` ({}) and \
3043 `gc_heap_reservation_for_growth` ({}) must be the same",
3044 tunables.memory_reservation_for_growth,
3045 tunables.gc_heap_reservation_for_growth,
3046 );
3047 }
3048 if tunables.memory_may_move != tunables.gc_heap_may_move {
3049 bail!(
3050 "when using the pooling allocator with GC, `memory_may_move` ({}) \
3051 and `gc_heap_may_move` ({}) must be the same",
3052 tunables.memory_may_move,
3053 tunables.gc_heap_may_move,
3054 );
3055 }
3056 }
3057
3058 if tunables.debug_native && !tunables.debug_symbols {
3059 bail!("cannot enable native debug info while debug symbols are disabled");
3060 }
3061
3062 Ok((tunables, features))
3063 }
3064
3065 #[cfg(feature = "runtime")]
3066 pub(crate) fn build_allocator(
3067 &self,
3068 tunables: &Tunables,
3069 ) -> Result<Box<dyn InstanceAllocator + Send + Sync>> {
3070 let _ = tunables;
3071
3072 match &self.allocation_strategy {
3073 InstanceAllocationStrategy::OnDemand => {
3074 let mut _allocator = try_new::<Box<_>>(OnDemandInstanceAllocator::new(
3075 self.mem_creator.clone(),
3076 self.async_stack_size,
3077 self.async_stack_zeroing,
3078 ))?;
3079 #[cfg(feature = "async")]
3080 if let Some(stack_creator) = &self.stack_creator {
3081 _allocator.set_stack_creator(stack_creator.clone());
3082 }
3083 Ok(_allocator as _)
3084 }
3085 #[cfg(feature = "pooling-allocator")]
3086 InstanceAllocationStrategy::Pooling(config) => {
3087 let mut config = config.clone();
3088 let _ = &mut config;
3089 #[cfg(feature = "async")]
3090 {
3091 config.stack_size = self.async_stack_size;
3092 config.async_stack_zeroing = self.async_stack_zeroing;
3093 }
3094 let allocator = try_new::<Box<_>>(
3095 crate::runtime::vm::PoolingInstanceAllocator::new(&config, tunables)?,
3096 )?;
3097 Ok(allocator as _)
3098 }
3099 }
3100 }
3101
3102 #[cfg(feature = "runtime")]
3103 pub(crate) fn build_gc_runtime(&self) -> Result<Option<Arc<dyn GcRuntime>>> {
3104 if !self.features().gc_types() {
3105 return Ok(None);
3106 }
3107
3108 #[cfg(not(feature = "gc"))]
3109 bail!("cannot create a GC runtime: the `gc` feature was disabled at compile time");
3110
3111 #[cfg(feature = "gc")]
3112 #[cfg_attr(
3113 not(any(feature = "gc-null", feature = "gc-drc", feature = "gc-copying")),
3114 expect(unreachable_code, reason = "definitions known to be dummy")
3115 )]
3116 {
3117 Ok(Some(match self.collector.try_not_auto()? {
3118 #[cfg(feature = "gc-drc")]
3119 Collector::DeferredReferenceCounting => {
3120 try_new::<Arc<_>>(crate::runtime::vm::DrcCollector::default())? as _
3121 }
3122 #[cfg(not(feature = "gc-drc"))]
3123 Collector::DeferredReferenceCounting => unreachable!(),
3124
3125 #[cfg(feature = "gc-null")]
3126 Collector::Null => {
3127 try_new::<Arc<_>>(crate::runtime::vm::NullCollector::default())? as _
3128 }
3129 #[cfg(not(feature = "gc-null"))]
3130 Collector::Null => unreachable!(),
3131
3132 #[cfg(feature = "gc-copying")]
3133 Collector::Copying => {
3134 try_new::<Arc<_>>(crate::runtime::vm::CopyingCollector::default())? as _
3135 }
3136 #[cfg(not(feature = "gc-copying"))]
3137 Collector::Copying => unreachable!(),
3138
3139 Collector::Auto => unreachable!(),
3140 }))
3141 }
3142 }
3143
3144 #[cfg(feature = "runtime")]
3145 pub(crate) fn build_profiler(&self) -> Result<Box<dyn ProfilingAgent>> {
3146 Ok(match self.profiling_strategy {
3147 ProfilingStrategy::PerfMap => profiling_agent::new_perfmap()?,
3148 ProfilingStrategy::JitDump => profiling_agent::new_jitdump()?,
3149 ProfilingStrategy::VTune => profiling_agent::new_vtune()?,
3150 ProfilingStrategy::None => profiling_agent::new_null(),
3151 ProfilingStrategy::Pulley => profiling_agent::new_pulley()?,
3152 })
3153 }
3154
3155 #[cfg(any(feature = "cranelift", feature = "winch"))]
3156 pub(crate) fn build_compiler(
3157 mut self,
3158 tunables: &mut Tunables,
3159 features: WasmFeatures,
3160 ) -> Result<(Self, Box<dyn wasmtime_environ::Compiler>)> {
3161 let target = self.compiler_target();
3162
3163 // The target passed to the builders below is an `Option<Triple>` where
3164 // `None` represents the current host with CPU features inferred from
3165 // the host's CPU itself. The `target` above is not an `Option`, so
3166 // switch it to `None` in the case that a target wasn't explicitly
3167 // specified (which indicates no feature inference) and the target
3168 // matches the host.
3169 let target_for_builder =
3170 if self.target.is_none() && target == target_lexicon::Triple::host() {
3171 None
3172 } else {
3173 Some(target.clone())
3174 };
3175
3176 let mut compiler = match self.compiler_config_mut().strategy {
3177 #[cfg(feature = "cranelift")]
3178 Some(Strategy::Cranelift) => wasmtime_cranelift::builder(target_for_builder)?,
3179 #[cfg(not(feature = "cranelift"))]
3180 Some(Strategy::Cranelift) => bail!("cranelift support not compiled in"),
3181 #[cfg(feature = "winch")]
3182 Some(Strategy::Winch) => wasmtime_winch::builder(target_for_builder)?,
3183 #[cfg(not(feature = "winch"))]
3184 Some(Strategy::Winch) => bail!("winch support not compiled in"),
3185
3186 None | Some(Strategy::Auto) => unreachable!(),
3187 };
3188
3189 if let Some(path) = &self.compiler_config_mut().clif_dir {
3190 compiler.clif_dir(path)?;
3191 }
3192
3193 // If probestack is enabled for a target, Wasmtime will always use the
3194 // inline strategy which doesn't require us to define a `__probestack`
3195 // function or similar.
3196 self.compiler_config_mut().settings.insert(
3197 "probestack_strategy".into(),
3198 ("inline".into(), UserSpecified::No),
3199 );
3200
3201 // We enable stack probing by default on all targets.
3202 // This is required on Windows because of the way Windows
3203 // commits its stacks, but it's also a good idea on other
3204 // platforms to ensure guard pages are hit for large frame
3205 // sizes.
3206 self.compiler_config_mut()
3207 .flags
3208 .insert("enable_probestack".into(), UserSpecified::No);
3209
3210 // The current wasm multivalue implementation depends on this.
3211 // FIXME(#9510) handle this in wasmtime-cranelift instead.
3212 self.compiler_config_mut()
3213 .flags
3214 .insert("enable_multi_ret_implicit_sret".into(), UserSpecified::No);
3215
3216 if let Some(unwind_requested) = self.native_unwind_info {
3217 if !self
3218 .compiler_config_mut()
3219 .ensure_setting_unset_or_given("unwind_info", &unwind_requested.to_string())
3220 {
3221 bail!(
3222 "incompatible settings requested for Cranelift and Wasmtime `unwind-info` settings"
3223 );
3224 }
3225 }
3226
3227 if target.operating_system == target_lexicon::OperatingSystem::Windows {
3228 if !self
3229 .compiler_config_mut()
3230 .ensure_setting_unset_or_given("unwind_info", "true")
3231 {
3232 bail!("`native_unwind_info` cannot be disabled on Windows");
3233 }
3234 }
3235
3236 // We require frame pointers for correct stack walking, which is safety
3237 // critical in the presence of reference types, and otherwise it is just
3238 // really bad developer experience to get wrong.
3239 self.compiler_config_mut().settings.insert(
3240 "preserve_frame_pointers".into(),
3241 ("true".into(), UserSpecified::No),
3242 );
3243
3244 if !tunables.signals_based_traps {
3245 let mut ok = self
3246 .compiler_config_mut()
3247 .ensure_setting_unset_or_given("enable_table_access_spectre_mitigation", "false");
3248 ok = ok
3249 && self.compiler_config_mut().ensure_setting_unset_or_given(
3250 "enable_heap_access_spectre_mitigation",
3251 "false",
3252 );
3253
3254 // Right now spectre-mitigated bounds checks will load from zero so
3255 // if host-based signal handlers are disabled then that's a mismatch
3256 // and doesn't work right now. Fixing this will require more thought
3257 // of how to implement the bounds check in spectre-only mode.
3258 if !ok {
3259 bail!(
3260 "when signals-based traps are disabled then spectre \
3261 mitigations must also be disabled"
3262 );
3263 }
3264 }
3265
3266 if features.contains(WasmFeatures::RELAXED_SIMD) && !features.contains(WasmFeatures::SIMD) {
3267 bail!("cannot disable the simd proposal but enable the relaxed simd proposal");
3268 }
3269
3270 if features.contains(WasmFeatures::STACK_SWITCHING) {
3271 use target_lexicon::OperatingSystem;
3272 let model = match target.operating_system {
3273 OperatingSystem::Windows => "update_windows_tib",
3274 OperatingSystem::Linux
3275 | OperatingSystem::MacOSX(_)
3276 | OperatingSystem::Darwin(_) => "basic",
3277 _ => bail!("stack-switching feature not supported on this platform "),
3278 };
3279
3280 if !self
3281 .compiler_config_mut()
3282 .ensure_setting_unset_or_given("stack_switch_model", model)
3283 {
3284 bail!(
3285 "compiler option 'stack_switch_model' must be set to '{model}' on this platform"
3286 );
3287 }
3288 }
3289
3290 // Apply compiler settings and flags
3291 compiler.set_tunables(tunables.clone())?;
3292 for (k, (v, _)) in self.compiler_config_mut().settings.iter() {
3293 compiler.set(k, v)?;
3294 }
3295 for (flag, _) in self.compiler_config_mut().flags.iter() {
3296 compiler.enable(flag)?;
3297 }
3298 *tunables = compiler.tunables().cloned().unwrap();
3299
3300 #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
3301 if let Some(cache_store) = &self.compiler_config_mut().cache_store {
3302 compiler.enable_incremental_compilation(cache_store.clone())?;
3303 }
3304
3305 compiler.wmemcheck(self.compiler_config_mut().wmemcheck);
3306
3307 let compiler = compiler.build()?;
3308
3309 // SIMD support can depend on ISA flags, such as `has_v` on riscv64,
3310 // which aren't known until now, so it's checked here and not in
3311 // `compiler_panicking_wasm_features`.
3312 if !compiler.supports_wasm_simd() {
3313 let simd = WasmFeatures::SIMD | WasmFeatures::RELAXED_SIMD;
3314 if let Some((name, _)) = (features & simd).iter_names().next() {
3315 bail!(
3316 "the wasm_{} feature is not supported on this compiler \
3317 configuration, enable the target's vector extension or \
3318 disable both simd and relaxed-simd",
3319 name.to_lowercase()
3320 );
3321 }
3322 }
3323
3324 Ok((self, compiler))
3325 }
3326
3327 /// Internal setting for whether adapter modules for components will have
3328 /// extra WebAssembly instructions inserted performing more debug checks
3329 /// then are necessary.
3330 #[cfg(feature = "component-model")]
3331 pub fn debug_adapter_modules(&mut self, debug: bool) -> &mut Self {
3332 self.tunables.debug_adapter_modules = Some(debug);
3333 self
3334 }
3335
3336 /// Enables clif output when compiling a WebAssembly module.
3337 #[cfg(any(feature = "cranelift", feature = "winch"))]
3338 pub fn emit_clif(&mut self, path: &Path) -> &mut Self {
3339 self.compiler_config_mut().clif_dir = Some(path.to_path_buf());
3340 self
3341 }
3342
3343 /// Configures whether, when on macOS, Mach ports are used for exception
3344 /// handling instead of traditional Unix-based signal handling.
3345 ///
3346 /// WebAssembly traps in Wasmtime are implemented with native faults, for
3347 /// example a `SIGSEGV` will occur when a WebAssembly guest accesses
3348 /// out-of-bounds memory. Handling this can be configured to either use Unix
3349 /// signals or Mach ports on macOS. By default Mach ports are used.
3350 ///
3351 /// Mach ports enable Wasmtime to work by default with foreign
3352 /// error-handling systems such as breakpad which also use Mach ports to
3353 /// handle signals. In this situation Wasmtime will continue to handle guest
3354 /// faults gracefully while any non-guest faults will get forwarded to
3355 /// process-level handlers such as breakpad. Some more background on this
3356 /// can be found in #2456.
3357 ///
3358 /// A downside of using mach ports, however, is that they don't interact
3359 /// well with `fork()`. Forking a Wasmtime process on macOS will produce a
3360 /// child process that cannot successfully run WebAssembly. In this
3361 /// situation traditional Unix signal handling should be used as that's
3362 /// inherited and works across forks.
3363 ///
3364 /// If your embedding wants to use a custom error handler which leverages
3365 /// Mach ports and you additionally wish to `fork()` the process and use
3366 /// Wasmtime in the child process that's not currently possible. Please
3367 /// reach out to us if you're in this bucket!
3368 ///
3369 /// This option defaults to `true`, using Mach ports by default.
3370 pub fn macos_use_mach_ports(&mut self, mach_ports: bool) -> &mut Self {
3371 self.macos_use_mach_ports = mach_ports;
3372 self
3373 }
3374
3375 /// Configures an embedder-provided function, `detect`, which is used to
3376 /// determine if an ISA-specific feature is available on the current host.
3377 ///
3378 /// This function is used to verify that any features enabled for a compiler
3379 /// backend, such as AVX support on x86\_64, are also available on the host.
3380 /// It is undefined behavior to execute an AVX instruction on a host that
3381 /// doesn't support AVX instructions, for example.
3382 ///
3383 /// When the `std` feature is active on this crate then this function is
3384 /// configured to a default implementation that uses the standard library's
3385 /// feature detection. When the `std` feature is disabled then there is no
3386 /// default available and this method must be called to configure a feature
3387 /// probing function.
3388 ///
3389 /// The `detect` function provided is given a string name of an ISA feature.
3390 /// The function should then return:
3391 ///
3392 /// * `Some(true)` - indicates that the feature was found on the host and it
3393 /// is supported.
3394 /// * `Some(false)` - the feature name was recognized but it was not
3395 /// detected on the host, for example the CPU is too old.
3396 /// * `None` - the feature name was not recognized and it's not known
3397 /// whether it's on the host or not.
3398 ///
3399 /// Feature names passed to `detect` match the same feature name used in the
3400 /// Rust standard library. For example `"sse4.2"` is used on x86\_64.
3401 ///
3402 /// # Unsafety
3403 ///
3404 /// This function is `unsafe` because it is undefined behavior to execute
3405 /// instructions that a host does not support. This means that the result of
3406 /// `detect` must be correct for memory safe execution at runtime.
3407 pub unsafe fn detect_host_feature(&mut self, detect: fn(&str) -> Option<bool>) -> &mut Self {
3408 self.detect_host_feature = Some(detect);
3409 self
3410 }
3411
3412 /// Configures Wasmtime to not use signals-based trap handlers, for example
3413 /// disables `SIGILL` and `SIGSEGV` handler registration on Unix platforms.
3414 ///
3415 /// > **Note:** this option has important performance ramifications, be sure
3416 /// > to understand the implications. Wasm programs have been measured to
3417 /// > run up to 2x slower when signals-based traps are disabled.
3418 ///
3419 /// Wasmtime will by default leverage signals-based trap handlers (or the
3420 /// platform equivalent, for example "vectored exception handlers" on
3421 /// Windows) to make generated code more efficient. For example, when
3422 /// Wasmtime can use signals-based traps, it can elide explicit bounds
3423 /// checks for Wasm linear memory accesses, instead relying on virtual
3424 /// memory guard pages to raise a `SIGSEGV` (on Unix) for out-of-bounds
3425 /// accesses, which Wasmtime's runtime then catches and handles. Another
3426 /// example is divide-by-zero: with signals-based traps, Wasmtime can let
3427 /// the hardware raise a trap when the divisor is zero. Without
3428 /// signals-based traps, Wasmtime must explicitly emit additional
3429 /// instructions to check for zero and conditionally branch to a trapping
3430 /// code path.
3431 ///
3432 /// Some environments however may not have access to signal handlers. For
3433 /// example embedded scenarios may not support virtual memory. Other
3434 /// environments where Wasmtime is embedded within the surrounding
3435 /// environment may require that new signal handlers aren't registered due
3436 /// to the global nature of signal handlers. This option exists to disable
3437 /// the signal handler registration when required for these scenarios.
3438 ///
3439 /// When signals-based trap handlers are disabled, then Wasmtime and its
3440 /// generated code will *never* rely on segfaults or other
3441 /// signals. Generated code will be slower because bounds must be explicitly
3442 /// checked along with other conditions like division by zero.
3443 ///
3444 /// The following additional factors can also affect Wasmtime's ability to
3445 /// elide explicit bounds checks and leverage signals-based traps:
3446 ///
3447 /// * The [`Config::memory_reservation`] and [`Config::memory_guard_size`]
3448 /// settings
3449 /// * The index type of the linear memory (e.g. 32-bit or 64-bit)
3450 /// * The page size of the linear memory
3451 ///
3452 /// When this option is disabled, the
3453 /// `enable_heap_access_spectre_mitigation` and
3454 /// `enable_table_access_spectre_mitigation` Cranelift settings must also be
3455 /// disabled. This means that generated code must have spectre mitigations
3456 /// disabled. This is because spectre mitigations rely on faults from
3457 /// loading from the null address to implement bounds checks.
3458 ///
3459 /// This option defaults to `true`: signals-based trap handlers are enabled
3460 /// by default.
3461 ///
3462 /// > **Note:** Disabling this option is not compatible with the Winch
3463 /// > compiler.
3464 pub fn signals_based_traps(&mut self, enable: bool) -> &mut Self {
3465 self.tunables.signals_based_traps = Some(enable);
3466 self
3467 }
3468
3469 /// Enable/disable GC support in Wasmtime entirely.
3470 ///
3471 /// This flag can be used to gate whether GC infrastructure is enabled or
3472 /// initialized in Wasmtime at all. Wasmtime's GC implementation is required
3473 /// for the [`Self::wasm_gc`] proposal, [`Self::wasm_function_references`],
3474 /// and [`Self::wasm_exceptions`] at this time. None of those proposal can
3475 /// be enabled without also having this option enabled.
3476 ///
3477 /// This option defaults to whether the crate `gc` feature is enabled or
3478 /// not, except when using [`Strategy::Winch`] where it defaults to
3479 /// `false`.
3480 pub fn gc_support(&mut self, enable: bool) -> &mut Self {
3481 self.wasm_features(WasmFeatures::GC_TYPES, enable)
3482 }
3483
3484 /// Explicitly indicate or not whether the host is using a hardware float
3485 /// ABI on x86 targets.
3486 ///
3487 /// This configuration option is only applicable on the
3488 /// `x86_64-unknown-none` Rust target and has no effect on other host
3489 /// targets. The `x86_64-unknown-none` Rust target does not support hardware
3490 /// floats by default and uses a "soft float" implementation and ABI. This
3491 /// means that `f32`, for example, is passed in a general-purpose register
3492 /// between functions instead of a floating-point register. This does not
3493 /// match Cranelift's ABI for `f32` where it's passed in floating-point
3494 /// registers. Cranelift does not have support for a "soft float"
3495 /// implementation where all floating-point operations are lowered to
3496 /// libcalls.
3497 ///
3498 /// This means that for the `x86_64-unknown-none` target the ABI between
3499 /// Wasmtime's libcalls and the host is incompatible when floats are used.
3500 /// This further means that, by default, Wasmtime is unable to load native
3501 /// code when compiled to the `x86_64-unknown-none` target. The purpose of
3502 /// this option is to explicitly allow loading code and bypass this check.
3503 ///
3504 /// Setting this configuration option to `true` indicates that either:
3505 /// (a) the Rust target is compiled with the hard-float ABI manually via
3506 /// `-Zbuild-std` and a custom target JSON configuration, or (b) sufficient
3507 /// x86 features have been enabled in the compiler such that float libcalls
3508 /// will not be used in Wasmtime. For (a) there is no way in Rust at this
3509 /// time to detect whether a hard-float or soft-float ABI is in use on
3510 /// stable Rust, so this manual opt-in is required. For (b) the only
3511 /// instance where Wasmtime passes a floating-point value in a register
3512 /// between the host and compiled wasm code is with libcalls.
3513 ///
3514 /// Float-based libcalls are only used when the compilation target for a
3515 /// wasm module has insufficient target features enabled for native
3516 /// support. For example SSE4.1 is required for the `f32.ceil` WebAssembly
3517 /// instruction to be compiled to a native instruction. If SSE4.1 is not
3518 /// enabled then `f32.ceil` is translated to a "libcall" which is
3519 /// implemented on the host. Float-based libcalls can be avoided with
3520 /// sufficient target features enabled, for example:
3521 ///
3522 /// * `self.cranelift_flag_enable("has_sse3")`
3523 /// * `self.cranelift_flag_enable("has_ssse3")`
3524 /// * `self.cranelift_flag_enable("has_sse41")`
3525 /// * `self.cranelift_flag_enable("has_sse42")`
3526 /// * `self.cranelift_flag_enable("has_fma")`
3527 ///
3528 /// Note that when these features are enabled Wasmtime will perform a
3529 /// runtime check to determine that the host actually has the feature
3530 /// present.
3531 ///
3532 /// For some more discussion see [#11506].
3533 ///
3534 /// [#11506]: https://github.com/bytecodealliance/wasmtime/issues/11506
3535 ///
3536 /// # Safety
3537 ///
3538 /// This method is not safe because it cannot be detected in Rust right now
3539 /// whether the host is compiled with a soft or hard float ABI. Additionally
3540 /// if the host is compiled with a soft float ABI disabling this check does
3541 /// not ensure that the wasm module in question has zero usage of floats
3542 /// in the boundary to the host.
3543 ///
3544 /// Safely using this method requires one of:
3545 ///
3546 /// * The host target is compiled to use hardware floats.
3547 /// * Wasm modules loaded are compiled with enough x86 Cranelift features
3548 /// enabled to avoid float-related hostcalls.
3549 pub unsafe fn x86_float_abi_ok(&mut self, enable: bool) -> &mut Self {
3550 self.x86_float_abi_ok = Some(enable);
3551 self
3552 }
3553
3554 /// Enable or disable the ability to create a
3555 /// [`SharedMemory`](crate::SharedMemory).
3556 ///
3557 /// The WebAssembly threads proposal, configured by [`Config::wasm_threads`]
3558 /// is on-by-default but there are enough deficiencies in Wasmtime's
3559 /// implementation and API integration that creation of a shared memory is
3560 /// disabled by default. This configuration knob can be used to enable this.
3561 ///
3562 /// When enabling this method be aware that wasm threads are, at this time,
3563 /// a [tier 2
3564 /// feature](https://docs.wasmtime.dev/stability-tiers.html#tier-2) in
3565 /// Wasmtime meaning that it will not receive security updates or fixes to
3566 /// historical releases. Additionally security CVEs will not be issued for
3567 /// bugs in the implementation.
3568 ///
3569 /// This option is `false` by default.
3570 pub fn shared_memory(&mut self, enable: bool) -> &mut Self {
3571 self.shared_memory = enable;
3572 self
3573 }
3574
3575 /// Specifies whether support for concurrent execution of WebAssembly is
3576 /// supported within this store.
3577 ///
3578 /// This configuration option affects whether runtime data structures are
3579 /// initialized within a `Store` on creation to support concurrent execution
3580 /// of WebAssembly guests. This is primarily applicable to the
3581 /// [`Config::wasm_component_model_async`] configuration which is the first
3582 /// time Wasmtime has supported concurrent execution of guests. This
3583 /// configuration option, for example, enables usage of
3584 /// [`Store::run_concurrent`], [`Func::call_concurrent`], [`StreamReader`],
3585 /// etc.
3586 ///
3587 /// This configuration option can be manually disabled to avoid initializing
3588 /// data structures in the [`Store`] related to concurrent execution. When
3589 /// this option is disabled then APIs related to concurrency will all fail
3590 /// with a panic. For example [`Store::run_concurrent`] will panic, creating
3591 /// a [`StreamReader`] will panic, etc.
3592 ///
3593 /// The value of this option additionally affects whether a [`Config`] is
3594 /// valid and the default set of enabled WebAssembly features. If this
3595 /// option is disabled then component-model features related to concurrency
3596 /// will all be disabled. If this option is enabled, then the options will
3597 /// retain their normal defaults. It is not valid to create a [`Config`]
3598 /// with component-model-async explicitly enabled and this option explicitly
3599 /// disabled, however.
3600 ///
3601 /// This option defaults to `true`.
3602 ///
3603 /// [`Store`]: crate::Store
3604 /// [`Store::run_concurrent`]: crate::Store::run_concurrent
3605 /// [`Func::call_concurrent`]: crate::component::Func::call_concurrent
3606 /// [`StreamReader`]: crate::component::StreamReader
3607 pub fn concurrency_support(&mut self, enable: bool) -> &mut Self {
3608 self.tunables.concurrency_support = Some(enable);
3609 self
3610 }
3611
3612 /// Configures whether compiled code is compatible with a Wasmtime runtime
3613 /// built with AddressSanitizer (ASan) enabled.
3614 ///
3615 /// Some code Wasmtime generates must cooperate with ASan's bookkeeping
3616 /// when it runs inside an ASan-instrumented host. For example,
3617 /// stack-switching instructions must tell ASan about every switch between
3618 /// stacks. When this option is enabled the generated code includes those
3619 /// hooks. A runtime built without ASan treats them as no-ops.
3620 ///
3621 /// This option is part of a compiled artifact's compatibility key.
3622 /// Artifacts produced by [`Module::serialize`] or
3623 /// [`Component::serialize`] can only be deserialized by an [`Engine`]
3624 /// with the same setting. Code compiled without this option must not run
3625 /// in an ASan-enabled runtime.
3626 ///
3627 /// This option is useful when compiling code outside of ASan, for
3628 /// example with `Engine::precompile_module`, that will later run in a
3629 /// Wasmtime built with `-Zsanitizer=address`.
3630 ///
3631 /// This option defaults to `true` if Wasmtime itself was built with ASan
3632 /// and `false` otherwise.
3633 ///
3634 /// [`Engine`]: crate::Engine
3635 /// [`Module::serialize`]: crate::Module::serialize
3636 /// [`Component::serialize`]: crate::component::Component::serialize
3637 pub fn asan_compatible_code(&mut self, enable: bool) -> &mut Self {
3638 self.tunables.asan_stack_switching = Some(enable);
3639 self
3640 }
3641
3642 /// Validate if the current configuration has conflicting overrides that prevent
3643 /// execution determinism. Returns an error if a conflict exists.
3644 ///
3645 /// Note: Keep this in sync with [`Config::enforce_determinism`].
3646 #[inline]
3647 #[cfg(feature = "rr")]
3648 pub(crate) fn validate_rr_determinism_conflicts(&self) -> Result<()> {
3649 if let Some(v) = self.tunables.relaxed_simd_deterministic {
3650 if v == false {
3651 bail!("Relaxed deterministic SIMD cannot be disabled when determinism is enforced");
3652 }
3653 }
3654 #[cfg(any(feature = "cranelift", feature = "winch"))]
3655 if let Some((v, _)) = self
3656 .compiler_config
3657 .as_ref()
3658 .and_then(|c| c.settings.get("enable_nan_canonicalization"))
3659 {
3660 if v != "true" {
3661 bail!("NaN canonicalization cannot be disabled when determinism is enforced");
3662 }
3663 }
3664 Ok(())
3665 }
3666
3667 /// Enable execution trace recording or replaying to the configuration.
3668 ///
3669 /// When either recording/replaying are enabled, validation fails if settings
3670 /// that control determinism are not set appropriately. In particular, RR requires
3671 /// doing the following:
3672 /// * Enabling NaN canonicalization with [`Config::cranelift_nan_canonicalization`].
3673 /// * Enabling deterministic relaxed SIMD with [`Config::relaxed_simd_deterministic`].
3674 #[inline]
3675 pub fn rr(&mut self, cfg: RRConfig) -> &mut Self {
3676 self.rr_config = cfg;
3677 self
3678 }
3679
3680 /// Whether or not trap metadata is generated in compiled wasms for internal
3681 /// asserts in the compiled code itself.
3682 ///
3683 /// Wasmtime inserts metadata within compiled artifacts which contain a
3684 /// table of known trap codes for all instructions. If a trap via a signal
3685 /// happens, and it's not listed in these tables, then that's considered a
3686 /// fatal bug that crashes the process. This option controls whether trap
3687 /// codes are inserted into metadata for internal asserts as part of
3688 /// Wasmtime's translation process. These internal asserts should never be
3689 /// triggered, but if they are then the process dies with a signal.
3690 ///
3691 /// Inserting trap metadata into compiled artifacts can take extra space in
3692 /// the final artifact. The trap tables for the artifact will be larger as
3693 /// they contain more trap codes to contain.
3694 ///
3695 /// This is intended as a debugging option and is set to `false` by
3696 /// default.
3697 pub fn metadata_for_internal_asserts(&mut self, enable: bool) -> &mut Self {
3698 self.tunables.metadata_for_internal_asserts = Some(enable);
3699 self
3700 }
3701
3702 /// Whether or not trap metadata is generated in compiled wasms for
3703 /// detection of corruption in the GC heap.
3704 ///
3705 /// For more information about what metadata is in this scenario, see
3706 /// [`Config::metadata_for_internal_asserts`]. Note, though, that this
3707 /// option is enabled by default unlike internal asserts. This is intended
3708 /// as a defense-in-depth option for generated code in the face of GC heap
3709 /// corruption. If the GC heap is corrupted and is detected then the
3710 /// trapping instruction will be gracefully handled and delivered to the
3711 /// embedder. Otherwise if this option were set to `false` then the process
3712 /// would be aborted due to a signal.
3713 pub fn metadata_for_gc_heap_corruption(&mut self, enable: bool) -> &mut Self {
3714 self.tunables.metadata_for_gc_heap_corruption = Some(enable);
3715 self
3716 }
3717}
3718
3719impl Default for Config {
3720 fn default() -> Config {
3721 Config::new()
3722 }
3723}
3724
3725impl fmt::Debug for Config {
3726 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
3727 let mut f = f.debug_struct("Config");
3728
3729 // Not every flag in WasmFeatures can be enabled as part of creating
3730 // a Config. This impl gives a complete picture of all WasmFeatures
3731 // enabled, and doesn't require maintenance by hand (which has become out
3732 // of date in the past), at the cost of possible confusion for why
3733 // a flag in this set doesn't have a Config setter.
3734 let features = self.features();
3735 for flag in WasmFeatures::FLAGS.iter() {
3736 f.field(
3737 &format!("wasm_{}", flag.name().to_lowercase()),
3738 &features.contains(*flag.value()),
3739 );
3740 }
3741
3742 f.field("parallel_compilation", &self.parallel_compilation);
3743 #[cfg(any(feature = "cranelift", feature = "winch"))]
3744 {
3745 f.field("compiler_config", &self.compiler_config);
3746 }
3747
3748 self.tunables.format(&mut f);
3749 f.finish()
3750 }
3751}
3752
3753/// Possible Compilation strategies for a wasm module.
3754///
3755/// This is used as an argument to the [`Config::strategy`] method.
3756#[non_exhaustive]
3757#[derive(PartialEq, Eq, Clone, Debug, Copy)]
3758pub enum Strategy {
3759 /// An indicator that the compilation strategy should be automatically
3760 /// selected.
3761 ///
3762 /// This is generally what you want for most projects and indicates that the
3763 /// `wasmtime` crate itself should make the decision about what the best
3764 /// code generator for a wasm module is.
3765 ///
3766 /// Currently this always defaults to Cranelift, but the default value may
3767 /// change over time.
3768 Auto,
3769
3770 /// Currently the default backend, Cranelift aims to be a reasonably fast
3771 /// code generator which generates high quality machine code.
3772 Cranelift,
3773
3774 /// A low-latency baseline compiler for WebAssembly.
3775 /// For more details regarding ISA support and Wasm proposals support
3776 /// see <https://docs.wasmtime.dev/stability-tiers.html#current-tier-status>
3777 Winch,
3778}
3779
3780#[cfg(any(feature = "winch", feature = "cranelift"))]
3781impl Strategy {
3782 fn not_auto(&self) -> Option<Strategy> {
3783 match self {
3784 Strategy::Auto => {
3785 if cfg!(feature = "cranelift") {
3786 Some(Strategy::Cranelift)
3787 } else if cfg!(feature = "winch") {
3788 Some(Strategy::Winch)
3789 } else {
3790 None
3791 }
3792 }
3793 other => Some(*other),
3794 }
3795 }
3796}
3797
3798/// Possible garbage collector implementations for Wasm.
3799///
3800/// This is used as an argument to the [`Config::collector`] method.
3801///
3802/// The properties of Wasmtime's available collectors are summarized in the
3803/// following table:
3804///
3805/// | Collector | Collects Garbage[^1] | Latency[^2] | Throughput[^3] | Allocation Speed[^4] | Heap Utilization[^5] |
3806/// |-----------------------------|-----------------------|-------------|----------------|----------------------|----------------------|
3807/// | `Copying` | Yes, including cycles | 🙁 | 🙂 | 🙂 | 🙁 |
3808/// | `DeferredReferenceCounting` | Yes, but not cycles | 🙂 | 🙁 | 😐 | 😐 |
3809/// | `Null` | No | 🙂 | 🙂 | 🙂 | 🙂 |
3810///
3811/// [^1]: Whether or not the collector is capable of collecting garbage and cyclic garbage.
3812///
3813/// [^2]: How long the Wasm program is paused during garbage
3814/// collections. Shorter is better. In general, better latency implies
3815/// worse throughput and vice versa.
3816///
3817/// [^3]: How fast the Wasm program runs when using this collector. Roughly
3818/// equivalent to the number of Wasm instructions executed per
3819/// second. Faster is better. In general, better throughput implies worse
3820/// latency and vice versa.
3821///
3822/// [^4]: How fast can individual objects be allocated?
3823///
3824/// [^5]: How many objects can the collector fit into N bytes of memory? That
3825/// is, how much space for bookkeeping and metadata does this collector
3826/// require? Less space taken up by metadata means more space for
3827/// additional objects. Reference counts are larger than mark bits and
3828/// free lists are larger than bump pointers, for example.
3829#[non_exhaustive]
3830#[derive(PartialEq, Eq, Clone, Debug, Copy)]
3831pub enum Collector {
3832 /// An indicator that the garbage collector should be automatically
3833 /// selected.
3834 ///
3835 /// This is generally what you want for most projects and indicates that the
3836 /// `wasmtime` crate itself should make the decision about what the best
3837 /// collector to use is.
3838 ///
3839 /// Currently this always defaults to the copying collector, but the default
3840 /// value may change over time.
3841 Auto,
3842
3843 /// The deferred reference-counting collector.
3844 ///
3845 /// A reference-counting collector, generally trading improved latency for
3846 /// worsened throughput. However, to avoid the largest overheads of
3847 /// reference counting, it avoids manipulating reference counts for Wasm
3848 /// objects on the stack. Instead, it will hold a reference count for an
3849 /// over-approximation of all objects that are currently on the stack, trace
3850 /// the stack during collection to find the precise set of on-stack roots,
3851 /// and decrement the reference count of any object that was in the
3852 /// over-approximation but not the precise set. This improves throughput,
3853 /// compared to "pure" reference counting, by performing many fewer
3854 /// refcount-increment and -decrement operations. The cost is the increased
3855 /// latency associated with tracing the stack.
3856 ///
3857 /// This collector cannot currently collect cycles; they will leak until the
3858 /// GC heap's store is dropped.
3859 DeferredReferenceCounting,
3860
3861 /// The null collector.
3862 ///
3863 /// This collector does not actually collect any garbage. It simply
3864 /// allocates objects until it runs out of memory, at which point further
3865 /// objects allocation attempts will trap.
3866 ///
3867 /// This collector is useful for incredibly short-running Wasm instances
3868 /// where additionally you would rather halt an over-allocating Wasm program
3869 /// than spend time collecting its garbage to allow it to keep running. It
3870 /// is also useful for measuring the overheads associated with other
3871 /// collectors, as this collector imposes as close to zero throughput and
3872 /// latency overhead as possible.
3873 Null,
3874
3875 /// The copying collector.
3876 ///
3877 /// A tracing collector that splits the GC heap in half, bump-allocates
3878 /// objects in one half until it fills up, and then does a GC and copies
3879 /// live objects into the other half, and repeats the process. It has fast
3880 /// allocation, collects cyclic garbage, and good collection throughput,
3881 /// however it suffers from poor latency due to its stop-the-world
3882 /// collections and poor heap utilization due to only using half the GC
3883 /// heap's full capacity at any given time.
3884 ///
3885 /// Note that this collector is still under construction and is not yet
3886 /// functional.
3887 Copying,
3888}
3889
3890impl Default for Collector {
3891 fn default() -> Collector {
3892 Collector::Auto
3893 }
3894}
3895
3896#[cfg(feature = "gc")]
3897impl Collector {
3898 fn not_auto(&self) -> Option<Collector> {
3899 match self {
3900 Collector::Auto => {
3901 if cfg!(feature = "gc-copying") {
3902 Some(Collector::Copying)
3903 } else if cfg!(feature = "gc-drc") {
3904 Some(Collector::DeferredReferenceCounting)
3905 } else if cfg!(feature = "gc-null") {
3906 Some(Collector::Null)
3907 } else {
3908 None
3909 }
3910 }
3911 other => Some(*other),
3912 }
3913 }
3914
3915 fn try_not_auto(&self) -> Result<Self> {
3916 match self.not_auto() {
3917 #[cfg(feature = "gc-drc")]
3918 Some(c @ Collector::DeferredReferenceCounting) => Ok(c),
3919 #[cfg(not(feature = "gc-drc"))]
3920 Some(Collector::DeferredReferenceCounting) => bail!(
3921 "cannot create an engine using the deferred reference-counting \
3922 collector because the `gc-drc` feature was not enabled at \
3923 compile time",
3924 ),
3925
3926 #[cfg(feature = "gc-null")]
3927 Some(c @ Collector::Null) => Ok(c),
3928 #[cfg(not(feature = "gc-null"))]
3929 Some(Collector::Null) => bail!(
3930 "cannot create an engine using the null collector because \
3931 the `gc-null` feature was not enabled at compile time",
3932 ),
3933
3934 #[cfg(feature = "gc-copying")]
3935 Some(c @ Collector::Copying) => Ok(c),
3936 #[cfg(not(feature = "gc-copying"))]
3937 Some(Collector::Copying) => bail!(
3938 "cannot create an engine using the copying collector because \
3939 the `gc-copying` feature was not enabled at compile time",
3940 ),
3941
3942 Some(Collector::Auto) => unreachable!(),
3943
3944 None => bail!(
3945 "cannot create an engine with GC support when none of the \
3946 collectors are available; enable one of the following \
3947 features: `gc-drc`, `gc-null`, `gc-copying`",
3948 ),
3949 }
3950 }
3951}
3952
3953/// Possible optimization levels for the Cranelift codegen backend.
3954#[non_exhaustive]
3955#[derive(Copy, Clone, Debug, Eq, PartialEq)]
3956pub enum OptLevel {
3957 /// No optimizations performed, minimizes compilation time by disabling most
3958 /// optimizations.
3959 None,
3960 /// Generates the fastest possible code, but may take longer.
3961 Speed,
3962 /// Similar to `speed`, but also performs transformations aimed at reducing
3963 /// code size.
3964 SpeedAndSize,
3965}
3966
3967/// Possible register allocator algorithms for the Cranelift codegen backend.
3968#[non_exhaustive]
3969#[derive(Copy, Clone, Debug, Eq, PartialEq)]
3970pub enum RegallocAlgorithm {
3971 /// Generates the fastest possible code, but may take longer.
3972 ///
3973 /// This algorithm performs "backtracking", which means that it may
3974 /// undo its earlier work and retry as it discovers conflicts. This
3975 /// results in better register utilization, producing fewer spills
3976 /// and moves, but can cause super-linear compile runtime.
3977 Backtracking,
3978 /// Generates acceptable code very quickly.
3979 ///
3980 /// This algorithm performs a single pass through the code,
3981 /// guaranteed to work in linear time. (Note that the rest of
3982 /// Cranelift is not necessarily guaranteed to run in linear time,
3983 /// however.) It cannot undo earlier decisions, however, and it
3984 /// cannot foresee constraints or issues that may occur further
3985 /// ahead in the code, so the code may have more spills and moves as
3986 /// a result.
3987 ///
3988 /// > **Note**: This algorithm is not yet production-ready and has
3989 /// > historically had known problems. It is not recommended to enable this
3990 /// > algorithm for security-sensitive applications and the Wasmtime project
3991 /// > does not consider this configuration option for issuing security
3992 /// > advisories at this time.
3993 SinglePass,
3994}
3995
3996/// Select which profiling technique to support.
3997#[derive(Debug, Clone, Copy, PartialEq)]
3998pub enum ProfilingStrategy {
3999 /// No profiler support.
4000 None,
4001
4002 /// Collect function name information as the "perf map" file format, used with `perf` on Linux.
4003 PerfMap,
4004
4005 /// Collect profiling info for "jitdump" file format, used with `perf` on
4006 /// Linux.
4007 JitDump,
4008
4009 /// Collect profiling info using the "ittapi", used with `VTune` on Linux.
4010 VTune,
4011
4012 /// Support for profiling Pulley, Wasmtime's interpreter. Note that enabling
4013 /// this at runtime requires enabling the `profile-pulley` Cargo feature at
4014 /// compile time.
4015 Pulley,
4016}
4017
4018/// Select how wasm backtrace detailed information is handled.
4019#[derive(Debug, Clone, Copy)]
4020pub enum WasmBacktraceDetails {
4021 /// Support is unconditionally enabled and wasmtime will parse and read
4022 /// debug information.
4023 Enable,
4024
4025 /// Support is disabled, and wasmtime will not parse debug information for
4026 /// backtrace details.
4027 Disable,
4028
4029 /// Support for backtrace details is conditional on the
4030 /// `WASMTIME_BACKTRACE_DETAILS` environment variable.
4031 Environment,
4032}
4033
4034/// Describe the tri-state configuration of keys such as MPK or PAGEMAP_SCAN.
4035#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
4036pub enum Enabled {
4037 /// Enable this feature if it's detected on the host system, otherwise leave
4038 /// it disabled.
4039 Auto,
4040 /// Enable this feature and fail configuration if the feature is not
4041 /// detected on the host system.
4042 Yes,
4043 /// Do not enable this feature, even if the host system supports it.
4044 No,
4045}
4046
4047/// Configuration options used with [`InstanceAllocationStrategy::Pooling`] to
4048/// change the behavior of the pooling instance allocator.
4049///
4050/// This structure has a builder-style API in the same manner as [`Config`] and
4051/// is configured with [`Config::allocation_strategy`].
4052///
4053/// Note that usage of the pooling allocator does not affect compiled
4054/// WebAssembly code. Compiled `*.cwasm` files, for example, are usable both
4055/// with and without the pooling allocator.
4056///
4057/// ## Advantages of Pooled Allocation
4058///
4059/// The main benefit of the pooling allocator is to make WebAssembly
4060/// instantiation both faster and more scalable in terms of parallelism.
4061/// Allocation is faster because virtual memory is already configured and ready
4062/// to go within the pool, there's no need to [`mmap`] (for example on Unix) a
4063/// new region and configure it with guard pages. By avoiding [`mmap`] this
4064/// avoids whole-process virtual memory locks which can improve scalability and
4065/// performance through avoiding this.
4066///
4067/// Additionally with pooled allocation it's possible to create "affine slots"
4068/// to a particular WebAssembly module or component over time. For example if
4069/// the same module is multiple times over time the pooling allocator will, by
4070/// default, attempt to reuse the same slot. This mean that the slot has been
4071/// pre-configured and can retain virtual memory mappings for a copy-on-write
4072/// image, for example (see [`Config::memory_init_cow`] for more information.
4073/// This means that in a steady state instance deallocation is a single
4074/// [`madvise`] to reset linear memory to its original contents followed by a
4075/// single (optional) [`mprotect`] during the next instantiation to shrink
4076/// memory back to its original size. Compared to non-pooled allocation this
4077/// avoids the need to [`mmap`] a new region of memory, [`munmap`] it, and
4078/// [`mprotect`] regions too.
4079///
4080/// Another benefit of pooled allocation is that it's possible to configure
4081/// things such that no virtual memory management is required at all in a steady
4082/// state. For example a pooling allocator can be configured with:
4083///
4084/// * [`Config::memory_init_cow`] disabled
4085/// * [`Config::memory_guard_size`] disabled
4086/// * [`Config::memory_reservation`] shrunk to minimal size
4087/// * [`PoolingAllocationConfig::table_keep_resident`] sufficiently large
4088/// * [`PoolingAllocationConfig::linear_memory_keep_resident`] sufficiently large
4089///
4090/// With all these options in place no virtual memory tricks are used at all and
4091/// everything is manually managed by Wasmtime (for example resetting memory is
4092/// a `memset(0)`). This is not as fast in a single-threaded scenario but can
4093/// provide benefits in high-parallelism situations as no virtual memory locks
4094/// or IPIs need happen.
4095///
4096/// ## Disadvantages of Pooled Allocation
4097///
4098/// Despite the above advantages to instantiation performance the pooling
4099/// allocator is not enabled by default in Wasmtime. One reason is that the
4100/// performance advantages are not necessarily portable, for example while the
4101/// pooling allocator works on Windows it has not been tuned for performance on
4102/// Windows in the same way it has on Linux.
4103///
4104/// Additionally the main cost of the pooling allocator is that it requires a
4105/// very large reservation of virtual memory (on the order of most of the
4106/// addressable virtual address space). WebAssembly 32-bit linear memories in
4107/// Wasmtime are, by default 4G address space reservations with a small guard
4108/// region both before and after the linear memory. Memories in the pooling
4109/// allocator are contiguous which means that we only need a guard after linear
4110/// memory because the previous linear memory's slot post-guard is our own
4111/// pre-guard. This means that, by default, the pooling allocator uses roughly
4112/// 4G of virtual memory per WebAssembly linear memory slot. 4G of virtual
4113/// memory is 32 bits of a 64-bit address. Many 64-bit systems can only
4114/// actually use 48-bit addresses by default (although this can be extended on
4115/// architectures nowadays too), and of those 48 bits one of them is reserved
4116/// to indicate kernel-vs-userspace. This leaves 47-32=15 bits left,
4117/// meaning you can only have at most 32k slots of linear memories on many
4118/// systems by default. This is a relatively small number and shows how the
4119/// pooling allocator can quickly exhaust all of virtual memory.
4120///
4121/// Another disadvantage of the pooling allocator is that it may keep memory
4122/// alive when nothing is using it. A previously used slot for an instance might
4123/// have paged-in memory that will not get paged out until the
4124/// [`Engine`] owning the pooling allocator is dropped. While
4125/// suitable for some applications this behavior may not be suitable for all
4126/// applications.
4127///
4128/// Finally the last disadvantage of the pooling allocator is that the
4129/// configuration values for the maximum number of instances, memories, tables,
4130/// etc, must all be fixed up-front. There's not always a clear answer as to
4131/// what these values should be so not all applications may be able to work
4132/// with this constraint.
4133///
4134/// [`madvise`]: https://man7.org/linux/man-pages/man2/madvise.2.html
4135/// [`mprotect`]: https://man7.org/linux/man-pages/man2/mprotect.2.html
4136/// [`mmap`]: https://man7.org/linux/man-pages/man2/mmap.2.html
4137/// [`munmap`]: https://man7.org/linux/man-pages/man2/munmap.2.html
4138#[derive(Debug, Clone)]
4139pub struct PoolingAllocationConfig {
4140 /// See `PoolingAllocatorConfig::max_unused_warm_slots` in `wasmtime`
4141 pub(crate) max_unused_warm_slots: u32,
4142 /// The target number of decommits to do per batch. This is not precise, as
4143 /// we can queue up decommits at times when we aren't prepared to
4144 /// immediately flush them, and so we may go over this target size
4145 /// occasionally.
4146 pub(crate) decommit_batch_size: usize,
4147 /// The size, in bytes, of async stacks to allocate (not including the guard
4148 /// page).
4149 #[cfg_attr(
4150 not(all(feature = "async", feature = "pooling-allocator")),
4151 expect(dead_code, reason = "easier to cfg")
4152 )]
4153 pub(crate) stack_size: usize,
4154 /// The limits to apply to instances allocated within this allocator.
4155 pub(crate) limits: InstanceLimits,
4156 /// Whether or not async stacks are zeroed after use.
4157 #[cfg_attr(
4158 not(all(feature = "async", feature = "pooling-allocator")),
4159 expect(dead_code, reason = "easier to cfg")
4160 )]
4161 pub(crate) async_stack_zeroing: bool,
4162 /// If async stack zeroing is enabled and the host platform is Linux this is
4163 /// how much memory to zero out with `memset`.
4164 ///
4165 /// The rest of memory will be zeroed out with `madvise`.
4166 pub(crate) async_stack_keep_resident: usize,
4167 /// How much linear memory, in bytes, to keep resident after resetting for
4168 /// use with the next instance. This much memory will be `memset` to zero
4169 /// when a linear memory is deallocated.
4170 ///
4171 /// Memory exceeding this amount in the wasm linear memory will be released
4172 /// with `madvise` back to the kernel.
4173 ///
4174 /// Only applicable on Linux.
4175 pub(crate) linear_memory_keep_resident: usize,
4176 /// Same as `linear_memory_keep_resident` but for tables.
4177 pub(crate) table_keep_resident: usize,
4178 /// Whether to enable memory protection keys.
4179 pub(crate) memory_protection_keys: Enabled,
4180 /// How many memory protection keys to allocate.
4181 pub(crate) max_memory_protection_keys: usize,
4182 /// Whether to enable PAGEMAP_SCAN on Linux.
4183 pub(crate) pagemap_scan: Enabled,
4184}
4185
4186impl Default for PoolingAllocationConfig {
4187 fn default() -> Self {
4188 Self {
4189 max_unused_warm_slots: 100,
4190 decommit_batch_size: 1,
4191 stack_size: 2 << 20,
4192 limits: InstanceLimits::default(),
4193 async_stack_zeroing: false,
4194 async_stack_keep_resident: 0,
4195 linear_memory_keep_resident: 0,
4196 table_keep_resident: 0,
4197 memory_protection_keys: Enabled::No,
4198 max_memory_protection_keys: 16,
4199 pagemap_scan: Enabled::No,
4200 }
4201 }
4202}
4203
4204/// Instance-related limit configuration for pooling.
4205///
4206/// More docs on this can be found at `wasmtime::PoolingAllocationConfig`.
4207#[derive(Debug, Copy, Clone)]
4208pub(crate) struct InstanceLimits {
4209 /// The maximum number of component instances that may be allocated
4210 /// concurrently.
4211 pub(crate) total_component_instances: u32,
4212
4213 /// The maximum size of a component's `VMComponentContext`, including
4214 /// the aggregate size of all its inner core modules' `VMContext` sizes.
4215 pub(crate) component_instance_size: usize,
4216
4217 /// The maximum number of core module instances that may be allocated
4218 /// concurrently.
4219 pub(crate) total_core_instances: u32,
4220
4221 /// The maximum number of core module instances that a single component may
4222 /// transitively contain.
4223 pub(crate) max_core_instances_per_component: u32,
4224
4225 /// The maximum number of Wasm linear memories that a component may
4226 /// transitively contain.
4227 pub(crate) max_memories_per_component: u32,
4228
4229 /// The maximum number of tables that a component may transitively contain.
4230 pub(crate) max_tables_per_component: u32,
4231
4232 /// The total number of linear memories in the pool, across all instances.
4233 pub(crate) total_memories: u32,
4234
4235 /// The total number of tables in the pool, across all instances.
4236 pub(crate) total_tables: u32,
4237
4238 /// The total number of async stacks in the pool, across all instances.
4239 pub(crate) total_stacks: u32,
4240
4241 /// Maximum size of a core instance's `VMContext`.
4242 pub(crate) core_instance_size: usize,
4243
4244 /// Maximum number of tables per instance.
4245 pub(crate) max_tables_per_module: u32,
4246
4247 /// Maximum number of word-size elements per table.
4248 ///
4249 /// Note that tables for element types such as continuations
4250 /// that use more than one word of storage may store fewer
4251 /// elements.
4252 pub(crate) table_elements: usize,
4253
4254 /// Maximum number of linear memories per instance.
4255 pub(crate) max_memories_per_module: u32,
4256
4257 /// Maximum byte size of a linear memory, must be smaller than
4258 /// `memory_reservation` in `Tunables`.
4259 pub(crate) max_memory_size: usize,
4260
4261 /// The total number of GC heaps in the pool, across all instances.
4262 pub(crate) total_gc_heaps: u32,
4263}
4264
4265impl Default for InstanceLimits {
4266 fn default() -> Self {
4267 let total = if cfg!(target_pointer_width = "32") {
4268 100
4269 } else {
4270 1000
4271 };
4272 // See doc comments for `wasmtime::PoolingAllocationConfig` for these
4273 // default values
4274 Self {
4275 total_component_instances: total,
4276 component_instance_size: 1 << 20, // 1 MiB
4277 total_core_instances: total,
4278 max_core_instances_per_component: u32::MAX,
4279 max_memories_per_component: u32::MAX,
4280 max_tables_per_component: u32::MAX,
4281 total_memories: total,
4282 total_tables: total,
4283 total_stacks: total,
4284 core_instance_size: 1 << 20, // 1 MiB
4285 max_tables_per_module: 1,
4286 // NB: in #8504 it was seen that a C# module in debug module can
4287 // have 10k+ elements.
4288 table_elements: 20_000,
4289 max_memories_per_module: 1,
4290 #[cfg(target_pointer_width = "64")]
4291 max_memory_size: 1 << 32, // 4G,
4292 #[cfg(target_pointer_width = "32")]
4293 max_memory_size: 10 << 20, // 10 MiB
4294 total_gc_heaps: total,
4295 }
4296 }
4297}
4298
4299impl PoolingAllocationConfig {
4300 /// Returns a new configuration builder with all default settings
4301 /// configured.
4302 pub fn new() -> PoolingAllocationConfig {
4303 PoolingAllocationConfig::default()
4304 }
4305
4306 /// Configures the maximum number of "unused warm slots" to retain in the
4307 /// pooling allocator.
4308 ///
4309 /// The pooling allocator operates over slots to allocate from, and each
4310 /// slot is considered "cold" if it's never been used before or "warm" if
4311 /// it's been used by some module in the past. Slots in the pooling
4312 /// allocator additionally track an "affinity" flag to a particular core
4313 /// wasm module. When a module is instantiated into a slot then the slot is
4314 /// considered affine to that module, even after the instance has been
4315 /// deallocated.
4316 ///
4317 /// When a new instance is created then a slot must be chosen, and the
4318 /// current algorithm for selecting a slot is:
4319 ///
4320 /// * If there are slots that are affine to the module being instantiated,
4321 /// then the most recently used slot is selected to be allocated from.
4322 /// This is done to improve reuse of resources such as memory mappings and
4323 /// additionally try to benefit from temporal locality for things like
4324 /// caches.
4325 ///
4326 /// * Otherwise if there are more than N affine slots to other modules, then
4327 /// one of those affine slots is chosen to be allocated. The slot chosen
4328 /// is picked on a least-recently-used basis.
4329 ///
4330 /// * Finally, if there are less than N affine slots to other modules, then
4331 /// the non-affine slots are allocated from.
4332 ///
4333 /// This setting, `max_unused_warm_slots`, is the value for N in the above
4334 /// algorithm. The purpose of this setting is to have a knob over the RSS
4335 /// impact of "unused slots" for a long-running wasm server.
4336 ///
4337 /// If this setting is set to 0, for example, then affine slots are
4338 /// aggressively reused on a least-recently-used basis. A "cold" slot is
4339 /// only used if there are no affine slots available to allocate from. This
4340 /// means that the set of slots used over the lifetime of a program is the
4341 /// same as the maximum concurrent number of wasm instances.
4342 ///
4343 /// If this setting is set to infinity, however, then cold slots are
4344 /// prioritized to be allocated from. This means that the set of slots used
4345 /// over the lifetime of a program will approach
4346 /// [`PoolingAllocationConfig::total_memories`], or the maximum number of
4347 /// slots in the pooling allocator.
4348 ///
4349 /// Wasmtime does not aggressively decommit all resources associated with a
4350 /// slot when the slot is not in use. For example the
4351 /// [`PoolingAllocationConfig::linear_memory_keep_resident`] option can be
4352 /// used to keep memory associated with a slot, even when it's not in use.
4353 /// This means that the total set of used slots in the pooling instance
4354 /// allocator can impact the overall RSS usage of a program.
4355 ///
4356 /// The default value for this option is `100`.
4357 pub fn max_unused_warm_slots(&mut self, max: u32) -> &mut Self {
4358 self.max_unused_warm_slots = max;
4359 self
4360 }
4361
4362 /// The target number of decommits to do per batch.
4363 ///
4364 /// This is not precise, as we can queue up decommits at times when we
4365 /// aren't prepared to immediately flush them, and so we may go over this
4366 /// target size occasionally.
4367 ///
4368 /// Note additionally that the queue of not-yet-decommitted entities is
4369 /// sharded to reduce lock contention: one shard per available CPU, capped
4370 /// at 16. Each shard batches up to this many decommits independently,
4371 /// meaning that up to `min(available_parallelism, 16) * (batch_size - 1)`
4372 /// decommits may be queued and not yet flushed at any given time.
4373 ///
4374 /// A batch size of one effectively disables batching.
4375 ///
4376 /// Defaults to `1`.
4377 pub fn decommit_batch_size(&mut self, batch_size: usize) -> &mut Self {
4378 self.decommit_batch_size = batch_size;
4379 self
4380 }
4381
4382 /// How much memory, in bytes, to keep resident for async stacks allocated
4383 /// with the pooling allocator.
4384 ///
4385 /// When [`Config::async_stack_zeroing`] is enabled then Wasmtime will reset
4386 /// the contents of async stacks back to zero upon deallocation. This option
4387 /// can be used to perform the zeroing operation with `memset` up to a
4388 /// certain threshold of bytes instead of using system calls to reset the
4389 /// stack to zero.
4390 ///
4391 /// Note that when using this option the memory with async stacks will
4392 /// never be decommitted.
4393 pub fn async_stack_keep_resident(&mut self, size: usize) -> &mut Self {
4394 self.async_stack_keep_resident = size;
4395 self
4396 }
4397
4398 /// How much memory, in bytes, to keep resident for each linear memory
4399 /// after deallocation.
4400 ///
4401 /// This option is only applicable on Linux and has no effect on other
4402 /// platforms.
4403 ///
4404 /// By default Wasmtime will use `madvise` to reset the entire contents of
4405 /// linear memory back to zero when a linear memory is deallocated. This
4406 /// option can be used to use `memset` instead to set memory back to zero
4407 /// which can, in some configurations, reduce the number of page faults
4408 /// taken when a slot is reused.
4409 pub fn linear_memory_keep_resident(&mut self, size: usize) -> &mut Self {
4410 self.linear_memory_keep_resident = size;
4411 self
4412 }
4413
4414 /// How much memory, in bytes, to keep resident for each table after
4415 /// deallocation.
4416 ///
4417 /// This option is only applicable on Linux and has no effect on other
4418 /// platforms.
4419 ///
4420 /// This option is the same as
4421 /// [`PoolingAllocationConfig::linear_memory_keep_resident`] except that it
4422 /// is applicable to tables instead.
4423 pub fn table_keep_resident(&mut self, size: usize) -> &mut Self {
4424 self.table_keep_resident = size;
4425 self
4426 }
4427
4428 /// The maximum number of concurrent component instances supported (default
4429 /// is `1000`).
4430 ///
4431 /// This provides an upper-bound on the total size of component
4432 /// metadata-related allocations, along with
4433 /// [`PoolingAllocationConfig::max_component_instance_size`]. The upper bound is
4434 ///
4435 /// ```text
4436 /// total_component_instances * max_component_instance_size
4437 /// ```
4438 ///
4439 /// where `max_component_instance_size` is rounded up to the size and alignment
4440 /// of the internal representation of the metadata.
4441 pub fn total_component_instances(&mut self, count: u32) -> &mut Self {
4442 self.limits.total_component_instances = count;
4443 self
4444 }
4445
4446 /// The maximum size, in bytes, allocated for a component instance's
4447 /// `VMComponentContext` metadata as well as the aggregate size of this
4448 /// component's core instances `VMContext` metadata.
4449 ///
4450 /// The [`wasmtime::component::Instance`][crate::component::Instance] type
4451 /// has a static size but its internal `VMComponentContext` is dynamically
4452 /// sized depending on the component being instantiated. This size limit
4453 /// loosely correlates to the size of the component, taking into account
4454 /// factors such as:
4455 ///
4456 /// * number of lifted and lowered functions,
4457 /// * number of memories
4458 /// * number of inner instances
4459 /// * number of resources
4460 ///
4461 /// If the allocated size per instance is too small then instantiation of a
4462 /// module will fail at runtime with an error indicating how many bytes were
4463 /// needed.
4464 ///
4465 /// In addition to the memory in the runtime for the component itself,
4466 /// components contain one or more core module instances. Each of these
4467 /// require some memory in the runtime as described in
4468 /// [`PoolingAllocationConfig::max_core_instance_size`]. The limit here
4469 /// applies against the sum of all of these individual allocations.
4470 ///
4471 /// The default value for this is 1MiB.
4472 ///
4473 /// This provides an upper-bound on the total size of all component's
4474 /// metadata-related allocations (for both the component and its embedded
4475 /// core module instances), along with
4476 /// [`PoolingAllocationConfig::total_component_instances`]. The upper bound is
4477 ///
4478 /// ```text
4479 /// total_component_instances * max_component_instance_size
4480 /// ```
4481 ///
4482 /// where `max_component_instance_size` is rounded up to the size and alignment
4483 /// of the internal representation of the metadata.
4484 pub fn max_component_instance_size(&mut self, size: usize) -> &mut Self {
4485 self.limits.component_instance_size = size;
4486 self
4487 }
4488
4489 /// The maximum number of core instances a single component may contain
4490 /// (default is unlimited).
4491 ///
4492 /// This method (along with
4493 /// [`PoolingAllocationConfig::max_memories_per_component`],
4494 /// [`PoolingAllocationConfig::max_tables_per_component`], and
4495 /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
4496 /// the amount of resources a single component allocation consumes.
4497 ///
4498 /// If a component will instantiate more core instances than `count`, then
4499 /// the component will fail to instantiate.
4500 pub fn max_core_instances_per_component(&mut self, count: u32) -> &mut Self {
4501 self.limits.max_core_instances_per_component = count;
4502 self
4503 }
4504
4505 /// The maximum number of Wasm linear memories that a single component may
4506 /// transitively contain (default is unlimited).
4507 ///
4508 /// This method (along with
4509 /// [`PoolingAllocationConfig::max_core_instances_per_component`],
4510 /// [`PoolingAllocationConfig::max_tables_per_component`], and
4511 /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
4512 /// the amount of resources a single component allocation consumes.
4513 ///
4514 /// If a component transitively contains more linear memories than `count`,
4515 /// then the component will fail to instantiate.
4516 pub fn max_memories_per_component(&mut self, count: u32) -> &mut Self {
4517 self.limits.max_memories_per_component = count;
4518 self
4519 }
4520
4521 /// The maximum number of tables that a single component may transitively
4522 /// contain (default is unlimited).
4523 ///
4524 /// This method (along with
4525 /// [`PoolingAllocationConfig::max_core_instances_per_component`],
4526 /// [`PoolingAllocationConfig::max_memories_per_component`],
4527 /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
4528 /// the amount of resources a single component allocation consumes.
4529 ///
4530 /// If a component will transitively contains more tables than `count`, then
4531 /// the component will fail to instantiate.
4532 pub fn max_tables_per_component(&mut self, count: u32) -> &mut Self {
4533 self.limits.max_tables_per_component = count;
4534 self
4535 }
4536
4537 /// The maximum number of concurrent Wasm linear memories supported (default
4538 /// is `1000`).
4539 ///
4540 /// This value has a direct impact on the amount of memory allocated by the pooling
4541 /// instance allocator.
4542 ///
4543 /// The pooling instance allocator allocates a memory pool, where each entry
4544 /// in the pool contains the reserved address space for each linear memory
4545 /// supported by an instance.
4546 ///
4547 /// The memory pool will reserve a large quantity of host process address
4548 /// space to elide the bounds checks required for correct WebAssembly memory
4549 /// semantics. Even with 64-bit address spaces, the address space is limited
4550 /// when dealing with a large number of linear memories.
4551 ///
4552 /// For example, on Linux x86_64, the userland address space limit is 128
4553 /// TiB. That might seem like a lot, but each linear memory will *reserve* 6
4554 /// GiB of space by default.
4555 pub fn total_memories(&mut self, count: u32) -> &mut Self {
4556 self.limits.total_memories = count;
4557 self
4558 }
4559
4560 /// The maximum number of concurrent tables supported (default is `1000`).
4561 ///
4562 /// This value has a direct impact on the amount of memory allocated by the
4563 /// pooling instance allocator.
4564 ///
4565 /// The pooling instance allocator allocates a table pool, where each entry
4566 /// in the pool contains the space needed for each WebAssembly table
4567 /// supported by an instance (see `table_elements` to control the size of
4568 /// each table).
4569 pub fn total_tables(&mut self, count: u32) -> &mut Self {
4570 self.limits.total_tables = count;
4571 self
4572 }
4573
4574 /// The maximum number of execution stacks allowed for asynchronous
4575 /// execution, when enabled (default is `1000`).
4576 ///
4577 /// This value has a direct impact on the amount of memory allocated by the
4578 /// pooling instance allocator.
4579 #[cfg(feature = "async")]
4580 pub fn total_stacks(&mut self, count: u32) -> &mut Self {
4581 self.limits.total_stacks = count;
4582 self
4583 }
4584
4585 /// The maximum number of concurrent core instances supported (default is
4586 /// `1000`).
4587 ///
4588 /// This provides an upper-bound on the total size of core instance
4589 /// metadata-related allocations, along with
4590 /// [`PoolingAllocationConfig::max_core_instance_size`]. The upper bound is
4591 ///
4592 /// ```text
4593 /// total_core_instances * max_core_instance_size
4594 /// ```
4595 ///
4596 /// where `max_core_instance_size` is rounded up to the size and alignment of
4597 /// the internal representation of the metadata.
4598 pub fn total_core_instances(&mut self, count: u32) -> &mut Self {
4599 self.limits.total_core_instances = count;
4600 self
4601 }
4602
4603 /// The maximum size, in bytes, allocated for a core instance's `VMContext`
4604 /// metadata.
4605 ///
4606 /// The [`Instance`][crate::Instance] type has a static size but its
4607 /// `VMContext` metadata is dynamically sized depending on the module being
4608 /// instantiated. This size limit loosely correlates to the size of the Wasm
4609 /// module, taking into account factors such as:
4610 ///
4611 /// * number of functions
4612 /// * number of globals
4613 /// * number of memories
4614 /// * number of tables
4615 /// * number of function types
4616 ///
4617 /// If the allocated size per instance is too small then instantiation of a
4618 /// module will fail at runtime with an error indicating how many bytes were
4619 /// needed.
4620 ///
4621 /// The default value for this is 1MiB.
4622 ///
4623 /// This provides an upper-bound on the total size of core instance
4624 /// metadata-related allocations, along with
4625 /// [`PoolingAllocationConfig::total_core_instances`]. The upper bound is
4626 ///
4627 /// ```text
4628 /// total_core_instances * max_core_instance_size
4629 /// ```
4630 ///
4631 /// where `max_core_instance_size` is rounded up to the size and alignment of
4632 /// the internal representation of the metadata.
4633 pub fn max_core_instance_size(&mut self, size: usize) -> &mut Self {
4634 self.limits.core_instance_size = size;
4635 self
4636 }
4637
4638 /// The maximum number of defined tables for a core module (default is `1`).
4639 ///
4640 /// This value controls the capacity of the `VMTableDefinition` table in
4641 /// each instance's `VMContext` structure.
4642 ///
4643 /// The allocated size of the table will be `tables *
4644 /// sizeof(VMTableDefinition)` for each instance regardless of how many
4645 /// tables are defined by an instance's module.
4646 pub fn max_tables_per_module(&mut self, tables: u32) -> &mut Self {
4647 self.limits.max_tables_per_module = tables;
4648 self
4649 }
4650
4651 /// The maximum table elements for any table defined in a module (default is
4652 /// `20000`).
4653 ///
4654 /// If a table's minimum element limit is greater than this value, the
4655 /// module will fail to instantiate.
4656 ///
4657 /// If a table's maximum element limit is unbounded or greater than this
4658 /// value, the maximum will be `table_elements` for the purpose of any
4659 /// `table.grow` instruction.
4660 ///
4661 /// This value is used to reserve the maximum space for each supported
4662 /// table; table elements are pointer-sized in the Wasmtime runtime.
4663 /// Therefore, the space reserved for each instance is `tables *
4664 /// table_elements * sizeof::<*const ()>`.
4665 pub fn table_elements(&mut self, elements: usize) -> &mut Self {
4666 self.limits.table_elements = elements;
4667 self
4668 }
4669
4670 /// The maximum number of defined linear memories for a module (default is
4671 /// `1`).
4672 ///
4673 /// This value controls the capacity of the `VMMemoryDefinition` table in
4674 /// each core instance's `VMContext` structure.
4675 ///
4676 /// The allocated size of the table will be `memories *
4677 /// sizeof(VMMemoryDefinition)` for each core instance regardless of how
4678 /// many memories are defined by the core instance's module.
4679 pub fn max_memories_per_module(&mut self, memories: u32) -> &mut Self {
4680 self.limits.max_memories_per_module = memories;
4681 self
4682 }
4683
4684 /// The maximum byte size that any WebAssembly linear memory may grow to.
4685 ///
4686 /// This option defaults to 4 GiB meaning that for 32-bit linear memories
4687 /// there is no restrictions. 64-bit linear memories will not be allowed to
4688 /// grow beyond 4 GiB by default.
4689 ///
4690 /// If a memory's minimum size is greater than this value, the module will
4691 /// fail to instantiate.
4692 ///
4693 /// If a memory's maximum size is unbounded or greater than this value, the
4694 /// maximum will be `max_memory_size` for the purpose of any `memory.grow`
4695 /// instruction.
4696 ///
4697 /// This value is used to control the maximum accessible space for each
4698 /// linear memory of a core instance. This can be thought of as a simple
4699 /// mechanism like [`Store::limiter`](crate::Store::limiter) to limit memory
4700 /// at runtime. This value can also affect striping/coloring behavior when
4701 /// used in conjunction with
4702 /// [`memory_protection_keys`](PoolingAllocationConfig::memory_protection_keys).
4703 ///
4704 /// The virtual memory reservation size of each linear memory is controlled
4705 /// by the [`Config::memory_reservation`] setting and this method's
4706 /// configuration cannot exceed [`Config::memory_reservation`].
4707 pub fn max_memory_size(&mut self, bytes: usize) -> &mut Self {
4708 self.limits.max_memory_size = bytes;
4709 self
4710 }
4711
4712 /// Configures whether memory protection keys (MPK) should be used for more
4713 /// efficient layout of pool-allocated memories.
4714 ///
4715 /// When using the pooling allocator (see [`Config::allocation_strategy`],
4716 /// [`InstanceAllocationStrategy::Pooling`]), memory protection keys can
4717 /// reduce the total amount of allocated virtual memory by eliminating guard
4718 /// regions between WebAssembly memories in the pool. It does so by
4719 /// "coloring" memory regions with different memory keys and setting which
4720 /// regions are accessible each time executions switches from host to guest
4721 /// (or vice versa).
4722 ///
4723 /// Leveraging MPK requires configuring a smaller-than-default
4724 /// [`max_memory_size`](PoolingAllocationConfig::max_memory_size) to enable
4725 /// this coloring/striping behavior. For example embeddings might want to
4726 /// reduce the default 4G allowance to 128M.
4727 ///
4728 /// MPK is only available on Linux (called `pku` there) and recent x86
4729 /// systems; we check for MPK support at runtime by examining the `CPUID`
4730 /// register. This configuration setting can be in three states:
4731 ///
4732 /// - `auto`: if MPK support is available the guard regions are removed; if
4733 /// not, the guard regions remain
4734 /// - `yes`: use MPK to eliminate guard regions; fail if MPK is not
4735 /// supported
4736 /// - `no`: never use MPK
4737 ///
4738 /// By default this value is `no`, but may become `auto` in future
4739 /// releases.
4740 ///
4741 /// __WARNING__: this configuration options is still experimental--use at
4742 /// your own risk! MPK uses kernel and CPU features to protect memory
4743 /// regions; you may observe segmentation faults if anything is
4744 /// misconfigured.
4745 #[cfg(feature = "memory-protection-keys")]
4746 pub fn memory_protection_keys(&mut self, enable: Enabled) -> &mut Self {
4747 self.memory_protection_keys = enable;
4748 self
4749 }
4750
4751 /// Sets an upper limit on how many memory protection keys (MPK) Wasmtime
4752 /// will use.
4753 ///
4754 /// This setting is only applicable when
4755 /// [`PoolingAllocationConfig::memory_protection_keys`] is set to `enable`
4756 /// or `auto`. Configuring this above the HW and OS limits (typically 15)
4757 /// has no effect.
4758 ///
4759 /// If multiple Wasmtime engines are used in the same process, note that all
4760 /// engines will share the same set of allocated keys; this setting will
4761 /// limit how many keys are allocated initially and thus available to all
4762 /// other engines.
4763 #[cfg(feature = "memory-protection-keys")]
4764 pub fn max_memory_protection_keys(&mut self, max: usize) -> &mut Self {
4765 self.max_memory_protection_keys = max;
4766 self
4767 }
4768
4769 /// Check if memory protection keys (MPK) are available on the current host.
4770 ///
4771 /// This is a convenience method for determining MPK availability using the
4772 /// same method that [`Enabled::Auto`] does. See
4773 /// [`PoolingAllocationConfig::memory_protection_keys`] for more
4774 /// information.
4775 #[cfg(feature = "memory-protection-keys")]
4776 pub fn are_memory_protection_keys_available() -> bool {
4777 crate::runtime::vm::mpk::is_supported()
4778 }
4779
4780 /// The maximum number of concurrent GC heaps supported (default is `1000`).
4781 ///
4782 /// This value has a direct impact on the amount of memory allocated by the
4783 /// pooling instance allocator.
4784 ///
4785 /// The pooling instance allocator allocates a GC heap pool, where each
4786 /// entry in the pool contains the space needed for each GC heap used by a
4787 /// store.
4788 #[cfg(feature = "gc")]
4789 pub fn total_gc_heaps(&mut self, count: u32) -> &mut Self {
4790 self.limits.total_gc_heaps = count;
4791 self
4792 }
4793
4794 /// Configures whether the Linux-specific [`PAGEMAP_SCAN` ioctl][ioctl] is
4795 /// used to help reset linear memory.
4796 ///
4797 /// When [`Self::linear_memory_keep_resident`] or
4798 /// [`Self::table_keep_resident`] options are configured to nonzero values
4799 /// the default behavior is to `memset` the lowest addresses of a table or
4800 /// memory back to their original contents. With the `PAGEMAP_SCAN` ioctl on
4801 /// Linux this can be done to more intelligently scan for resident pages in
4802 /// the region and only reset those pages back to their original contents
4803 /// with `memset` rather than assuming the low addresses are all resident.
4804 ///
4805 /// This ioctl has the potential to provide a number of performance benefits
4806 /// in high-reuse and high concurrency scenarios. Notably this enables
4807 /// Wasmtime to scan the entire region of WebAssembly linear memory and
4808 /// manually reset memory back to its original contents, up to
4809 /// [`Self::linear_memory_keep_resident`] bytes, possibly skipping an
4810 /// `madvise` entirely. This can be more efficient by avoiding removing
4811 /// pages from the address space entirely and additionally ensuring that
4812 /// future use of the linear memory doesn't incur page faults as the pages
4813 /// remain resident.
4814 ///
4815 /// At this time this configuration option is still being evaluated as to
4816 /// how appropriate it is for all use cases. It currently defaults to
4817 /// `no` or disabled but may change to `auto`, enable if supported, in the
4818 /// future. This option is only supported on Linux and requires a kernel
4819 /// version of 6.7 or higher.
4820 ///
4821 /// [ioctl]: https://www.man7.org/linux/man-pages/man2/PAGEMAP_SCAN.2const.html
4822 pub fn pagemap_scan(&mut self, enable: Enabled) -> &mut Self {
4823 self.pagemap_scan = enable;
4824 self
4825 }
4826
4827 /// Returns the configured
4828 /// [`PoolingAllocationConfig::decommit_batch_size`], if enabled.
4829 pub fn get_decommit_batch_size(&self) -> usize {
4830 self.decommit_batch_size
4831 }
4832
4833 /// Returns the configured
4834 /// [`PoolingAllocationConfig::max_unused_warm_slots`], if enabled.
4835 pub fn get_max_unused_warm_slots(&self) -> u32 {
4836 self.max_unused_warm_slots
4837 }
4838
4839 /// Returns the configured
4840 /// [`PoolingAllocationConfig::linear_memory_keep_resident`], if
4841 /// enabled.
4842 pub fn get_memory_keep_resident(&self) -> usize {
4843 self.linear_memory_keep_resident
4844 }
4845
4846 /// Returns the configured
4847 /// [`PoolingAllocationConfig::table_keep_resident`], if enabled.
4848 pub fn get_table_keep_resident(&self) -> usize {
4849 self.table_keep_resident
4850 }
4851
4852 /// Returns the configured
4853 /// [`PoolingAllocationConfig::async_stack_keep_resident`], if
4854 /// enabled.
4855 pub fn get_async_stack_keep_resident(&self) -> usize {
4856 self.async_stack_keep_resident
4857 }
4858
4859 /// Returns the configured
4860 /// [`PoolingAllocationConfig::memory_protection_keys`], if enabled.
4861 pub fn get_memory_protection_keys(&self) -> Enabled {
4862 self.memory_protection_keys
4863 }
4864
4865 /// Returns the configured
4866 /// [`PoolingAllocationConfig::max_memory_protection_keys`], if
4867 /// enabled.
4868 pub fn get_max_memory_protection_keys(&self) -> usize {
4869 self.max_memory_protection_keys
4870 }
4871
4872 /// Returns the configured
4873 /// [`PoolingAllocationConfig::pagemap_scan`], if enabled.
4874 pub fn get_pagemap_scan(&self) -> Enabled {
4875 self.pagemap_scan
4876 }
4877
4878 /// Returns the configured
4879 /// [`PoolingAllocationConfig::total_core_instances`], if enabled.
4880 pub fn get_total_core_instances(&self) -> u32 {
4881 self.limits.total_core_instances
4882 }
4883
4884 /// Returns the configured
4885 /// [`PoolingAllocationConfig::total_component_instances`], if
4886 /// enabled.
4887 pub fn get_total_component_instances(&self) -> u32 {
4888 self.limits.total_component_instances
4889 }
4890
4891 /// Returns the configured
4892 /// [`PoolingAllocationConfig::total_memories`], if enabled.
4893 pub fn get_total_memories(&self) -> u32 {
4894 self.limits.total_memories
4895 }
4896
4897 /// Returns the configured
4898 /// [`PoolingAllocationConfig::total_tables`], if enabled.
4899 pub fn get_total_tables(&self) -> u32 {
4900 self.limits.total_tables
4901 }
4902
4903 /// Returns the configured
4904 /// [`PoolingAllocationConfig::total_stacks`], if enabled.
4905 pub fn get_total_stacks(&self) -> u32 {
4906 self.limits.total_stacks
4907 }
4908
4909 /// Returns the configured
4910 /// [`PoolingAllocationConfig::total_gc_heaps`], if enabled.
4911 pub fn get_total_gc_heaps(&self) -> u32 {
4912 self.limits.total_gc_heaps
4913 }
4914
4915 /// Returns the configured
4916 /// [`PoolingAllocationConfig::max_memory_size`], if enabled.
4917 pub fn get_max_memory_size(&self) -> usize {
4918 self.limits.max_memory_size
4919 }
4920
4921 /// Returns the configured
4922 /// [`PoolingAllocationConfig::table_elements`], if enabled.
4923 pub fn get_table_elements(&self) -> usize {
4924 self.limits.table_elements
4925 }
4926
4927 /// Returns the configured
4928 /// [`PoolingAllocationConfig::max_core_instance_size`], if enabled.
4929 pub fn get_max_core_instance_size(&self) -> usize {
4930 self.limits.core_instance_size
4931 }
4932
4933 /// Returns the configured
4934 /// [`PoolingAllocationConfig::max_component_instance_size`], if
4935 /// enabled.
4936 pub fn get_max_component_instance_size(&self) -> usize {
4937 self.limits.component_instance_size
4938 }
4939
4940 /// Returns the configured
4941 /// [`PoolingAllocationConfig::max_core_instances_per_component`], if
4942 /// enabled.
4943 pub fn get_max_core_instances_per_component(&self) -> u32 {
4944 self.limits.max_core_instances_per_component
4945 }
4946
4947 /// Returns the configured
4948 /// [`PoolingAllocationConfig::max_memories_per_component`], if
4949 /// enabled.
4950 pub fn get_max_memories_per_component(&self) -> u32 {
4951 self.limits.max_memories_per_component
4952 }
4953
4954 /// Returns the configured
4955 /// [`PoolingAllocationConfig::max_tables_per_component`], if enabled.
4956 pub fn get_max_tables_per_component(&self) -> u32 {
4957 self.limits.max_tables_per_component
4958 }
4959
4960 /// Returns the configured
4961 /// [`PoolingAllocationConfig::max_tables_per_module`], if enabled.
4962 pub fn get_max_tables_per_module(&self) -> u32 {
4963 self.limits.max_tables_per_module
4964 }
4965
4966 /// Returns the configured
4967 /// [`PoolingAllocationConfig::max_memories_per_module`], if enabled.
4968 pub fn get_max_memories_per_module(&self) -> u32 {
4969 self.limits.max_memories_per_module
4970 }
4971}
4972
4973#[cfg(feature = "std")]
4974fn detect_host_feature(feature: &str) -> Option<bool> {
4975 #[cfg(target_arch = "aarch64")]
4976 {
4977 return match feature {
4978 "lse" => Some(std::arch::is_aarch64_feature_detected!("lse")),
4979 "paca" => Some(std::arch::is_aarch64_feature_detected!("paca")),
4980 "fp16" => Some(std::arch::is_aarch64_feature_detected!("fp16")),
4981 "dotprod" => Some(std::arch::is_aarch64_feature_detected!("dotprod")),
4982 "i8mm" => Some(std::arch::is_aarch64_feature_detected!("i8mm")),
4983
4984 _ => None,
4985 };
4986 }
4987
4988 // `is_s390x_feature_detected` is nightly only for now, so use the
4989 // STORE FACILITY LIST EXTENDED instruction as a temporary measure.
4990 #[cfg(target_arch = "s390x")]
4991 {
4992 let mut facility_list: [u64; 4] = [0; 4];
4993 unsafe {
4994 core::arch::asm!(
4995 "stfle 0({})",
4996 in(reg_addr) facility_list.as_mut_ptr() ,
4997 inout("r0") facility_list.len() as u64 - 1 => _,
4998 options(nostack)
4999 );
5000 }
5001 let get_facility_bit = |n: usize| {
5002 // NOTE: bits are numbered from the left.
5003 facility_list[n / 64] & (1 << (63 - (n % 64))) != 0
5004 };
5005
5006 return match feature {
5007 "mie3" => Some(get_facility_bit(61)),
5008 "mie4" => Some(get_facility_bit(84)),
5009 "vxrs_ext2" => Some(get_facility_bit(148)),
5010 "vxrs_ext3" => Some(get_facility_bit(198)),
5011
5012 _ => None,
5013 };
5014 }
5015
5016 #[cfg(target_arch = "riscv64")]
5017 {
5018 return match feature {
5019 // due to `is_riscv64_feature_detected` is not stable.
5020 // we cannot use it. For now lie and say all features are always
5021 // found to keep tests working.
5022 _ => Some(true),
5023 };
5024 }
5025
5026 #[cfg(target_arch = "x86_64")]
5027 {
5028 return match feature {
5029 "cmpxchg16b" => Some(std::is_x86_feature_detected!("cmpxchg16b")),
5030 "sse3" => Some(std::is_x86_feature_detected!("sse3")),
5031 "ssse3" => Some(std::is_x86_feature_detected!("ssse3")),
5032 "sse4.1" => Some(std::is_x86_feature_detected!("sse4.1")),
5033 "sse4.2" => Some(std::is_x86_feature_detected!("sse4.2")),
5034 "popcnt" => Some(std::is_x86_feature_detected!("popcnt")),
5035 "avx" => Some(std::is_x86_feature_detected!("avx")),
5036 "avx2" => Some(std::is_x86_feature_detected!("avx2")),
5037 "fma" => Some(std::is_x86_feature_detected!("fma")),
5038 "avxvnni" => Some(std::is_x86_feature_detected!("avxvnni")),
5039 "bmi1" => Some(std::is_x86_feature_detected!("bmi1")),
5040 "bmi2" => Some(std::is_x86_feature_detected!("bmi2")),
5041 "avx512bitalg" => Some(std::is_x86_feature_detected!("avx512bitalg")),
5042 "avx512dq" => Some(std::is_x86_feature_detected!("avx512dq")),
5043 "avx512f" => Some(std::is_x86_feature_detected!("avx512f")),
5044 "avx512vl" => Some(std::is_x86_feature_detected!("avx512vl")),
5045 "avx512vbmi" => Some(std::is_x86_feature_detected!("avx512vbmi")),
5046 "avx512vnni" => Some(std::is_x86_feature_detected!("avx512vnni")),
5047 "lzcnt" => Some(std::is_x86_feature_detected!("lzcnt")),
5048
5049 _ => None,
5050 };
5051 }
5052
5053 #[allow(
5054 unreachable_code,
5055 reason = "reachable or not depending on if a target above matches"
5056 )]
5057 {
5058 let _ = feature;
5059 return None;
5060 }
5061}
5062
5063// What follows in this impl block is intended to be a somewhat-mechanical
5064// mostly-complete set of getters for relevant configuration options on
5065// `Config`. The `Config` type does not reflect a complete configuration so
5066// default values cannot be directly read from it. An `Engine`, however,
5067// represents a concrete and complete configuration with all default values
5068// fully specified. The purpose of these getters are then to perform a dual
5069// function of reflecting what was explicitly configured above as well as
5070// defaults that Wasmtime sets.
5071//
5072// The current pattern is:
5073//
5074// * All methods are `get_<config_name>`
5075// * Return values return `T` instead of `Option<T>` where possible unless the
5076// state for `T` is completely missing.
5077//
5078// This impl is primarily in service of
5079// `wasmtime_cli_flags::CommonOptions::from_engine` at this time, and CLI flags
5080// are not as comprehensive as `Config` options, but it's expected that the set
5081// will settle/grow over time.
5082impl Engine {
5083 /// Returns the configured [`Config::memory_may_move`] value.
5084 pub fn get_memory_may_move(&self) -> bool {
5085 self.tunables().memory_may_move
5086 }
5087
5088 /// Returns the configured [`Config::memory_reservation`] value.
5089 pub fn get_memory_reservation(&self) -> u64 {
5090 self.tunables().memory_reservation
5091 }
5092
5093 /// Returns the configured [`Config::memory_reservation_for_growth`] value.
5094 pub fn get_memory_reservation_for_growth(&self) -> u64 {
5095 self.tunables().memory_reservation_for_growth
5096 }
5097
5098 /// Returns the configured [`Config::memory_guard_size`] value.
5099 pub fn get_memory_guard_size(&self) -> u64 {
5100 self.tunables().memory_guard_size
5101 }
5102
5103 /// Returns the configured [`Config::gc_heap_may_move`] value.
5104 pub fn get_gc_heap_may_move(&self) -> bool {
5105 self.tunables().gc_heap_may_move
5106 }
5107
5108 /// Returns the configured [`Config::gc_heap_reservation`] value.
5109 pub fn get_gc_heap_reservation(&self) -> u64 {
5110 self.tunables().gc_heap_reservation
5111 }
5112
5113 /// Returns the configured [`Config::gc_heap_initial_size`] value.
5114 pub fn get_gc_heap_initial_size(&self) -> u64 {
5115 self.tunables().gc_heap_initial_size
5116 }
5117
5118 /// Returns the configured [`Config::gc_heap_reservation_for_growth`] value.
5119 pub fn get_gc_heap_reservation_for_growth(&self) -> u64 {
5120 self.tunables().gc_heap_reservation_for_growth
5121 }
5122
5123 /// Returns the configured [`Config::gc_heap_guard_size`] value.
5124 pub fn get_gc_heap_guard_size(&self) -> u64 {
5125 self.tunables().gc_heap_guard_size
5126 }
5127
5128 /// Returns the configured [`Config::guard_before_linear_memory`] value.
5129 pub fn get_guard_before_linear_memory(&self) -> bool {
5130 self.tunables().guard_before_linear_memory
5131 }
5132
5133 /// Returns the configured [`Config::table_lazy_init`] value.
5134 pub fn get_table_lazy_init(&self) -> bool {
5135 self.tunables().table_lazy_init
5136 }
5137
5138 /// Returns the configured [`Config::memory_init_cow`] value.
5139 pub fn get_memory_init_cow(&self) -> bool {
5140 self.tunables().memory_init_cow
5141 }
5142
5143 /// Returns the configured [`Config::memory_guaranteed_dense_image_size`] value.
5144 pub fn get_memory_guaranteed_dense_image_size(&self) -> u64 {
5145 self.config().memory_guaranteed_dense_image_size
5146 }
5147
5148 /// Returns the configured [`Config::signals_based_traps`] value.
5149 pub fn get_signals_based_traps(&self) -> bool {
5150 self.tunables().signals_based_traps
5151 }
5152
5153 /// Returns the configured [`Config::gc_zeal_alloc_counter`] value.
5154 pub fn get_gc_zeal_alloc_counter(&self) -> Option<core::num::NonZeroU32> {
5155 self.tunables().gc_zeal_alloc_counter
5156 }
5157
5158 /// Returns the configured [`Config::cranelift_opt_level`] value.
5159 pub fn get_cranelift_opt_level(&self) -> Option<OptLevel> {
5160 #[cfg(any(feature = "cranelift", feature = "winch"))]
5161 if let Some(compiler) = self.compiler() {
5162 let flags = compiler.flags();
5163 let (_, FlagValue::Enum(opt)) = flags.iter().find(|(f, _)| *f == "opt_level")? else {
5164 return None;
5165 };
5166 return match &opt[..] {
5167 "none" => Some(OptLevel::None),
5168 "speed" => Some(OptLevel::Speed),
5169 "speed_and_size" => Some(OptLevel::SpeedAndSize),
5170 _ => None,
5171 };
5172 }
5173 None
5174 }
5175
5176 /// Returns the configured [`Config::cranelift_regalloc_algorithm`] value.
5177 pub fn get_cranelift_regalloc_algorithm(&self) -> Option<RegallocAlgorithm> {
5178 #[cfg(any(feature = "cranelift", feature = "winch"))]
5179 if let Some(compiler) = self.compiler() {
5180 let flags = compiler.flags();
5181 let (_, FlagValue::Enum(opt)) =
5182 flags.iter().find(|(f, _)| *f == "regalloc_algorithm")?
5183 else {
5184 return None;
5185 };
5186 return match &opt[..] {
5187 "backtracking" => Some(RegallocAlgorithm::Backtracking),
5188 "single_pass" => Some(RegallocAlgorithm::SinglePass),
5189 _ => None,
5190 };
5191 }
5192 None
5193 }
5194
5195 /// Returns the configured [`Config::strategy`] value.
5196 pub fn get_strategy(&self) -> Option<Strategy> {
5197 self.config().get_strategy()
5198 }
5199
5200 /// Returns the configured [`Config::collector`] value.
5201 pub fn get_collector(&self) -> Option<Collector> {
5202 #[cfg(feature = "gc")]
5203 return Some(self.config().collector);
5204 #[cfg(not(feature = "gc"))]
5205 return None;
5206 }
5207
5208 /// Returns the configured [`Config::cranelift_debug_verifier`] value.
5209 pub fn get_cranelift_debug_verifier(&self) -> Option<bool> {
5210 #[cfg(any(feature = "cranelift", feature = "winch"))]
5211 if let Some(compiler) = self.compiler() {
5212 let flags = compiler.flags();
5213 let (_, FlagValue::Bool(b)) = flags.iter().find(|(f, _)| *f == "enable_verifier")?
5214 else {
5215 return None;
5216 };
5217 return Some(*b);
5218 }
5219 None
5220 }
5221
5222 /// Returns the configured [`Config::compiler_inlining`] value.
5223 pub fn get_compiler_inlining(&self) -> Inlining {
5224 self.tunables().inlining
5225 }
5226
5227 /// Returns the configured [`Config::native_unwind_info`] value.
5228 pub fn get_native_unwind_info(&self) -> Option<bool> {
5229 #[cfg(any(feature = "cranelift", feature = "winch"))]
5230 if let Some(compiler) = self.compiler() {
5231 let flags = compiler.flags();
5232 let (_, FlagValue::Bool(b)) = flags.iter().find(|(f, _)| *f == "unwind_info")? else {
5233 return None;
5234 };
5235 return Some(*b);
5236 }
5237 None
5238 }
5239
5240 /// Returns the configured [`Config::parallel_compilation`] value.
5241 pub fn get_parallel_compilation(&self) -> bool {
5242 self.config().parallel_compilation
5243 }
5244
5245 /// Returns the configured [`Config::metadata_for_internal_asserts`] value.
5246 pub fn get_metadata_for_internal_asserts(&self) -> bool {
5247 self.tunables().metadata_for_internal_asserts
5248 }
5249
5250 /// Returns the configured [`Config::metadata_for_gc_heap_corruption`] value.
5251 pub fn get_metadata_for_gc_heap_corruption(&self) -> bool {
5252 self.tunables().metadata_for_gc_heap_corruption
5253 }
5254
5255 /// Returns the runtime pooling allocator configuration, if the pooling
5256 /// allocator is in use.
5257 pub fn get_pooling_config(&self) -> Option<&PoolingAllocationConfig> {
5258 #[cfg(feature = "pooling-allocator")]
5259 {
5260 Some(self.allocator().as_pooling()?.config())
5261 }
5262 #[cfg(not(feature = "pooling-allocator"))]
5263 {
5264 None
5265 }
5266 }
5267
5268 /// Returns the configured wasm proposals enabled in this engine.
5269 pub fn get_wasm_features(&self) -> WasmFeatures {
5270 self.features()
5271 }
5272
5273 /// Returns the configured [`Config::async_stack_size`] value.
5274 pub fn get_async_stack_size(&self) -> usize {
5275 self.config().async_stack_size
5276 }
5277
5278 /// Returns the configured [`Config::async_stack_zeroing`] value.
5279 pub fn get_async_stack_zeroing(&self) -> bool {
5280 self.config().async_stack_zeroing
5281 }
5282
5283 /// Returns the configured [`Config::wasm_branch_hinting`] value.
5284 pub fn get_wasm_branch_hinting(&self) -> bool {
5285 self.tunables().branch_hinting
5286 }
5287
5288 /// Returns the configured [`Config::concurrency_support`] value.
5289 pub fn get_concurrency_support(&self) -> bool {
5290 self.tunables().concurrency_support
5291 }
5292
5293 /// Returns the configured [`Config::asan_compatible_code`] value.
5294 pub fn get_asan_compatible_code(&self) -> bool {
5295 self.tunables().asan_stack_switching
5296 }
5297
5298 /// Returns the configured [`Config::epoch_interruption`] value.
5299 pub fn get_epoch_interruption(&self) -> bool {
5300 self.tunables().epoch_interruption
5301 }
5302
5303 /// Returns the configured [`Config::mmu_interruption`] value.
5304 #[doc(hidden)]
5305 pub fn get_mmu_interruption(&self) -> bool {
5306 self.tunables().mmu_interruption
5307 }
5308
5309 /// Returns the configured [`Config::consume_fuel`] value.
5310 pub fn get_consume_fuel(&self) -> bool {
5311 self.tunables().consume_fuel
5312 }
5313
5314 /// Returns the configured [`Config::max_wasm_stack`] value.
5315 pub fn get_max_wasm_stack(&self) -> usize {
5316 self.config().max_wasm_stack
5317 }
5318
5319 /// Returns the configured [`Config::cranelift_nan_canonicalization`] value.
5320 pub fn get_cranelift_nan_canonicalization(&self) -> Option<bool> {
5321 #[cfg(any(feature = "cranelift", feature = "winch"))]
5322 if let Some(compiler) = self.compiler() {
5323 let flags = compiler.flags();
5324 let (_, FlagValue::Bool(b)) = flags
5325 .iter()
5326 .find(|(f, _)| *f == "enable_nan_canonicalization")?
5327 else {
5328 return None;
5329 };
5330 return Some(*b);
5331 }
5332 None
5333 }
5334
5335 /// Returns the configured [`Config::relaxed_simd_deterministic`] value.
5336 pub fn get_relaxed_simd_deterministic(&self) -> bool {
5337 self.tunables().relaxed_simd_deterministic
5338 }
5339
5340 /// Returns the configured [`Config::shared_memory`] value.
5341 pub fn get_shared_memory(&self) -> bool {
5342 self.config().shared_memory
5343 }
5344
5345 /// Returns the configured [`Config::generate_address_map`] value.
5346 pub fn get_generate_address_map(&self) -> bool {
5347 self.tunables().generate_address_map
5348 }
5349
5350 /// Returns the configured [`Config::debug_info`] value.
5351 pub fn get_debug_info(&self) -> bool {
5352 self.tunables().debug_native
5353 }
5354
5355 /// Returns the configured [`Config::guest_debug`] value.
5356 pub fn get_guest_debug(&self) -> bool {
5357 self.tunables().debug_guest
5358 }
5359
5360 /// Returns the configured [`Config::debug_symbols`] value.
5361 pub fn get_debug_symbols(&self) -> bool {
5362 self.tunables().debug_symbols
5363 }
5364
5365 /// Returns the configured [`Config::wasm_backtrace_max_frames`] value.
5366 pub fn get_wasm_backtrace_max_frames(&self) -> usize {
5367 self.config()
5368 .wasm_backtrace_max_frames
5369 .map(|f| f.get())
5370 .unwrap_or(0)
5371 }
5372
5373 /// Returns the configured [`Config::target`] value.
5374 pub fn get_target(&self) -> Option<String> {
5375 #[cfg(any(feature = "cranelift", feature = "winch"))]
5376 if let Some(compiler) = self.compiler() {
5377 return Some(compiler.triple().to_string());
5378 }
5379 None
5380 }
5381
5382 /// Returns the enabled flags via [`Config::cranelift_flag_enable`].
5383 pub fn get_cranelift_flags_enabled(&self) -> impl Iterator<Item = &str> {
5384 #[cfg(any(feature = "cranelift", feature = "winch"))]
5385 if let Some(config) = &self.config().compiler_config {
5386 return config
5387 .flags
5388 .iter()
5389 .filter_map(|(k, v)| match v {
5390 UserSpecified::Yes => Some(k.as_str()),
5391 UserSpecified::No => None,
5392 })
5393 .collect::<Vec<_>>()
5394 .into_iter();
5395 }
5396
5397 Vec::new().into_iter()
5398 }
5399
5400 /// Returns the enabled flags via [`Config::cranelift_flag_set`].
5401 pub fn get_cranelift_flags_set(&self) -> impl Iterator<Item = (&str, &str)> {
5402 #[cfg(any(feature = "cranelift", feature = "winch"))]
5403 if let Some(config) = &self.config().compiler_config {
5404 return config
5405 .settings
5406 .iter()
5407 .filter_map(|(k, (v, s))| match s {
5408 UserSpecified::Yes => Some((k.as_str(), v.as_str())),
5409 UserSpecified::No => None,
5410 })
5411 .collect::<Vec<_>>()
5412 .into_iter();
5413 }
5414
5415 Vec::new().into_iter()
5416 }
5417}