Skip to main content

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        if !cfg!(feature = "threads") && features.threads() {
2817            bail!("support for threads was disabled at compile time")
2818        }
2819
2820        if !cfg!(feature = "stack-switching") && features.contains(WasmFeatures::STACK_SWITCHING) {
2821            bail!("support for stack switching was disabled at compile time")
2822        }
2823
2824        match &self.rr_config {
2825            #[cfg(feature = "rr")]
2826            RRConfig::Recording | RRConfig::Replaying => {
2827                self.validate_rr_determinism_conflicts()?;
2828            }
2829            RRConfig::None => {}
2830        };
2831
2832        let mut tunables = Tunables::default_for_target(&self.compiler_target())?;
2833
2834        // Stack switching is emitted inline in compiled Wasm. In
2835        // ASan-enabled builds the compiler must arrange the
2836        // corresponding fiber switch handshake around every such
2837        // instruction. This defaults to how Wasmtime itself was built
2838        // but can be overridden with `Config::asan_compatible_code`.
2839        tunables.asan_stack_switching = cfg!(asan);
2840
2841        // By default this is enabled with the Cargo feature, and if the feature
2842        // is missing this is disabled.
2843        tunables.concurrency_support = cfg!(feature = "component-model-async");
2844
2845        #[cfg(feature = "rr")]
2846        {
2847            tunables.recording = matches!(self.rr_config, RRConfig::Recording);
2848        }
2849
2850        // If no target is explicitly specified then further refine `tunables`
2851        // for the configuration of this host depending on what platform
2852        // features were found available at compile time. This means that anyone
2853        // cross-compiling for a customized host will need to further refine
2854        // compilation options.
2855        if self.target.is_none() {
2856            // If this platform doesn't have native signals then change some
2857            // defaults to account for that. Note that VM guards are turned off
2858            // here because that's primarily a feature of eliding
2859            // bounds-checks.
2860            if !cfg!(has_native_signals) {
2861                tunables.signals_based_traps = cfg!(has_native_signals);
2862                tunables.memory_guard_size = 0;
2863                tunables.gc_heap_guard_size = 0;
2864            }
2865
2866            // When virtual memory is not available use slightly different
2867            // defaults for tunables to be more amenable to `MallocMemory`.
2868            // Note that these can still be overridden by config options.
2869            if !cfg!(has_virtual_memory) {
2870                tunables.memory_reservation = 0;
2871                tunables.memory_reservation_for_growth = 1 << 20; // 1MB
2872                tunables.memory_init_cow = false;
2873                tunables.gc_heap_reservation = 0;
2874                tunables.gc_heap_reservation_for_growth = 1 << 20; // 1MB
2875            }
2876        }
2877
2878        // If guest-debugging is enabled, we must disable
2879        // signals-based traps. Do this before we process the user's
2880        // provided tunables settings so we can detect a conflict with
2881        // an explicit request to use signals-based traps.
2882        #[cfg(feature = "debug")]
2883        if self.tunables.debug_guest == Some(true) {
2884            tunables.signals_based_traps = false;
2885        }
2886
2887        // Inlining currently falls over with the `stack_switch` instruction.
2888        #[cfg(any(feature = "cranelift", feature = "winch"))]
2889        if features.contains(WasmFeatures::STACK_SWITCHING) {
2890            if let Some(inlining) = self.tunables.inlining
2891                && inlining != Inlining::No
2892            {
2893                bail!("cannot enable compiler inlining when stack switching is enabled");
2894            }
2895            tunables.inlining = Inlining::No;
2896        }
2897
2898        self.tunables.configure(&mut tunables);
2899
2900        // Debuggers set watchpoints through linear memories' shadows.
2901        tunables.memory_watchpoints = tunables.debug_guest;
2902
2903        // If no GC heap tunables are explicitly configured, copy the memory
2904        // tunables' configured values so that GC heaps default to the same
2905        // configuration as linear memories.
2906        if !self.any_gc_heap_tunables_configured() {
2907            tunables.gc_heap_reservation = tunables.memory_reservation;
2908            tunables.gc_heap_guard_size = tunables.memory_guard_size;
2909            tunables.gc_heap_reservation_for_growth = tunables.memory_reservation_for_growth;
2910            tunables.gc_heap_may_move = tunables.memory_may_move;
2911        }
2912
2913        // Validate that the configuration of reservation/guards is sensible
2914        // enough to ever possibly actually get allocated. If this doesn't fit
2915        // in the target's address space then there's no hope.
2916        let guard_regions = if tunables.guard_before_linear_memory {
2917            2
2918        } else {
2919            1
2920        };
2921        let max_size = match self.compiler_target().pointer_width() {
2922            Ok(width) if width.bits() < 64 => (1 << width.bits()) - 1,
2923            _ => u64::MAX,
2924        };
2925        for (what, reservation, guard_size) in [
2926            (
2927                "memory",
2928                tunables.memory_reservation,
2929                tunables.memory_guard_size,
2930            ),
2931            (
2932                "gc_heap",
2933                tunables.gc_heap_reservation,
2934                tunables.gc_heap_guard_size,
2935            ),
2936        ] {
2937            if guard_size
2938                .checked_mul(guard_regions)
2939                .and_then(|g| g.checked_add(reservation))
2940                .is_none_or(|size| size > max_size)
2941            {
2942                bail!(
2943                    "`{what}_reservation` ({reservation}) plus `{what}_guard_size` \
2944                     ({guard_size}) overflows the target's address space"
2945                );
2946            }
2947        }
2948
2949        // If we're going to compile with winch, we must use the winch calling convention.
2950        #[cfg(any(feature = "cranelift", feature = "winch"))]
2951        {
2952            tunables.winch_callable = self
2953                .compiler_config
2954                .as_ref()
2955                .is_some_and(|c| c.strategy == Some(Strategy::Winch));
2956        }
2957
2958        tunables.collector = if features.gc_types() {
2959            #[cfg(feature = "gc")]
2960            {
2961                use wasmtime_environ::Collector as EnvCollector;
2962                Some(match self.collector.try_not_auto()? {
2963                    Collector::DeferredReferenceCounting => EnvCollector::DeferredReferenceCounting,
2964                    Collector::Null => EnvCollector::Null,
2965                    Collector::Copying => EnvCollector::Copying,
2966                    Collector::Auto => unreachable!(),
2967                })
2968            }
2969            #[cfg(not(feature = "gc"))]
2970            bail!("cannot use GC types: the `gc` feature was disabled at compile time")
2971        } else {
2972            None
2973        };
2974
2975        if tunables.debug_guest {
2976            ensure!(
2977                cfg!(feature = "debug"),
2978                "debug instrumentation support was disabled at compile time"
2979            );
2980            ensure!(
2981                !tunables.signals_based_traps,
2982                "cannot use signals-based traps with guest debugging enabled"
2983            );
2984        }
2985
2986        if tunables.mmu_interruption {
2987            // Only with signals-based traps can MMU interruption's signal
2988            // handler be installed (at engine creation time).
2989            ensure!(
2990                tunables.signals_based_traps,
2991                "MMU interruption requires signals-based traps"
2992            );
2993        }
2994        // Concurrency support is required for some component model features.
2995        let requires_concurrency = WasmFeatures::CM_ASYNC
2996            | WasmFeatures::CM_MORE_ASYNC_BUILTINS
2997            | WasmFeatures::CM_ASYNC_STACKFUL
2998            | WasmFeatures::CM_THREADING
2999            | WasmFeatures::CM_ERROR_CONTEXT;
3000        if tunables.concurrency_support && !cfg!(feature = "component-model-async") {
3001            bail!(
3002                "concurrency support was requested but was not \
3003                 compiled into this build of Wasmtime"
3004            )
3005        }
3006        if !tunables.concurrency_support && features.intersects(requires_concurrency) {
3007            bail!(
3008                "concurrency support must be enabled to use the component \
3009                 model async or threading features"
3010            )
3011        }
3012
3013        // Generated adapters between components will use `ref.func` in some
3014        // async-related situations so `component-model-async` requires
3015        // `reference-types`.
3016        if features.contains(WasmFeatures::CM_ASYNC)
3017            && !features.contains(WasmFeatures::REFERENCE_TYPES)
3018        {
3019            bail!("the component-model-async feature requires the wasm reference-types proposal");
3020        }
3021
3022        // If the pooling allocator is used and GC is enabled, check that
3023        // memories and the GC heap are configured identically, since the
3024        // pooling allocator can't support differently-configured heaps.
3025        #[cfg(feature = "pooling-allocator")]
3026        if matches!(
3027            &self.allocation_strategy,
3028            InstanceAllocationStrategy::Pooling(_)
3029        ) && tunables.collector.is_some()
3030        {
3031            if tunables.memory_reservation != tunables.gc_heap_reservation {
3032                bail!(
3033                    "when using the pooling allocator with GC, `memory_reservation` ({}) \
3034                     and `gc_heap_reservation` ({}) must be the same",
3035                    tunables.memory_reservation,
3036                    tunables.gc_heap_reservation,
3037                );
3038            }
3039            if tunables.memory_guard_size != tunables.gc_heap_guard_size {
3040                bail!(
3041                    "when using the pooling allocator with GC, `memory_guard_size` ({}) \
3042                     and `gc_heap_guard_size` ({}) must be the same",
3043                    tunables.memory_guard_size,
3044                    tunables.gc_heap_guard_size,
3045                );
3046            }
3047            if tunables.memory_reservation_for_growth != tunables.gc_heap_reservation_for_growth {
3048                bail!(
3049                    "when using the pooling allocator with GC, \
3050                     `memory_reservation_for_growth` ({}) and \
3051                     `gc_heap_reservation_for_growth` ({}) must be the same",
3052                    tunables.memory_reservation_for_growth,
3053                    tunables.gc_heap_reservation_for_growth,
3054                );
3055            }
3056            if tunables.memory_may_move != tunables.gc_heap_may_move {
3057                bail!(
3058                    "when using the pooling allocator with GC, `memory_may_move` ({}) \
3059                     and `gc_heap_may_move` ({}) must be the same",
3060                    tunables.memory_may_move,
3061                    tunables.gc_heap_may_move,
3062                );
3063            }
3064        }
3065
3066        if tunables.debug_native && !tunables.debug_symbols {
3067            bail!("cannot enable native debug info while debug symbols are disabled");
3068        }
3069
3070        Ok((tunables, features))
3071    }
3072
3073    #[cfg(feature = "runtime")]
3074    pub(crate) fn build_allocator(
3075        &self,
3076        tunables: &Tunables,
3077    ) -> Result<Box<dyn InstanceAllocator + Send + Sync>> {
3078        let _ = tunables;
3079
3080        match &self.allocation_strategy {
3081            InstanceAllocationStrategy::OnDemand => {
3082                let mut _allocator = try_new::<Box<_>>(OnDemandInstanceAllocator::new(
3083                    self.mem_creator.clone(),
3084                    self.async_stack_size,
3085                    self.async_stack_zeroing,
3086                ))?;
3087                #[cfg(feature = "async")]
3088                if let Some(stack_creator) = &self.stack_creator {
3089                    _allocator.set_stack_creator(stack_creator.clone());
3090                }
3091                Ok(_allocator as _)
3092            }
3093            #[cfg(feature = "pooling-allocator")]
3094            InstanceAllocationStrategy::Pooling(config) => {
3095                let mut config = config.clone();
3096                let _ = &mut config;
3097                #[cfg(feature = "async")]
3098                {
3099                    config.stack_size = self.async_stack_size;
3100                    config.async_stack_zeroing = self.async_stack_zeroing;
3101                }
3102                let allocator = try_new::<Box<_>>(
3103                    crate::runtime::vm::PoolingInstanceAllocator::new(&config, tunables)?,
3104                )?;
3105                Ok(allocator as _)
3106            }
3107        }
3108    }
3109
3110    #[cfg(feature = "runtime")]
3111    pub(crate) fn build_gc_runtime(&self) -> Result<Option<Arc<dyn GcRuntime>>> {
3112        if !self.features().gc_types() {
3113            return Ok(None);
3114        }
3115
3116        #[cfg(not(feature = "gc"))]
3117        bail!("cannot create a GC runtime: the `gc` feature was disabled at compile time");
3118
3119        #[cfg(feature = "gc")]
3120        #[cfg_attr(
3121            not(any(feature = "gc-null", feature = "gc-drc", feature = "gc-copying")),
3122            expect(unreachable_code, reason = "definitions known to be dummy")
3123        )]
3124        {
3125            Ok(Some(match self.collector.try_not_auto()? {
3126                #[cfg(feature = "gc-drc")]
3127                Collector::DeferredReferenceCounting => {
3128                    try_new::<Arc<_>>(crate::runtime::vm::DrcCollector::default())? as _
3129                }
3130                #[cfg(not(feature = "gc-drc"))]
3131                Collector::DeferredReferenceCounting => unreachable!(),
3132
3133                #[cfg(feature = "gc-null")]
3134                Collector::Null => {
3135                    try_new::<Arc<_>>(crate::runtime::vm::NullCollector::default())? as _
3136                }
3137                #[cfg(not(feature = "gc-null"))]
3138                Collector::Null => unreachable!(),
3139
3140                #[cfg(feature = "gc-copying")]
3141                Collector::Copying => {
3142                    try_new::<Arc<_>>(crate::runtime::vm::CopyingCollector::default())? as _
3143                }
3144                #[cfg(not(feature = "gc-copying"))]
3145                Collector::Copying => unreachable!(),
3146
3147                Collector::Auto => unreachable!(),
3148            }))
3149        }
3150    }
3151
3152    #[cfg(feature = "runtime")]
3153    pub(crate) fn build_profiler(&self) -> Result<Box<dyn ProfilingAgent>> {
3154        Ok(match self.profiling_strategy {
3155            ProfilingStrategy::PerfMap => profiling_agent::new_perfmap()?,
3156            ProfilingStrategy::JitDump => profiling_agent::new_jitdump()?,
3157            ProfilingStrategy::VTune => profiling_agent::new_vtune()?,
3158            ProfilingStrategy::None => profiling_agent::new_null(),
3159            ProfilingStrategy::Pulley => profiling_agent::new_pulley()?,
3160        })
3161    }
3162
3163    #[cfg(any(feature = "cranelift", feature = "winch"))]
3164    pub(crate) fn build_compiler(
3165        mut self,
3166        tunables: &mut Tunables,
3167        features: WasmFeatures,
3168    ) -> Result<(Self, Box<dyn wasmtime_environ::Compiler>)> {
3169        let target = self.compiler_target();
3170
3171        // The target passed to the builders below is an `Option<Triple>` where
3172        // `None` represents the current host with CPU features inferred from
3173        // the host's CPU itself. The `target` above is not an `Option`, so
3174        // switch it to `None` in the case that a target wasn't explicitly
3175        // specified (which indicates no feature inference) and the target
3176        // matches the host.
3177        let target_for_builder =
3178            if self.target.is_none() && target == target_lexicon::Triple::host() {
3179                None
3180            } else {
3181                Some(target.clone())
3182            };
3183
3184        let mut compiler = match self.compiler_config_mut().strategy {
3185            #[cfg(feature = "cranelift")]
3186            Some(Strategy::Cranelift) => wasmtime_cranelift::builder(target_for_builder)?,
3187            #[cfg(not(feature = "cranelift"))]
3188            Some(Strategy::Cranelift) => bail!("cranelift support not compiled in"),
3189            #[cfg(feature = "winch")]
3190            Some(Strategy::Winch) => wasmtime_winch::builder(target_for_builder)?,
3191            #[cfg(not(feature = "winch"))]
3192            Some(Strategy::Winch) => bail!("winch support not compiled in"),
3193
3194            None | Some(Strategy::Auto) => unreachable!(),
3195        };
3196
3197        if let Some(path) = &self.compiler_config_mut().clif_dir {
3198            compiler.clif_dir(path)?;
3199        }
3200
3201        // If probestack is enabled for a target, Wasmtime will always use the
3202        // inline strategy which doesn't require us to define a `__probestack`
3203        // function or similar.
3204        self.compiler_config_mut().settings.insert(
3205            "probestack_strategy".into(),
3206            ("inline".into(), UserSpecified::No),
3207        );
3208
3209        // We enable stack probing by default on all targets.
3210        // This is required on Windows because of the way Windows
3211        // commits its stacks, but it's also a good idea on other
3212        // platforms to ensure guard pages are hit for large frame
3213        // sizes.
3214        self.compiler_config_mut()
3215            .flags
3216            .insert("enable_probestack".into(), UserSpecified::No);
3217
3218        // The current wasm multivalue implementation depends on this.
3219        // FIXME(#9510) handle this in wasmtime-cranelift instead.
3220        self.compiler_config_mut()
3221            .flags
3222            .insert("enable_multi_ret_implicit_sret".into(), UserSpecified::No);
3223
3224        if let Some(unwind_requested) = self.native_unwind_info {
3225            if !self
3226                .compiler_config_mut()
3227                .ensure_setting_unset_or_given("unwind_info", &unwind_requested.to_string())
3228            {
3229                bail!(
3230                    "incompatible settings requested for Cranelift and Wasmtime `unwind-info` settings"
3231                );
3232            }
3233        }
3234
3235        if target.operating_system == target_lexicon::OperatingSystem::Windows {
3236            if !self
3237                .compiler_config_mut()
3238                .ensure_setting_unset_or_given("unwind_info", "true")
3239            {
3240                bail!("`native_unwind_info` cannot be disabled on Windows");
3241            }
3242        }
3243
3244        // We require frame pointers for correct stack walking, which is safety
3245        // critical in the presence of reference types, and otherwise it is just
3246        // really bad developer experience to get wrong.
3247        self.compiler_config_mut().settings.insert(
3248            "preserve_frame_pointers".into(),
3249            ("true".into(), UserSpecified::No),
3250        );
3251
3252        if !tunables.signals_based_traps {
3253            let mut ok = self
3254                .compiler_config_mut()
3255                .ensure_setting_unset_or_given("enable_table_access_spectre_mitigation", "false");
3256            ok = ok
3257                && self.compiler_config_mut().ensure_setting_unset_or_given(
3258                    "enable_heap_access_spectre_mitigation",
3259                    "false",
3260                );
3261
3262            // Right now spectre-mitigated bounds checks will load from zero so
3263            // if host-based signal handlers are disabled then that's a mismatch
3264            // and doesn't work right now. Fixing this will require more thought
3265            // of how to implement the bounds check in spectre-only mode.
3266            if !ok {
3267                bail!(
3268                    "when signals-based traps are disabled then spectre \
3269                     mitigations must also be disabled"
3270                );
3271            }
3272        }
3273
3274        if features.contains(WasmFeatures::RELAXED_SIMD) && !features.contains(WasmFeatures::SIMD) {
3275            bail!("cannot disable the simd proposal but enable the relaxed simd proposal");
3276        }
3277
3278        if features.contains(WasmFeatures::STACK_SWITCHING) {
3279            use target_lexicon::OperatingSystem;
3280            let model = match target.operating_system {
3281                OperatingSystem::Windows => "update_windows_tib",
3282                OperatingSystem::Linux
3283                | OperatingSystem::MacOSX(_)
3284                | OperatingSystem::Darwin(_) => "basic",
3285                _ => bail!("stack-switching feature not supported on this platform "),
3286            };
3287
3288            if !self
3289                .compiler_config_mut()
3290                .ensure_setting_unset_or_given("stack_switch_model", model)
3291            {
3292                bail!(
3293                    "compiler option 'stack_switch_model' must be set to '{model}' on this platform"
3294                );
3295            }
3296        }
3297
3298        // Apply compiler settings and flags
3299        compiler.set_tunables(tunables.clone())?;
3300        for (k, (v, _)) in self.compiler_config_mut().settings.iter() {
3301            compiler.set(k, v)?;
3302        }
3303        for (flag, _) in self.compiler_config_mut().flags.iter() {
3304            compiler.enable(flag)?;
3305        }
3306        *tunables = compiler.tunables().cloned().unwrap();
3307
3308        #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
3309        if let Some(cache_store) = &self.compiler_config_mut().cache_store {
3310            compiler.enable_incremental_compilation(cache_store.clone())?;
3311        }
3312
3313        compiler.wmemcheck(self.compiler_config_mut().wmemcheck);
3314
3315        let compiler = compiler.build()?;
3316
3317        // SIMD support can depend on ISA flags, such as `has_v` on riscv64,
3318        // which aren't known until now, so it's checked here and not in
3319        // `compiler_panicking_wasm_features`.
3320        if !compiler.supports_wasm_simd() {
3321            let simd = WasmFeatures::SIMD | WasmFeatures::RELAXED_SIMD;
3322            if let Some((name, _)) = (features & simd).iter_names().next() {
3323                bail!(
3324                    "the wasm_{} feature is not supported on this compiler \
3325                     configuration, enable the target's vector extension or \
3326                     disable both simd and relaxed-simd",
3327                    name.to_lowercase()
3328                );
3329            }
3330        }
3331
3332        Ok((self, compiler))
3333    }
3334
3335    /// Internal setting for whether adapter modules for components will have
3336    /// extra WebAssembly instructions inserted performing more debug checks
3337    /// then are necessary.
3338    #[cfg(feature = "component-model")]
3339    pub fn debug_adapter_modules(&mut self, debug: bool) -> &mut Self {
3340        self.tunables.debug_adapter_modules = Some(debug);
3341        self
3342    }
3343
3344    /// Enables clif output when compiling a WebAssembly module.
3345    #[cfg(any(feature = "cranelift", feature = "winch"))]
3346    pub fn emit_clif(&mut self, path: &Path) -> &mut Self {
3347        self.compiler_config_mut().clif_dir = Some(path.to_path_buf());
3348        self
3349    }
3350
3351    /// Configures whether, when on macOS, Mach ports are used for exception
3352    /// handling instead of traditional Unix-based signal handling.
3353    ///
3354    /// WebAssembly traps in Wasmtime are implemented with native faults, for
3355    /// example a `SIGSEGV` will occur when a WebAssembly guest accesses
3356    /// out-of-bounds memory. Handling this can be configured to either use Unix
3357    /// signals or Mach ports on macOS. By default Mach ports are used.
3358    ///
3359    /// Mach ports enable Wasmtime to work by default with foreign
3360    /// error-handling systems such as breakpad which also use Mach ports to
3361    /// handle signals. In this situation Wasmtime will continue to handle guest
3362    /// faults gracefully while any non-guest faults will get forwarded to
3363    /// process-level handlers such as breakpad. Some more background on this
3364    /// can be found in #2456.
3365    ///
3366    /// A downside of using mach ports, however, is that they don't interact
3367    /// well with `fork()`. Forking a Wasmtime process on macOS will produce a
3368    /// child process that cannot successfully run WebAssembly. In this
3369    /// situation traditional Unix signal handling should be used as that's
3370    /// inherited and works across forks.
3371    ///
3372    /// If your embedding wants to use a custom error handler which leverages
3373    /// Mach ports and you additionally wish to `fork()` the process and use
3374    /// Wasmtime in the child process that's not currently possible. Please
3375    /// reach out to us if you're in this bucket!
3376    ///
3377    /// This option defaults to `true`, using Mach ports by default.
3378    pub fn macos_use_mach_ports(&mut self, mach_ports: bool) -> &mut Self {
3379        self.macos_use_mach_ports = mach_ports;
3380        self
3381    }
3382
3383    /// Configures an embedder-provided function, `detect`, which is used to
3384    /// determine if an ISA-specific feature is available on the current host.
3385    ///
3386    /// This function is used to verify that any features enabled for a compiler
3387    /// backend, such as AVX support on x86\_64, are also available on the host.
3388    /// It is undefined behavior to execute an AVX instruction on a host that
3389    /// doesn't support AVX instructions, for example.
3390    ///
3391    /// When the `std` feature is active on this crate then this function is
3392    /// configured to a default implementation that uses the standard library's
3393    /// feature detection. When the `std` feature is disabled then there is no
3394    /// default available and this method must be called to configure a feature
3395    /// probing function.
3396    ///
3397    /// The `detect` function provided is given a string name of an ISA feature.
3398    /// The function should then return:
3399    ///
3400    /// * `Some(true)` - indicates that the feature was found on the host and it
3401    ///   is supported.
3402    /// * `Some(false)` - the feature name was recognized but it was not
3403    ///   detected on the host, for example the CPU is too old.
3404    /// * `None` - the feature name was not recognized and it's not known
3405    ///   whether it's on the host or not.
3406    ///
3407    /// Feature names passed to `detect` match the same feature name used in the
3408    /// Rust standard library. For example `"sse4.2"` is used on x86\_64.
3409    ///
3410    /// # Unsafety
3411    ///
3412    /// This function is `unsafe` because it is undefined behavior to execute
3413    /// instructions that a host does not support. This means that the result of
3414    /// `detect` must be correct for memory safe execution at runtime.
3415    pub unsafe fn detect_host_feature(&mut self, detect: fn(&str) -> Option<bool>) -> &mut Self {
3416        self.detect_host_feature = Some(detect);
3417        self
3418    }
3419
3420    /// Configures Wasmtime to not use signals-based trap handlers, for example
3421    /// disables `SIGILL` and `SIGSEGV` handler registration on Unix platforms.
3422    ///
3423    /// > **Note:** this option has important performance ramifications, be sure
3424    /// > to understand the implications. Wasm programs have been measured to
3425    /// > run up to 2x slower when signals-based traps are disabled.
3426    ///
3427    /// Wasmtime will by default leverage signals-based trap handlers (or the
3428    /// platform equivalent, for example "vectored exception handlers" on
3429    /// Windows) to make generated code more efficient. For example, when
3430    /// Wasmtime can use signals-based traps, it can elide explicit bounds
3431    /// checks for Wasm linear memory accesses, instead relying on virtual
3432    /// memory guard pages to raise a `SIGSEGV` (on Unix) for out-of-bounds
3433    /// accesses, which Wasmtime's runtime then catches and handles. Another
3434    /// example is divide-by-zero: with signals-based traps, Wasmtime can let
3435    /// the hardware raise a trap when the divisor is zero. Without
3436    /// signals-based traps, Wasmtime must explicitly emit additional
3437    /// instructions to check for zero and conditionally branch to a trapping
3438    /// code path.
3439    ///
3440    /// Some environments however may not have access to signal handlers. For
3441    /// example embedded scenarios may not support virtual memory. Other
3442    /// environments where Wasmtime is embedded within the surrounding
3443    /// environment may require that new signal handlers aren't registered due
3444    /// to the global nature of signal handlers. This option exists to disable
3445    /// the signal handler registration when required for these scenarios.
3446    ///
3447    /// When signals-based trap handlers are disabled, then Wasmtime and its
3448    /// generated code will *never* rely on segfaults or other
3449    /// signals. Generated code will be slower because bounds must be explicitly
3450    /// checked along with other conditions like division by zero.
3451    ///
3452    /// The following additional factors can also affect Wasmtime's ability to
3453    /// elide explicit bounds checks and leverage signals-based traps:
3454    ///
3455    /// * The [`Config::memory_reservation`] and [`Config::memory_guard_size`]
3456    ///   settings
3457    /// * The index type of the linear memory (e.g. 32-bit or 64-bit)
3458    /// * The page size of the linear memory
3459    ///
3460    /// When this option is disabled, the
3461    /// `enable_heap_access_spectre_mitigation` and
3462    /// `enable_table_access_spectre_mitigation` Cranelift settings must also be
3463    /// disabled. This means that generated code must have spectre mitigations
3464    /// disabled. This is because spectre mitigations rely on faults from
3465    /// loading from the null address to implement bounds checks.
3466    ///
3467    /// This option defaults to `true`: signals-based trap handlers are enabled
3468    /// by default.
3469    ///
3470    /// > **Note:** Disabling this option is not compatible with the Winch
3471    /// > compiler.
3472    pub fn signals_based_traps(&mut self, enable: bool) -> &mut Self {
3473        self.tunables.signals_based_traps = Some(enable);
3474        self
3475    }
3476
3477    /// Enable/disable GC support in Wasmtime entirely.
3478    ///
3479    /// This flag can be used to gate whether GC infrastructure is enabled or
3480    /// initialized in Wasmtime at all. Wasmtime's GC implementation is required
3481    /// for the [`Self::wasm_gc`] proposal, [`Self::wasm_function_references`],
3482    /// and [`Self::wasm_exceptions`] at this time. None of those proposal can
3483    /// be enabled without also having this option enabled.
3484    ///
3485    /// This option defaults to whether the crate `gc` feature is enabled or
3486    /// not, except when using [`Strategy::Winch`] where it defaults to
3487    /// `false`.
3488    pub fn gc_support(&mut self, enable: bool) -> &mut Self {
3489        self.wasm_features(WasmFeatures::GC_TYPES, enable)
3490    }
3491
3492    /// Explicitly indicate or not whether the host is using a hardware float
3493    /// ABI on x86 targets.
3494    ///
3495    /// This configuration option is only applicable on the
3496    /// `x86_64-unknown-none` Rust target and has no effect on other host
3497    /// targets. The `x86_64-unknown-none` Rust target does not support hardware
3498    /// floats by default and uses a "soft float" implementation and ABI. This
3499    /// means that `f32`, for example, is passed in a general-purpose register
3500    /// between functions instead of a floating-point register. This does not
3501    /// match Cranelift's ABI for `f32` where it's passed in floating-point
3502    /// registers.  Cranelift does not have support for a "soft float"
3503    /// implementation where all floating-point operations are lowered to
3504    /// libcalls.
3505    ///
3506    /// This means that for the `x86_64-unknown-none` target the ABI between
3507    /// Wasmtime's libcalls and the host is incompatible when floats are used.
3508    /// This further means that, by default, Wasmtime is unable to load native
3509    /// code when compiled to the `x86_64-unknown-none` target. The purpose of
3510    /// this option is to explicitly allow loading code and bypass this check.
3511    ///
3512    /// Setting this configuration option to `true` indicates that either:
3513    /// (a) the Rust target is compiled with the hard-float ABI manually via
3514    /// `-Zbuild-std` and a custom target JSON configuration, or (b) sufficient
3515    /// x86 features have been enabled in the compiler such that float libcalls
3516    /// will not be used in Wasmtime. For (a) there is no way in Rust at this
3517    /// time to detect whether a hard-float or soft-float ABI is in use on
3518    /// stable Rust, so this manual opt-in is required. For (b) the only
3519    /// instance where Wasmtime passes a floating-point value in a register
3520    /// between the host and compiled wasm code is with libcalls.
3521    ///
3522    /// Float-based libcalls are only used when the compilation target for a
3523    /// wasm module has insufficient target features enabled for native
3524    /// support. For example SSE4.1 is required for the `f32.ceil` WebAssembly
3525    /// instruction to be compiled to a native instruction. If SSE4.1 is not
3526    /// enabled then `f32.ceil` is translated to a "libcall" which is
3527    /// implemented on the host. Float-based libcalls can be avoided with
3528    /// sufficient target features enabled, for example:
3529    ///
3530    /// * `self.cranelift_flag_enable("has_sse3")`
3531    /// * `self.cranelift_flag_enable("has_ssse3")`
3532    /// * `self.cranelift_flag_enable("has_sse41")`
3533    /// * `self.cranelift_flag_enable("has_sse42")`
3534    /// * `self.cranelift_flag_enable("has_fma")`
3535    ///
3536    /// Note that when these features are enabled Wasmtime will perform a
3537    /// runtime check to determine that the host actually has the feature
3538    /// present.
3539    ///
3540    /// For some more discussion see [#11506].
3541    ///
3542    /// [#11506]: https://github.com/bytecodealliance/wasmtime/issues/11506
3543    ///
3544    /// # Safety
3545    ///
3546    /// This method is not safe because it cannot be detected in Rust right now
3547    /// whether the host is compiled with a soft or hard float ABI. Additionally
3548    /// if the host is compiled with a soft float ABI disabling this check does
3549    /// not ensure that the wasm module in question has zero usage of floats
3550    /// in the boundary to the host.
3551    ///
3552    /// Safely using this method requires one of:
3553    ///
3554    /// * The host target is compiled to use hardware floats.
3555    /// * Wasm modules loaded are compiled with enough x86 Cranelift features
3556    ///   enabled to avoid float-related hostcalls.
3557    pub unsafe fn x86_float_abi_ok(&mut self, enable: bool) -> &mut Self {
3558        self.x86_float_abi_ok = Some(enable);
3559        self
3560    }
3561
3562    /// Enable or disable the ability to create a
3563    /// [`SharedMemory`](crate::SharedMemory).
3564    ///
3565    /// The WebAssembly threads proposal, configured by [`Config::wasm_threads`]
3566    /// is on-by-default but there are enough deficiencies in Wasmtime's
3567    /// implementation and API integration that creation of a shared memory is
3568    /// disabled by default. This configuration knob can be used to enable this.
3569    ///
3570    /// When enabling this method be aware that wasm threads are, at this time,
3571    /// a [tier 2
3572    /// feature](https://docs.wasmtime.dev/stability-tiers.html#tier-2) in
3573    /// Wasmtime meaning that it will not receive security updates or fixes to
3574    /// historical releases. Additionally security CVEs will not be issued for
3575    /// bugs in the implementation.
3576    ///
3577    /// This option is `false` by default.
3578    pub fn shared_memory(&mut self, enable: bool) -> &mut Self {
3579        self.shared_memory = enable;
3580        self
3581    }
3582
3583    /// Specifies whether support for concurrent execution of WebAssembly is
3584    /// supported within this store.
3585    ///
3586    /// This configuration option affects whether runtime data structures are
3587    /// initialized within a `Store` on creation to support concurrent execution
3588    /// of WebAssembly guests. This is primarily applicable to the
3589    /// [`Config::wasm_component_model_async`] configuration which is the first
3590    /// time Wasmtime has supported concurrent execution of guests. This
3591    /// configuration option, for example, enables usage of
3592    /// [`Store::run_concurrent`], [`Func::call_concurrent`], [`StreamReader`],
3593    /// etc.
3594    ///
3595    /// This configuration option can be manually disabled to avoid initializing
3596    /// data structures in the [`Store`] related to concurrent execution. When
3597    /// this option is disabled then APIs related to concurrency will all fail
3598    /// with a panic. For example [`Store::run_concurrent`] will panic, creating
3599    /// a [`StreamReader`] will panic, etc.
3600    ///
3601    /// The value of this option additionally affects whether a [`Config`] is
3602    /// valid and the default set of enabled WebAssembly features. If this
3603    /// option is disabled then component-model features related to concurrency
3604    /// will all be disabled. If this option is enabled, then the options will
3605    /// retain their normal defaults. It is not valid to create a [`Config`]
3606    /// with component-model-async explicitly enabled and this option explicitly
3607    /// disabled, however.
3608    ///
3609    /// This option defaults to `true`.
3610    ///
3611    /// [`Store`]: crate::Store
3612    /// [`Store::run_concurrent`]: crate::Store::run_concurrent
3613    /// [`Func::call_concurrent`]: crate::component::Func::call_concurrent
3614    /// [`StreamReader`]: crate::component::StreamReader
3615    pub fn concurrency_support(&mut self, enable: bool) -> &mut Self {
3616        self.tunables.concurrency_support = Some(enable);
3617        self
3618    }
3619
3620    /// Configures whether compiled code is compatible with a Wasmtime runtime
3621    /// built with AddressSanitizer (ASan) enabled.
3622    ///
3623    /// Some code Wasmtime generates must cooperate with ASan's bookkeeping
3624    /// when it runs inside an ASan-instrumented host. For example,
3625    /// stack-switching instructions must tell ASan about every switch between
3626    /// stacks. When this option is enabled the generated code includes those
3627    /// hooks. A runtime built without ASan treats them as no-ops.
3628    ///
3629    /// This option is part of a compiled artifact's compatibility key.
3630    /// Artifacts produced by [`Module::serialize`] or
3631    /// [`Component::serialize`] can only be deserialized by an [`Engine`]
3632    /// with the same setting. Code compiled without this option must not run
3633    /// in an ASan-enabled runtime.
3634    ///
3635    /// This option is useful when compiling code outside of ASan, for
3636    /// example with `Engine::precompile_module`, that will later run in a
3637    /// Wasmtime built with `-Zsanitizer=address`.
3638    ///
3639    /// This option defaults to `true` if Wasmtime itself was built with ASan
3640    /// and `false` otherwise.
3641    ///
3642    /// [`Engine`]: crate::Engine
3643    /// [`Module::serialize`]: crate::Module::serialize
3644    /// [`Component::serialize`]: crate::component::Component::serialize
3645    pub fn asan_compatible_code(&mut self, enable: bool) -> &mut Self {
3646        self.tunables.asan_stack_switching = Some(enable);
3647        self
3648    }
3649
3650    /// Validate if the current configuration has conflicting overrides that prevent
3651    /// execution determinism. Returns an error if a conflict exists.
3652    ///
3653    /// Note: Keep this in sync with [`Config::enforce_determinism`].
3654    #[inline]
3655    #[cfg(feature = "rr")]
3656    pub(crate) fn validate_rr_determinism_conflicts(&self) -> Result<()> {
3657        if let Some(v) = self.tunables.relaxed_simd_deterministic {
3658            if v == false {
3659                bail!("Relaxed deterministic SIMD cannot be disabled when determinism is enforced");
3660            }
3661        }
3662        #[cfg(any(feature = "cranelift", feature = "winch"))]
3663        if let Some((v, _)) = self
3664            .compiler_config
3665            .as_ref()
3666            .and_then(|c| c.settings.get("enable_nan_canonicalization"))
3667        {
3668            if v != "true" {
3669                bail!("NaN canonicalization cannot be disabled when determinism is enforced");
3670            }
3671        }
3672        Ok(())
3673    }
3674
3675    /// Enable execution trace recording or replaying to the configuration.
3676    ///
3677    /// When either recording/replaying are enabled, validation fails if settings
3678    /// that control determinism are not set appropriately. In particular, RR requires
3679    /// doing the following:
3680    /// * Enabling NaN canonicalization with [`Config::cranelift_nan_canonicalization`].
3681    /// * Enabling deterministic relaxed SIMD with [`Config::relaxed_simd_deterministic`].
3682    #[inline]
3683    pub fn rr(&mut self, cfg: RRConfig) -> &mut Self {
3684        self.rr_config = cfg;
3685        self
3686    }
3687
3688    /// Whether or not trap metadata is generated in compiled wasms for internal
3689    /// asserts in the compiled code itself.
3690    ///
3691    /// Wasmtime inserts metadata within compiled artifacts which contain a
3692    /// table of known trap codes for all instructions. If a trap via a signal
3693    /// happens, and it's not listed in these tables, then that's considered a
3694    /// fatal bug that crashes the process. This option controls whether trap
3695    /// codes are inserted into metadata for internal asserts as part of
3696    /// Wasmtime's translation process. These internal asserts should never be
3697    /// triggered, but if they are then the process dies with a signal.
3698    ///
3699    /// Inserting trap metadata into compiled artifacts can take extra space in
3700    /// the final artifact. The trap tables for the artifact will be larger as
3701    /// they contain more trap codes to contain.
3702    ///
3703    /// This is intended as a debugging option and is set to `false` by
3704    /// default.
3705    pub fn metadata_for_internal_asserts(&mut self, enable: bool) -> &mut Self {
3706        self.tunables.metadata_for_internal_asserts = Some(enable);
3707        self
3708    }
3709
3710    /// Whether or not trap metadata is generated in compiled wasms for
3711    /// detection of corruption in the GC heap.
3712    ///
3713    /// For more information about what metadata is in this scenario, see
3714    /// [`Config::metadata_for_internal_asserts`]. Note, though, that this
3715    /// option is enabled by default unlike internal asserts. This is intended
3716    /// as a defense-in-depth option for generated code in the face of GC heap
3717    /// corruption. If the GC heap is corrupted and is detected then the
3718    /// trapping instruction will be gracefully handled and delivered to the
3719    /// embedder. Otherwise if this option were set to `false` then the process
3720    /// would be aborted due to a signal.
3721    pub fn metadata_for_gc_heap_corruption(&mut self, enable: bool) -> &mut Self {
3722        self.tunables.metadata_for_gc_heap_corruption = Some(enable);
3723        self
3724    }
3725}
3726
3727impl Default for Config {
3728    fn default() -> Config {
3729        Config::new()
3730    }
3731}
3732
3733impl fmt::Debug for Config {
3734    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
3735        let mut f = f.debug_struct("Config");
3736
3737        // Not every flag in WasmFeatures can be enabled as part of creating
3738        // a Config. This impl gives a complete picture of all WasmFeatures
3739        // enabled, and doesn't require maintenance by hand (which has become out
3740        // of date in the past), at the cost of possible confusion for why
3741        // a flag in this set doesn't have a Config setter.
3742        let features = self.features();
3743        for flag in WasmFeatures::FLAGS.iter() {
3744            f.field(
3745                &format!("wasm_{}", flag.name().to_lowercase()),
3746                &features.contains(*flag.value()),
3747            );
3748        }
3749
3750        f.field("parallel_compilation", &self.parallel_compilation);
3751        #[cfg(any(feature = "cranelift", feature = "winch"))]
3752        {
3753            f.field("compiler_config", &self.compiler_config);
3754        }
3755
3756        self.tunables.format(&mut f);
3757        f.finish()
3758    }
3759}
3760
3761/// Possible Compilation strategies for a wasm module.
3762///
3763/// This is used as an argument to the [`Config::strategy`] method.
3764#[non_exhaustive]
3765#[derive(PartialEq, Eq, Clone, Debug, Copy)]
3766pub enum Strategy {
3767    /// An indicator that the compilation strategy should be automatically
3768    /// selected.
3769    ///
3770    /// This is generally what you want for most projects and indicates that the
3771    /// `wasmtime` crate itself should make the decision about what the best
3772    /// code generator for a wasm module is.
3773    ///
3774    /// Currently this always defaults to Cranelift, but the default value may
3775    /// change over time.
3776    Auto,
3777
3778    /// Currently the default backend, Cranelift aims to be a reasonably fast
3779    /// code generator which generates high quality machine code.
3780    Cranelift,
3781
3782    /// A low-latency baseline compiler for WebAssembly.
3783    /// For more details regarding ISA support and Wasm proposals support
3784    /// see <https://docs.wasmtime.dev/stability-tiers.html#current-tier-status>
3785    Winch,
3786}
3787
3788#[cfg(any(feature = "winch", feature = "cranelift"))]
3789impl Strategy {
3790    fn not_auto(&self) -> Option<Strategy> {
3791        match self {
3792            Strategy::Auto => {
3793                if cfg!(feature = "cranelift") {
3794                    Some(Strategy::Cranelift)
3795                } else if cfg!(feature = "winch") {
3796                    Some(Strategy::Winch)
3797                } else {
3798                    None
3799                }
3800            }
3801            other => Some(*other),
3802        }
3803    }
3804}
3805
3806/// Possible garbage collector implementations for Wasm.
3807///
3808/// This is used as an argument to the [`Config::collector`] method.
3809///
3810/// The properties of Wasmtime's available collectors are summarized in the
3811/// following table:
3812///
3813/// | Collector                   | Collects Garbage[^1]  | Latency[^2] | Throughput[^3] | Allocation Speed[^4] | Heap Utilization[^5] |
3814/// |-----------------------------|-----------------------|-------------|----------------|----------------------|----------------------|
3815/// | `Copying`                   | Yes, including cycles | 🙁         | 🙂             | 🙂                   | 🙁                  |
3816/// | `DeferredReferenceCounting` | Yes, but not cycles   | 🙂         | 🙁             | 😐                   | 😐                  |
3817/// | `Null`                      | No                    | 🙂         | 🙂             | 🙂                   | 🙂                  |
3818///
3819/// [^1]: Whether or not the collector is capable of collecting garbage and cyclic garbage.
3820///
3821/// [^2]: How long the Wasm program is paused during garbage
3822///       collections. Shorter is better. In general, better latency implies
3823///       worse throughput and vice versa.
3824///
3825/// [^3]: How fast the Wasm program runs when using this collector. Roughly
3826///       equivalent to the number of Wasm instructions executed per
3827///       second. Faster is better. In general, better throughput implies worse
3828///       latency and vice versa.
3829///
3830/// [^4]: How fast can individual objects be allocated?
3831///
3832/// [^5]: How many objects can the collector fit into N bytes of memory? That
3833///       is, how much space for bookkeeping and metadata does this collector
3834///       require? Less space taken up by metadata means more space for
3835///       additional objects. Reference counts are larger than mark bits and
3836///       free lists are larger than bump pointers, for example.
3837#[non_exhaustive]
3838#[derive(PartialEq, Eq, Clone, Debug, Copy)]
3839pub enum Collector {
3840    /// An indicator that the garbage collector should be automatically
3841    /// selected.
3842    ///
3843    /// This is generally what you want for most projects and indicates that the
3844    /// `wasmtime` crate itself should make the decision about what the best
3845    /// collector to use is.
3846    ///
3847    /// Currently this always defaults to the copying collector, but the default
3848    /// value may change over time.
3849    Auto,
3850
3851    /// The deferred reference-counting collector.
3852    ///
3853    /// A reference-counting collector, generally trading improved latency for
3854    /// worsened throughput. However, to avoid the largest overheads of
3855    /// reference counting, it avoids manipulating reference counts for Wasm
3856    /// objects on the stack. Instead, it will hold a reference count for an
3857    /// over-approximation of all objects that are currently on the stack, trace
3858    /// the stack during collection to find the precise set of on-stack roots,
3859    /// and decrement the reference count of any object that was in the
3860    /// over-approximation but not the precise set. This improves throughput,
3861    /// compared to "pure" reference counting, by performing many fewer
3862    /// refcount-increment and -decrement operations. The cost is the increased
3863    /// latency associated with tracing the stack.
3864    ///
3865    /// This collector cannot currently collect cycles; they will leak until the
3866    /// GC heap's store is dropped.
3867    DeferredReferenceCounting,
3868
3869    /// The null collector.
3870    ///
3871    /// This collector does not actually collect any garbage. It simply
3872    /// allocates objects until it runs out of memory, at which point further
3873    /// objects allocation attempts will trap.
3874    ///
3875    /// This collector is useful for incredibly short-running Wasm instances
3876    /// where additionally you would rather halt an over-allocating Wasm program
3877    /// than spend time collecting its garbage to allow it to keep running. It
3878    /// is also useful for measuring the overheads associated with other
3879    /// collectors, as this collector imposes as close to zero throughput and
3880    /// latency overhead as possible.
3881    Null,
3882
3883    /// The copying collector.
3884    ///
3885    /// A tracing collector that splits the GC heap in half, bump-allocates
3886    /// objects in one half until it fills up, and then does a GC and copies
3887    /// live objects into the other half, and repeats the process. It has fast
3888    /// allocation, collects cyclic garbage, and good collection throughput,
3889    /// however it suffers from poor latency due to its stop-the-world
3890    /// collections and poor heap utilization due to only using half the GC
3891    /// heap's full capacity at any given time.
3892    ///
3893    /// Note that this collector is still under construction and is not yet
3894    /// functional.
3895    Copying,
3896}
3897
3898impl Default for Collector {
3899    fn default() -> Collector {
3900        Collector::Auto
3901    }
3902}
3903
3904#[cfg(feature = "gc")]
3905impl Collector {
3906    fn not_auto(&self) -> Option<Collector> {
3907        match self {
3908            Collector::Auto => {
3909                if cfg!(feature = "gc-copying") {
3910                    Some(Collector::Copying)
3911                } else if cfg!(feature = "gc-drc") {
3912                    Some(Collector::DeferredReferenceCounting)
3913                } else if cfg!(feature = "gc-null") {
3914                    Some(Collector::Null)
3915                } else {
3916                    None
3917                }
3918            }
3919            other => Some(*other),
3920        }
3921    }
3922
3923    fn try_not_auto(&self) -> Result<Self> {
3924        match self.not_auto() {
3925            #[cfg(feature = "gc-drc")]
3926            Some(c @ Collector::DeferredReferenceCounting) => Ok(c),
3927            #[cfg(not(feature = "gc-drc"))]
3928            Some(Collector::DeferredReferenceCounting) => bail!(
3929                "cannot create an engine using the deferred reference-counting \
3930                 collector because the `gc-drc` feature was not enabled at \
3931                 compile time",
3932            ),
3933
3934            #[cfg(feature = "gc-null")]
3935            Some(c @ Collector::Null) => Ok(c),
3936            #[cfg(not(feature = "gc-null"))]
3937            Some(Collector::Null) => bail!(
3938                "cannot create an engine using the null collector because \
3939                 the `gc-null` feature was not enabled at compile time",
3940            ),
3941
3942            #[cfg(feature = "gc-copying")]
3943            Some(c @ Collector::Copying) => Ok(c),
3944            #[cfg(not(feature = "gc-copying"))]
3945            Some(Collector::Copying) => bail!(
3946                "cannot create an engine using the copying collector because \
3947                 the `gc-copying` feature was not enabled at compile time",
3948            ),
3949
3950            Some(Collector::Auto) => unreachable!(),
3951
3952            None => bail!(
3953                "cannot create an engine with GC support when none of the \
3954                 collectors are available; enable one of the following \
3955                 features: `gc-drc`, `gc-null`, `gc-copying`",
3956            ),
3957        }
3958    }
3959}
3960
3961/// Possible optimization levels for the Cranelift codegen backend.
3962#[non_exhaustive]
3963#[derive(Copy, Clone, Debug, Eq, PartialEq)]
3964pub enum OptLevel {
3965    /// No optimizations performed, minimizes compilation time by disabling most
3966    /// optimizations.
3967    None,
3968    /// Generates the fastest possible code, but may take longer.
3969    Speed,
3970    /// Similar to `speed`, but also performs transformations aimed at reducing
3971    /// code size.
3972    SpeedAndSize,
3973}
3974
3975/// Possible register allocator algorithms for the Cranelift codegen backend.
3976#[non_exhaustive]
3977#[derive(Copy, Clone, Debug, Eq, PartialEq)]
3978pub enum RegallocAlgorithm {
3979    /// Generates the fastest possible code, but may take longer.
3980    ///
3981    /// This algorithm performs "backtracking", which means that it may
3982    /// undo its earlier work and retry as it discovers conflicts. This
3983    /// results in better register utilization, producing fewer spills
3984    /// and moves, but can cause super-linear compile runtime.
3985    Backtracking,
3986    /// Generates acceptable code very quickly.
3987    ///
3988    /// This algorithm performs a single pass through the code,
3989    /// guaranteed to work in linear time.  (Note that the rest of
3990    /// Cranelift is not necessarily guaranteed to run in linear time,
3991    /// however.) It cannot undo earlier decisions, however, and it
3992    /// cannot foresee constraints or issues that may occur further
3993    /// ahead in the code, so the code may have more spills and moves as
3994    /// a result.
3995    ///
3996    /// > **Note**: This algorithm is not yet production-ready and has
3997    /// > historically had known problems. It is not recommended to enable this
3998    /// > algorithm for security-sensitive applications and the Wasmtime project
3999    /// > does not consider this configuration option for issuing security
4000    /// > advisories at this time.
4001    SinglePass,
4002}
4003
4004/// Select which profiling technique to support.
4005#[derive(Debug, Clone, Copy, PartialEq)]
4006pub enum ProfilingStrategy {
4007    /// No profiler support.
4008    None,
4009
4010    /// Collect function name information as the "perf map" file format, used with `perf` on Linux.
4011    PerfMap,
4012
4013    /// Collect profiling info for "jitdump" file format, used with `perf` on
4014    /// Linux.
4015    JitDump,
4016
4017    /// Collect profiling info using the "ittapi", used with `VTune` on Linux.
4018    VTune,
4019
4020    /// Support for profiling Pulley, Wasmtime's interpreter. Note that enabling
4021    /// this at runtime requires enabling the `profile-pulley` Cargo feature at
4022    /// compile time.
4023    Pulley,
4024}
4025
4026/// Select how wasm backtrace detailed information is handled.
4027#[derive(Debug, Clone, Copy)]
4028pub enum WasmBacktraceDetails {
4029    /// Support is unconditionally enabled and wasmtime will parse and read
4030    /// debug information.
4031    Enable,
4032
4033    /// Support is disabled, and wasmtime will not parse debug information for
4034    /// backtrace details.
4035    Disable,
4036
4037    /// Support for backtrace details is conditional on the
4038    /// `WASMTIME_BACKTRACE_DETAILS` environment variable.
4039    Environment,
4040}
4041
4042/// Describe the tri-state configuration of keys such as MPK or PAGEMAP_SCAN.
4043#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
4044pub enum Enabled {
4045    /// Enable this feature if it's detected on the host system, otherwise leave
4046    /// it disabled.
4047    Auto,
4048    /// Enable this feature and fail configuration if the feature is not
4049    /// detected on the host system.
4050    Yes,
4051    /// Do not enable this feature, even if the host system supports it.
4052    No,
4053}
4054
4055/// Configuration options used with [`InstanceAllocationStrategy::Pooling`] to
4056/// change the behavior of the pooling instance allocator.
4057///
4058/// This structure has a builder-style API in the same manner as [`Config`] and
4059/// is configured with [`Config::allocation_strategy`].
4060///
4061/// Note that usage of the pooling allocator does not affect compiled
4062/// WebAssembly code. Compiled `*.cwasm` files, for example, are usable both
4063/// with and without the pooling allocator.
4064///
4065/// ## Advantages of Pooled Allocation
4066///
4067/// The main benefit of the pooling allocator is to make WebAssembly
4068/// instantiation both faster and more scalable in terms of parallelism.
4069/// Allocation is faster because virtual memory is already configured and ready
4070/// to go within the pool, there's no need to [`mmap`] (for example on Unix) a
4071/// new region and configure it with guard pages. By avoiding [`mmap`] this
4072/// avoids whole-process virtual memory locks which can improve scalability and
4073/// performance through avoiding this.
4074///
4075/// Additionally with pooled allocation it's possible to create "affine slots"
4076/// to a particular WebAssembly module or component over time. For example if
4077/// the same module is multiple times over time the pooling allocator will, by
4078/// default, attempt to reuse the same slot. This mean that the slot has been
4079/// pre-configured and can retain virtual memory mappings for a copy-on-write
4080/// image, for example (see [`Config::memory_init_cow`] for more information.
4081/// This means that in a steady state instance deallocation is a single
4082/// [`madvise`] to reset linear memory to its original contents followed by a
4083/// single (optional) [`mprotect`] during the next instantiation to shrink
4084/// memory back to its original size. Compared to non-pooled allocation this
4085/// avoids the need to [`mmap`] a new region of memory, [`munmap`] it, and
4086/// [`mprotect`] regions too.
4087///
4088/// Another benefit of pooled allocation is that it's possible to configure
4089/// things such that no virtual memory management is required at all in a steady
4090/// state. For example a pooling allocator can be configured with:
4091///
4092/// * [`Config::memory_init_cow`] disabled
4093/// * [`Config::memory_guard_size`] disabled
4094/// * [`Config::memory_reservation`] shrunk to minimal size
4095/// * [`PoolingAllocationConfig::table_keep_resident`] sufficiently large
4096/// * [`PoolingAllocationConfig::linear_memory_keep_resident`] sufficiently large
4097///
4098/// With all these options in place no virtual memory tricks are used at all and
4099/// everything is manually managed by Wasmtime (for example resetting memory is
4100/// a `memset(0)`). This is not as fast in a single-threaded scenario but can
4101/// provide benefits in high-parallelism situations as no virtual memory locks
4102/// or IPIs need happen.
4103///
4104/// ## Disadvantages of Pooled Allocation
4105///
4106/// Despite the above advantages to instantiation performance the pooling
4107/// allocator is not enabled by default in Wasmtime. One reason is that the
4108/// performance advantages are not necessarily portable, for example while the
4109/// pooling allocator works on Windows it has not been tuned for performance on
4110/// Windows in the same way it has on Linux.
4111///
4112/// Additionally the main cost of the pooling allocator is that it requires a
4113/// very large reservation of virtual memory (on the order of most of the
4114/// addressable virtual address space). WebAssembly 32-bit linear memories in
4115/// Wasmtime are, by default 4G address space reservations with a small guard
4116/// region both before and after the linear memory. Memories in the pooling
4117/// allocator are contiguous which means that we only need a guard after linear
4118/// memory because the previous linear memory's slot post-guard is our own
4119/// pre-guard. This means that, by default, the pooling allocator uses roughly
4120/// 4G of virtual memory per WebAssembly linear memory slot. 4G of virtual
4121/// memory is 32 bits of a 64-bit address. Many 64-bit systems can only
4122/// actually use 48-bit addresses by default (although this can be extended on
4123/// architectures nowadays too), and of those 48 bits one of them is reserved
4124/// to indicate kernel-vs-userspace. This leaves 47-32=15 bits left,
4125/// meaning you can only have at most 32k slots of linear memories on many
4126/// systems by default. This is a relatively small number and shows how the
4127/// pooling allocator can quickly exhaust all of virtual memory.
4128///
4129/// Another disadvantage of the pooling allocator is that it may keep memory
4130/// alive when nothing is using it. A previously used slot for an instance might
4131/// have paged-in memory that will not get paged out until the
4132/// [`Engine`] owning the pooling allocator is dropped. While
4133/// suitable for some applications this behavior may not be suitable for all
4134/// applications.
4135///
4136/// Finally the last disadvantage of the pooling allocator is that the
4137/// configuration values for the maximum number of instances, memories, tables,
4138/// etc, must all be fixed up-front. There's not always a clear answer as to
4139/// what these values should be so not all applications may be able to work
4140/// with this constraint.
4141///
4142/// [`madvise`]: https://man7.org/linux/man-pages/man2/madvise.2.html
4143/// [`mprotect`]: https://man7.org/linux/man-pages/man2/mprotect.2.html
4144/// [`mmap`]: https://man7.org/linux/man-pages/man2/mmap.2.html
4145/// [`munmap`]: https://man7.org/linux/man-pages/man2/munmap.2.html
4146#[derive(Debug, Clone)]
4147pub struct PoolingAllocationConfig {
4148    /// See `PoolingAllocatorConfig::max_unused_warm_slots` in `wasmtime`
4149    pub(crate) max_unused_warm_slots: u32,
4150    /// The target number of decommits to do per batch. This is not precise, as
4151    /// we can queue up decommits at times when we aren't prepared to
4152    /// immediately flush them, and so we may go over this target size
4153    /// occasionally.
4154    pub(crate) decommit_batch_size: usize,
4155    /// The size, in bytes, of async stacks to allocate (not including the guard
4156    /// page).
4157    #[cfg_attr(
4158        not(all(feature = "async", feature = "pooling-allocator")),
4159        expect(dead_code, reason = "easier to cfg")
4160    )]
4161    pub(crate) stack_size: usize,
4162    /// The limits to apply to instances allocated within this allocator.
4163    pub(crate) limits: InstanceLimits,
4164    /// Whether or not async stacks are zeroed after use.
4165    #[cfg_attr(
4166        not(all(feature = "async", feature = "pooling-allocator")),
4167        expect(dead_code, reason = "easier to cfg")
4168    )]
4169    pub(crate) async_stack_zeroing: bool,
4170    /// If async stack zeroing is enabled and the host platform is Linux this is
4171    /// how much memory to zero out with `memset`.
4172    ///
4173    /// The rest of memory will be zeroed out with `madvise`.
4174    pub(crate) async_stack_keep_resident: usize,
4175    /// How much linear memory, in bytes, to keep resident after resetting for
4176    /// use with the next instance. This much memory will be `memset` to zero
4177    /// when a linear memory is deallocated.
4178    ///
4179    /// Memory exceeding this amount in the wasm linear memory will be released
4180    /// with `madvise` back to the kernel.
4181    ///
4182    /// Only applicable on Linux.
4183    pub(crate) linear_memory_keep_resident: usize,
4184    /// Same as `linear_memory_keep_resident` but for tables.
4185    pub(crate) table_keep_resident: usize,
4186    /// Whether to enable memory protection keys.
4187    pub(crate) memory_protection_keys: Enabled,
4188    /// How many memory protection keys to allocate.
4189    pub(crate) max_memory_protection_keys: usize,
4190    /// Whether to enable PAGEMAP_SCAN on Linux.
4191    pub(crate) pagemap_scan: Enabled,
4192}
4193
4194impl Default for PoolingAllocationConfig {
4195    fn default() -> Self {
4196        Self {
4197            max_unused_warm_slots: 100,
4198            decommit_batch_size: 1,
4199            stack_size: 2 << 20,
4200            limits: InstanceLimits::default(),
4201            async_stack_zeroing: false,
4202            async_stack_keep_resident: 0,
4203            linear_memory_keep_resident: 0,
4204            table_keep_resident: 0,
4205            memory_protection_keys: Enabled::No,
4206            max_memory_protection_keys: 16,
4207            pagemap_scan: Enabled::No,
4208        }
4209    }
4210}
4211
4212/// Instance-related limit configuration for pooling.
4213///
4214/// More docs on this can be found at `wasmtime::PoolingAllocationConfig`.
4215#[derive(Debug, Copy, Clone)]
4216pub(crate) struct InstanceLimits {
4217    /// The maximum number of component instances that may be allocated
4218    /// concurrently.
4219    pub(crate) total_component_instances: u32,
4220
4221    /// The maximum size of a component's `VMComponentContext`, including
4222    /// the aggregate size of all its inner core modules' `VMContext` sizes.
4223    pub(crate) component_instance_size: usize,
4224
4225    /// The maximum number of core module instances that may be allocated
4226    /// concurrently.
4227    pub(crate) total_core_instances: u32,
4228
4229    /// The maximum number of core module instances that a single component may
4230    /// transitively contain.
4231    pub(crate) max_core_instances_per_component: u32,
4232
4233    /// The maximum number of Wasm linear memories that a component may
4234    /// transitively contain.
4235    pub(crate) max_memories_per_component: u32,
4236
4237    /// The maximum number of tables that a component may transitively contain.
4238    pub(crate) max_tables_per_component: u32,
4239
4240    /// The total number of linear memories in the pool, across all instances.
4241    pub(crate) total_memories: u32,
4242
4243    /// The total number of tables in the pool, across all instances.
4244    pub(crate) total_tables: u32,
4245
4246    /// The total number of async stacks in the pool, across all instances.
4247    pub(crate) total_stacks: u32,
4248
4249    /// Maximum size of a core instance's `VMContext`.
4250    pub(crate) core_instance_size: usize,
4251
4252    /// Maximum number of tables per instance.
4253    pub(crate) max_tables_per_module: u32,
4254
4255    /// Maximum number of word-size elements per table.
4256    ///
4257    /// Note that tables for element types such as continuations
4258    /// that use more than one word of storage may store fewer
4259    /// elements.
4260    pub(crate) table_elements: usize,
4261
4262    /// Maximum number of linear memories per instance.
4263    pub(crate) max_memories_per_module: u32,
4264
4265    /// Maximum byte size of a linear memory, must be smaller than
4266    /// `memory_reservation` in `Tunables`.
4267    pub(crate) max_memory_size: usize,
4268
4269    /// The total number of GC heaps in the pool, across all instances.
4270    pub(crate) total_gc_heaps: u32,
4271}
4272
4273impl Default for InstanceLimits {
4274    fn default() -> Self {
4275        let total = if cfg!(target_pointer_width = "32") {
4276            100
4277        } else {
4278            1000
4279        };
4280        // See doc comments for `wasmtime::PoolingAllocationConfig` for these
4281        // default values
4282        Self {
4283            total_component_instances: total,
4284            component_instance_size: 1 << 20, // 1 MiB
4285            total_core_instances: total,
4286            max_core_instances_per_component: u32::MAX,
4287            max_memories_per_component: u32::MAX,
4288            max_tables_per_component: u32::MAX,
4289            total_memories: total,
4290            total_tables: total,
4291            total_stacks: total,
4292            core_instance_size: 1 << 20, // 1 MiB
4293            max_tables_per_module: 1,
4294            // NB: in #8504 it was seen that a C# module in debug module can
4295            // have 10k+ elements.
4296            table_elements: 20_000,
4297            max_memories_per_module: 1,
4298            #[cfg(target_pointer_width = "64")]
4299            max_memory_size: 1 << 32, // 4G,
4300            #[cfg(target_pointer_width = "32")]
4301            max_memory_size: 10 << 20, // 10 MiB
4302            total_gc_heaps: total,
4303        }
4304    }
4305}
4306
4307impl PoolingAllocationConfig {
4308    /// Returns a new configuration builder with all default settings
4309    /// configured.
4310    pub fn new() -> PoolingAllocationConfig {
4311        PoolingAllocationConfig::default()
4312    }
4313
4314    /// Configures the maximum number of "unused warm slots" to retain in the
4315    /// pooling allocator.
4316    ///
4317    /// The pooling allocator operates over slots to allocate from, and each
4318    /// slot is considered "cold" if it's never been used before or "warm" if
4319    /// it's been used by some module in the past. Slots in the pooling
4320    /// allocator additionally track an "affinity" flag to a particular core
4321    /// wasm module. When a module is instantiated into a slot then the slot is
4322    /// considered affine to that module, even after the instance has been
4323    /// deallocated.
4324    ///
4325    /// When a new instance is created then a slot must be chosen, and the
4326    /// current algorithm for selecting a slot is:
4327    ///
4328    /// * If there are slots that are affine to the module being instantiated,
4329    ///   then the most recently used slot is selected to be allocated from.
4330    ///   This is done to improve reuse of resources such as memory mappings and
4331    ///   additionally try to benefit from temporal locality for things like
4332    ///   caches.
4333    ///
4334    /// * Otherwise if there are more than N affine slots to other modules, then
4335    ///   one of those affine slots is chosen to be allocated. The slot chosen
4336    ///   is picked on a least-recently-used basis.
4337    ///
4338    /// * Finally, if there are less than N affine slots to other modules, then
4339    ///   the non-affine slots are allocated from.
4340    ///
4341    /// This setting, `max_unused_warm_slots`, is the value for N in the above
4342    /// algorithm. The purpose of this setting is to have a knob over the RSS
4343    /// impact of "unused slots" for a long-running wasm server.
4344    ///
4345    /// If this setting is set to 0, for example, then affine slots are
4346    /// aggressively reused on a least-recently-used basis. A "cold" slot is
4347    /// only used if there are no affine slots available to allocate from. This
4348    /// means that the set of slots used over the lifetime of a program is the
4349    /// same as the maximum concurrent number of wasm instances.
4350    ///
4351    /// If this setting is set to infinity, however, then cold slots are
4352    /// prioritized to be allocated from. This means that the set of slots used
4353    /// over the lifetime of a program will approach
4354    /// [`PoolingAllocationConfig::total_memories`], or the maximum number of
4355    /// slots in the pooling allocator.
4356    ///
4357    /// Wasmtime does not aggressively decommit all resources associated with a
4358    /// slot when the slot is not in use. For example the
4359    /// [`PoolingAllocationConfig::linear_memory_keep_resident`] option can be
4360    /// used to keep memory associated with a slot, even when it's not in use.
4361    /// This means that the total set of used slots in the pooling instance
4362    /// allocator can impact the overall RSS usage of a program.
4363    ///
4364    /// The default value for this option is `100`.
4365    pub fn max_unused_warm_slots(&mut self, max: u32) -> &mut Self {
4366        self.max_unused_warm_slots = max;
4367        self
4368    }
4369
4370    /// The target number of decommits to do per batch.
4371    ///
4372    /// This is not precise, as we can queue up decommits at times when we
4373    /// aren't prepared to immediately flush them, and so we may go over this
4374    /// target size occasionally.
4375    ///
4376    /// Note additionally that the queue of not-yet-decommitted entities is
4377    /// sharded to reduce lock contention: one shard per available CPU, capped
4378    /// at 16. Each shard batches up to this many decommits independently,
4379    /// meaning that up to `min(available_parallelism, 16) * (batch_size - 1)`
4380    /// decommits may be queued and not yet flushed at any given time.
4381    ///
4382    /// A batch size of one effectively disables batching.
4383    ///
4384    /// Defaults to `1`.
4385    pub fn decommit_batch_size(&mut self, batch_size: usize) -> &mut Self {
4386        self.decommit_batch_size = batch_size;
4387        self
4388    }
4389
4390    /// How much memory, in bytes, to keep resident for async stacks allocated
4391    /// with the pooling allocator.
4392    ///
4393    /// When [`Config::async_stack_zeroing`] is enabled then Wasmtime will reset
4394    /// the contents of async stacks back to zero upon deallocation. This option
4395    /// can be used to perform the zeroing operation with `memset` up to a
4396    /// certain threshold of bytes instead of using system calls to reset the
4397    /// stack to zero.
4398    ///
4399    /// Note that when using this option the memory with async stacks will
4400    /// never be decommitted.
4401    pub fn async_stack_keep_resident(&mut self, size: usize) -> &mut Self {
4402        self.async_stack_keep_resident = size;
4403        self
4404    }
4405
4406    /// How much memory, in bytes, to keep resident for each linear memory
4407    /// after deallocation.
4408    ///
4409    /// This option is only applicable on Linux and has no effect on other
4410    /// platforms.
4411    ///
4412    /// By default Wasmtime will use `madvise` to reset the entire contents of
4413    /// linear memory back to zero when a linear memory is deallocated. This
4414    /// option can be used to use `memset` instead to set memory back to zero
4415    /// which can, in some configurations, reduce the number of page faults
4416    /// taken when a slot is reused.
4417    pub fn linear_memory_keep_resident(&mut self, size: usize) -> &mut Self {
4418        self.linear_memory_keep_resident = size;
4419        self
4420    }
4421
4422    /// How much memory, in bytes, to keep resident for each table after
4423    /// deallocation.
4424    ///
4425    /// This option is only applicable on Linux and has no effect on other
4426    /// platforms.
4427    ///
4428    /// This option is the same as
4429    /// [`PoolingAllocationConfig::linear_memory_keep_resident`] except that it
4430    /// is applicable to tables instead.
4431    pub fn table_keep_resident(&mut self, size: usize) -> &mut Self {
4432        self.table_keep_resident = size;
4433        self
4434    }
4435
4436    /// The maximum number of concurrent component instances supported (default
4437    /// is `1000`).
4438    ///
4439    /// This provides an upper-bound on the total size of component
4440    /// metadata-related allocations, along with
4441    /// [`PoolingAllocationConfig::max_component_instance_size`]. The upper bound is
4442    ///
4443    /// ```text
4444    /// total_component_instances * max_component_instance_size
4445    /// ```
4446    ///
4447    /// where `max_component_instance_size` is rounded up to the size and alignment
4448    /// of the internal representation of the metadata.
4449    pub fn total_component_instances(&mut self, count: u32) -> &mut Self {
4450        self.limits.total_component_instances = count;
4451        self
4452    }
4453
4454    /// The maximum size, in bytes, allocated for a component instance's
4455    /// `VMComponentContext` metadata as well as the aggregate size of this
4456    /// component's core instances `VMContext` metadata.
4457    ///
4458    /// The [`wasmtime::component::Instance`][crate::component::Instance] type
4459    /// has a static size but its internal `VMComponentContext` is dynamically
4460    /// sized depending on the component being instantiated. This size limit
4461    /// loosely correlates to the size of the component, taking into account
4462    /// factors such as:
4463    ///
4464    /// * number of lifted and lowered functions,
4465    /// * number of memories
4466    /// * number of inner instances
4467    /// * number of resources
4468    ///
4469    /// If the allocated size per instance is too small then instantiation of a
4470    /// module will fail at runtime with an error indicating how many bytes were
4471    /// needed.
4472    ///
4473    /// In addition to the memory in the runtime for the component itself,
4474    /// components contain one or more core module instances. Each of these
4475    /// require some memory in the runtime as described in
4476    /// [`PoolingAllocationConfig::max_core_instance_size`]. The limit here
4477    /// applies against the sum of all of these individual allocations.
4478    ///
4479    /// The default value for this is 1MiB.
4480    ///
4481    /// This provides an upper-bound on the total size of all component's
4482    /// metadata-related allocations (for both the component and its embedded
4483    /// core module instances), along with
4484    /// [`PoolingAllocationConfig::total_component_instances`]. The upper bound is
4485    ///
4486    /// ```text
4487    /// total_component_instances * max_component_instance_size
4488    /// ```
4489    ///
4490    /// where `max_component_instance_size` is rounded up to the size and alignment
4491    /// of the internal representation of the metadata.
4492    pub fn max_component_instance_size(&mut self, size: usize) -> &mut Self {
4493        self.limits.component_instance_size = size;
4494        self
4495    }
4496
4497    /// The maximum number of core instances a single component may contain
4498    /// (default is unlimited).
4499    ///
4500    /// This method (along with
4501    /// [`PoolingAllocationConfig::max_memories_per_component`],
4502    /// [`PoolingAllocationConfig::max_tables_per_component`], and
4503    /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
4504    /// the amount of resources a single component allocation consumes.
4505    ///
4506    /// If a component will instantiate more core instances than `count`, then
4507    /// the component will fail to instantiate.
4508    pub fn max_core_instances_per_component(&mut self, count: u32) -> &mut Self {
4509        self.limits.max_core_instances_per_component = count;
4510        self
4511    }
4512
4513    /// The maximum number of Wasm linear memories that a single component may
4514    /// transitively contain (default is unlimited).
4515    ///
4516    /// This method (along with
4517    /// [`PoolingAllocationConfig::max_core_instances_per_component`],
4518    /// [`PoolingAllocationConfig::max_tables_per_component`], and
4519    /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
4520    /// the amount of resources a single component allocation consumes.
4521    ///
4522    /// If a component transitively contains more linear memories than `count`,
4523    /// then the component will fail to instantiate.
4524    pub fn max_memories_per_component(&mut self, count: u32) -> &mut Self {
4525        self.limits.max_memories_per_component = count;
4526        self
4527    }
4528
4529    /// The maximum number of tables that a single component may transitively
4530    /// contain (default is unlimited).
4531    ///
4532    /// This method (along with
4533    /// [`PoolingAllocationConfig::max_core_instances_per_component`],
4534    /// [`PoolingAllocationConfig::max_memories_per_component`],
4535    /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
4536    /// the amount of resources a single component allocation consumes.
4537    ///
4538    /// If a component will transitively contains more tables than `count`, then
4539    /// the component will fail to instantiate.
4540    pub fn max_tables_per_component(&mut self, count: u32) -> &mut Self {
4541        self.limits.max_tables_per_component = count;
4542        self
4543    }
4544
4545    /// The maximum number of concurrent Wasm linear memories supported (default
4546    /// is `1000`).
4547    ///
4548    /// This value has a direct impact on the amount of memory allocated by the pooling
4549    /// instance allocator.
4550    ///
4551    /// The pooling instance allocator allocates a memory pool, where each entry
4552    /// in the pool contains the reserved address space for each linear memory
4553    /// supported by an instance.
4554    ///
4555    /// The memory pool will reserve a large quantity of host process address
4556    /// space to elide the bounds checks required for correct WebAssembly memory
4557    /// semantics. Even with 64-bit address spaces, the address space is limited
4558    /// when dealing with a large number of linear memories.
4559    ///
4560    /// For example, on Linux x86_64, the userland address space limit is 128
4561    /// TiB. That might seem like a lot, but each linear memory will *reserve* 6
4562    /// GiB of space by default.
4563    pub fn total_memories(&mut self, count: u32) -> &mut Self {
4564        self.limits.total_memories = count;
4565        self
4566    }
4567
4568    /// The maximum number of concurrent tables supported (default is `1000`).
4569    ///
4570    /// This value has a direct impact on the amount of memory allocated by the
4571    /// pooling instance allocator.
4572    ///
4573    /// The pooling instance allocator allocates a table pool, where each entry
4574    /// in the pool contains the space needed for each WebAssembly table
4575    /// supported by an instance (see `table_elements` to control the size of
4576    /// each table).
4577    pub fn total_tables(&mut self, count: u32) -> &mut Self {
4578        self.limits.total_tables = count;
4579        self
4580    }
4581
4582    /// The maximum number of execution stacks allowed for asynchronous
4583    /// execution, when enabled (default is `1000`).
4584    ///
4585    /// This value has a direct impact on the amount of memory allocated by the
4586    /// pooling instance allocator.
4587    #[cfg(feature = "async")]
4588    pub fn total_stacks(&mut self, count: u32) -> &mut Self {
4589        self.limits.total_stacks = count;
4590        self
4591    }
4592
4593    /// The maximum number of concurrent core instances supported (default is
4594    /// `1000`).
4595    ///
4596    /// This provides an upper-bound on the total size of core instance
4597    /// metadata-related allocations, along with
4598    /// [`PoolingAllocationConfig::max_core_instance_size`]. The upper bound is
4599    ///
4600    /// ```text
4601    /// total_core_instances * max_core_instance_size
4602    /// ```
4603    ///
4604    /// where `max_core_instance_size` is rounded up to the size and alignment of
4605    /// the internal representation of the metadata.
4606    pub fn total_core_instances(&mut self, count: u32) -> &mut Self {
4607        self.limits.total_core_instances = count;
4608        self
4609    }
4610
4611    /// The maximum size, in bytes, allocated for a core instance's `VMContext`
4612    /// metadata.
4613    ///
4614    /// The [`Instance`][crate::Instance] type has a static size but its
4615    /// `VMContext` metadata is dynamically sized depending on the module being
4616    /// instantiated. This size limit loosely correlates to the size of the Wasm
4617    /// module, taking into account factors such as:
4618    ///
4619    /// * number of functions
4620    /// * number of globals
4621    /// * number of memories
4622    /// * number of tables
4623    /// * number of function types
4624    ///
4625    /// If the allocated size per instance is too small then instantiation of a
4626    /// module will fail at runtime with an error indicating how many bytes were
4627    /// needed.
4628    ///
4629    /// The default value for this is 1MiB.
4630    ///
4631    /// This provides an upper-bound on the total size of core instance
4632    /// metadata-related allocations, along with
4633    /// [`PoolingAllocationConfig::total_core_instances`]. The upper bound is
4634    ///
4635    /// ```text
4636    /// total_core_instances * max_core_instance_size
4637    /// ```
4638    ///
4639    /// where `max_core_instance_size` is rounded up to the size and alignment of
4640    /// the internal representation of the metadata.
4641    pub fn max_core_instance_size(&mut self, size: usize) -> &mut Self {
4642        self.limits.core_instance_size = size;
4643        self
4644    }
4645
4646    /// The maximum number of defined tables for a core module (default is `1`).
4647    ///
4648    /// This value controls the capacity of the `VMTableDefinition` table in
4649    /// each instance's `VMContext` structure.
4650    ///
4651    /// The allocated size of the table will be `tables *
4652    /// sizeof(VMTableDefinition)` for each instance regardless of how many
4653    /// tables are defined by an instance's module.
4654    pub fn max_tables_per_module(&mut self, tables: u32) -> &mut Self {
4655        self.limits.max_tables_per_module = tables;
4656        self
4657    }
4658
4659    /// The maximum table elements for any table defined in a module (default is
4660    /// `20000`).
4661    ///
4662    /// If a table's minimum element limit is greater than this value, the
4663    /// module will fail to instantiate.
4664    ///
4665    /// If a table's maximum element limit is unbounded or greater than this
4666    /// value, the maximum will be `table_elements` for the purpose of any
4667    /// `table.grow` instruction.
4668    ///
4669    /// This value is used to reserve the maximum space for each supported
4670    /// table; table elements are pointer-sized in the Wasmtime runtime.
4671    /// Therefore, the space reserved for each instance is `tables *
4672    /// table_elements * sizeof::<*const ()>`.
4673    pub fn table_elements(&mut self, elements: usize) -> &mut Self {
4674        self.limits.table_elements = elements;
4675        self
4676    }
4677
4678    /// The maximum number of defined linear memories for a module (default is
4679    /// `1`).
4680    ///
4681    /// This value controls the capacity of the `VMMemoryDefinition` table in
4682    /// each core instance's `VMContext` structure.
4683    ///
4684    /// The allocated size of the table will be `memories *
4685    /// sizeof(VMMemoryDefinition)` for each core instance regardless of how
4686    /// many memories are defined by the core instance's module.
4687    pub fn max_memories_per_module(&mut self, memories: u32) -> &mut Self {
4688        self.limits.max_memories_per_module = memories;
4689        self
4690    }
4691
4692    /// The maximum byte size that any WebAssembly linear memory may grow to.
4693    ///
4694    /// This option defaults to 4 GiB meaning that for 32-bit linear memories
4695    /// there is no restrictions. 64-bit linear memories will not be allowed to
4696    /// grow beyond 4 GiB by default.
4697    ///
4698    /// If a memory's minimum size is greater than this value, the module will
4699    /// fail to instantiate.
4700    ///
4701    /// If a memory's maximum size is unbounded or greater than this value, the
4702    /// maximum will be `max_memory_size` for the purpose of any `memory.grow`
4703    /// instruction.
4704    ///
4705    /// This value is used to control the maximum accessible space for each
4706    /// linear memory of a core instance. This can be thought of as a simple
4707    /// mechanism like [`Store::limiter`](crate::Store::limiter) to limit memory
4708    /// at runtime. This value can also affect striping/coloring behavior when
4709    /// used in conjunction with
4710    /// [`memory_protection_keys`](PoolingAllocationConfig::memory_protection_keys).
4711    ///
4712    /// The virtual memory reservation size of each linear memory is controlled
4713    /// by the [`Config::memory_reservation`] setting and this method's
4714    /// configuration cannot exceed [`Config::memory_reservation`].
4715    pub fn max_memory_size(&mut self, bytes: usize) -> &mut Self {
4716        self.limits.max_memory_size = bytes;
4717        self
4718    }
4719
4720    /// Configures whether memory protection keys (MPK) should be used for more
4721    /// efficient layout of pool-allocated memories.
4722    ///
4723    /// When using the pooling allocator (see [`Config::allocation_strategy`],
4724    /// [`InstanceAllocationStrategy::Pooling`]), memory protection keys can
4725    /// reduce the total amount of allocated virtual memory by eliminating guard
4726    /// regions between WebAssembly memories in the pool. It does so by
4727    /// "coloring" memory regions with different memory keys and setting which
4728    /// regions are accessible each time executions switches from host to guest
4729    /// (or vice versa).
4730    ///
4731    /// Leveraging MPK requires configuring a smaller-than-default
4732    /// [`max_memory_size`](PoolingAllocationConfig::max_memory_size) to enable
4733    /// this coloring/striping behavior. For example embeddings might want to
4734    /// reduce the default 4G allowance to 128M.
4735    ///
4736    /// MPK is only available on Linux (called `pku` there) and recent x86
4737    /// systems; we check for MPK support at runtime by examining the `CPUID`
4738    /// register. This configuration setting can be in three states:
4739    ///
4740    /// - `auto`: if MPK support is available the guard regions are removed; if
4741    ///   not, the guard regions remain
4742    /// - `yes`: use MPK to eliminate guard regions; fail if MPK is not
4743    ///   supported
4744    /// - `no`: never use MPK
4745    ///
4746    /// By default this value is `no`, but may become `auto` in future
4747    /// releases.
4748    ///
4749    /// __WARNING__: this configuration options is still experimental--use at
4750    /// your own risk! MPK uses kernel and CPU features to protect memory
4751    /// regions; you may observe segmentation faults if anything is
4752    /// misconfigured.
4753    #[cfg(feature = "memory-protection-keys")]
4754    pub fn memory_protection_keys(&mut self, enable: Enabled) -> &mut Self {
4755        self.memory_protection_keys = enable;
4756        self
4757    }
4758
4759    /// Sets an upper limit on how many memory protection keys (MPK) Wasmtime
4760    /// will use.
4761    ///
4762    /// This setting is only applicable when
4763    /// [`PoolingAllocationConfig::memory_protection_keys`] is set to `enable`
4764    /// or `auto`. Configuring this above the HW and OS limits (typically 15)
4765    /// has no effect.
4766    ///
4767    /// If multiple Wasmtime engines are used in the same process, note that all
4768    /// engines will share the same set of allocated keys; this setting will
4769    /// limit how many keys are allocated initially and thus available to all
4770    /// other engines.
4771    #[cfg(feature = "memory-protection-keys")]
4772    pub fn max_memory_protection_keys(&mut self, max: usize) -> &mut Self {
4773        self.max_memory_protection_keys = max;
4774        self
4775    }
4776
4777    /// Check if memory protection keys (MPK) are available on the current host.
4778    ///
4779    /// This is a convenience method for determining MPK availability using the
4780    /// same method that [`Enabled::Auto`] does. See
4781    /// [`PoolingAllocationConfig::memory_protection_keys`] for more
4782    /// information.
4783    #[cfg(feature = "memory-protection-keys")]
4784    pub fn are_memory_protection_keys_available() -> bool {
4785        crate::runtime::vm::mpk::is_supported()
4786    }
4787
4788    /// The maximum number of concurrent GC heaps supported (default is `1000`).
4789    ///
4790    /// This value has a direct impact on the amount of memory allocated by the
4791    /// pooling instance allocator.
4792    ///
4793    /// The pooling instance allocator allocates a GC heap pool, where each
4794    /// entry in the pool contains the space needed for each GC heap used by a
4795    /// store.
4796    #[cfg(feature = "gc")]
4797    pub fn total_gc_heaps(&mut self, count: u32) -> &mut Self {
4798        self.limits.total_gc_heaps = count;
4799        self
4800    }
4801
4802    /// Configures whether the Linux-specific [`PAGEMAP_SCAN` ioctl][ioctl] is
4803    /// used to help reset linear memory.
4804    ///
4805    /// When [`Self::linear_memory_keep_resident`] or
4806    /// [`Self::table_keep_resident`] options are configured to nonzero values
4807    /// the default behavior is to `memset` the lowest addresses of a table or
4808    /// memory back to their original contents. With the `PAGEMAP_SCAN` ioctl on
4809    /// Linux this can be done to more intelligently scan for resident pages in
4810    /// the region and only reset those pages back to their original contents
4811    /// with `memset` rather than assuming the low addresses are all resident.
4812    ///
4813    /// This ioctl has the potential to provide a number of performance benefits
4814    /// in high-reuse and high concurrency scenarios. Notably this enables
4815    /// Wasmtime to scan the entire region of WebAssembly linear memory and
4816    /// manually reset memory back to its original contents, up to
4817    /// [`Self::linear_memory_keep_resident`] bytes, possibly skipping an
4818    /// `madvise` entirely. This can be more efficient by avoiding removing
4819    /// pages from the address space entirely and additionally ensuring that
4820    /// future use of the linear memory doesn't incur page faults as the pages
4821    /// remain resident.
4822    ///
4823    /// At this time this configuration option is still being evaluated as to
4824    /// how appropriate it is for all use cases. It currently defaults to
4825    /// `no` or disabled but may change to `auto`, enable if supported, in the
4826    /// future. This option is only supported on Linux and requires a kernel
4827    /// version of 6.7 or higher.
4828    ///
4829    /// [ioctl]: https://www.man7.org/linux/man-pages/man2/PAGEMAP_SCAN.2const.html
4830    pub fn pagemap_scan(&mut self, enable: Enabled) -> &mut Self {
4831        self.pagemap_scan = enable;
4832        self
4833    }
4834
4835    /// Returns the configured
4836    /// [`PoolingAllocationConfig::decommit_batch_size`], if enabled.
4837    pub fn get_decommit_batch_size(&self) -> usize {
4838        self.decommit_batch_size
4839    }
4840
4841    /// Returns the configured
4842    /// [`PoolingAllocationConfig::max_unused_warm_slots`], if enabled.
4843    pub fn get_max_unused_warm_slots(&self) -> u32 {
4844        self.max_unused_warm_slots
4845    }
4846
4847    /// Returns the configured
4848    /// [`PoolingAllocationConfig::linear_memory_keep_resident`], if
4849    /// enabled.
4850    pub fn get_memory_keep_resident(&self) -> usize {
4851        self.linear_memory_keep_resident
4852    }
4853
4854    /// Returns the configured
4855    /// [`PoolingAllocationConfig::table_keep_resident`], if enabled.
4856    pub fn get_table_keep_resident(&self) -> usize {
4857        self.table_keep_resident
4858    }
4859
4860    /// Returns the configured
4861    /// [`PoolingAllocationConfig::async_stack_keep_resident`], if
4862    /// enabled.
4863    pub fn get_async_stack_keep_resident(&self) -> usize {
4864        self.async_stack_keep_resident
4865    }
4866
4867    /// Returns the configured
4868    /// [`PoolingAllocationConfig::memory_protection_keys`], if enabled.
4869    pub fn get_memory_protection_keys(&self) -> Enabled {
4870        self.memory_protection_keys
4871    }
4872
4873    /// Returns the configured
4874    /// [`PoolingAllocationConfig::max_memory_protection_keys`], if
4875    /// enabled.
4876    pub fn get_max_memory_protection_keys(&self) -> usize {
4877        self.max_memory_protection_keys
4878    }
4879
4880    /// Returns the configured
4881    /// [`PoolingAllocationConfig::pagemap_scan`], if enabled.
4882    pub fn get_pagemap_scan(&self) -> Enabled {
4883        self.pagemap_scan
4884    }
4885
4886    /// Returns the configured
4887    /// [`PoolingAllocationConfig::total_core_instances`], if enabled.
4888    pub fn get_total_core_instances(&self) -> u32 {
4889        self.limits.total_core_instances
4890    }
4891
4892    /// Returns the configured
4893    /// [`PoolingAllocationConfig::total_component_instances`], if
4894    /// enabled.
4895    pub fn get_total_component_instances(&self) -> u32 {
4896        self.limits.total_component_instances
4897    }
4898
4899    /// Returns the configured
4900    /// [`PoolingAllocationConfig::total_memories`], if enabled.
4901    pub fn get_total_memories(&self) -> u32 {
4902        self.limits.total_memories
4903    }
4904
4905    /// Returns the configured
4906    /// [`PoolingAllocationConfig::total_tables`], if enabled.
4907    pub fn get_total_tables(&self) -> u32 {
4908        self.limits.total_tables
4909    }
4910
4911    /// Returns the configured
4912    /// [`PoolingAllocationConfig::total_stacks`], if enabled.
4913    pub fn get_total_stacks(&self) -> u32 {
4914        self.limits.total_stacks
4915    }
4916
4917    /// Returns the configured
4918    /// [`PoolingAllocationConfig::total_gc_heaps`], if enabled.
4919    pub fn get_total_gc_heaps(&self) -> u32 {
4920        self.limits.total_gc_heaps
4921    }
4922
4923    /// Returns the configured
4924    /// [`PoolingAllocationConfig::max_memory_size`], if enabled.
4925    pub fn get_max_memory_size(&self) -> usize {
4926        self.limits.max_memory_size
4927    }
4928
4929    /// Returns the configured
4930    /// [`PoolingAllocationConfig::table_elements`], if enabled.
4931    pub fn get_table_elements(&self) -> usize {
4932        self.limits.table_elements
4933    }
4934
4935    /// Returns the configured
4936    /// [`PoolingAllocationConfig::max_core_instance_size`], if enabled.
4937    pub fn get_max_core_instance_size(&self) -> usize {
4938        self.limits.core_instance_size
4939    }
4940
4941    /// Returns the configured
4942    /// [`PoolingAllocationConfig::max_component_instance_size`], if
4943    /// enabled.
4944    pub fn get_max_component_instance_size(&self) -> usize {
4945        self.limits.component_instance_size
4946    }
4947
4948    /// Returns the configured
4949    /// [`PoolingAllocationConfig::max_core_instances_per_component`], if
4950    /// enabled.
4951    pub fn get_max_core_instances_per_component(&self) -> u32 {
4952        self.limits.max_core_instances_per_component
4953    }
4954
4955    /// Returns the configured
4956    /// [`PoolingAllocationConfig::max_memories_per_component`], if
4957    /// enabled.
4958    pub fn get_max_memories_per_component(&self) -> u32 {
4959        self.limits.max_memories_per_component
4960    }
4961
4962    /// Returns the configured
4963    /// [`PoolingAllocationConfig::max_tables_per_component`], if enabled.
4964    pub fn get_max_tables_per_component(&self) -> u32 {
4965        self.limits.max_tables_per_component
4966    }
4967
4968    /// Returns the configured
4969    /// [`PoolingAllocationConfig::max_tables_per_module`], if enabled.
4970    pub fn get_max_tables_per_module(&self) -> u32 {
4971        self.limits.max_tables_per_module
4972    }
4973
4974    /// Returns the configured
4975    /// [`PoolingAllocationConfig::max_memories_per_module`], if enabled.
4976    pub fn get_max_memories_per_module(&self) -> u32 {
4977        self.limits.max_memories_per_module
4978    }
4979}
4980
4981#[cfg(feature = "std")]
4982fn detect_host_feature(feature: &str) -> Option<bool> {
4983    #[cfg(target_arch = "aarch64")]
4984    {
4985        return match feature {
4986            "lse" => Some(std::arch::is_aarch64_feature_detected!("lse")),
4987            "paca" => Some(std::arch::is_aarch64_feature_detected!("paca")),
4988            "fp16" => Some(std::arch::is_aarch64_feature_detected!("fp16")),
4989            "dotprod" => Some(std::arch::is_aarch64_feature_detected!("dotprod")),
4990            "i8mm" => Some(std::arch::is_aarch64_feature_detected!("i8mm")),
4991
4992            _ => None,
4993        };
4994    }
4995
4996    // `is_s390x_feature_detected` is nightly only for now, so use the
4997    // STORE FACILITY LIST EXTENDED instruction as a temporary measure.
4998    #[cfg(target_arch = "s390x")]
4999    {
5000        let mut facility_list: [u64; 4] = [0; 4];
5001        unsafe {
5002            core::arch::asm!(
5003                "stfle 0({})",
5004                in(reg_addr) facility_list.as_mut_ptr() ,
5005                inout("r0") facility_list.len() as u64 - 1 => _,
5006                options(nostack)
5007            );
5008        }
5009        let get_facility_bit = |n: usize| {
5010            // NOTE: bits are numbered from the left.
5011            facility_list[n / 64] & (1 << (63 - (n % 64))) != 0
5012        };
5013
5014        return match feature {
5015            "mie3" => Some(get_facility_bit(61)),
5016            "mie4" => Some(get_facility_bit(84)),
5017            "vxrs_ext2" => Some(get_facility_bit(148)),
5018            "vxrs_ext3" => Some(get_facility_bit(198)),
5019
5020            _ => None,
5021        };
5022    }
5023
5024    #[cfg(target_arch = "riscv64")]
5025    {
5026        return match feature {
5027            // due to `is_riscv64_feature_detected` is not stable.
5028            // we cannot use it. For now lie and say all features are always
5029            // found to keep tests working.
5030            _ => Some(true),
5031        };
5032    }
5033
5034    #[cfg(target_arch = "x86_64")]
5035    {
5036        return match feature {
5037            "cmpxchg16b" => Some(std::is_x86_feature_detected!("cmpxchg16b")),
5038            "sse3" => Some(std::is_x86_feature_detected!("sse3")),
5039            "ssse3" => Some(std::is_x86_feature_detected!("ssse3")),
5040            "sse4.1" => Some(std::is_x86_feature_detected!("sse4.1")),
5041            "sse4.2" => Some(std::is_x86_feature_detected!("sse4.2")),
5042            "popcnt" => Some(std::is_x86_feature_detected!("popcnt")),
5043            "avx" => Some(std::is_x86_feature_detected!("avx")),
5044            "avx2" => Some(std::is_x86_feature_detected!("avx2")),
5045            "fma" => Some(std::is_x86_feature_detected!("fma")),
5046            "avxvnni" => Some(std::is_x86_feature_detected!("avxvnni")),
5047            "bmi1" => Some(std::is_x86_feature_detected!("bmi1")),
5048            "bmi2" => Some(std::is_x86_feature_detected!("bmi2")),
5049            "avx512bitalg" => Some(std::is_x86_feature_detected!("avx512bitalg")),
5050            "avx512dq" => Some(std::is_x86_feature_detected!("avx512dq")),
5051            "avx512f" => Some(std::is_x86_feature_detected!("avx512f")),
5052            "avx512vl" => Some(std::is_x86_feature_detected!("avx512vl")),
5053            "avx512vbmi" => Some(std::is_x86_feature_detected!("avx512vbmi")),
5054            "avx512vnni" => Some(std::is_x86_feature_detected!("avx512vnni")),
5055            "lzcnt" => Some(std::is_x86_feature_detected!("lzcnt")),
5056
5057            _ => None,
5058        };
5059    }
5060
5061    #[allow(
5062        unreachable_code,
5063        reason = "reachable or not depending on if a target above matches"
5064    )]
5065    {
5066        let _ = feature;
5067        return None;
5068    }
5069}
5070
5071// What follows in this impl block is intended to be a somewhat-mechanical
5072// mostly-complete set of getters for relevant configuration options on
5073// `Config`. The `Config` type does not reflect a complete configuration so
5074// default values cannot be directly read from it. An `Engine`, however,
5075// represents a concrete and complete configuration with all default values
5076// fully specified. The purpose of these getters are then to perform a dual
5077// function of reflecting what was explicitly configured above as well as
5078// defaults that Wasmtime sets.
5079//
5080// The current pattern is:
5081//
5082// * All methods are `get_<config_name>`
5083// * Return values return `T` instead of `Option<T>` where possible unless the
5084//   state for `T` is completely missing.
5085//
5086// This impl is primarily in service of
5087// `wasmtime_cli_flags::CommonOptions::from_engine` at this time, and CLI flags
5088// are not as comprehensive as `Config` options, but it's expected that the set
5089// will settle/grow over time.
5090impl Engine {
5091    /// Returns the configured [`Config::memory_may_move`] value.
5092    pub fn get_memory_may_move(&self) -> bool {
5093        self.tunables().memory_may_move
5094    }
5095
5096    /// Returns the configured [`Config::memory_reservation`] value.
5097    pub fn get_memory_reservation(&self) -> u64 {
5098        self.tunables().memory_reservation
5099    }
5100
5101    /// Returns the configured [`Config::memory_reservation_for_growth`] value.
5102    pub fn get_memory_reservation_for_growth(&self) -> u64 {
5103        self.tunables().memory_reservation_for_growth
5104    }
5105
5106    /// Returns the configured [`Config::memory_guard_size`] value.
5107    pub fn get_memory_guard_size(&self) -> u64 {
5108        self.tunables().memory_guard_size
5109    }
5110
5111    /// Returns the configured [`Config::gc_heap_may_move`] value.
5112    pub fn get_gc_heap_may_move(&self) -> bool {
5113        self.tunables().gc_heap_may_move
5114    }
5115
5116    /// Returns the configured [`Config::gc_heap_reservation`] value.
5117    pub fn get_gc_heap_reservation(&self) -> u64 {
5118        self.tunables().gc_heap_reservation
5119    }
5120
5121    /// Returns the configured [`Config::gc_heap_initial_size`] value.
5122    pub fn get_gc_heap_initial_size(&self) -> u64 {
5123        self.tunables().gc_heap_initial_size
5124    }
5125
5126    /// Returns the configured [`Config::gc_heap_reservation_for_growth`] value.
5127    pub fn get_gc_heap_reservation_for_growth(&self) -> u64 {
5128        self.tunables().gc_heap_reservation_for_growth
5129    }
5130
5131    /// Returns the configured [`Config::gc_heap_guard_size`] value.
5132    pub fn get_gc_heap_guard_size(&self) -> u64 {
5133        self.tunables().gc_heap_guard_size
5134    }
5135
5136    /// Returns the configured [`Config::guard_before_linear_memory`] value.
5137    pub fn get_guard_before_linear_memory(&self) -> bool {
5138        self.tunables().guard_before_linear_memory
5139    }
5140
5141    /// Returns the configured [`Config::table_lazy_init`] value.
5142    pub fn get_table_lazy_init(&self) -> bool {
5143        self.tunables().table_lazy_init
5144    }
5145
5146    /// Returns the configured [`Config::memory_init_cow`] value.
5147    pub fn get_memory_init_cow(&self) -> bool {
5148        self.tunables().memory_init_cow
5149    }
5150
5151    /// Returns the configured [`Config::memory_guaranteed_dense_image_size`] value.
5152    pub fn get_memory_guaranteed_dense_image_size(&self) -> u64 {
5153        self.config().memory_guaranteed_dense_image_size
5154    }
5155
5156    /// Returns the configured [`Config::signals_based_traps`] value.
5157    pub fn get_signals_based_traps(&self) -> bool {
5158        self.tunables().signals_based_traps
5159    }
5160
5161    /// Returns the configured [`Config::gc_zeal_alloc_counter`] value.
5162    pub fn get_gc_zeal_alloc_counter(&self) -> Option<core::num::NonZeroU32> {
5163        self.tunables().gc_zeal_alloc_counter
5164    }
5165
5166    /// Returns the configured [`Config::cranelift_opt_level`] value.
5167    pub fn get_cranelift_opt_level(&self) -> Option<OptLevel> {
5168        #[cfg(any(feature = "cranelift", feature = "winch"))]
5169        if let Some(compiler) = self.compiler() {
5170            let flags = compiler.flags();
5171            let (_, FlagValue::Enum(opt)) = flags.iter().find(|(f, _)| *f == "opt_level")? else {
5172                return None;
5173            };
5174            return match &opt[..] {
5175                "none" => Some(OptLevel::None),
5176                "speed" => Some(OptLevel::Speed),
5177                "speed_and_size" => Some(OptLevel::SpeedAndSize),
5178                _ => None,
5179            };
5180        }
5181        None
5182    }
5183
5184    /// Returns the configured [`Config::cranelift_regalloc_algorithm`] value.
5185    pub fn get_cranelift_regalloc_algorithm(&self) -> Option<RegallocAlgorithm> {
5186        #[cfg(any(feature = "cranelift", feature = "winch"))]
5187        if let Some(compiler) = self.compiler() {
5188            let flags = compiler.flags();
5189            let (_, FlagValue::Enum(opt)) =
5190                flags.iter().find(|(f, _)| *f == "regalloc_algorithm")?
5191            else {
5192                return None;
5193            };
5194            return match &opt[..] {
5195                "backtracking" => Some(RegallocAlgorithm::Backtracking),
5196                "single_pass" => Some(RegallocAlgorithm::SinglePass),
5197                _ => None,
5198            };
5199        }
5200        None
5201    }
5202
5203    /// Returns the configured [`Config::strategy`] value.
5204    pub fn get_strategy(&self) -> Option<Strategy> {
5205        self.config().get_strategy()
5206    }
5207
5208    /// Returns the configured [`Config::collector`] value.
5209    pub fn get_collector(&self) -> Option<Collector> {
5210        #[cfg(feature = "gc")]
5211        return Some(self.config().collector);
5212        #[cfg(not(feature = "gc"))]
5213        return None;
5214    }
5215
5216    /// Returns the configured [`Config::cranelift_debug_verifier`] value.
5217    pub fn get_cranelift_debug_verifier(&self) -> Option<bool> {
5218        #[cfg(any(feature = "cranelift", feature = "winch"))]
5219        if let Some(compiler) = self.compiler() {
5220            let flags = compiler.flags();
5221            let (_, FlagValue::Bool(b)) = flags.iter().find(|(f, _)| *f == "enable_verifier")?
5222            else {
5223                return None;
5224            };
5225            return Some(*b);
5226        }
5227        None
5228    }
5229
5230    /// Returns the configured [`Config::compiler_inlining`] value.
5231    pub fn get_compiler_inlining(&self) -> Inlining {
5232        self.tunables().inlining
5233    }
5234
5235    /// Returns the configured [`Config::native_unwind_info`] value.
5236    pub fn get_native_unwind_info(&self) -> Option<bool> {
5237        #[cfg(any(feature = "cranelift", feature = "winch"))]
5238        if let Some(compiler) = self.compiler() {
5239            let flags = compiler.flags();
5240            let (_, FlagValue::Bool(b)) = flags.iter().find(|(f, _)| *f == "unwind_info")? else {
5241                return None;
5242            };
5243            return Some(*b);
5244        }
5245        None
5246    }
5247
5248    /// Returns the configured [`Config::parallel_compilation`] value.
5249    pub fn get_parallel_compilation(&self) -> bool {
5250        self.config().parallel_compilation
5251    }
5252
5253    /// Returns the configured [`Config::metadata_for_internal_asserts`] value.
5254    pub fn get_metadata_for_internal_asserts(&self) -> bool {
5255        self.tunables().metadata_for_internal_asserts
5256    }
5257
5258    /// Returns the configured [`Config::metadata_for_gc_heap_corruption`] value.
5259    pub fn get_metadata_for_gc_heap_corruption(&self) -> bool {
5260        self.tunables().metadata_for_gc_heap_corruption
5261    }
5262
5263    /// Returns the runtime pooling allocator configuration, if the pooling
5264    /// allocator is in use.
5265    pub fn get_pooling_config(&self) -> Option<&PoolingAllocationConfig> {
5266        #[cfg(feature = "pooling-allocator")]
5267        {
5268            Some(self.allocator().as_pooling()?.config())
5269        }
5270        #[cfg(not(feature = "pooling-allocator"))]
5271        {
5272            None
5273        }
5274    }
5275
5276    /// Returns the configured wasm proposals enabled in this engine.
5277    pub fn get_wasm_features(&self) -> WasmFeatures {
5278        self.features()
5279    }
5280
5281    /// Returns the configured [`Config::async_stack_size`] value.
5282    pub fn get_async_stack_size(&self) -> usize {
5283        self.config().async_stack_size
5284    }
5285
5286    /// Returns the configured [`Config::async_stack_zeroing`] value.
5287    pub fn get_async_stack_zeroing(&self) -> bool {
5288        self.config().async_stack_zeroing
5289    }
5290
5291    /// Returns the configured [`Config::wasm_branch_hinting`] value.
5292    pub fn get_wasm_branch_hinting(&self) -> bool {
5293        self.tunables().branch_hinting
5294    }
5295
5296    /// Returns the configured [`Config::concurrency_support`] value.
5297    pub fn get_concurrency_support(&self) -> bool {
5298        self.tunables().concurrency_support
5299    }
5300
5301    /// Returns the configured [`Config::asan_compatible_code`] value.
5302    pub fn get_asan_compatible_code(&self) -> bool {
5303        self.tunables().asan_stack_switching
5304    }
5305
5306    /// Returns the configured [`Config::epoch_interruption`] value.
5307    pub fn get_epoch_interruption(&self) -> bool {
5308        self.tunables().epoch_interruption
5309    }
5310
5311    /// Returns the configured [`Config::mmu_interruption`] value.
5312    #[doc(hidden)]
5313    pub fn get_mmu_interruption(&self) -> bool {
5314        self.tunables().mmu_interruption
5315    }
5316
5317    /// Returns the configured [`Config::consume_fuel`] value.
5318    pub fn get_consume_fuel(&self) -> bool {
5319        self.tunables().consume_fuel
5320    }
5321
5322    /// Returns the configured [`Config::max_wasm_stack`] value.
5323    pub fn get_max_wasm_stack(&self) -> usize {
5324        self.config().max_wasm_stack
5325    }
5326
5327    /// Returns the configured [`Config::cranelift_nan_canonicalization`] value.
5328    pub fn get_cranelift_nan_canonicalization(&self) -> Option<bool> {
5329        #[cfg(any(feature = "cranelift", feature = "winch"))]
5330        if let Some(compiler) = self.compiler() {
5331            let flags = compiler.flags();
5332            let (_, FlagValue::Bool(b)) = flags
5333                .iter()
5334                .find(|(f, _)| *f == "enable_nan_canonicalization")?
5335            else {
5336                return None;
5337            };
5338            return Some(*b);
5339        }
5340        None
5341    }
5342
5343    /// Returns the configured [`Config::relaxed_simd_deterministic`] value.
5344    pub fn get_relaxed_simd_deterministic(&self) -> bool {
5345        self.tunables().relaxed_simd_deterministic
5346    }
5347
5348    /// Returns the configured [`Config::shared_memory`] value.
5349    pub fn get_shared_memory(&self) -> bool {
5350        self.config().shared_memory
5351    }
5352
5353    /// Returns the configured [`Config::generate_address_map`] value.
5354    pub fn get_generate_address_map(&self) -> bool {
5355        self.tunables().generate_address_map
5356    }
5357
5358    /// Returns the configured [`Config::debug_info`] value.
5359    pub fn get_debug_info(&self) -> bool {
5360        self.tunables().debug_native
5361    }
5362
5363    /// Returns the configured [`Config::guest_debug`] value.
5364    pub fn get_guest_debug(&self) -> bool {
5365        self.tunables().debug_guest
5366    }
5367
5368    /// Returns the configured [`Config::debug_symbols`] value.
5369    pub fn get_debug_symbols(&self) -> bool {
5370        self.tunables().debug_symbols
5371    }
5372
5373    /// Returns the configured [`Config::wasm_backtrace_max_frames`] value.
5374    pub fn get_wasm_backtrace_max_frames(&self) -> usize {
5375        self.config()
5376            .wasm_backtrace_max_frames
5377            .map(|f| f.get())
5378            .unwrap_or(0)
5379    }
5380
5381    /// Returns the configured [`Config::target`] value.
5382    pub fn get_target(&self) -> Option<String> {
5383        #[cfg(any(feature = "cranelift", feature = "winch"))]
5384        if let Some(compiler) = self.compiler() {
5385            return Some(compiler.triple().to_string());
5386        }
5387        None
5388    }
5389
5390    /// Returns the enabled flags via [`Config::cranelift_flag_enable`].
5391    pub fn get_cranelift_flags_enabled(&self) -> impl Iterator<Item = &str> {
5392        #[cfg(any(feature = "cranelift", feature = "winch"))]
5393        if let Some(config) = &self.config().compiler_config {
5394            return config
5395                .flags
5396                .iter()
5397                .filter_map(|(k, v)| match v {
5398                    UserSpecified::Yes => Some(k.as_str()),
5399                    UserSpecified::No => None,
5400                })
5401                .collect::<Vec<_>>()
5402                .into_iter();
5403        }
5404
5405        Vec::new().into_iter()
5406    }
5407
5408    /// Returns the enabled flags via [`Config::cranelift_flag_set`].
5409    pub fn get_cranelift_flags_set(&self) -> impl Iterator<Item = (&str, &str)> {
5410        #[cfg(any(feature = "cranelift", feature = "winch"))]
5411        if let Some(config) = &self.config().compiler_config {
5412            return config
5413                .settings
5414                .iter()
5415                .filter_map(|(k, (v, s))| match s {
5416                    UserSpecified::Yes => Some((k.as_str(), v.as_str())),
5417                    UserSpecified::No => None,
5418                })
5419                .collect::<Vec<_>>()
5420                .into_iter();
5421        }
5422
5423        Vec::new().into_iter()
5424    }
5425}