wasmtime/
config.rs

1use crate::prelude::*;
2use alloc::sync::Arc;
3use bitflags::Flags;
4use core::fmt;
5use core::str::FromStr;
6#[cfg(any(feature = "cache", feature = "cranelift", feature = "winch"))]
7use std::path::Path;
8use wasmparser::WasmFeatures;
9use wasmtime_environ::{ConfigTunables, TripleExt, Tunables};
10
11#[cfg(feature = "runtime")]
12use crate::memory::MemoryCreator;
13#[cfg(feature = "runtime")]
14use crate::profiling_agent::{self, ProfilingAgent};
15#[cfg(feature = "runtime")]
16use crate::runtime::vm::{
17    GcRuntime, InstanceAllocator, OnDemandInstanceAllocator, RuntimeMemoryCreator,
18};
19#[cfg(feature = "runtime")]
20use crate::trampoline::MemoryCreatorProxy;
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;
33
34/// Represents the module instance allocation strategy to use.
35#[derive(Clone)]
36#[non_exhaustive]
37pub enum InstanceAllocationStrategy {
38    /// The on-demand instance allocation strategy.
39    ///
40    /// Resources related to a module instance are allocated at instantiation time and
41    /// immediately deallocated when the `Store` referencing the instance is dropped.
42    ///
43    /// This is the default allocation strategy for Wasmtime.
44    OnDemand,
45    /// The pooling instance allocation strategy.
46    ///
47    /// A pool of resources is created in advance and module instantiation reuses resources
48    /// from the pool. Resources are returned to the pool when the `Store` referencing the instance
49    /// is dropped.
50    #[cfg(feature = "pooling-allocator")]
51    Pooling(PoolingAllocationConfig),
52}
53
54impl InstanceAllocationStrategy {
55    /// The default pooling instance allocation strategy.
56    #[cfg(feature = "pooling-allocator")]
57    pub fn pooling() -> Self {
58        Self::Pooling(Default::default())
59    }
60}
61
62impl Default for InstanceAllocationStrategy {
63    fn default() -> Self {
64        Self::OnDemand
65    }
66}
67
68#[cfg(feature = "pooling-allocator")]
69impl From<PoolingAllocationConfig> for InstanceAllocationStrategy {
70    fn from(cfg: PoolingAllocationConfig) -> InstanceAllocationStrategy {
71        InstanceAllocationStrategy::Pooling(cfg)
72    }
73}
74
75#[derive(Clone)]
76/// Configure the strategy used for versioning in serializing and deserializing [`crate::Module`].
77pub enum ModuleVersionStrategy {
78    /// Use the wasmtime crate's Cargo package version.
79    WasmtimeVersion,
80    /// Use a custom version string. Must be at most 255 bytes.
81    Custom(String),
82    /// Emit no version string in serialization, and accept all version strings in deserialization.
83    None,
84}
85
86impl Default for ModuleVersionStrategy {
87    fn default() -> Self {
88        ModuleVersionStrategy::WasmtimeVersion
89    }
90}
91
92impl core::hash::Hash for ModuleVersionStrategy {
93    fn hash<H: core::hash::Hasher>(&self, hasher: &mut H) {
94        match self {
95            Self::WasmtimeVersion => env!("CARGO_PKG_VERSION").hash(hasher),
96            Self::Custom(s) => s.hash(hasher),
97            Self::None => {}
98        };
99    }
100}
101
102/// Global configuration options used to create an [`Engine`](crate::Engine)
103/// and customize its behavior.
104///
105/// This structure exposed a builder-like interface and is primarily consumed by
106/// [`Engine::new()`](crate::Engine::new).
107///
108/// The validation of `Config` is deferred until the engine is being built, thus
109/// a problematic config may cause `Engine::new` to fail.
110///
111/// # Defaults
112///
113/// The `Default` trait implementation and the return value from
114/// [`Config::new()`] are the same and represent the default set of
115/// configuration for an engine. The exact set of defaults will differ based on
116/// properties such as enabled Cargo features at compile time and the configured
117/// target (see [`Config::target`]). Configuration options document their
118/// default values and what the conditional value of the default is where
119/// applicable.
120#[derive(Clone)]
121pub struct Config {
122    #[cfg(any(feature = "cranelift", feature = "winch"))]
123    compiler_config: CompilerConfig,
124    target: Option<target_lexicon::Triple>,
125    #[cfg(feature = "gc")]
126    collector: Collector,
127    profiling_strategy: ProfilingStrategy,
128    tunables: ConfigTunables,
129
130    #[cfg(feature = "cache")]
131    pub(crate) cache: Option<Cache>,
132    #[cfg(feature = "runtime")]
133    pub(crate) mem_creator: Option<Arc<dyn RuntimeMemoryCreator>>,
134    #[cfg(feature = "runtime")]
135    pub(crate) custom_code_memory: Option<Arc<dyn CustomCodeMemory>>,
136    pub(crate) allocation_strategy: InstanceAllocationStrategy,
137    pub(crate) max_wasm_stack: usize,
138    /// Explicitly enabled features via `Config::wasm_*` methods. This is a
139    /// signal that the embedder specifically wants something turned on
140    /// regardless of the defaults that Wasmtime might otherwise have enabled.
141    ///
142    /// Note that this, and `disabled_features` below, start as the empty set of
143    /// features to only track explicit user requests.
144    pub(crate) enabled_features: WasmFeatures,
145    /// Same as `enabled_features`, but for those that are explicitly disabled.
146    pub(crate) disabled_features: WasmFeatures,
147    pub(crate) wasm_backtrace: bool,
148    pub(crate) wasm_backtrace_details_env_used: bool,
149    pub(crate) native_unwind_info: Option<bool>,
150    #[cfg(any(feature = "async", feature = "stack-switching"))]
151    pub(crate) async_stack_size: usize,
152    #[cfg(feature = "async")]
153    pub(crate) async_stack_zeroing: bool,
154    #[cfg(feature = "async")]
155    pub(crate) stack_creator: Option<Arc<dyn RuntimeFiberStackCreator>>,
156    pub(crate) async_support: bool,
157    pub(crate) module_version: ModuleVersionStrategy,
158    pub(crate) parallel_compilation: bool,
159    pub(crate) memory_guaranteed_dense_image_size: u64,
160    pub(crate) force_memory_init_memfd: bool,
161    pub(crate) wmemcheck: bool,
162    #[cfg(feature = "coredump")]
163    pub(crate) coredump_on_trap: bool,
164    pub(crate) macos_use_mach_ports: bool,
165    pub(crate) detect_host_feature: Option<fn(&str) -> Option<bool>>,
166}
167
168/// User-provided configuration for the compiler.
169#[cfg(any(feature = "cranelift", feature = "winch"))]
170#[derive(Debug, Clone)]
171struct CompilerConfig {
172    strategy: Option<Strategy>,
173    settings: crate::hash_map::HashMap<String, String>,
174    flags: crate::hash_set::HashSet<String>,
175    #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
176    cache_store: Option<Arc<dyn CacheStore>>,
177    clif_dir: Option<std::path::PathBuf>,
178    wmemcheck: bool,
179}
180
181#[cfg(any(feature = "cranelift", feature = "winch"))]
182impl CompilerConfig {
183    fn new() -> Self {
184        Self {
185            strategy: Strategy::Auto.not_auto(),
186            settings: Default::default(),
187            flags: Default::default(),
188            #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
189            cache_store: None,
190            clif_dir: None,
191            wmemcheck: false,
192        }
193    }
194
195    /// Ensures that the key is not set or equals to the given value.
196    /// If the key is not set, it will be set to the given value.
197    ///
198    /// # Returns
199    ///
200    /// Returns true if successfully set or already had the given setting
201    /// value, or false if the setting was explicitly set to something
202    /// else previously.
203    fn ensure_setting_unset_or_given(&mut self, k: &str, v: &str) -> bool {
204        if let Some(value) = self.settings.get(k) {
205            if value != v {
206                return false;
207            }
208        } else {
209            self.settings.insert(k.to_string(), v.to_string());
210        }
211        true
212    }
213}
214
215#[cfg(any(feature = "cranelift", feature = "winch"))]
216impl Default for CompilerConfig {
217    fn default() -> Self {
218        Self::new()
219    }
220}
221
222impl Config {
223    /// Creates a new configuration object with the default configuration
224    /// specified.
225    pub fn new() -> Self {
226        let mut ret = Self {
227            tunables: ConfigTunables::default(),
228            #[cfg(any(feature = "cranelift", feature = "winch"))]
229            compiler_config: CompilerConfig::default(),
230            target: None,
231            #[cfg(feature = "gc")]
232            collector: Collector::default(),
233            #[cfg(feature = "cache")]
234            cache: None,
235            profiling_strategy: ProfilingStrategy::None,
236            #[cfg(feature = "runtime")]
237            mem_creator: None,
238            #[cfg(feature = "runtime")]
239            custom_code_memory: None,
240            allocation_strategy: InstanceAllocationStrategy::OnDemand,
241            // 512k of stack -- note that this is chosen currently to not be too
242            // big, not be too small, and be a good default for most platforms.
243            // One platform of particular note is Windows where the stack size
244            // of the main thread seems to, by default, be smaller than that of
245            // Linux and macOS. This 512k value at least lets our current test
246            // suite pass on the main thread of Windows (using `--test-threads
247            // 1` forces this), or at least it passed when this change was
248            // committed.
249            max_wasm_stack: 512 * 1024,
250            wasm_backtrace: true,
251            wasm_backtrace_details_env_used: false,
252            native_unwind_info: None,
253            enabled_features: WasmFeatures::empty(),
254            disabled_features: WasmFeatures::empty(),
255            #[cfg(any(feature = "async", feature = "stack-switching"))]
256            async_stack_size: 2 << 20,
257            #[cfg(feature = "async")]
258            async_stack_zeroing: false,
259            #[cfg(feature = "async")]
260            stack_creator: None,
261            async_support: false,
262            module_version: ModuleVersionStrategy::default(),
263            parallel_compilation: !cfg!(miri),
264            memory_guaranteed_dense_image_size: 16 << 20,
265            force_memory_init_memfd: false,
266            wmemcheck: false,
267            #[cfg(feature = "coredump")]
268            coredump_on_trap: false,
269            macos_use_mach_ports: !cfg!(miri),
270            #[cfg(feature = "std")]
271            detect_host_feature: Some(detect_host_feature),
272            #[cfg(not(feature = "std"))]
273            detect_host_feature: None,
274        };
275        #[cfg(any(feature = "cranelift", feature = "winch"))]
276        {
277            ret.cranelift_debug_verifier(false);
278            ret.cranelift_opt_level(OptLevel::Speed);
279
280            // When running under MIRI try to optimize for compile time of wasm
281            // code itself as much as possible. Disable optimizations by
282            // default.
283            if cfg!(miri) {
284                ret.cranelift_opt_level(OptLevel::None);
285            }
286        }
287
288        ret.wasm_backtrace_details(WasmBacktraceDetails::Environment);
289
290        ret
291    }
292
293    /// Configures the target platform of this [`Config`].
294    ///
295    /// This method is used to configure the output of compilation in an
296    /// [`Engine`](crate::Engine). This can be used, for example, to
297    /// cross-compile from one platform to another. By default, the host target
298    /// triple is used meaning compiled code is suitable to run on the host.
299    ///
300    /// Note that the [`Module`](crate::Module) type can only be created if the
301    /// target configured here matches the host. Otherwise if a cross-compile is
302    /// being performed where the host doesn't match the target then
303    /// [`Engine::precompile_module`](crate::Engine::precompile_module) must be
304    /// used instead.
305    ///
306    /// Target-specific flags (such as CPU features) will not be inferred by
307    /// default for the target when one is provided here. This means that this
308    /// can also be used, for example, with the host architecture to disable all
309    /// host-inferred feature flags. Configuring target-specific flags can be
310    /// done with [`Config::cranelift_flag_set`] and
311    /// [`Config::cranelift_flag_enable`].
312    ///
313    /// # Errors
314    ///
315    /// This method will error if the given target triple is not supported.
316    pub fn target(&mut self, target: &str) -> Result<&mut Self> {
317        self.target =
318            Some(target_lexicon::Triple::from_str(target).map_err(|e| anyhow::anyhow!(e))?);
319
320        Ok(self)
321    }
322
323    /// Enables the incremental compilation cache in Cranelift, using the provided `CacheStore`
324    /// backend for storage.
325    #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
326    pub fn enable_incremental_compilation(
327        &mut self,
328        cache_store: Arc<dyn CacheStore>,
329    ) -> Result<&mut Self> {
330        self.compiler_config.cache_store = Some(cache_store);
331        Ok(self)
332    }
333
334    /// Whether or not to enable support for asynchronous functions in Wasmtime.
335    ///
336    /// When enabled, the config can optionally define host functions with `async`.
337    /// Instances created and functions called with this `Config` *must* be called
338    /// through their asynchronous APIs, however. For example using
339    /// [`Func::call`](crate::Func::call) will panic when used with this config.
340    ///
341    /// # Asynchronous Wasm
342    ///
343    /// WebAssembly does not currently have a way to specify at the bytecode
344    /// level what is and isn't async. Host-defined functions, however, may be
345    /// defined as `async`. WebAssembly imports always appear synchronous, which
346    /// gives rise to a bit of an impedance mismatch here. To solve this
347    /// Wasmtime supports "asynchronous configs" which enables calling these
348    /// asynchronous functions in a way that looks synchronous to the executing
349    /// WebAssembly code.
350    ///
351    /// An asynchronous config must always invoke wasm code asynchronously,
352    /// meaning we'll always represent its computation as a
353    /// [`Future`](std::future::Future). The `poll` method of the futures
354    /// returned by Wasmtime will perform the actual work of calling the
355    /// WebAssembly. Wasmtime won't manage its own thread pools or similar,
356    /// that's left up to the embedder.
357    ///
358    /// To implement futures in a way that WebAssembly sees asynchronous host
359    /// functions as synchronous, all async Wasmtime futures will execute on a
360    /// separately allocated native stack from the thread otherwise executing
361    /// Wasmtime. This separate native stack can then be switched to and from.
362    /// Using this whenever an `async` host function returns a future that
363    /// resolves to `Pending` we switch away from the temporary stack back to
364    /// the main stack and propagate the `Pending` status.
365    ///
366    /// In general it's encouraged that the integration with `async` and
367    /// wasmtime is designed early on in your embedding of Wasmtime to ensure
368    /// that it's planned that WebAssembly executes in the right context of your
369    /// application.
370    ///
371    /// # Execution in `poll`
372    ///
373    /// The [`Future::poll`](std::future::Future::poll) method is the main
374    /// driving force behind Rust's futures. That method's own documentation
375    /// states "an implementation of `poll` should strive to return quickly, and
376    /// should not block". This, however, can be at odds with executing
377    /// WebAssembly code as part of the `poll` method itself. If your
378    /// WebAssembly is untrusted then this could allow the `poll` method to take
379    /// arbitrarily long in the worst case, likely blocking all other
380    /// asynchronous tasks.
381    ///
382    /// To remedy this situation you have a few possible ways to solve this:
383    ///
384    /// * The most efficient solution is to enable
385    ///   [`Config::epoch_interruption`] in conjunction with
386    ///   [`crate::Store::epoch_deadline_async_yield_and_update`]. Coupled with
387    ///   periodic calls to [`crate::Engine::increment_epoch`] this will cause
388    ///   executing WebAssembly to periodically yield back according to the
389    ///   epoch configuration settings. This enables `Future::poll` to take at
390    ///   most a certain amount of time according to epoch configuration
391    ///   settings and when increments happen. The benefit of this approach is
392    ///   that the instrumentation in compiled code is quite lightweight, but a
393    ///   downside can be that the scheduling is somewhat nondeterministic since
394    ///   increments are usually timer-based which are not always deterministic.
395    ///
396    ///   Note that to prevent infinite execution of wasm it's recommended to
397    ///   place a timeout on the entire future representing executing wasm code
398    ///   and the periodic yields with epochs should ensure that when the
399    ///   timeout is reached it's appropriately recognized.
400    ///
401    /// * Alternatively you can enable the
402    ///   [`Config::consume_fuel`](crate::Config::consume_fuel) method as well
403    ///   as [`crate::Store::fuel_async_yield_interval`] When doing so this will
404    ///   configure Wasmtime futures to yield periodically while they're
405    ///   executing WebAssembly code. After consuming the specified amount of
406    ///   fuel wasm futures will return `Poll::Pending` from their `poll`
407    ///   method, and will get automatically re-polled later. This enables the
408    ///   `Future::poll` method to take roughly a fixed amount of time since
409    ///   fuel is guaranteed to get consumed while wasm is executing. Unlike
410    ///   epoch-based preemption this is deterministic since wasm always
411    ///   consumes a fixed amount of fuel per-operation. The downside of this
412    ///   approach, however, is that the compiled code instrumentation is
413    ///   significantly more expensive than epoch checks.
414    ///
415    ///   Note that to prevent infinite execution of wasm it's recommended to
416    ///   place a timeout on the entire future representing executing wasm code
417    ///   and the periodic yields with epochs should ensure that when the
418    ///   timeout is reached it's appropriately recognized.
419    ///
420    /// In all cases special care needs to be taken when integrating
421    /// asynchronous wasm into your application. You should carefully plan where
422    /// WebAssembly will execute and what compute resources will be allotted to
423    /// it. If Wasmtime doesn't support exactly what you'd like just yet, please
424    /// feel free to open an issue!
425    #[cfg(feature = "async")]
426    pub fn async_support(&mut self, enable: bool) -> &mut Self {
427        self.async_support = enable;
428        self
429    }
430
431    /// Configures whether DWARF debug information will be emitted during
432    /// compilation.
433    ///
434    /// Note that the `debug-builtins` compile-time Cargo feature must also be
435    /// enabled for native debuggers such as GDB or LLDB to be able to debug
436    /// guest WebAssembly programs.
437    ///
438    /// By default this option is `false`.
439    /// **Note** Enabling this option is not compatible with the Winch compiler.
440    pub fn debug_info(&mut self, enable: bool) -> &mut Self {
441        self.tunables.generate_native_debuginfo = Some(enable);
442        self
443    }
444
445    /// Configures whether [`WasmBacktrace`] will be present in the context of
446    /// errors returned from Wasmtime.
447    ///
448    /// A backtrace may be collected whenever an error is returned from a host
449    /// function call through to WebAssembly or when WebAssembly itself hits a
450    /// trap condition, such as an out-of-bounds memory access. This flag
451    /// indicates, in these conditions, whether the backtrace is collected or
452    /// not.
453    ///
454    /// Currently wasm backtraces are implemented through frame pointer walking.
455    /// This means that collecting a backtrace is expected to be a fast and
456    /// relatively cheap operation. Additionally backtrace collection is
457    /// suitable in concurrent environments since one thread capturing a
458    /// backtrace won't block other threads.
459    ///
460    /// Collected backtraces are attached via [`anyhow::Error::context`] to
461    /// errors returned from host functions. The [`WasmBacktrace`] type can be
462    /// acquired via [`anyhow::Error::downcast_ref`] to inspect the backtrace.
463    /// When this option is disabled then this context is never applied to
464    /// errors coming out of wasm.
465    ///
466    /// This option is `true` by default.
467    ///
468    /// [`WasmBacktrace`]: crate::WasmBacktrace
469    pub fn wasm_backtrace(&mut self, enable: bool) -> &mut Self {
470        self.wasm_backtrace = enable;
471        self
472    }
473
474    /// Configures whether backtraces in `Trap` will parse debug info in the wasm file to
475    /// have filename/line number information.
476    ///
477    /// When enabled this will causes modules to retain debugging information
478    /// found in wasm binaries. This debug information will be used when a trap
479    /// happens to symbolicate each stack frame and attempt to print a
480    /// filename/line number for each wasm frame in the stack trace.
481    ///
482    /// By default this option is `WasmBacktraceDetails::Environment`, meaning
483    /// that wasm will read `WASMTIME_BACKTRACE_DETAILS` to indicate whether
484    /// details should be parsed. Note that the `std` feature of this crate must
485    /// be active to read environment variables, otherwise this is disabled by
486    /// default.
487    pub fn wasm_backtrace_details(&mut self, enable: WasmBacktraceDetails) -> &mut Self {
488        self.wasm_backtrace_details_env_used = false;
489        self.tunables.parse_wasm_debuginfo = match enable {
490            WasmBacktraceDetails::Enable => Some(true),
491            WasmBacktraceDetails::Disable => Some(false),
492            WasmBacktraceDetails::Environment => {
493                #[cfg(feature = "std")]
494                {
495                    self.wasm_backtrace_details_env_used = true;
496                    std::env::var("WASMTIME_BACKTRACE_DETAILS")
497                        .map(|s| Some(s == "1"))
498                        .unwrap_or(Some(false))
499                }
500                #[cfg(not(feature = "std"))]
501                {
502                    Some(false)
503                }
504            }
505        };
506        self
507    }
508
509    /// Configures whether to generate native unwind information
510    /// (e.g. `.eh_frame` on Linux).
511    ///
512    /// This configuration option only exists to help third-party stack
513    /// capturing mechanisms, such as the system's unwinder or the `backtrace`
514    /// crate, determine how to unwind through Wasm frames. It does not affect
515    /// whether Wasmtime can capture Wasm backtraces or not. The presence of
516    /// [`WasmBacktrace`] is controlled by the [`Config::wasm_backtrace`]
517    /// option.
518    ///
519    /// Native unwind information is included:
520    /// - When targeting Windows, since the Windows ABI requires it.
521    /// - By default.
522    ///
523    /// Note that systems loading many modules may wish to disable this
524    /// configuration option instead of leaving it on-by-default. Some platforms
525    /// exhibit quadratic behavior when registering/unregistering unwinding
526    /// information which can greatly slow down the module loading/unloading
527    /// process.
528    ///
529    /// [`WasmBacktrace`]: crate::WasmBacktrace
530    pub fn native_unwind_info(&mut self, enable: bool) -> &mut Self {
531        self.native_unwind_info = Some(enable);
532        self
533    }
534
535    /// Configures whether execution of WebAssembly will "consume fuel" to
536    /// either halt or yield execution as desired.
537    ///
538    /// This can be used to deterministically prevent infinitely-executing
539    /// WebAssembly code by instrumenting generated code to consume fuel as it
540    /// executes. When fuel runs out a trap is raised, however [`Store`] can be
541    /// configured to yield execution periodically via
542    /// [`crate::Store::fuel_async_yield_interval`].
543    ///
544    /// Note that a [`Store`] starts with no fuel, so if you enable this option
545    /// you'll have to be sure to pour some fuel into [`Store`] before
546    /// executing some code.
547    ///
548    /// By default this option is `false`.
549    ///
550    /// **Note** Enabling this option is not compatible with the Winch compiler.
551    ///
552    /// [`Store`]: crate::Store
553    pub fn consume_fuel(&mut self, enable: bool) -> &mut Self {
554        self.tunables.consume_fuel = Some(enable);
555        self
556    }
557
558    /// Enables epoch-based interruption.
559    ///
560    /// When executing code in async mode, we sometimes want to
561    /// implement a form of cooperative timeslicing: long-running Wasm
562    /// guest code should periodically yield to the executor
563    /// loop. This yielding could be implemented by using "fuel" (see
564    /// [`consume_fuel`](Config::consume_fuel)). However, fuel
565    /// instrumentation is somewhat expensive: it modifies the
566    /// compiled form of the Wasm code so that it maintains a precise
567    /// instruction count, frequently checking this count against the
568    /// remaining fuel. If one does not need this precise count or
569    /// deterministic interruptions, and only needs a periodic
570    /// interrupt of some form, then It would be better to have a more
571    /// lightweight mechanism.
572    ///
573    /// Epoch-based interruption is that mechanism. There is a global
574    /// "epoch", which is a counter that divides time into arbitrary
575    /// periods (or epochs). This counter lives on the
576    /// [`Engine`](crate::Engine) and can be incremented by calling
577    /// [`Engine::increment_epoch`](crate::Engine::increment_epoch).
578    /// Epoch-based instrumentation works by setting a "deadline
579    /// epoch". The compiled code knows the deadline, and at certain
580    /// points, checks the current epoch against that deadline. It
581    /// will yield if the deadline has been reached.
582    ///
583    /// The idea is that checking an infrequently-changing counter is
584    /// cheaper than counting and frequently storing a precise metric
585    /// (instructions executed) locally. The interruptions are not
586    /// deterministic, but if the embedder increments the epoch in a
587    /// periodic way (say, every regular timer tick by a thread or
588    /// signal handler), then we can ensure that all async code will
589    /// yield to the executor within a bounded time.
590    ///
591    /// The deadline check cannot be avoided by malicious wasm code. It is safe
592    /// to use epoch deadlines to limit the execution time of untrusted
593    /// code.
594    ///
595    /// The [`Store`](crate::Store) tracks the deadline, and controls
596    /// what happens when the deadline is reached during
597    /// execution. Several behaviors are possible:
598    ///
599    /// - Trap if code is executing when the epoch deadline is
600    ///   met. See
601    ///   [`Store::epoch_deadline_trap`](crate::Store::epoch_deadline_trap).
602    ///
603    /// - Call an arbitrary function. This function may chose to trap or
604    ///   increment the epoch. See
605    ///   [`Store::epoch_deadline_callback`](crate::Store::epoch_deadline_callback).
606    ///
607    /// - Yield to the executor loop, then resume when the future is
608    ///   next polled. See
609    ///   [`Store::epoch_deadline_async_yield_and_update`](crate::Store::epoch_deadline_async_yield_and_update).
610    ///
611    /// Trapping is the default. The yielding behaviour may be used for
612    /// the timeslicing behavior described above.
613    ///
614    /// This feature is available with or without async support.
615    /// However, without async support, the timeslicing behaviour is
616    /// not available. This means epoch-based interruption can only
617    /// serve as a simple external-interruption mechanism.
618    ///
619    /// An initial deadline must be set before executing code by calling
620    /// [`Store::set_epoch_deadline`](crate::Store::set_epoch_deadline). If this
621    /// deadline is not configured then wasm will immediately trap.
622    ///
623    /// ## Interaction with blocking host calls
624    ///
625    /// Epochs (and fuel) do not assist in handling WebAssembly code blocked in
626    /// a call to the host. For example if the WebAssembly function calls
627    /// `wasi:io/poll/poll` to sleep epochs will not assist in waking this up or
628    /// timing it out. Epochs intentionally only affect running WebAssembly code
629    /// itself and it's left to the embedder to determine how best to wake up
630    /// indefinitely blocking code in the host.
631    ///
632    /// The typical solution for this, however, is to use
633    /// [`Config::async_support(true)`](Config::async_support) and the `async`
634    /// variant of WASI host functions. This models computation as a Rust
635    /// `Future` which means that when blocking happens the future is only
636    /// suspended and control yields back to the main event loop. This gives the
637    /// embedder the opportunity to use `tokio::time::timeout` for example on a
638    /// wasm computation and have the desired effect of cancelling a blocking
639    /// operation when a timeout expires.
640    ///
641    /// ## When to use fuel vs. epochs
642    ///
643    /// In general, epoch-based interruption results in faster
644    /// execution. This difference is sometimes significant: in some
645    /// measurements, up to 2-3x. This is because epoch-based
646    /// interruption does less work: it only watches for a global
647    /// rarely-changing counter to increment, rather than keeping a
648    /// local frequently-changing counter and comparing it to a
649    /// deadline.
650    ///
651    /// Fuel, in contrast, should be used when *deterministic*
652    /// yielding or trapping is needed. For example, if it is required
653    /// that the same function call with the same starting state will
654    /// always either complete or trap with an out-of-fuel error,
655    /// deterministically, then fuel with a fixed bound should be
656    /// used.
657    ///
658    /// **Note** Enabling this option is not compatible with the Winch compiler.
659    ///
660    /// # See Also
661    ///
662    /// - [`Engine::increment_epoch`](crate::Engine::increment_epoch)
663    /// - [`Store::set_epoch_deadline`](crate::Store::set_epoch_deadline)
664    /// - [`Store::epoch_deadline_trap`](crate::Store::epoch_deadline_trap)
665    /// - [`Store::epoch_deadline_callback`](crate::Store::epoch_deadline_callback)
666    /// - [`Store::epoch_deadline_async_yield_and_update`](crate::Store::epoch_deadline_async_yield_and_update)
667    pub fn epoch_interruption(&mut self, enable: bool) -> &mut Self {
668        self.tunables.epoch_interruption = Some(enable);
669        self
670    }
671
672    /// Configures the maximum amount of stack space available for
673    /// executing WebAssembly code.
674    ///
675    /// WebAssembly has well-defined semantics on stack overflow. This is
676    /// intended to be a knob which can help configure how much stack space
677    /// wasm execution is allowed to consume. Note that the number here is not
678    /// super-precise, but rather wasm will take at most "pretty close to this
679    /// much" stack space.
680    ///
681    /// If a wasm call (or series of nested wasm calls) take more stack space
682    /// than the `size` specified then a stack overflow trap will be raised.
683    ///
684    /// Caveat: this knob only limits the stack space consumed by wasm code.
685    /// More importantly, it does not ensure that this much stack space is
686    /// available on the calling thread stack. Exhausting the thread stack
687    /// typically leads to an **abort** of the process.
688    ///
689    /// Here are some examples of how that could happen:
690    ///
691    /// - Let's assume this option is set to 2 MiB and then a thread that has
692    ///   a stack with 512 KiB left.
693    ///
694    ///   If wasm code consumes more than 512 KiB then the process will be aborted.
695    ///
696    /// - Assuming the same conditions, but this time wasm code does not consume
697    ///   any stack but calls into a host function. The host function consumes
698    ///   more than 512 KiB of stack space. The process will be aborted.
699    ///
700    /// There's another gotcha related to recursive calling into wasm: the stack
701    /// space consumed by a host function is counted towards this limit. The
702    /// host functions are not prevented from consuming more than this limit.
703    /// However, if the host function that used more than this limit and called
704    /// back into wasm, then the execution will trap immediately because of
705    /// stack overflow.
706    ///
707    /// When the `async` feature is enabled, this value cannot exceed the
708    /// `async_stack_size` option. Be careful not to set this value too close
709    /// to `async_stack_size` as doing so may limit how much stack space
710    /// is available for host functions.
711    ///
712    /// By default this option is 512 KiB.
713    ///
714    /// # Errors
715    ///
716    /// The `Engine::new` method will fail if the `size` specified here is
717    /// either 0 or larger than the [`Config::async_stack_size`] configuration.
718    pub fn max_wasm_stack(&mut self, size: usize) -> &mut Self {
719        self.max_wasm_stack = size;
720        self
721    }
722
723    /// Configures the size of the stacks used for asynchronous execution.
724    ///
725    /// This setting configures the size of the stacks that are allocated for
726    /// asynchronous execution. The value cannot be less than `max_wasm_stack`.
727    ///
728    /// The amount of stack space guaranteed for host functions is
729    /// `async_stack_size - max_wasm_stack`, so take care not to set these two values
730    /// close to one another; doing so may cause host functions to overflow the
731    /// stack and abort the process.
732    ///
733    /// By default this option is 2 MiB.
734    ///
735    /// # Errors
736    ///
737    /// The `Engine::new` method will fail if the value for this option is
738    /// smaller than the [`Config::max_wasm_stack`] option.
739    #[cfg(any(feature = "async", feature = "stack-switching"))]
740    pub fn async_stack_size(&mut self, size: usize) -> &mut Self {
741        self.async_stack_size = size;
742        self
743    }
744
745    /// Configures whether or not stacks used for async futures are zeroed
746    /// before (re)use.
747    ///
748    /// When the [`async_support`](Config::async_support) method is enabled for
749    /// Wasmtime and the [`call_async`] variant of calling WebAssembly is used
750    /// then Wasmtime will create a separate runtime execution stack for each
751    /// future produced by [`call_async`]. By default upon allocation, depending
752    /// on the platform, these stacks might be filled with uninitialized
753    /// memory. This is safe and correct because, modulo bugs in Wasmtime,
754    /// compiled Wasm code will never read from a stack slot before it
755    /// initializes the stack slot.
756    ///
757    /// However, as a defense-in-depth mechanism, you may configure Wasmtime to
758    /// ensure that these stacks are zeroed before they are used. Notably, if
759    /// you are using the pooling allocator, stacks can be pooled and reused
760    /// across different Wasm guests; ensuring that stacks are zeroed can
761    /// prevent data leakage between Wasm guests even in the face of potential
762    /// read-of-stack-slot-before-initialization bugs in Wasmtime's compiler.
763    ///
764    /// Stack zeroing can be a costly operation in highly concurrent
765    /// environments due to modifications of the virtual address space requiring
766    /// process-wide synchronization. It can also be costly in `no-std`
767    /// environments that must manually zero memory, and cannot rely on an OS
768    /// and virtual memory to provide zeroed pages.
769    ///
770    /// This option defaults to `false`.
771    ///
772    /// [`call_async`]: crate::TypedFunc::call_async
773    #[cfg(feature = "async")]
774    pub fn async_stack_zeroing(&mut self, enable: bool) -> &mut Self {
775        self.async_stack_zeroing = enable;
776        self
777    }
778
779    fn wasm_feature(&mut self, flag: WasmFeatures, enable: bool) -> &mut Self {
780        self.enabled_features.set(flag, enable);
781        self.disabled_features.set(flag, !enable);
782        self
783    }
784
785    /// Configures whether the WebAssembly tail calls proposal will be enabled
786    /// for compilation or not.
787    ///
788    /// The [WebAssembly tail calls proposal] introduces the `return_call` and
789    /// `return_call_indirect` instructions. These instructions allow for Wasm
790    /// programs to implement some recursive algorithms with *O(1)* stack space
791    /// usage.
792    ///
793    /// This is `true` by default except when the Winch compiler is enabled.
794    ///
795    /// [WebAssembly tail calls proposal]: https://github.com/WebAssembly/tail-call
796    pub fn wasm_tail_call(&mut self, enable: bool) -> &mut Self {
797        self.wasm_feature(WasmFeatures::TAIL_CALL, enable);
798        self
799    }
800
801    /// Configures whether the WebAssembly custom-page-sizes proposal will be
802    /// enabled for compilation or not.
803    ///
804    /// The [WebAssembly custom-page-sizes proposal] allows a memory to
805    /// customize its page sizes. By default, Wasm page sizes are 64KiB
806    /// large. This proposal allows the memory to opt into smaller page sizes
807    /// instead, allowing Wasm to run in environments with less than 64KiB RAM
808    /// available, for example.
809    ///
810    /// Note that the page size is part of the memory's type, and because
811    /// different memories may have different types, they may also have
812    /// different page sizes.
813    ///
814    /// Currently the only valid page sizes are 64KiB (the default) and 1
815    /// byte. Future extensions may relax this constraint and allow all powers
816    /// of two.
817    ///
818    /// Support for this proposal is disabled by default.
819    ///
820    /// [WebAssembly custom-page-sizes proposal]: https://github.com/WebAssembly/custom-page-sizes
821    pub fn wasm_custom_page_sizes(&mut self, enable: bool) -> &mut Self {
822        self.wasm_feature(WasmFeatures::CUSTOM_PAGE_SIZES, enable);
823        self
824    }
825
826    /// Configures whether the WebAssembly [threads] proposal will be enabled
827    /// for compilation.
828    ///
829    /// This feature gates items such as shared memories and atomic
830    /// instructions. Note that the threads feature depends on the bulk memory
831    /// feature, which is enabled by default. Additionally note that while the
832    /// wasm feature is called "threads" it does not actually include the
833    /// ability to spawn threads. Spawning threads is part of the [wasi-threads]
834    /// proposal which is a separately gated feature in Wasmtime.
835    ///
836    /// Embeddings of Wasmtime are able to build their own custom threading
837    /// scheme on top of the core wasm threads proposal, however.
838    ///
839    /// The default value for this option is whether the `threads`
840    /// crate feature of Wasmtime is enabled or not. By default this crate
841    /// feature is enabled.
842    ///
843    /// [threads]: https://github.com/webassembly/threads
844    /// [wasi-threads]: https://github.com/webassembly/wasi-threads
845    #[cfg(feature = "threads")]
846    pub fn wasm_threads(&mut self, enable: bool) -> &mut Self {
847        self.wasm_feature(WasmFeatures::THREADS, enable);
848        self
849    }
850
851    /// Configures whether the WebAssembly [shared-everything-threads] proposal
852    /// will be enabled for compilation.
853    ///
854    /// This feature gates extended use of the `shared` attribute on items other
855    /// than memories, extra atomic instructions, and new component model
856    /// intrinsics for spawning threads. It depends on the
857    /// [`wasm_threads`][Self::wasm_threads] being enabled.
858    ///
859    /// [shared-everything-threads]:
860    ///     https://github.com/webassembly/shared-everything-threads
861    pub fn wasm_shared_everything_threads(&mut self, enable: bool) -> &mut Self {
862        self.wasm_feature(WasmFeatures::SHARED_EVERYTHING_THREADS, enable);
863        self
864    }
865
866    /// Configures whether the [WebAssembly reference types proposal][proposal]
867    /// will be enabled for compilation.
868    ///
869    /// This feature gates items such as the `externref` and `funcref` types as
870    /// well as allowing a module to define multiple tables.
871    ///
872    /// Note that the reference types proposal depends on the bulk memory proposal.
873    ///
874    /// This feature is `true` by default.
875    ///
876    /// # Errors
877    ///
878    /// The validation of this feature are deferred until the engine is being built,
879    /// and thus may cause `Engine::new` fail if the `bulk_memory` feature is disabled.
880    ///
881    /// [proposal]: https://github.com/webassembly/reference-types
882    #[cfg(feature = "gc")]
883    pub fn wasm_reference_types(&mut self, enable: bool) -> &mut Self {
884        self.wasm_feature(WasmFeatures::REFERENCE_TYPES, enable);
885        self
886    }
887
888    /// Configures whether the [WebAssembly function references
889    /// proposal][proposal] will be enabled for compilation.
890    ///
891    /// This feature gates non-nullable reference types, function reference
892    /// types, `call_ref`, `ref.func`, and non-nullable reference related
893    /// instructions.
894    ///
895    /// Note that the function references proposal depends on the reference
896    /// types proposal.
897    ///
898    /// This feature is `false` by default.
899    ///
900    /// [proposal]: https://github.com/WebAssembly/function-references
901    #[cfg(feature = "gc")]
902    pub fn wasm_function_references(&mut self, enable: bool) -> &mut Self {
903        self.wasm_feature(WasmFeatures::FUNCTION_REFERENCES, enable);
904        self
905    }
906
907    /// Configures whether the [WebAssembly wide-arithmetic][proposal] will be
908    /// enabled for compilation.
909    ///
910    /// This feature is `false` by default.
911    ///
912    /// [proposal]: https://github.com/WebAssembly/wide-arithmetic
913    pub fn wasm_wide_arithmetic(&mut self, enable: bool) -> &mut Self {
914        self.wasm_feature(WasmFeatures::WIDE_ARITHMETIC, enable);
915        self
916    }
917
918    /// Configures whether the [WebAssembly Garbage Collection
919    /// proposal][proposal] will be enabled for compilation.
920    ///
921    /// This feature gates `struct` and `array` type definitions and references,
922    /// the `i31ref` type, and all related instructions.
923    ///
924    /// Note that the function references proposal depends on the typed function
925    /// references proposal.
926    ///
927    /// This feature is `false` by default.
928    ///
929    /// **Warning: Wasmtime's implementation of the GC proposal is still in
930    /// progress and generally not ready for primetime.**
931    ///
932    /// [proposal]: https://github.com/WebAssembly/gc
933    #[cfg(feature = "gc")]
934    pub fn wasm_gc(&mut self, enable: bool) -> &mut Self {
935        self.wasm_feature(WasmFeatures::GC, enable);
936        self
937    }
938
939    /// Configures whether the WebAssembly SIMD proposal will be
940    /// enabled for compilation.
941    ///
942    /// The [WebAssembly SIMD proposal][proposal]. This feature gates items such
943    /// as the `v128` type and all of its operators being in a module. Note that
944    /// this does not enable the [relaxed simd proposal].
945    ///
946    /// **Note**
947    ///
948    /// On x86_64 platforms the base CPU feature requirement for SIMD
949    /// is SSE2 for the Cranelift compiler and AVX for the Winch compiler.
950    ///
951    /// This is `true` by default.
952    ///
953    /// [proposal]: https://github.com/webassembly/simd
954    /// [relaxed simd proposal]: https://github.com/WebAssembly/relaxed-simd
955    pub fn wasm_simd(&mut self, enable: bool) -> &mut Self {
956        self.wasm_feature(WasmFeatures::SIMD, enable);
957        self
958    }
959
960    /// Configures whether the WebAssembly Relaxed SIMD proposal will be
961    /// enabled for compilation.
962    ///
963    /// The relaxed SIMD proposal adds new instructions to WebAssembly which,
964    /// for some specific inputs, are allowed to produce different results on
965    /// different hosts. More-or-less this proposal enables exposing
966    /// platform-specific semantics of SIMD instructions in a controlled
967    /// fashion to a WebAssembly program. From an embedder's perspective this
968    /// means that WebAssembly programs may execute differently depending on
969    /// whether the host is x86_64 or AArch64, for example.
970    ///
971    /// By default Wasmtime lowers relaxed SIMD instructions to the fastest
972    /// lowering for the platform it's running on. This means that, by default,
973    /// some relaxed SIMD instructions may have different results for the same
974    /// inputs across x86_64 and AArch64. This behavior can be disabled through
975    /// the [`Config::relaxed_simd_deterministic`] option which will force
976    /// deterministic behavior across all platforms, as classified by the
977    /// specification, at the cost of performance.
978    ///
979    /// This is `true` by default.
980    ///
981    /// [proposal]: https://github.com/webassembly/relaxed-simd
982    pub fn wasm_relaxed_simd(&mut self, enable: bool) -> &mut Self {
983        self.wasm_feature(WasmFeatures::RELAXED_SIMD, enable);
984        self
985    }
986
987    /// This option can be used to control the behavior of the [relaxed SIMD
988    /// proposal's][proposal] instructions.
989    ///
990    /// The relaxed SIMD proposal introduces instructions that are allowed to
991    /// have different behavior on different architectures, primarily to afford
992    /// an efficient implementation on all architectures. This means, however,
993    /// that the same module may execute differently on one host than another,
994    /// which typically is not otherwise the case. This option is provided to
995    /// force Wasmtime to generate deterministic code for all relaxed simd
996    /// instructions, at the cost of performance, for all architectures. When
997    /// this option is enabled then the deterministic behavior of all
998    /// instructions in the relaxed SIMD proposal is selected.
999    ///
1000    /// This is `false` by default.
1001    ///
1002    /// [proposal]: https://github.com/webassembly/relaxed-simd
1003    pub fn relaxed_simd_deterministic(&mut self, enable: bool) -> &mut Self {
1004        self.tunables.relaxed_simd_deterministic = Some(enable);
1005        self
1006    }
1007
1008    /// Configures whether the [WebAssembly bulk memory operations
1009    /// proposal][proposal] will be enabled for compilation.
1010    ///
1011    /// This feature gates items such as the `memory.copy` instruction, passive
1012    /// data/table segments, etc, being in a module.
1013    ///
1014    /// This is `true` by default.
1015    ///
1016    /// Feature `reference_types`, which is also `true` by default, requires
1017    /// this feature to be enabled. Thus disabling this feature must also disable
1018    /// `reference_types` as well using [`wasm_reference_types`](crate::Config::wasm_reference_types).
1019    ///
1020    /// # Errors
1021    ///
1022    /// Disabling this feature without disabling `reference_types` will cause
1023    /// `Engine::new` to fail.
1024    ///
1025    /// [proposal]: https://github.com/webassembly/bulk-memory-operations
1026    pub fn wasm_bulk_memory(&mut self, enable: bool) -> &mut Self {
1027        self.wasm_feature(WasmFeatures::BULK_MEMORY, enable);
1028        self
1029    }
1030
1031    /// Configures whether the WebAssembly multi-value [proposal] will
1032    /// be enabled for compilation.
1033    ///
1034    /// This feature gates functions and blocks returning multiple values in a
1035    /// module, for example.
1036    ///
1037    /// This is `true` by default.
1038    ///
1039    /// [proposal]: https://github.com/webassembly/multi-value
1040    pub fn wasm_multi_value(&mut self, enable: bool) -> &mut Self {
1041        self.wasm_feature(WasmFeatures::MULTI_VALUE, enable);
1042        self
1043    }
1044
1045    /// Configures whether the WebAssembly multi-memory [proposal] will
1046    /// be enabled for compilation.
1047    ///
1048    /// This feature gates modules having more than one linear memory
1049    /// declaration or import.
1050    ///
1051    /// This is `true` by default.
1052    ///
1053    /// [proposal]: https://github.com/webassembly/multi-memory
1054    pub fn wasm_multi_memory(&mut self, enable: bool) -> &mut Self {
1055        self.wasm_feature(WasmFeatures::MULTI_MEMORY, enable);
1056        self
1057    }
1058
1059    /// Configures whether the WebAssembly memory64 [proposal] will
1060    /// be enabled for compilation.
1061    ///
1062    /// Note that this the upstream specification is not finalized and Wasmtime
1063    /// may also have bugs for this feature since it hasn't been exercised
1064    /// much.
1065    ///
1066    /// This is `false` by default.
1067    ///
1068    /// [proposal]: https://github.com/webassembly/memory64
1069    pub fn wasm_memory64(&mut self, enable: bool) -> &mut Self {
1070        self.wasm_feature(WasmFeatures::MEMORY64, enable);
1071        self
1072    }
1073
1074    /// Configures whether the WebAssembly extended-const [proposal] will
1075    /// be enabled for compilation.
1076    ///
1077    /// This is `true` by default.
1078    ///
1079    /// [proposal]: https://github.com/webassembly/extended-const
1080    pub fn wasm_extended_const(&mut self, enable: bool) -> &mut Self {
1081        self.wasm_feature(WasmFeatures::EXTENDED_CONST, enable);
1082        self
1083    }
1084
1085    /// Configures whether the [WebAssembly stack switching
1086    /// proposal][proposal] will be enabled for compilation.
1087    ///
1088    /// This feature gates the use of control tags.
1089    ///
1090    /// This feature depends on the `function_reference_types` and
1091    /// `exceptions` features.
1092    ///
1093    /// This feature is `false` by default.
1094    ///
1095    /// # Errors
1096    ///
1097    /// [proposal]: https://github.com/webassembly/stack-switching
1098    pub fn wasm_stack_switching(&mut self, enable: bool) -> &mut Self {
1099        self.wasm_feature(WasmFeatures::STACK_SWITCHING, enable);
1100        self
1101    }
1102
1103    /// Configures whether the WebAssembly component-model [proposal] will
1104    /// be enabled for compilation.
1105    ///
1106    /// This flag can be used to blanket disable all components within Wasmtime.
1107    /// Otherwise usage of components requires statically using
1108    /// [`Component`](crate::component::Component) instead of
1109    /// [`Module`](crate::Module) for example anyway.
1110    ///
1111    /// The default value for this option is whether the `component-model`
1112    /// crate feature of Wasmtime is enabled or not. By default this crate
1113    /// feature is enabled.
1114    ///
1115    /// [proposal]: https://github.com/webassembly/component-model
1116    #[cfg(feature = "component-model")]
1117    pub fn wasm_component_model(&mut self, enable: bool) -> &mut Self {
1118        self.wasm_feature(WasmFeatures::COMPONENT_MODEL, enable);
1119        self
1120    }
1121
1122    /// Configures whether components support the async ABI [proposal] for
1123    /// lifting and lowering functions, as well as `stream`, `future`, and
1124    /// `error-context` types.
1125    ///
1126    /// Please note that Wasmtime's support for this feature is _very_
1127    /// incomplete.
1128    ///
1129    /// [proposal]:
1130    ///     https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1131    #[cfg(feature = "component-model-async")]
1132    pub fn wasm_component_model_async(&mut self, enable: bool) -> &mut Self {
1133        self.wasm_feature(WasmFeatures::CM_ASYNC, enable);
1134        self
1135    }
1136
1137    /// This corresponds to the 🚝 emoji in the component model specification.
1138    ///
1139    /// Please note that Wasmtime's support for this feature is _very_
1140    /// incomplete.
1141    ///
1142    /// [proposal]:
1143    ///     https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1144    #[cfg(feature = "component-model-async")]
1145    pub fn wasm_component_model_async_builtins(&mut self, enable: bool) -> &mut Self {
1146        self.wasm_feature(WasmFeatures::CM_ASYNC_BUILTINS, enable);
1147        self
1148    }
1149
1150    /// This corresponds to the 🚟 emoji in the component model specification.
1151    ///
1152    /// Please note that Wasmtime's support for this feature is _very_
1153    /// incomplete.
1154    ///
1155    /// [proposal]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1156    #[cfg(feature = "component-model-async")]
1157    pub fn wasm_component_model_async_stackful(&mut self, enable: bool) -> &mut Self {
1158        self.wasm_feature(WasmFeatures::CM_ASYNC_STACKFUL, enable);
1159        self
1160    }
1161
1162    /// This corresponds to the 📝 emoji in the component model specification.
1163    ///
1164    /// Please note that Wasmtime's support for this feature is _very_
1165    /// incomplete.
1166    ///
1167    /// [proposal]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md
1168    #[cfg(feature = "component-model")]
1169    pub fn wasm_component_model_error_context(&mut self, enable: bool) -> &mut Self {
1170        self.wasm_feature(WasmFeatures::CM_ERROR_CONTEXT, enable);
1171        self
1172    }
1173
1174    /// Configures whether the [GC extension to the component-model
1175    /// proposal][proposal] is enabled or not.
1176    ///
1177    /// This corresponds to the 🛸 emoji in the component model specification.
1178    ///
1179    /// Please note that Wasmtime's support for this feature is _very_
1180    /// incomplete.
1181    ///
1182    /// [proposal]: https://github.com/WebAssembly/component-model/issues/525
1183    #[cfg(feature = "component-model")]
1184    pub fn wasm_component_model_gc(&mut self, enable: bool) -> &mut Self {
1185        self.wasm_feature(WasmFeatures::CM_GC, enable);
1186        self
1187    }
1188
1189    #[doc(hidden)] // FIXME(#3427) - if/when implemented then un-hide this
1190    pub fn wasm_exceptions(&mut self, enable: bool) -> &mut Self {
1191        self.wasm_feature(WasmFeatures::EXCEPTIONS, enable);
1192        self
1193    }
1194
1195    #[doc(hidden)] // FIXME(#3427) - if/when implemented then un-hide this
1196    #[deprecated = "This configuration option only exists for internal \
1197                    usage with the spec testsuite. It may be removed at \
1198                    any time and without warning. Do not rely on it!"]
1199    pub fn wasm_legacy_exceptions(&mut self, enable: bool) -> &mut Self {
1200        self.wasm_feature(WasmFeatures::LEGACY_EXCEPTIONS, enable);
1201        self
1202    }
1203
1204    /// Configures which compilation strategy will be used for wasm modules.
1205    ///
1206    /// This method can be used to configure which compiler is used for wasm
1207    /// modules, and for more documentation consult the [`Strategy`] enumeration
1208    /// and its documentation.
1209    ///
1210    /// The default value for this is `Strategy::Auto`.
1211    #[cfg(any(feature = "cranelift", feature = "winch"))]
1212    pub fn strategy(&mut self, strategy: Strategy) -> &mut Self {
1213        self.compiler_config.strategy = strategy.not_auto();
1214        self
1215    }
1216
1217    /// Configures which garbage collector will be used for Wasm modules.
1218    ///
1219    /// This method can be used to configure which garbage collector
1220    /// implementation is used for Wasm modules. For more documentation, consult
1221    /// the [`Collector`] enumeration and its documentation.
1222    ///
1223    /// The default value for this is `Collector::Auto`.
1224    #[cfg(feature = "gc")]
1225    pub fn collector(&mut self, collector: Collector) -> &mut Self {
1226        self.collector = collector;
1227        self
1228    }
1229
1230    /// Creates a default profiler based on the profiling strategy chosen.
1231    ///
1232    /// Profiler creation calls the type's default initializer where the purpose is
1233    /// really just to put in place the type used for profiling.
1234    ///
1235    /// Some [`ProfilingStrategy`] require specific platforms or particular feature
1236    /// to be enabled, such as `ProfilingStrategy::JitDump` requires the `jitdump`
1237    /// feature.
1238    ///
1239    /// # Errors
1240    ///
1241    /// The validation of this field is deferred until the engine is being built, and thus may
1242    /// cause `Engine::new` fail if the required feature is disabled, or the platform is not
1243    /// supported.
1244    pub fn profiler(&mut self, profile: ProfilingStrategy) -> &mut Self {
1245        self.profiling_strategy = profile;
1246        self
1247    }
1248
1249    /// Configures whether the debug verifier of Cranelift is enabled or not.
1250    ///
1251    /// When Cranelift is used as a code generation backend this will configure
1252    /// it to have the `enable_verifier` flag which will enable a number of debug
1253    /// checks inside of Cranelift. This is largely only useful for the
1254    /// developers of wasmtime itself.
1255    ///
1256    /// The default value for this is `false`
1257    #[cfg(any(feature = "cranelift", feature = "winch"))]
1258    pub fn cranelift_debug_verifier(&mut self, enable: bool) -> &mut Self {
1259        let val = if enable { "true" } else { "false" };
1260        self.compiler_config
1261            .settings
1262            .insert("enable_verifier".to_string(), val.to_string());
1263        self
1264    }
1265
1266    /// Configures the Cranelift code generator optimization level.
1267    ///
1268    /// When the Cranelift code generator is used you can configure the
1269    /// optimization level used for generated code in a few various ways. For
1270    /// more information see the documentation of [`OptLevel`].
1271    ///
1272    /// The default value for this is `OptLevel::Speed`.
1273    #[cfg(any(feature = "cranelift", feature = "winch"))]
1274    pub fn cranelift_opt_level(&mut self, level: OptLevel) -> &mut Self {
1275        let val = match level {
1276            OptLevel::None => "none",
1277            OptLevel::Speed => "speed",
1278            OptLevel::SpeedAndSize => "speed_and_size",
1279        };
1280        self.compiler_config
1281            .settings
1282            .insert("opt_level".to_string(), val.to_string());
1283        self
1284    }
1285
1286    /// Configures the regalloc algorithm used by the Cranelift code generator.
1287    ///
1288    /// Cranelift can select any of several register allocator algorithms. Each
1289    /// of these algorithms generates correct code, but they represent different
1290    /// tradeoffs between compile speed (how expensive the compilation process
1291    /// is) and run-time speed (how fast the generated code runs).
1292    /// For more information see the documentation of [`RegallocAlgorithm`].
1293    ///
1294    /// The default value for this is `RegallocAlgorithm::Backtracking`.
1295    #[cfg(any(feature = "cranelift", feature = "winch"))]
1296    pub fn cranelift_regalloc_algorithm(&mut self, algo: RegallocAlgorithm) -> &mut Self {
1297        let val = match algo {
1298            RegallocAlgorithm::Backtracking => "backtracking",
1299        };
1300        self.compiler_config
1301            .settings
1302            .insert("regalloc_algorithm".to_string(), val.to_string());
1303        self
1304    }
1305
1306    /// Configures whether Cranelift should perform a NaN-canonicalization pass.
1307    ///
1308    /// When Cranelift is used as a code generation backend this will configure
1309    /// it to replace NaNs with a single canonical value. This is useful for
1310    /// users requiring entirely deterministic WebAssembly computation.  This is
1311    /// not required by the WebAssembly spec, so it is not enabled by default.
1312    ///
1313    /// Note that this option affects not only WebAssembly's `f32` and `f64`
1314    /// types but additionally the `v128` type. This option will cause
1315    /// operations using any of these types to have extra checks placed after
1316    /// them to normalize NaN values as needed.
1317    ///
1318    /// The default value for this is `false`
1319    #[cfg(any(feature = "cranelift", feature = "winch"))]
1320    pub fn cranelift_nan_canonicalization(&mut self, enable: bool) -> &mut Self {
1321        let val = if enable { "true" } else { "false" };
1322        self.compiler_config
1323            .settings
1324            .insert("enable_nan_canonicalization".to_string(), val.to_string());
1325        self
1326    }
1327
1328    /// Controls whether proof-carrying code (PCC) is used to validate
1329    /// lowering of Wasm sandbox checks.
1330    ///
1331    /// Proof-carrying code carries "facts" about program values from
1332    /// the IR all the way to machine code, and checks those facts
1333    /// against known machine-instruction semantics. This guards
1334    /// against bugs in instruction lowering that might create holes
1335    /// in the Wasm sandbox.
1336    ///
1337    /// PCC is designed to be fast: it does not require complex
1338    /// solvers or logic engines to verify, but only a linear pass
1339    /// over a trail of "breadcrumbs" or facts at each intermediate
1340    /// value. Thus, it is appropriate to enable in production.
1341    #[cfg(any(feature = "cranelift", feature = "winch"))]
1342    pub fn cranelift_pcc(&mut self, enable: bool) -> &mut Self {
1343        let val = if enable { "true" } else { "false" };
1344        self.compiler_config
1345            .settings
1346            .insert("enable_pcc".to_string(), val.to_string());
1347        self
1348    }
1349
1350    /// Allows setting a Cranelift boolean flag or preset. This allows
1351    /// fine-tuning of Cranelift settings.
1352    ///
1353    /// Since Cranelift flags may be unstable, this method should not be considered to be stable
1354    /// either; other `Config` functions should be preferred for stability.
1355    ///
1356    /// # Safety
1357    ///
1358    /// This is marked as unsafe, because setting the wrong flag might break invariants,
1359    /// resulting in execution hazards.
1360    ///
1361    /// # Errors
1362    ///
1363    /// The validation of the flags are deferred until the engine is being built, and thus may
1364    /// cause `Engine::new` fail if the flag's name does not exist, or the value is not appropriate
1365    /// for the flag type.
1366    #[cfg(any(feature = "cranelift", feature = "winch"))]
1367    pub unsafe fn cranelift_flag_enable(&mut self, flag: &str) -> &mut Self {
1368        self.compiler_config.flags.insert(flag.to_string());
1369        self
1370    }
1371
1372    /// Allows settings another Cranelift flag defined by a flag name and value. This allows
1373    /// fine-tuning of Cranelift settings.
1374    ///
1375    /// Since Cranelift flags may be unstable, this method should not be considered to be stable
1376    /// either; other `Config` functions should be preferred for stability.
1377    ///
1378    /// # Safety
1379    ///
1380    /// This is marked as unsafe, because setting the wrong flag might break invariants,
1381    /// resulting in execution hazards.
1382    ///
1383    /// # Errors
1384    ///
1385    /// The validation of the flags are deferred until the engine is being built, and thus may
1386    /// cause `Engine::new` fail if the flag's name does not exist, or incompatible with other
1387    /// settings.
1388    ///
1389    /// For example, feature `wasm_backtrace` will set `unwind_info` to `true`, but if it's
1390    /// manually set to false then it will fail.
1391    #[cfg(any(feature = "cranelift", feature = "winch"))]
1392    pub unsafe fn cranelift_flag_set(&mut self, name: &str, value: &str) -> &mut Self {
1393        self.compiler_config
1394            .settings
1395            .insert(name.to_string(), value.to_string());
1396        self
1397    }
1398
1399    /// Set a custom [`Cache`].
1400    ///
1401    /// To load a cache from a file, use [`Cache::from_file`]. Otherwise, you can create a new
1402    /// cache config using [`CacheConfig::new`] and passing that to [`Cache::new`].
1403    ///
1404    /// If you want to disable the cache, you can call this method with `None`.
1405    ///
1406    /// By default, new configs do not have caching enabled.
1407    /// Every call to [`Module::new(my_wasm)`][crate::Module::new] will recompile `my_wasm`,
1408    /// even when it is unchanged, unless an enabled `CacheConfig` is provided.
1409    ///
1410    /// This method is only available when the `cache` feature of this crate is
1411    /// enabled.
1412    ///
1413    /// [docs]: https://bytecodealliance.github.io/wasmtime/cli-cache.html
1414    #[cfg(feature = "cache")]
1415    pub fn cache(&mut self, cache: Option<Cache>) -> &mut Self {
1416        self.cache = cache;
1417        self
1418    }
1419
1420    /// Sets a custom memory creator.
1421    ///
1422    /// Custom memory creators are used when creating host `Memory` objects or when
1423    /// creating instance linear memories for the on-demand instance allocation strategy.
1424    #[cfg(feature = "runtime")]
1425    pub fn with_host_memory(&mut self, mem_creator: Arc<dyn MemoryCreator>) -> &mut Self {
1426        self.mem_creator = Some(Arc::new(MemoryCreatorProxy(mem_creator)));
1427        self
1428    }
1429
1430    /// Sets a custom stack creator.
1431    ///
1432    /// Custom memory creators are used when creating creating async instance stacks for
1433    /// the on-demand instance allocation strategy.
1434    #[cfg(feature = "async")]
1435    pub fn with_host_stack(&mut self, stack_creator: Arc<dyn StackCreator>) -> &mut Self {
1436        self.stack_creator = Some(Arc::new(StackCreatorProxy(stack_creator)));
1437        self
1438    }
1439
1440    /// Sets a custom executable-memory publisher.
1441    ///
1442    /// Custom executable-memory publishers are hooks that allow
1443    /// Wasmtime to make certain regions of memory executable when
1444    /// loading precompiled modules or compiling new modules
1445    /// in-process. In most modern operating systems, memory allocated
1446    /// for heap usage is readable and writable by default but not
1447    /// executable. To jump to machine code stored in that memory, we
1448    /// need to make it executable. For security reasons, we usually
1449    /// also make it read-only at the same time, so the executing code
1450    /// can't be modified later.
1451    ///
1452    /// By default, Wasmtime will use the appropriate system calls on
1453    /// the host platform for this work. However, it also allows
1454    /// plugging in a custom implementation via this configuration
1455    /// option. This may be useful on custom or `no_std` platforms,
1456    /// for example, especially where virtual memory is not otherwise
1457    /// used by Wasmtime (no `signals-and-traps` feature).
1458    #[cfg(feature = "runtime")]
1459    pub fn with_custom_code_memory(
1460        &mut self,
1461        custom_code_memory: Option<Arc<dyn CustomCodeMemory>>,
1462    ) -> &mut Self {
1463        self.custom_code_memory = custom_code_memory;
1464        self
1465    }
1466
1467    /// Sets the instance allocation strategy to use.
1468    ///
1469    /// This is notably used in conjunction with
1470    /// [`InstanceAllocationStrategy::Pooling`] and [`PoolingAllocationConfig`].
1471    pub fn allocation_strategy(
1472        &mut self,
1473        strategy: impl Into<InstanceAllocationStrategy>,
1474    ) -> &mut Self {
1475        self.allocation_strategy = strategy.into();
1476        self
1477    }
1478
1479    /// Specifies the capacity of linear memories, in bytes, in their initial
1480    /// allocation.
1481    ///
1482    /// > Note: this value has important performance ramifications, be sure to
1483    /// > benchmark when setting this to a non-default value and read over this
1484    /// > documentation.
1485    ///
1486    /// This function will change the size of the initial memory allocation made
1487    /// for linear memories. This setting is only applicable when the initial
1488    /// size of a linear memory is below this threshold. Linear memories are
1489    /// allocated in the virtual address space of the host process with OS APIs
1490    /// such as `mmap` and this setting affects how large the allocation will
1491    /// be.
1492    ///
1493    /// ## Background: WebAssembly Linear Memories
1494    ///
1495    /// WebAssembly linear memories always start with a minimum size and can
1496    /// possibly grow up to a maximum size. The minimum size is always specified
1497    /// in a WebAssembly module itself and the maximum size can either be
1498    /// optionally specified in the module or inherently limited by the index
1499    /// type. For example for this module:
1500    ///
1501    /// ```wasm
1502    /// (module
1503    ///     (memory $a 4)
1504    ///     (memory $b 4096 4096 (pagesize 1))
1505    ///     (memory $c i64 10)
1506    /// )
1507    /// ```
1508    ///
1509    /// * Memory `$a` initially allocates 4 WebAssembly pages (256KiB) and can
1510    ///   grow up to 4GiB, the limit of the 32-bit index space.
1511    /// * Memory `$b` initially allocates 4096 WebAssembly pages, but in this
1512    ///   case its page size is 1, so it's 4096 bytes. Memory can also grow no
1513    ///   further meaning that it will always be 4096 bytes.
1514    /// * Memory `$c` is a 64-bit linear memory which starts with 640KiB of
1515    ///   memory and can theoretically grow up to 2^64 bytes, although most
1516    ///   hosts will run out of memory long before that.
1517    ///
1518    /// All operations on linear memories done by wasm are required to be
1519    /// in-bounds. Any access beyond the end of a linear memory is considered a
1520    /// trap.
1521    ///
1522    /// ## What this setting affects: Virtual Memory
1523    ///
1524    /// This setting is used to configure the behavior of the size of the linear
1525    /// memory allocation performed for each of these memories. For example the
1526    /// initial linear memory allocation looks like this:
1527    ///
1528    /// ```text
1529    ///              memory_reservation
1530    ///                    |
1531    ///          ◄─────────┴────────────────►
1532    /// ┌───────┬─────────┬──────────────────┬───────┐
1533    /// │ guard │ initial │ ... capacity ... │ guard │
1534    /// └───────┴─────────┴──────────────────┴───────┘
1535    ///  ◄──┬──►                              ◄──┬──►
1536    ///     │                                    │
1537    ///     │                             memory_guard_size
1538    ///     │
1539    ///     │
1540    ///  memory_guard_size (if guard_before_linear_memory)
1541    /// ```
1542    ///
1543    /// Memory in the `initial` range is accessible to the instance and can be
1544    /// read/written by wasm code. Memory in the `guard` regions is never
1545    /// accessible to wasm code and memory in `capacity` is initially
1546    /// inaccessible but may become accessible through `memory.grow` instructions
1547    /// for example.
1548    ///
1549    /// This means that this setting is the size of the initial chunk of virtual
1550    /// memory that a linear memory may grow into.
1551    ///
1552    /// ## What this setting affects: Runtime Speed
1553    ///
1554    /// This is a performance-sensitive setting which is taken into account
1555    /// during the compilation process of a WebAssembly module. For example if a
1556    /// 32-bit WebAssembly linear memory has a `memory_reservation` size of 4GiB
1557    /// then bounds checks can be elided because `capacity` will be guaranteed
1558    /// to be unmapped for all addressable bytes that wasm can access (modulo a
1559    /// few details).
1560    ///
1561    /// If `memory_reservation` was something smaller like 256KiB then that
1562    /// would have a much smaller impact on virtual memory but the compile code
1563    /// would then need to have explicit bounds checks to ensure that
1564    /// loads/stores are in-bounds.
1565    ///
1566    /// The goal of this setting is to enable skipping bounds checks in most
1567    /// modules by default. Some situations which require explicit bounds checks
1568    /// though are:
1569    ///
1570    /// * When `memory_reservation` is smaller than the addressable size of the
1571    ///   linear memory. For example if 64-bit linear memories always need
1572    ///   bounds checks as they can address the entire virtual address spacce.
1573    ///   For 32-bit linear memories a `memory_reservation` minimum size of 4GiB
1574    ///   is required to elide bounds checks.
1575    ///
1576    /// * When linear memories have a page size of 1 then bounds checks are
1577    ///   required. In this situation virtual memory can't be relied upon
1578    ///   because that operates at the host page size granularity where wasm
1579    ///   requires a per-byte level granularity.
1580    ///
1581    /// * Configuration settings such as [`Config::signals_based_traps`] can be
1582    ///   used to disable the use of signal handlers and virtual memory so
1583    ///   explicit bounds checks are required.
1584    ///
1585    /// * When [`Config::memory_guard_size`] is too small a bounds check may be
1586    ///   required. For 32-bit wasm addresses are actually 33-bit effective
1587    ///   addresses because loads/stores have a 32-bit static offset to add to
1588    ///   the dynamic 32-bit address. If the static offset is larger than the
1589    ///   size of the guard region then an explicit bounds check is required.
1590    ///
1591    /// ## What this setting affects: Memory Growth Behavior
1592    ///
1593    /// In addition to affecting bounds checks emitted in compiled code this
1594    /// setting also affects how WebAssembly linear memories are grown. The
1595    /// `memory.grow` instruction can be used to make a linear memory larger and
1596    /// this is also affected by APIs such as
1597    /// [`Memory::grow`](crate::Memory::grow).
1598    ///
1599    /// In these situations when the amount being grown is small enough to fit
1600    /// within the remaining capacity then the linear memory doesn't have to be
1601    /// moved at runtime. If the capacity runs out though then a new linear
1602    /// memory allocation must be made and the contents of linear memory is
1603    /// copied over.
1604    ///
1605    /// For example here's a situation where a copy happens:
1606    ///
1607    /// * The `memory_reservation` setting is configured to 128KiB.
1608    /// * A WebAssembly linear memory starts with a single 64KiB page.
1609    /// * This memory can be grown by one page to contain the full 128KiB of
1610    ///   memory.
1611    /// * If grown by one more page, though, then a 192KiB allocation must be
1612    ///   made and the previous 128KiB of contents are copied into the new
1613    ///   allocation.
1614    ///
1615    /// This growth behavior can have a significant performance impact if lots
1616    /// of data needs to be copied on growth. Conversely if memory growth never
1617    /// needs to happen because the capacity will always be large enough then
1618    /// optimizations can be applied to cache the base pointer of linear memory.
1619    ///
1620    /// When memory is grown then the
1621    /// [`Config::memory_reservation_for_growth`] is used for the new
1622    /// memory allocation to have memory to grow into.
1623    ///
1624    /// When using the pooling allocator via [`PoolingAllocationConfig`] then
1625    /// memories are never allowed to move so requests for growth are instead
1626    /// rejected with an error.
1627    ///
1628    /// ## When this setting is not used
1629    ///
1630    /// This setting is ignored and unused when the initial size of linear
1631    /// memory is larger than this threshold. For example if this setting is set
1632    /// to 1MiB but a wasm module requires a 2MiB minimum allocation then this
1633    /// setting is ignored. In this situation the minimum size of memory will be
1634    /// allocated along with [`Config::memory_reservation_for_growth`]
1635    /// after it to grow into.
1636    ///
1637    /// That means that this value can be set to zero. That can be useful in
1638    /// benchmarking to see the overhead of bounds checks for example.
1639    /// Additionally it can be used to minimize the virtual memory allocated by
1640    /// Wasmtime.
1641    ///
1642    /// ## Default Value
1643    ///
1644    /// The default value for this property depends on the host platform. For
1645    /// 64-bit platforms there's lots of address space available, so the default
1646    /// configured here is 4GiB. When coupled with the default size of
1647    /// [`Config::memory_guard_size`] this means that 32-bit WebAssembly linear
1648    /// memories with 64KiB page sizes will skip almost all bounds checks by
1649    /// default.
1650    ///
1651    /// For 32-bit platforms this value defaults to 10MiB. This means that
1652    /// bounds checks will be required on 32-bit platforms.
1653    pub fn memory_reservation(&mut self, bytes: u64) -> &mut Self {
1654        self.tunables.memory_reservation = Some(bytes);
1655        self
1656    }
1657
1658    /// Indicates whether linear memories may relocate their base pointer at
1659    /// runtime.
1660    ///
1661    /// WebAssembly linear memories either have a maximum size that's explicitly
1662    /// listed in the type of a memory or inherently limited by the index type
1663    /// of the memory (e.g. 4GiB for 32-bit linear memories). Depending on how
1664    /// the linear memory is allocated (see [`Config::memory_reservation`]) it
1665    /// may be necessary to move the memory in the host's virtual address space
1666    /// during growth. This option controls whether this movement is allowed or
1667    /// not.
1668    ///
1669    /// An example of a linear memory needing to move is when
1670    /// [`Config::memory_reservation`] is 0 then a linear memory will be
1671    /// allocated as the minimum size of the memory plus
1672    /// [`Config::memory_reservation_for_growth`]. When memory grows beyond the
1673    /// reservation for growth then the memory needs to be relocated.
1674    ///
1675    /// When this option is set to `false` then it can have a number of impacts
1676    /// on how memories work at runtime:
1677    ///
1678    /// * Modules can be compiled with static knowledge the base pointer of
1679    ///   linear memory never changes to enable optimizations such as
1680    ///   loop invariant code motion (hoisting the base pointer out of a loop).
1681    ///
1682    /// * Memories cannot grow in excess of their original allocation. This
1683    ///   means that [`Config::memory_reservation`] and
1684    ///   [`Config::memory_reservation_for_growth`] may need tuning to ensure
1685    ///   the memory configuration works at runtime.
1686    ///
1687    /// The default value for this option is `true`.
1688    pub fn memory_may_move(&mut self, enable: bool) -> &mut Self {
1689        self.tunables.memory_may_move = Some(enable);
1690        self
1691    }
1692
1693    /// Configures the size, in bytes, of the guard region used at the end of a
1694    /// linear memory's address space reservation.
1695    ///
1696    /// > Note: this value has important performance ramifications, be sure to
1697    /// > understand what this value does before tweaking it and benchmarking.
1698    ///
1699    /// This setting controls how many bytes are guaranteed to be unmapped after
1700    /// the virtual memory allocation of a linear memory. When
1701    /// combined with sufficiently large values of
1702    /// [`Config::memory_reservation`] (e.g. 4GiB for 32-bit linear memories)
1703    /// then a guard region can be used to eliminate bounds checks in generated
1704    /// code.
1705    ///
1706    /// This setting additionally can be used to help deduplicate bounds checks
1707    /// in code that otherwise requires bounds checks. For example with a 4KiB
1708    /// guard region then a 64-bit linear memory which accesses addresses `x+8`
1709    /// and `x+16` only needs to perform a single bounds check on `x`. If that
1710    /// bounds check passes then the offset is guaranteed to either reside in
1711    /// linear memory or the guard region, resulting in deterministic behavior
1712    /// either way.
1713    ///
1714    /// ## How big should the guard be?
1715    ///
1716    /// In general, like with configuring [`Config::memory_reservation`], you
1717    /// probably don't want to change this value from the defaults. Removing
1718    /// bounds checks is dependent on a number of factors where the size of the
1719    /// guard region is only one piece of the equation. Other factors include:
1720    ///
1721    /// * [`Config::memory_reservation`]
1722    /// * The index type of the linear memory (e.g. 32-bit or 64-bit)
1723    /// * The page size of the linear memory
1724    /// * Other settings such as [`Config::signals_based_traps`]
1725    ///
1726    /// Embeddings using virtual memory almost always want at least some guard
1727    /// region, but otherwise changes from the default should be profiled
1728    /// locally to see the performance impact.
1729    ///
1730    /// ## Default
1731    ///
1732    /// The default value for this property is 32MiB on 64-bit platforms. This
1733    /// allows eliminating almost all bounds checks on loads/stores with an
1734    /// immediate offset of less than 32MiB. On 32-bit platforms this defaults
1735    /// to 64KiB.
1736    pub fn memory_guard_size(&mut self, bytes: u64) -> &mut Self {
1737        self.tunables.memory_guard_size = Some(bytes);
1738        self
1739    }
1740
1741    /// Configures the size, in bytes, of the extra virtual memory space
1742    /// reserved after a linear memory is relocated.
1743    ///
1744    /// This setting is used in conjunction with [`Config::memory_reservation`]
1745    /// to configure what happens after a linear memory is relocated in the host
1746    /// address space. If the initial size of a linear memory exceeds
1747    /// [`Config::memory_reservation`] or if it grows beyond that size
1748    /// throughout its lifetime then this setting will be used.
1749    ///
1750    /// When a linear memory is relocated it will initially look like this:
1751    ///
1752    /// ```text
1753    ///            memory.size
1754    ///                 │
1755    ///          ◄──────┴─────►
1756    /// ┌───────┬──────────────┬───────┐
1757    /// │ guard │  accessible  │ guard │
1758    /// └───────┴──────────────┴───────┘
1759    ///                         ◄──┬──►
1760    ///                            │
1761    ///                     memory_guard_size
1762    /// ```
1763    ///
1764    /// where `accessible` needs to be grown but there's no more memory to grow
1765    /// into. A new region of the virtual address space will be allocated that
1766    /// looks like this:
1767    ///
1768    /// ```text
1769    ///                           memory_reservation_for_growth
1770    ///                                       │
1771    ///            memory.size                │
1772    ///                 │                     │
1773    ///          ◄──────┴─────► ◄─────────────┴───────────►
1774    /// ┌───────┬──────────────┬───────────────────────────┬───────┐
1775    /// │ guard │  accessible  │ .. reserved for growth .. │ guard │
1776    /// └───────┴──────────────┴───────────────────────────┴───────┘
1777    ///                                                     ◄──┬──►
1778    ///                                                        │
1779    ///                                               memory_guard_size
1780    /// ```
1781    ///
1782    /// This means that up to `memory_reservation_for_growth` bytes can be
1783    /// allocated again before the entire linear memory needs to be moved again
1784    /// when another `memory_reservation_for_growth` bytes will be appended to
1785    /// the size of the allocation.
1786    ///
1787    /// Note that this is a currently simple heuristic for optimizing the growth
1788    /// of dynamic memories, primarily implemented for the memory64 proposal
1789    /// where the maximum size of memory is larger than 4GiB. This setting is
1790    /// unlikely to be a one-size-fits-all style approach and if you're an
1791    /// embedder running into issues with growth and are interested in having
1792    /// other growth strategies available here please feel free to [open an
1793    /// issue on the Wasmtime repository][issue]!
1794    ///
1795    /// [issue]: https://github.com/bytecodealliance/wasmtime/issues/new
1796    ///
1797    /// ## Default
1798    ///
1799    /// For 64-bit platforms this defaults to 2GiB, and for 32-bit platforms
1800    /// this defaults to 1MiB.
1801    pub fn memory_reservation_for_growth(&mut self, bytes: u64) -> &mut Self {
1802        self.tunables.memory_reservation_for_growth = Some(bytes);
1803        self
1804    }
1805
1806    /// Indicates whether a guard region is present before allocations of
1807    /// linear memory.
1808    ///
1809    /// Guard regions before linear memories are never used during normal
1810    /// operation of WebAssembly modules, even if they have out-of-bounds
1811    /// loads. The only purpose for a preceding guard region in linear memory
1812    /// is extra protection against possible bugs in code generators like
1813    /// Cranelift. This setting does not affect performance in any way, but will
1814    /// result in larger virtual memory reservations for linear memories (it
1815    /// won't actually ever use more memory, just use more of the address
1816    /// space).
1817    ///
1818    /// The size of the guard region before linear memory is the same as the
1819    /// guard size that comes after linear memory, which is configured by
1820    /// [`Config::memory_guard_size`].
1821    ///
1822    /// ## Default
1823    ///
1824    /// This value defaults to `true`.
1825    pub fn guard_before_linear_memory(&mut self, enable: bool) -> &mut Self {
1826        self.tunables.guard_before_linear_memory = Some(enable);
1827        self
1828    }
1829
1830    /// Indicates whether to initialize tables lazily, so that instantiation
1831    /// is fast but indirect calls are a little slower. If false, tables
1832    /// are initialized eagerly during instantiation from any active element
1833    /// segments that apply to them.
1834    ///
1835    /// **Note** Disabling this option is not compatible with the Winch compiler.
1836    ///
1837    /// ## Default
1838    ///
1839    /// This value defaults to `true`.
1840    pub fn table_lazy_init(&mut self, table_lazy_init: bool) -> &mut Self {
1841        self.tunables.table_lazy_init = Some(table_lazy_init);
1842        self
1843    }
1844
1845    /// Configure the version information used in serialized and deserialized [`crate::Module`]s.
1846    /// This effects the behavior of [`crate::Module::serialize()`], as well as
1847    /// [`crate::Module::deserialize()`] and related functions.
1848    ///
1849    /// The default strategy is to use the wasmtime crate's Cargo package version.
1850    pub fn module_version(&mut self, strategy: ModuleVersionStrategy) -> Result<&mut Self> {
1851        match strategy {
1852            // This case requires special precondition for assertion in SerializedModule::to_bytes
1853            ModuleVersionStrategy::Custom(ref v) => {
1854                if v.as_bytes().len() > 255 {
1855                    bail!("custom module version cannot be more than 255 bytes: {}", v);
1856                }
1857            }
1858            _ => {}
1859        }
1860        self.module_version = strategy;
1861        Ok(self)
1862    }
1863
1864    /// Configure whether wasmtime should compile a module using multiple
1865    /// threads.
1866    ///
1867    /// Disabling this will result in a single thread being used to compile
1868    /// the wasm bytecode.
1869    ///
1870    /// By default parallel compilation is enabled.
1871    #[cfg(feature = "parallel-compilation")]
1872    pub fn parallel_compilation(&mut self, parallel: bool) -> &mut Self {
1873        self.parallel_compilation = parallel;
1874        self
1875    }
1876
1877    /// Configures whether compiled artifacts will contain information to map
1878    /// native program addresses back to the original wasm module.
1879    ///
1880    /// This configuration option is `true` by default and, if enabled,
1881    /// generates the appropriate tables in compiled modules to map from native
1882    /// address back to wasm source addresses. This is used for displaying wasm
1883    /// program counters in backtraces as well as generating filenames/line
1884    /// numbers if so configured as well (and the original wasm module has DWARF
1885    /// debugging information present).
1886    pub fn generate_address_map(&mut self, generate: bool) -> &mut Self {
1887        self.tunables.generate_address_map = Some(generate);
1888        self
1889    }
1890
1891    /// Configures whether copy-on-write memory-mapped data is used to
1892    /// initialize a linear memory.
1893    ///
1894    /// Initializing linear memory via a copy-on-write mapping can drastically
1895    /// improve instantiation costs of a WebAssembly module because copying
1896    /// memory is deferred. Additionally if a page of memory is only ever read
1897    /// from WebAssembly and never written too then the same underlying page of
1898    /// data will be reused between all instantiations of a module meaning that
1899    /// if a module is instantiated many times this can lower the overall memory
1900    /// required needed to run that module.
1901    ///
1902    /// The main disadvantage of copy-on-write initialization, however, is that
1903    /// it may be possible for highly-parallel scenarios to be less scalable. If
1904    /// a page is read initially by a WebAssembly module then that page will be
1905    /// mapped to a read-only copy shared between all WebAssembly instances. If
1906    /// the same page is then written, however, then a private copy is created
1907    /// and swapped out from the read-only version. This also requires an [IPI],
1908    /// however, which can be a significant bottleneck in high-parallelism
1909    /// situations.
1910    ///
1911    /// This feature is only applicable when a WebAssembly module meets specific
1912    /// criteria to be initialized in this fashion, such as:
1913    ///
1914    /// * Only memories defined in the module can be initialized this way.
1915    /// * Data segments for memory must use statically known offsets.
1916    /// * Data segments for memory must all be in-bounds.
1917    ///
1918    /// Modules which do not meet these criteria will fall back to
1919    /// initialization of linear memory based on copying memory.
1920    ///
1921    /// This feature of Wasmtime is also platform-specific:
1922    ///
1923    /// * Linux - this feature is supported for all instances of [`Module`].
1924    ///   Modules backed by an existing mmap (such as those created by
1925    ///   [`Module::deserialize_file`]) will reuse that mmap to cow-initialize
1926    ///   memory. Other instance of [`Module`] may use the `memfd_create`
1927    ///   syscall to create an initialization image to `mmap`.
1928    /// * Unix (not Linux) - this feature is only supported when loading modules
1929    ///   from a precompiled file via [`Module::deserialize_file`] where there
1930    ///   is a file descriptor to use to map data into the process. Note that
1931    ///   the module must have been compiled with this setting enabled as well.
1932    /// * Windows - there is no support for this feature at this time. Memory
1933    ///   initialization will always copy bytes.
1934    ///
1935    /// By default this option is enabled.
1936    ///
1937    /// [`Module::deserialize_file`]: crate::Module::deserialize_file
1938    /// [`Module`]: crate::Module
1939    /// [IPI]: https://en.wikipedia.org/wiki/Inter-processor_interrupt
1940    pub fn memory_init_cow(&mut self, enable: bool) -> &mut Self {
1941        self.tunables.memory_init_cow = Some(enable);
1942        self
1943    }
1944
1945    /// A configuration option to force the usage of `memfd_create` on Linux to
1946    /// be used as the backing source for a module's initial memory image.
1947    ///
1948    /// When [`Config::memory_init_cow`] is enabled, which is enabled by
1949    /// default, module memory initialization images are taken from a module's
1950    /// original mmap if possible. If a precompiled module was loaded from disk
1951    /// this means that the disk's file is used as an mmap source for the
1952    /// initial linear memory contents. This option can be used to force, on
1953    /// Linux, that instead of using the original file on disk a new in-memory
1954    /// file is created with `memfd_create` to hold the contents of the initial
1955    /// image.
1956    ///
1957    /// This option can be used to avoid possibly loading the contents of memory
1958    /// from disk through a page fault. Instead with `memfd_create` the contents
1959    /// of memory are always in RAM, meaning that even page faults which
1960    /// initially populate a wasm linear memory will only work with RAM instead
1961    /// of ever hitting the disk that the original precompiled module is stored
1962    /// on.
1963    ///
1964    /// This option is disabled by default.
1965    pub fn force_memory_init_memfd(&mut self, enable: bool) -> &mut Self {
1966        self.force_memory_init_memfd = enable;
1967        self
1968    }
1969
1970    /// Configures whether or not a coredump should be generated and attached to
1971    /// the anyhow::Error when a trap is raised.
1972    ///
1973    /// This option is disabled by default.
1974    #[cfg(feature = "coredump")]
1975    pub fn coredump_on_trap(&mut self, enable: bool) -> &mut Self {
1976        self.coredump_on_trap = enable;
1977        self
1978    }
1979
1980    /// Enables memory error checking for wasm programs.
1981    ///
1982    /// This option is disabled by default.
1983    #[cfg(any(feature = "cranelift", feature = "winch"))]
1984    pub fn wmemcheck(&mut self, enable: bool) -> &mut Self {
1985        self.wmemcheck = enable;
1986        self.compiler_config.wmemcheck = enable;
1987        self
1988    }
1989
1990    /// Configures the "guaranteed dense image size" for copy-on-write
1991    /// initialized memories.
1992    ///
1993    /// When using the [`Config::memory_init_cow`] feature to initialize memory
1994    /// efficiently (which is enabled by default), compiled modules contain an
1995    /// image of the module's initial heap. If the module has a fairly sparse
1996    /// initial heap, with just a few data segments at very different offsets,
1997    /// this could result in a large region of zero bytes in the image. In
1998    /// other words, it's not very memory-efficient.
1999    ///
2000    /// We normally use a heuristic to avoid this: if less than half
2001    /// of the initialized range (first non-zero to last non-zero
2002    /// byte) of any memory in the module has pages with nonzero
2003    /// bytes, then we avoid creating a memory image for the entire module.
2004    ///
2005    /// However, if the embedder always needs the instantiation-time efficiency
2006    /// of copy-on-write initialization, and is otherwise carefully controlling
2007    /// parameters of the modules (for example, by limiting the maximum heap
2008    /// size of the modules), then it may be desirable to ensure a memory image
2009    /// is created even if this could go against the heuristic above. Thus, we
2010    /// add another condition: there is a size of initialized data region up to
2011    /// which we *always* allow a memory image. The embedder can set this to a
2012    /// known maximum heap size if they desire to always get the benefits of
2013    /// copy-on-write images.
2014    ///
2015    /// In the future we may implement a "best of both worlds"
2016    /// solution where we have a dense image up to some limit, and
2017    /// then support a sparse list of initializers beyond that; this
2018    /// would get most of the benefit of copy-on-write and pay the incremental
2019    /// cost of eager initialization only for those bits of memory
2020    /// that are out-of-bounds. However, for now, an embedder desiring
2021    /// fast instantiation should ensure that this setting is as large
2022    /// as the maximum module initial memory content size.
2023    ///
2024    /// By default this value is 16 MiB.
2025    pub fn memory_guaranteed_dense_image_size(&mut self, size_in_bytes: u64) -> &mut Self {
2026        self.memory_guaranteed_dense_image_size = size_in_bytes;
2027        self
2028    }
2029
2030    /// Whether to enable function inlining during compilation or not.
2031    ///
2032    /// This may result in faster execution at runtime, but adds additional
2033    /// compilation time. Inlining may also enlarge the size of compiled
2034    /// artifacts (for example, the size of the result of
2035    /// [`Engine::precompile_component`]).
2036    ///
2037    /// Inlining is not supported by all of Wasmtime's compilation strategies;
2038    /// currently, it only Cranelift supports it. This setting will be ignored
2039    /// when using a compilation strategy that does not support inlining, like
2040    /// Winch.
2041    ///
2042    /// Note that inlining is still somewhat experimental at the moment (as of
2043    /// the Wasmtime version 36).
2044    pub fn compiler_inlining(&mut self, inlining: bool) -> &mut Self {
2045        self.tunables.inlining = Some(inlining);
2046        self
2047    }
2048
2049    /// Returns the set of features that the currently selected compiler backend
2050    /// does not support at all and may panic on.
2051    ///
2052    /// Wasmtime strives to reject unknown modules or unsupported modules with
2053    /// first-class errors instead of panics. Not all compiler backends have the
2054    /// same level of feature support on all platforms as well. This method
2055    /// returns a set of features that the currently selected compiler
2056    /// configuration is known to not support and may panic on. This acts as a
2057    /// first-level filter on incoming wasm modules/configuration to fail-fast
2058    /// instead of panicking later on.
2059    ///
2060    /// Note that if a feature is not listed here it does not mean that the
2061    /// backend fully supports the proposal. Instead that means that the backend
2062    /// doesn't ever panic on the proposal, but errors during compilation may
2063    /// still be returned. This means that features listed here are definitely
2064    /// not supported at all, but features not listed here may still be
2065    /// partially supported. For example at the time of this writing the Winch
2066    /// backend partially supports simd so it's not listed here. Winch doesn't
2067    /// fully support simd but unimplemented instructions just return errors.
2068    fn compiler_panicking_wasm_features(&self) -> WasmFeatures {
2069        #[cfg(any(feature = "cranelift", feature = "winch"))]
2070        match self.compiler_config.strategy {
2071            None | Some(Strategy::Cranelift) => {
2072                let mut unsupported = WasmFeatures::empty();
2073
2074                // Pulley at this time fundamentally doesn't support the
2075                // `threads` proposal, notably shared memory, because Rust can't
2076                // safely implement loads/stores in the face of shared memory.
2077                // Stack switching is not implemented, either.
2078                if self.compiler_target().is_pulley() {
2079                    unsupported |= WasmFeatures::THREADS;
2080                    unsupported |= WasmFeatures::STACK_SWITCHING;
2081                }
2082
2083                use target_lexicon::*;
2084                match self.compiler_target() {
2085                    Triple {
2086                        architecture: Architecture::X86_64 | Architecture::X86_64h,
2087                        operating_system:
2088                            OperatingSystem::Linux
2089                            | OperatingSystem::MacOSX(_)
2090                            | OperatingSystem::Darwin(_),
2091                        ..
2092                    } => {
2093                        // Stack switching supported on (non-Pulley) Cranelift.
2094                    }
2095
2096                    _ => {
2097                        // On platforms other than x64 Unix-like, we don't
2098                        // support stack switching.
2099                        unsupported |= WasmFeatures::STACK_SWITCHING;
2100                    }
2101                }
2102                unsupported
2103            }
2104            Some(Strategy::Winch) => {
2105                let mut unsupported = WasmFeatures::GC
2106                    | WasmFeatures::FUNCTION_REFERENCES
2107                    | WasmFeatures::RELAXED_SIMD
2108                    | WasmFeatures::TAIL_CALL
2109                    | WasmFeatures::GC_TYPES
2110                    | WasmFeatures::EXCEPTIONS
2111                    | WasmFeatures::LEGACY_EXCEPTIONS
2112                    | WasmFeatures::STACK_SWITCHING;
2113                match self.compiler_target().architecture {
2114                    target_lexicon::Architecture::Aarch64(_) => {
2115                        unsupported |= WasmFeatures::THREADS;
2116                        unsupported |= WasmFeatures::WIDE_ARITHMETIC;
2117                    }
2118
2119                    // Winch doesn't support other non-x64 architectures at this
2120                    // time either but will return an first-class error for
2121                    // them.
2122                    _ => {}
2123                }
2124                unsupported
2125            }
2126            Some(Strategy::Auto) => unreachable!(),
2127        }
2128        #[cfg(not(any(feature = "cranelift", feature = "winch")))]
2129        return WasmFeatures::empty();
2130    }
2131
2132    /// Calculates the set of features that are enabled for this `Config`.
2133    ///
2134    /// This method internally will start with the an empty set of features to
2135    /// avoid being tied to wasmparser's defaults. Next Wasmtime's set of
2136    /// default features are added to this set, some of which are conditional
2137    /// depending on crate features. Finally explicitly requested features via
2138    /// `wasm_*` methods on `Config` are applied. Everything is then validated
2139    /// later in `Config::validate`.
2140    fn features(&self) -> WasmFeatures {
2141        // Wasmtime by default supports all of the wasm 2.0 version of the
2142        // specification.
2143        let mut features = WasmFeatures::WASM2;
2144
2145        // On-by-default features that wasmtime has. Note that these are all
2146        // subject to the criteria at
2147        // https://docs.wasmtime.dev/contributing-implementing-wasm-proposals.html
2148        // and
2149        // https://docs.wasmtime.dev/stability-wasm-proposals.html
2150        features |= WasmFeatures::MULTI_MEMORY;
2151        features |= WasmFeatures::RELAXED_SIMD;
2152        features |= WasmFeatures::TAIL_CALL;
2153        features |= WasmFeatures::EXTENDED_CONST;
2154        features |= WasmFeatures::MEMORY64;
2155        // NB: if you add a feature above this line please double-check
2156        // https://docs.wasmtime.dev/stability-wasm-proposals.html
2157        // to ensure all requirements are met and/or update the documentation
2158        // there too.
2159
2160        // Set some features to their conditionally-enabled defaults depending
2161        // on crate compile-time features.
2162        features.set(WasmFeatures::GC_TYPES, cfg!(feature = "gc"));
2163        features.set(WasmFeatures::THREADS, cfg!(feature = "threads"));
2164        features.set(
2165            WasmFeatures::COMPONENT_MODEL,
2166            cfg!(feature = "component-model"),
2167        );
2168
2169        // From the default set of proposals remove any that the current
2170        // compiler backend may panic on if the module contains them.
2171        features = features & !self.compiler_panicking_wasm_features();
2172
2173        // After wasmtime's defaults are configured then factor in user requests
2174        // and disable/enable features. Note that the enable/disable sets should
2175        // be disjoint.
2176        debug_assert!((self.enabled_features & self.disabled_features).is_empty());
2177        features &= !self.disabled_features;
2178        features |= self.enabled_features;
2179
2180        features
2181    }
2182
2183    /// Returns the configured compiler target for this `Config`.
2184    pub(crate) fn compiler_target(&self) -> target_lexicon::Triple {
2185        // If a target is explicitly configured, always use that.
2186        if let Some(target) = self.target.clone() {
2187            return target;
2188        }
2189
2190        // If the `build.rs` script determined that this platform uses pulley by
2191        // default, then use Pulley.
2192        if cfg!(default_target_pulley) {
2193            return target_lexicon::Triple::pulley_host();
2194        }
2195
2196        // And at this point the target is for sure the host.
2197        target_lexicon::Triple::host()
2198    }
2199
2200    pub(crate) fn validate(&self) -> Result<(Tunables, WasmFeatures)> {
2201        let features = self.features();
2202
2203        // First validate that the selected compiler backend and configuration
2204        // supports the set of `features` that are enabled. This will help
2205        // provide more first class errors instead of panics about unsupported
2206        // features and configurations.
2207        let unsupported = features & self.compiler_panicking_wasm_features();
2208        if !unsupported.is_empty() {
2209            for flag in WasmFeatures::FLAGS.iter() {
2210                if !unsupported.contains(*flag.value()) {
2211                    continue;
2212                }
2213                bail!(
2214                    "the wasm_{} feature is not supported on this compiler configuration",
2215                    flag.name().to_lowercase()
2216                );
2217            }
2218
2219            panic!("should have returned an error by now")
2220        }
2221
2222        #[cfg(any(feature = "async", feature = "stack-switching"))]
2223        if self.async_support && self.max_wasm_stack > self.async_stack_size {
2224            bail!("max_wasm_stack size cannot exceed the async_stack_size");
2225        }
2226        if self.max_wasm_stack == 0 {
2227            bail!("max_wasm_stack size cannot be zero");
2228        }
2229        #[cfg(not(feature = "wmemcheck"))]
2230        if self.wmemcheck {
2231            bail!("wmemcheck (memory checker) was requested but is not enabled in this build");
2232        }
2233
2234        let mut tunables = Tunables::default_for_target(&self.compiler_target())?;
2235
2236        // If no target is explicitly specified then further refine `tunables`
2237        // for the configuration of this host depending on what platform
2238        // features were found available at compile time. This means that anyone
2239        // cross-compiling for a customized host will need to further refine
2240        // compilation options.
2241        if self.target.is_none() {
2242            // If this platform doesn't have native signals then change some
2243            // defaults to account for that. Note that VM guards are turned off
2244            // here because that's primarily a feature of eliding
2245            // bounds-checks.
2246            if !cfg!(has_native_signals) {
2247                tunables.signals_based_traps = cfg!(has_native_signals);
2248                tunables.memory_guard_size = 0;
2249            }
2250
2251            // When virtual memory is not available use slightly different
2252            // defaults for tunables to be more amenable to `MallocMemory`.
2253            // Note that these can still be overridden by config options.
2254            if !cfg!(has_virtual_memory) {
2255                tunables.memory_reservation = 0;
2256                tunables.memory_reservation_for_growth = 1 << 20; // 1MB
2257                tunables.memory_init_cow = false;
2258            }
2259        }
2260
2261        self.tunables.configure(&mut tunables);
2262
2263        // If we're going to compile with winch, we must use the winch calling convention.
2264        #[cfg(any(feature = "cranelift", feature = "winch"))]
2265        {
2266            tunables.winch_callable = self.compiler_config.strategy == Some(Strategy::Winch);
2267        }
2268
2269        tunables.collector = if features.gc_types() {
2270            #[cfg(feature = "gc")]
2271            {
2272                use wasmtime_environ::Collector as EnvCollector;
2273                Some(match self.collector.try_not_auto()? {
2274                    Collector::DeferredReferenceCounting => EnvCollector::DeferredReferenceCounting,
2275                    Collector::Null => EnvCollector::Null,
2276                    Collector::Auto => unreachable!(),
2277                })
2278            }
2279            #[cfg(not(feature = "gc"))]
2280            bail!("cannot use GC types: the `gc` feature was disabled at compile time")
2281        } else {
2282            None
2283        };
2284
2285        Ok((tunables, features))
2286    }
2287
2288    #[cfg(feature = "runtime")]
2289    pub(crate) fn build_allocator(
2290        &self,
2291        tunables: &Tunables,
2292    ) -> Result<Box<dyn InstanceAllocator + Send + Sync>> {
2293        #[cfg(feature = "async")]
2294        let (stack_size, stack_zeroing) = (self.async_stack_size, self.async_stack_zeroing);
2295
2296        #[cfg(not(feature = "async"))]
2297        let (stack_size, stack_zeroing) = (0, false);
2298
2299        let _ = tunables;
2300
2301        match &self.allocation_strategy {
2302            InstanceAllocationStrategy::OnDemand => {
2303                let mut _allocator = Box::new(OnDemandInstanceAllocator::new(
2304                    self.mem_creator.clone(),
2305                    stack_size,
2306                    stack_zeroing,
2307                ));
2308                #[cfg(feature = "async")]
2309                if let Some(stack_creator) = &self.stack_creator {
2310                    _allocator.set_stack_creator(stack_creator.clone());
2311                }
2312                Ok(_allocator)
2313            }
2314            #[cfg(feature = "pooling-allocator")]
2315            InstanceAllocationStrategy::Pooling(config) => {
2316                let mut config = config.config;
2317                config.stack_size = stack_size;
2318                config.async_stack_zeroing = stack_zeroing;
2319                Ok(Box::new(crate::runtime::vm::PoolingInstanceAllocator::new(
2320                    &config, tunables,
2321                )?))
2322            }
2323        }
2324    }
2325
2326    #[cfg(feature = "runtime")]
2327    pub(crate) fn build_gc_runtime(&self) -> Result<Option<Arc<dyn GcRuntime>>> {
2328        if !self.features().gc_types() {
2329            return Ok(None);
2330        }
2331
2332        #[cfg(not(feature = "gc"))]
2333        bail!("cannot create a GC runtime: the `gc` feature was disabled at compile time");
2334
2335        #[cfg(feature = "gc")]
2336        #[cfg_attr(
2337            not(any(feature = "gc-null", feature = "gc-drc")),
2338            expect(unreachable_code, reason = "definitions known to be dummy")
2339        )]
2340        {
2341            Ok(Some(match self.collector.try_not_auto()? {
2342                #[cfg(feature = "gc-drc")]
2343                Collector::DeferredReferenceCounting => {
2344                    Arc::new(crate::runtime::vm::DrcCollector::default()) as Arc<dyn GcRuntime>
2345                }
2346                #[cfg(not(feature = "gc-drc"))]
2347                Collector::DeferredReferenceCounting => unreachable!(),
2348
2349                #[cfg(feature = "gc-null")]
2350                Collector::Null => {
2351                    Arc::new(crate::runtime::vm::NullCollector::default()) as Arc<dyn GcRuntime>
2352                }
2353                #[cfg(not(feature = "gc-null"))]
2354                Collector::Null => unreachable!(),
2355
2356                Collector::Auto => unreachable!(),
2357            }))
2358        }
2359    }
2360
2361    #[cfg(feature = "runtime")]
2362    pub(crate) fn build_profiler(&self) -> Result<Box<dyn ProfilingAgent>> {
2363        Ok(match self.profiling_strategy {
2364            ProfilingStrategy::PerfMap => profiling_agent::new_perfmap()?,
2365            ProfilingStrategy::JitDump => profiling_agent::new_jitdump()?,
2366            ProfilingStrategy::VTune => profiling_agent::new_vtune()?,
2367            ProfilingStrategy::None => profiling_agent::new_null(),
2368            ProfilingStrategy::Pulley => profiling_agent::new_pulley()?,
2369        })
2370    }
2371
2372    #[cfg(any(feature = "cranelift", feature = "winch"))]
2373    pub(crate) fn build_compiler(
2374        mut self,
2375        tunables: &Tunables,
2376        features: WasmFeatures,
2377    ) -> Result<(Self, Box<dyn wasmtime_environ::Compiler>)> {
2378        let target = self.compiler_target();
2379
2380        // The target passed to the builders below is an `Option<Triple>` where
2381        // `None` represents the current host with CPU features inferred from
2382        // the host's CPU itself. The `target` above is not an `Option`, so
2383        // switch it to `None` in the case that a target wasn't explicitly
2384        // specified (which indicates no feature inference) and the target
2385        // matches the host.
2386        let target_for_builder =
2387            if self.target.is_none() && target == target_lexicon::Triple::host() {
2388                None
2389            } else {
2390                Some(target.clone())
2391            };
2392
2393        let mut compiler = match self.compiler_config.strategy {
2394            #[cfg(feature = "cranelift")]
2395            Some(Strategy::Cranelift) => wasmtime_cranelift::builder(target_for_builder)?,
2396            #[cfg(not(feature = "cranelift"))]
2397            Some(Strategy::Cranelift) => bail!("cranelift support not compiled in"),
2398            #[cfg(feature = "winch")]
2399            Some(Strategy::Winch) => wasmtime_winch::builder(target_for_builder)?,
2400            #[cfg(not(feature = "winch"))]
2401            Some(Strategy::Winch) => bail!("winch support not compiled in"),
2402
2403            None | Some(Strategy::Auto) => unreachable!(),
2404        };
2405
2406        if let Some(path) = &self.compiler_config.clif_dir {
2407            compiler.clif_dir(path)?;
2408        }
2409
2410        // If probestack is enabled for a target, Wasmtime will always use the
2411        // inline strategy which doesn't require us to define a `__probestack`
2412        // function or similar.
2413        self.compiler_config
2414            .settings
2415            .insert("probestack_strategy".into(), "inline".into());
2416
2417        // We enable stack probing by default on all targets.
2418        // This is required on Windows because of the way Windows
2419        // commits its stacks, but it's also a good idea on other
2420        // platforms to ensure guard pages are hit for large frame
2421        // sizes.
2422        self.compiler_config
2423            .flags
2424            .insert("enable_probestack".into());
2425
2426        // The current wasm multivalue implementation depends on this.
2427        // FIXME(#9510) handle this in wasmtime-cranelift instead.
2428        self.compiler_config
2429            .flags
2430            .insert("enable_multi_ret_implicit_sret".into());
2431
2432        if let Some(unwind_requested) = self.native_unwind_info {
2433            if !self
2434                .compiler_config
2435                .ensure_setting_unset_or_given("unwind_info", &unwind_requested.to_string())
2436            {
2437                bail!(
2438                    "incompatible settings requested for Cranelift and Wasmtime `unwind-info` settings"
2439                );
2440            }
2441        }
2442
2443        if target.operating_system == target_lexicon::OperatingSystem::Windows {
2444            if !self
2445                .compiler_config
2446                .ensure_setting_unset_or_given("unwind_info", "true")
2447            {
2448                bail!("`native_unwind_info` cannot be disabled on Windows");
2449            }
2450        }
2451
2452        // We require frame pointers for correct stack walking, which is safety
2453        // critical in the presence of reference types, and otherwise it is just
2454        // really bad developer experience to get wrong.
2455        self.compiler_config
2456            .settings
2457            .insert("preserve_frame_pointers".into(), "true".into());
2458
2459        if !tunables.signals_based_traps {
2460            let mut ok = self
2461                .compiler_config
2462                .ensure_setting_unset_or_given("enable_table_access_spectre_mitigation", "false");
2463            ok = ok
2464                && self.compiler_config.ensure_setting_unset_or_given(
2465                    "enable_heap_access_spectre_mitigation",
2466                    "false",
2467                );
2468
2469            // Right now spectre-mitigated bounds checks will load from zero so
2470            // if host-based signal handlers are disabled then that's a mismatch
2471            // and doesn't work right now. Fixing this will require more thought
2472            // of how to implement the bounds check in spectre-only mode.
2473            if !ok {
2474                bail!(
2475                    "when signals-based traps are disabled then spectre \
2476                     mitigations must also be disabled"
2477                );
2478            }
2479        }
2480
2481        // check for incompatible compiler options and set required values
2482        if features.contains(WasmFeatures::REFERENCE_TYPES) {
2483            if !self
2484                .compiler_config
2485                .ensure_setting_unset_or_given("enable_safepoints", "true")
2486            {
2487                bail!(
2488                    "compiler option 'enable_safepoints' must be enabled when 'reference types' is enabled"
2489                );
2490            }
2491        }
2492
2493        if features.contains(WasmFeatures::RELAXED_SIMD) && !features.contains(WasmFeatures::SIMD) {
2494            bail!("cannot disable the simd proposal but enable the relaxed simd proposal");
2495        }
2496
2497        if features.contains(WasmFeatures::STACK_SWITCHING) {
2498            use target_lexicon::OperatingSystem;
2499            let model = match target.operating_system {
2500                OperatingSystem::Windows => "update_windows_tib",
2501                OperatingSystem::Linux
2502                | OperatingSystem::MacOSX(_)
2503                | OperatingSystem::Darwin(_) => "basic",
2504                _ => bail!("stack-switching feature not supported on this platform "),
2505            };
2506
2507            if !self
2508                .compiler_config
2509                .ensure_setting_unset_or_given("stack_switch_model", model)
2510            {
2511                bail!(
2512                    "compiler option 'stack_switch_model' must be set to '{}' on this platform",
2513                    model
2514                );
2515            }
2516        }
2517
2518        // Apply compiler settings and flags
2519        compiler.set_tunables(tunables.clone())?;
2520        for (k, v) in self.compiler_config.settings.iter() {
2521            compiler.set(k, v)?;
2522        }
2523        for flag in self.compiler_config.flags.iter() {
2524            compiler.enable(flag)?;
2525        }
2526
2527        #[cfg(all(feature = "incremental-cache", feature = "cranelift"))]
2528        if let Some(cache_store) = &self.compiler_config.cache_store {
2529            compiler.enable_incremental_compilation(cache_store.clone())?;
2530        }
2531
2532        compiler.wmemcheck(self.compiler_config.wmemcheck);
2533
2534        Ok((self, compiler.build()?))
2535    }
2536
2537    /// Internal setting for whether adapter modules for components will have
2538    /// extra WebAssembly instructions inserted performing more debug checks
2539    /// then are necessary.
2540    #[cfg(feature = "component-model")]
2541    pub fn debug_adapter_modules(&mut self, debug: bool) -> &mut Self {
2542        self.tunables.debug_adapter_modules = Some(debug);
2543        self
2544    }
2545
2546    /// Enables clif output when compiling a WebAssembly module.
2547    #[cfg(any(feature = "cranelift", feature = "winch"))]
2548    pub fn emit_clif(&mut self, path: &Path) -> &mut Self {
2549        self.compiler_config.clif_dir = Some(path.to_path_buf());
2550        self
2551    }
2552
2553    /// Configures whether, when on macOS, Mach ports are used for exception
2554    /// handling instead of traditional Unix-based signal handling.
2555    ///
2556    /// WebAssembly traps in Wasmtime are implemented with native faults, for
2557    /// example a `SIGSEGV` will occur when a WebAssembly guest accesses
2558    /// out-of-bounds memory. Handling this can be configured to either use Unix
2559    /// signals or Mach ports on macOS. By default Mach ports are used.
2560    ///
2561    /// Mach ports enable Wasmtime to work by default with foreign
2562    /// error-handling systems such as breakpad which also use Mach ports to
2563    /// handle signals. In this situation Wasmtime will continue to handle guest
2564    /// faults gracefully while any non-guest faults will get forwarded to
2565    /// process-level handlers such as breakpad. Some more background on this
2566    /// can be found in #2456.
2567    ///
2568    /// A downside of using mach ports, however, is that they don't interact
2569    /// well with `fork()`. Forking a Wasmtime process on macOS will produce a
2570    /// child process that cannot successfully run WebAssembly. In this
2571    /// situation traditional Unix signal handling should be used as that's
2572    /// inherited and works across forks.
2573    ///
2574    /// If your embedding wants to use a custom error handler which leverages
2575    /// Mach ports and you additionally wish to `fork()` the process and use
2576    /// Wasmtime in the child process that's not currently possible. Please
2577    /// reach out to us if you're in this bucket!
2578    ///
2579    /// This option defaults to `true`, using Mach ports by default.
2580    pub fn macos_use_mach_ports(&mut self, mach_ports: bool) -> &mut Self {
2581        self.macos_use_mach_ports = mach_ports;
2582        self
2583    }
2584
2585    /// Configures an embedder-provided function, `detect`, which is used to
2586    /// determine if an ISA-specific feature is available on the current host.
2587    ///
2588    /// This function is used to verify that any features enabled for a compiler
2589    /// backend, such as AVX support on x86\_64, are also available on the host.
2590    /// It is undefined behavior to execute an AVX instruction on a host that
2591    /// doesn't support AVX instructions, for example.
2592    ///
2593    /// When the `std` feature is active on this crate then this function is
2594    /// configured to a default implementation that uses the standard library's
2595    /// feature detection. When the `std` feature is disabled then there is no
2596    /// default available and this method must be called to configure a feature
2597    /// probing function.
2598    ///
2599    /// The `detect` function provided is given a string name of an ISA feature.
2600    /// The function should then return:
2601    ///
2602    /// * `Some(true)` - indicates that the feature was found on the host and it
2603    ///   is supported.
2604    /// * `Some(false)` - the feature name was recognized but it was not
2605    ///   detected on the host, for example the CPU is too old.
2606    /// * `None` - the feature name was not recognized and it's not known
2607    ///   whether it's on the host or not.
2608    ///
2609    /// Feature names passed to `detect` match the same feature name used in the
2610    /// Rust standard library. For example `"sse4.2"` is used on x86\_64.
2611    ///
2612    /// # Unsafety
2613    ///
2614    /// This function is `unsafe` because it is undefined behavior to execute
2615    /// instructions that a host does not support. This means that the result of
2616    /// `detect` must be correct for memory safe execution at runtime.
2617    pub unsafe fn detect_host_feature(&mut self, detect: fn(&str) -> Option<bool>) -> &mut Self {
2618        self.detect_host_feature = Some(detect);
2619        self
2620    }
2621
2622    /// Configures Wasmtime to not use signals-based trap handlers, for example
2623    /// disables `SIGILL` and `SIGSEGV` handler registration on Unix platforms.
2624    ///
2625    /// > **Note:** this option has important performance ramifications, be sure
2626    /// > to understand the implications. Wasm programs have been measured to
2627    /// > run up to 2x slower when signals-based traps are disabled.
2628    ///
2629    /// Wasmtime will by default leverage signals-based trap handlers (or the
2630    /// platform equivalent, for example "vectored exception handlers" on
2631    /// Windows) to make generated code more efficient. For example, when
2632    /// Wasmtime can use signals-based traps, it can elide explicit bounds
2633    /// checks for Wasm linear memory accesses, instead relying on virtual
2634    /// memory guard pages to raise a `SIGSEGV` (on Unix) for out-of-bounds
2635    /// accesses, which Wasmtime's runtime then catches and handles. Another
2636    /// example is divide-by-zero: with signals-based traps, Wasmtime can let
2637    /// the hardware raise a trap when the divisor is zero. Without
2638    /// signals-based traps, Wasmtime must explicitly emit additional
2639    /// instructions to check for zero and conditionally branch to a trapping
2640    /// code path.
2641    ///
2642    /// Some environments however may not have access to signal handlers. For
2643    /// example embedded scenarios may not support virtual memory. Other
2644    /// environments where Wasmtime is embedded within the surrounding
2645    /// environment may require that new signal handlers aren't registered due
2646    /// to the global nature of signal handlers. This option exists to disable
2647    /// the signal handler registration when required for these scenarios.
2648    ///
2649    /// When signals-based trap handlers are disabled, then Wasmtime and its
2650    /// generated code will *never* rely on segfaults or other
2651    /// signals. Generated code will be slower because bounds must be explicitly
2652    /// checked along with other conditions like division by zero.
2653    ///
2654    /// The following additional factors can also affect Wasmtime's ability to
2655    /// elide explicit bounds checks and leverage signals-based traps:
2656    ///
2657    /// * The [`Config::memory_reservation`] and [`Config::memory_guard_size`]
2658    ///   settings
2659    /// * The index type of the linear memory (e.g. 32-bit or 64-bit)
2660    /// * The page size of the linear memory
2661    ///
2662    /// When this option is disabled, the
2663    /// `enable_heap_access_spectre_mitigation` and
2664    /// `enable_table_access_spectre_mitigation` Cranelift settings must also be
2665    /// disabled. This means that generated code must have spectre mitigations
2666    /// disabled. This is because spectre mitigations rely on faults from
2667    /// loading from the null address to implement bounds checks.
2668    ///
2669    /// This option defaults to `true`: signals-based trap handlers are enabled
2670    /// by default.
2671    ///
2672    /// > **Note:** Disabling this option is not compatible with the Winch
2673    /// > compiler.
2674    pub fn signals_based_traps(&mut self, enable: bool) -> &mut Self {
2675        self.tunables.signals_based_traps = Some(enable);
2676        self
2677    }
2678}
2679
2680impl Default for Config {
2681    fn default() -> Config {
2682        Config::new()
2683    }
2684}
2685
2686impl fmt::Debug for Config {
2687    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2688        let mut f = f.debug_struct("Config");
2689
2690        // Not every flag in WasmFeatures can be enabled as part of creating
2691        // a Config. This impl gives a complete picture of all WasmFeatures
2692        // enabled, and doesn't require maintenance by hand (which has become out
2693        // of date in the past), at the cost of possible confusion for why
2694        // a flag in this set doesn't have a Config setter.
2695        let features = self.features();
2696        for flag in WasmFeatures::FLAGS.iter() {
2697            f.field(
2698                &format!("wasm_{}", flag.name().to_lowercase()),
2699                &features.contains(*flag.value()),
2700            );
2701        }
2702
2703        f.field("parallel_compilation", &self.parallel_compilation);
2704        #[cfg(any(feature = "cranelift", feature = "winch"))]
2705        {
2706            f.field("compiler_config", &self.compiler_config);
2707        }
2708
2709        self.tunables.format(&mut f);
2710        f.finish()
2711    }
2712}
2713
2714/// Possible Compilation strategies for a wasm module.
2715///
2716/// This is used as an argument to the [`Config::strategy`] method.
2717#[non_exhaustive]
2718#[derive(PartialEq, Eq, Clone, Debug, Copy)]
2719pub enum Strategy {
2720    /// An indicator that the compilation strategy should be automatically
2721    /// selected.
2722    ///
2723    /// This is generally what you want for most projects and indicates that the
2724    /// `wasmtime` crate itself should make the decision about what the best
2725    /// code generator for a wasm module is.
2726    ///
2727    /// Currently this always defaults to Cranelift, but the default value may
2728    /// change over time.
2729    Auto,
2730
2731    /// Currently the default backend, Cranelift aims to be a reasonably fast
2732    /// code generator which generates high quality machine code.
2733    Cranelift,
2734
2735    /// A baseline compiler for WebAssembly, currently under active development and not ready for
2736    /// production applications.
2737    Winch,
2738}
2739
2740#[cfg(any(feature = "winch", feature = "cranelift"))]
2741impl Strategy {
2742    fn not_auto(&self) -> Option<Strategy> {
2743        match self {
2744            Strategy::Auto => {
2745                if cfg!(feature = "cranelift") {
2746                    Some(Strategy::Cranelift)
2747                } else if cfg!(feature = "winch") {
2748                    Some(Strategy::Winch)
2749                } else {
2750                    None
2751                }
2752            }
2753            other => Some(*other),
2754        }
2755    }
2756}
2757
2758/// Possible garbage collector implementations for Wasm.
2759///
2760/// This is used as an argument to the [`Config::collector`] method.
2761///
2762/// The properties of Wasmtime's available collectors are summarized in the
2763/// following table:
2764///
2765/// | Collector                   | Collects Garbage[^1] | Latency[^2] | Throughput[^3] | Allocation Speed[^4] | Heap Utilization[^5] |
2766/// |-----------------------------|----------------------|-------------|----------------|----------------------|----------------------|
2767/// | `DeferredReferenceCounting` | Yes, but not cycles  | 🙂         | 🙁             | 😐                   | 😐                  |
2768/// | `Null`                      | No                   | 🙂         | 🙂             | 🙂                   | 🙂                  |
2769///
2770/// [^1]: Whether or not the collector is capable of collecting garbage and cyclic garbage.
2771///
2772/// [^2]: How long the Wasm program is paused during garbage
2773///       collections. Shorter is better. In general, better latency implies
2774///       worse throughput and vice versa.
2775///
2776/// [^3]: How fast the Wasm program runs when using this collector. Roughly
2777///       equivalent to the number of Wasm instructions executed per
2778///       second. Faster is better. In general, better throughput implies worse
2779///       latency and vice versa.
2780///
2781/// [^4]: How fast can individual objects be allocated?
2782///
2783/// [^5]: How many objects can the collector fit into N bytes of memory? That
2784///       is, how much space for bookkeeping and metadata does this collector
2785///       require? Less space taken up by metadata means more space for
2786///       additional objects. Reference counts are larger than mark bits and
2787///       free lists are larger than bump pointers, for example.
2788#[non_exhaustive]
2789#[derive(PartialEq, Eq, Clone, Debug, Copy)]
2790pub enum Collector {
2791    /// An indicator that the garbage collector should be automatically
2792    /// selected.
2793    ///
2794    /// This is generally what you want for most projects and indicates that the
2795    /// `wasmtime` crate itself should make the decision about what the best
2796    /// collector for a wasm module is.
2797    ///
2798    /// Currently this always defaults to the deferred reference-counting
2799    /// collector, but the default value may change over time.
2800    Auto,
2801
2802    /// The deferred reference-counting collector.
2803    ///
2804    /// A reference-counting collector, generally trading improved latency for
2805    /// worsened throughput. However, to avoid the largest overheads of
2806    /// reference counting, it avoids manipulating reference counts for Wasm
2807    /// objects on the stack. Instead, it will hold a reference count for an
2808    /// over-approximation of all objects that are currently on the stack, trace
2809    /// the stack during collection to find the precise set of on-stack roots,
2810    /// and decrement the reference count of any object that was in the
2811    /// over-approximation but not the precise set. This improves throughput,
2812    /// compared to "pure" reference counting, by performing many fewer
2813    /// refcount-increment and -decrement operations. The cost is the increased
2814    /// latency associated with tracing the stack.
2815    ///
2816    /// This collector cannot currently collect cycles; they will leak until the
2817    /// GC heap's store is dropped.
2818    DeferredReferenceCounting,
2819
2820    /// The null collector.
2821    ///
2822    /// This collector does not actually collect any garbage. It simply
2823    /// allocates objects until it runs out of memory, at which point further
2824    /// objects allocation attempts will trap.
2825    ///
2826    /// This collector is useful for incredibly short-running Wasm instances
2827    /// where additionally you would rather halt an over-allocating Wasm program
2828    /// than spend time collecting its garbage to allow it to keep running. It
2829    /// is also useful for measuring the overheads associated with other
2830    /// collectors, as this collector imposes as close to zero throughput and
2831    /// latency overhead as possible.
2832    Null,
2833}
2834
2835impl Default for Collector {
2836    fn default() -> Collector {
2837        Collector::Auto
2838    }
2839}
2840
2841#[cfg(feature = "gc")]
2842impl Collector {
2843    fn not_auto(&self) -> Option<Collector> {
2844        match self {
2845            Collector::Auto => {
2846                if cfg!(feature = "gc-drc") {
2847                    Some(Collector::DeferredReferenceCounting)
2848                } else if cfg!(feature = "gc-null") {
2849                    Some(Collector::Null)
2850                } else {
2851                    None
2852                }
2853            }
2854            other => Some(*other),
2855        }
2856    }
2857
2858    fn try_not_auto(&self) -> Result<Self> {
2859        match self.not_auto() {
2860            #[cfg(feature = "gc-drc")]
2861            Some(c @ Collector::DeferredReferenceCounting) => Ok(c),
2862            #[cfg(not(feature = "gc-drc"))]
2863            Some(Collector::DeferredReferenceCounting) => bail!(
2864                "cannot create an engine using the deferred reference-counting \
2865                 collector because the `gc-drc` feature was not enabled at \
2866                 compile time",
2867            ),
2868
2869            #[cfg(feature = "gc-null")]
2870            Some(c @ Collector::Null) => Ok(c),
2871            #[cfg(not(feature = "gc-null"))]
2872            Some(Collector::Null) => bail!(
2873                "cannot create an engine using the null collector because \
2874                 the `gc-null` feature was not enabled at compile time",
2875            ),
2876
2877            Some(Collector::Auto) => unreachable!(),
2878
2879            None => bail!(
2880                "cannot create an engine with GC support when none of the \
2881                 collectors are available; enable one of the following \
2882                 features: `gc-drc`, `gc-null`",
2883            ),
2884        }
2885    }
2886}
2887
2888/// Possible optimization levels for the Cranelift codegen backend.
2889#[non_exhaustive]
2890#[derive(Copy, Clone, Debug, Eq, PartialEq)]
2891pub enum OptLevel {
2892    /// No optimizations performed, minimizes compilation time by disabling most
2893    /// optimizations.
2894    None,
2895    /// Generates the fastest possible code, but may take longer.
2896    Speed,
2897    /// Similar to `speed`, but also performs transformations aimed at reducing
2898    /// code size.
2899    SpeedAndSize,
2900}
2901
2902/// Possible register allocator algorithms for the Cranelift codegen backend.
2903#[non_exhaustive]
2904#[derive(Copy, Clone, Debug, Eq, PartialEq)]
2905pub enum RegallocAlgorithm {
2906    /// Generates the fastest possible code, but may take longer.
2907    ///
2908    /// This algorithm performs "backtracking", which means that it may
2909    /// undo its earlier work and retry as it discovers conflicts. This
2910    /// results in better register utilization, producing fewer spills
2911    /// and moves, but can cause super-linear compile runtime.
2912    Backtracking,
2913}
2914
2915/// Select which profiling technique to support.
2916#[derive(Debug, Clone, Copy, PartialEq)]
2917pub enum ProfilingStrategy {
2918    /// No profiler support.
2919    None,
2920
2921    /// Collect function name information as the "perf map" file format, used with `perf` on Linux.
2922    PerfMap,
2923
2924    /// Collect profiling info for "jitdump" file format, used with `perf` on
2925    /// Linux.
2926    JitDump,
2927
2928    /// Collect profiling info using the "ittapi", used with `VTune` on Linux.
2929    VTune,
2930
2931    /// Support for profiling Pulley, Wasmtime's interpreter. Note that enabling
2932    /// this at runtime requires enabling the `profile-pulley` Cargo feature at
2933    /// compile time.
2934    Pulley,
2935}
2936
2937/// Select how wasm backtrace detailed information is handled.
2938#[derive(Debug, Clone, Copy)]
2939pub enum WasmBacktraceDetails {
2940    /// Support is unconditionally enabled and wasmtime will parse and read
2941    /// debug information.
2942    Enable,
2943
2944    /// Support is disabled, and wasmtime will not parse debug information for
2945    /// backtrace details.
2946    Disable,
2947
2948    /// Support for backtrace details is conditional on the
2949    /// `WASMTIME_BACKTRACE_DETAILS` environment variable.
2950    Environment,
2951}
2952
2953/// Describe the tri-state configuration of memory protection keys (MPK).
2954#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
2955pub enum MpkEnabled {
2956    /// Use MPK if supported by the current system; fall back to guard regions
2957    /// otherwise.
2958    Auto,
2959    /// Use MPK or fail if not supported.
2960    Enable,
2961    /// Do not use MPK.
2962    Disable,
2963}
2964
2965/// Configuration options used with [`InstanceAllocationStrategy::Pooling`] to
2966/// change the behavior of the pooling instance allocator.
2967///
2968/// This structure has a builder-style API in the same manner as [`Config`] and
2969/// is configured with [`Config::allocation_strategy`].
2970///
2971/// Note that usage of the pooling allocator does not affect compiled
2972/// WebAssembly code. Compiled `*.cwasm` files, for example, are usable both
2973/// with and without the pooling allocator.
2974///
2975/// ## Advantages of Pooled Allocation
2976///
2977/// The main benefit of the pooling allocator is to make WebAssembly
2978/// instantiation both faster and more scalable in terms of parallelism.
2979/// Allocation is faster because virtual memory is already configured and ready
2980/// to go within the pool, there's no need to [`mmap`] (for example on Unix) a
2981/// new region and configure it with guard pages. By avoiding [`mmap`] this
2982/// avoids whole-process virtual memory locks which can improve scalability and
2983/// performance through avoiding this.
2984///
2985/// Additionally with pooled allocation it's possible to create "affine slots"
2986/// to a particular WebAssembly module or component over time. For example if
2987/// the same module is multiple times over time the pooling allocator will, by
2988/// default, attempt to reuse the same slot. This mean that the slot has been
2989/// pre-configured and can retain virtual memory mappings for a copy-on-write
2990/// image, for example (see [`Config::memory_init_cow`] for more information.
2991/// This means that in a steady state instance deallocation is a single
2992/// [`madvise`] to reset linear memory to its original contents followed by a
2993/// single (optional) [`mprotect`] during the next instantiation to shrink
2994/// memory back to its original size. Compared to non-pooled allocation this
2995/// avoids the need to [`mmap`] a new region of memory, [`munmap`] it, and
2996/// [`mprotect`] regions too.
2997///
2998/// Another benefit of pooled allocation is that it's possible to configure
2999/// things such that no virtual memory management is required at all in a steady
3000/// state. For example a pooling allocator can be configured with:
3001///
3002/// * [`Config::memory_init_cow`] disabled
3003/// * [`Config::memory_guard_size`] disabled
3004/// * [`Config::memory_reservation`] shrunk to minimal size
3005/// * [`PoolingAllocationConfig::table_keep_resident`] sufficiently large
3006/// * [`PoolingAllocationConfig::linear_memory_keep_resident`] sufficiently large
3007///
3008/// With all these options in place no virtual memory tricks are used at all and
3009/// everything is manually managed by Wasmtime (for example resetting memory is
3010/// a `memset(0)`). This is not as fast in a single-threaded scenario but can
3011/// provide benefits in high-parallelism situations as no virtual memory locks
3012/// or IPIs need happen.
3013///
3014/// ## Disadvantages of Pooled Allocation
3015///
3016/// Despite the above advantages to instantiation performance the pooling
3017/// allocator is not enabled by default in Wasmtime. One reason is that the
3018/// performance advantages are not necessarily portable, for example while the
3019/// pooling allocator works on Windows it has not been tuned for performance on
3020/// Windows in the same way it has on Linux.
3021///
3022/// Additionally the main cost of the pooling allocator is that it requires a
3023/// very large reservation of virtual memory (on the order of most of the
3024/// addressable virtual address space). WebAssembly 32-bit linear memories in
3025/// Wasmtime are, by default 4G address space reservations with a small guard
3026/// region both before and after the linear memory. Memories in the pooling
3027/// allocator are contiguous which means that we only need a guard after linear
3028/// memory because the previous linear memory's slot post-guard is our own
3029/// pre-guard. This means that, by default, the pooling allocator uses roughly
3030/// 4G of virtual memory per WebAssembly linear memory slot. 4G of virtual
3031/// memory is 32 bits of a 64-bit address. Many 64-bit systems can only
3032/// actually use 48-bit addresses by default (although this can be extended on
3033/// architectures nowadays too), and of those 48 bits one of them is reserved
3034/// to indicate kernel-vs-userspace. This leaves 47-32=15 bits left,
3035/// meaning you can only have at most 32k slots of linear memories on many
3036/// systems by default. This is a relatively small number and shows how the
3037/// pooling allocator can quickly exhaust all of virtual memory.
3038///
3039/// Another disadvantage of the pooling allocator is that it may keep memory
3040/// alive when nothing is using it. A previously used slot for an instance might
3041/// have paged-in memory that will not get paged out until the
3042/// [`Engine`](crate::Engine) owning the pooling allocator is dropped. While
3043/// suitable for some applications this behavior may not be suitable for all
3044/// applications.
3045///
3046/// Finally the last disadvantage of the pooling allocator is that the
3047/// configuration values for the maximum number of instances, memories, tables,
3048/// etc, must all be fixed up-front. There's not always a clear answer as to
3049/// what these values should be so not all applications may be able to work
3050/// with this constraint.
3051///
3052/// [`madvise`]: https://man7.org/linux/man-pages/man2/madvise.2.html
3053/// [`mprotect`]: https://man7.org/linux/man-pages/man2/mprotect.2.html
3054/// [`mmap`]: https://man7.org/linux/man-pages/man2/mmap.2.html
3055/// [`munmap`]: https://man7.org/linux/man-pages/man2/munmap.2.html
3056#[cfg(feature = "pooling-allocator")]
3057#[derive(Debug, Clone, Default)]
3058pub struct PoolingAllocationConfig {
3059    config: crate::runtime::vm::PoolingInstanceAllocatorConfig,
3060}
3061
3062#[cfg(feature = "pooling-allocator")]
3063impl PoolingAllocationConfig {
3064    /// Returns a new configuration builder with all default settings
3065    /// configured.
3066    pub fn new() -> PoolingAllocationConfig {
3067        PoolingAllocationConfig::default()
3068    }
3069
3070    /// Configures the maximum number of "unused warm slots" to retain in the
3071    /// pooling allocator.
3072    ///
3073    /// The pooling allocator operates over slots to allocate from, and each
3074    /// slot is considered "cold" if it's never been used before or "warm" if
3075    /// it's been used by some module in the past. Slots in the pooling
3076    /// allocator additionally track an "affinity" flag to a particular core
3077    /// wasm module. When a module is instantiated into a slot then the slot is
3078    /// considered affine to that module, even after the instance has been
3079    /// deallocated.
3080    ///
3081    /// When a new instance is created then a slot must be chosen, and the
3082    /// current algorithm for selecting a slot is:
3083    ///
3084    /// * If there are slots that are affine to the module being instantiated,
3085    ///   then the most recently used slot is selected to be allocated from.
3086    ///   This is done to improve reuse of resources such as memory mappings and
3087    ///   additionally try to benefit from temporal locality for things like
3088    ///   caches.
3089    ///
3090    /// * Otherwise if there are more than N affine slots to other modules, then
3091    ///   one of those affine slots is chosen to be allocated. The slot chosen
3092    ///   is picked on a least-recently-used basis.
3093    ///
3094    /// * Finally, if there are less than N affine slots to other modules, then
3095    ///   the non-affine slots are allocated from.
3096    ///
3097    /// This setting, `max_unused_warm_slots`, is the value for N in the above
3098    /// algorithm. The purpose of this setting is to have a knob over the RSS
3099    /// impact of "unused slots" for a long-running wasm server.
3100    ///
3101    /// If this setting is set to 0, for example, then affine slots are
3102    /// aggressively reused on a least-recently-used basis. A "cold" slot is
3103    /// only used if there are no affine slots available to allocate from. This
3104    /// means that the set of slots used over the lifetime of a program is the
3105    /// same as the maximum concurrent number of wasm instances.
3106    ///
3107    /// If this setting is set to infinity, however, then cold slots are
3108    /// prioritized to be allocated from. This means that the set of slots used
3109    /// over the lifetime of a program will approach
3110    /// [`PoolingAllocationConfig::total_memories`], or the maximum number of
3111    /// slots in the pooling allocator.
3112    ///
3113    /// Wasmtime does not aggressively decommit all resources associated with a
3114    /// slot when the slot is not in use. For example the
3115    /// [`PoolingAllocationConfig::linear_memory_keep_resident`] option can be
3116    /// used to keep memory associated with a slot, even when it's not in use.
3117    /// This means that the total set of used slots in the pooling instance
3118    /// allocator can impact the overall RSS usage of a program.
3119    ///
3120    /// The default value for this option is `100`.
3121    pub fn max_unused_warm_slots(&mut self, max: u32) -> &mut Self {
3122        self.config.max_unused_warm_slots = max;
3123        self
3124    }
3125
3126    /// The target number of decommits to do per batch.
3127    ///
3128    /// This is not precise, as we can queue up decommits at times when we
3129    /// aren't prepared to immediately flush them, and so we may go over this
3130    /// target size occasionally.
3131    ///
3132    /// A batch size of one effectively disables batching.
3133    ///
3134    /// Defaults to `1`.
3135    pub fn decommit_batch_size(&mut self, batch_size: usize) -> &mut Self {
3136        self.config.decommit_batch_size = batch_size;
3137        self
3138    }
3139
3140    /// How much memory, in bytes, to keep resident for async stacks allocated
3141    /// with the pooling allocator.
3142    ///
3143    /// When [`PoolingAllocationConfig::async_stack_zeroing`] is enabled then
3144    /// Wasmtime will reset the contents of async stacks back to zero upon
3145    /// deallocation. This option can be used to perform the zeroing operation
3146    /// with `memset` up to a certain threshold of bytes instead of using system
3147    /// calls to reset the stack to zero.
3148    ///
3149    /// Note that when using this option the memory with async stacks will
3150    /// never be decommitted.
3151    #[cfg(feature = "async")]
3152    pub fn async_stack_keep_resident(&mut self, size: usize) -> &mut Self {
3153        self.config.async_stack_keep_resident = size;
3154        self
3155    }
3156
3157    /// How much memory, in bytes, to keep resident for each linear memory
3158    /// after deallocation.
3159    ///
3160    /// This option is only applicable on Linux and has no effect on other
3161    /// platforms.
3162    ///
3163    /// By default Wasmtime will use `madvise` to reset the entire contents of
3164    /// linear memory back to zero when a linear memory is deallocated. This
3165    /// option can be used to use `memset` instead to set memory back to zero
3166    /// which can, in some configurations, reduce the number of page faults
3167    /// taken when a slot is reused.
3168    pub fn linear_memory_keep_resident(&mut self, size: usize) -> &mut Self {
3169        self.config.linear_memory_keep_resident = size;
3170        self
3171    }
3172
3173    /// How much memory, in bytes, to keep resident for each table after
3174    /// deallocation.
3175    ///
3176    /// This option is only applicable on Linux and has no effect on other
3177    /// platforms.
3178    ///
3179    /// This option is the same as
3180    /// [`PoolingAllocationConfig::linear_memory_keep_resident`] except that it
3181    /// is applicable to tables instead.
3182    pub fn table_keep_resident(&mut self, size: usize) -> &mut Self {
3183        self.config.table_keep_resident = size;
3184        self
3185    }
3186
3187    /// The maximum number of concurrent component instances supported (default
3188    /// is `1000`).
3189    ///
3190    /// This provides an upper-bound on the total size of component
3191    /// metadata-related allocations, along with
3192    /// [`PoolingAllocationConfig::max_component_instance_size`]. The upper bound is
3193    ///
3194    /// ```text
3195    /// total_component_instances * max_component_instance_size
3196    /// ```
3197    ///
3198    /// where `max_component_instance_size` is rounded up to the size and alignment
3199    /// of the internal representation of the metadata.
3200    pub fn total_component_instances(&mut self, count: u32) -> &mut Self {
3201        self.config.limits.total_component_instances = count;
3202        self
3203    }
3204
3205    /// The maximum size, in bytes, allocated for a component instance's
3206    /// `VMComponentContext` metadata.
3207    ///
3208    /// The [`wasmtime::component::Instance`][crate::component::Instance] type
3209    /// has a static size but its internal `VMComponentContext` is dynamically
3210    /// sized depending on the component being instantiated. This size limit
3211    /// loosely correlates to the size of the component, taking into account
3212    /// factors such as:
3213    ///
3214    /// * number of lifted and lowered functions,
3215    /// * number of memories
3216    /// * number of inner instances
3217    /// * number of resources
3218    ///
3219    /// If the allocated size per instance is too small then instantiation of a
3220    /// module will fail at runtime with an error indicating how many bytes were
3221    /// needed.
3222    ///
3223    /// The default value for this is 1MiB.
3224    ///
3225    /// This provides an upper-bound on the total size of component
3226    /// metadata-related allocations, along with
3227    /// [`PoolingAllocationConfig::total_component_instances`]. The upper bound is
3228    ///
3229    /// ```text
3230    /// total_component_instances * max_component_instance_size
3231    /// ```
3232    ///
3233    /// where `max_component_instance_size` is rounded up to the size and alignment
3234    /// of the internal representation of the metadata.
3235    pub fn max_component_instance_size(&mut self, size: usize) -> &mut Self {
3236        self.config.limits.component_instance_size = size;
3237        self
3238    }
3239
3240    /// The maximum number of core instances a single component may contain
3241    /// (default is unlimited).
3242    ///
3243    /// This method (along with
3244    /// [`PoolingAllocationConfig::max_memories_per_component`],
3245    /// [`PoolingAllocationConfig::max_tables_per_component`], and
3246    /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
3247    /// the amount of resources a single component allocation consumes.
3248    ///
3249    /// If a component will instantiate more core instances than `count`, then
3250    /// the component will fail to instantiate.
3251    pub fn max_core_instances_per_component(&mut self, count: u32) -> &mut Self {
3252        self.config.limits.max_core_instances_per_component = count;
3253        self
3254    }
3255
3256    /// The maximum number of Wasm linear memories that a single component may
3257    /// transitively contain (default is unlimited).
3258    ///
3259    /// This method (along with
3260    /// [`PoolingAllocationConfig::max_core_instances_per_component`],
3261    /// [`PoolingAllocationConfig::max_tables_per_component`], and
3262    /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
3263    /// the amount of resources a single component allocation consumes.
3264    ///
3265    /// If a component transitively contains more linear memories than `count`,
3266    /// then the component will fail to instantiate.
3267    pub fn max_memories_per_component(&mut self, count: u32) -> &mut Self {
3268        self.config.limits.max_memories_per_component = count;
3269        self
3270    }
3271
3272    /// The maximum number of tables that a single component may transitively
3273    /// contain (default is unlimited).
3274    ///
3275    /// This method (along with
3276    /// [`PoolingAllocationConfig::max_core_instances_per_component`],
3277    /// [`PoolingAllocationConfig::max_memories_per_component`],
3278    /// [`PoolingAllocationConfig::max_component_instance_size`]) allows you to cap
3279    /// the amount of resources a single component allocation consumes.
3280    ///
3281    /// If a component will transitively contains more tables than `count`, then
3282    /// the component will fail to instantiate.
3283    pub fn max_tables_per_component(&mut self, count: u32) -> &mut Self {
3284        self.config.limits.max_tables_per_component = count;
3285        self
3286    }
3287
3288    /// The maximum number of concurrent Wasm linear memories supported (default
3289    /// is `1000`).
3290    ///
3291    /// This value has a direct impact on the amount of memory allocated by the pooling
3292    /// instance allocator.
3293    ///
3294    /// The pooling instance allocator allocates a memory pool, where each entry
3295    /// in the pool contains the reserved address space for each linear memory
3296    /// supported by an instance.
3297    ///
3298    /// The memory pool will reserve a large quantity of host process address
3299    /// space to elide the bounds checks required for correct WebAssembly memory
3300    /// semantics. Even with 64-bit address spaces, the address space is limited
3301    /// when dealing with a large number of linear memories.
3302    ///
3303    /// For example, on Linux x86_64, the userland address space limit is 128
3304    /// TiB. That might seem like a lot, but each linear memory will *reserve* 6
3305    /// GiB of space by default.
3306    pub fn total_memories(&mut self, count: u32) -> &mut Self {
3307        self.config.limits.total_memories = count;
3308        self
3309    }
3310
3311    /// The maximum number of concurrent tables supported (default is `1000`).
3312    ///
3313    /// This value has a direct impact on the amount of memory allocated by the
3314    /// pooling instance allocator.
3315    ///
3316    /// The pooling instance allocator allocates a table pool, where each entry
3317    /// in the pool contains the space needed for each WebAssembly table
3318    /// supported by an instance (see `table_elements` to control the size of
3319    /// each table).
3320    pub fn total_tables(&mut self, count: u32) -> &mut Self {
3321        self.config.limits.total_tables = count;
3322        self
3323    }
3324
3325    /// The maximum number of execution stacks allowed for asynchronous
3326    /// execution, when enabled (default is `1000`).
3327    ///
3328    /// This value has a direct impact on the amount of memory allocated by the
3329    /// pooling instance allocator.
3330    #[cfg(feature = "async")]
3331    pub fn total_stacks(&mut self, count: u32) -> &mut Self {
3332        self.config.limits.total_stacks = count;
3333        self
3334    }
3335
3336    /// The maximum number of concurrent core instances supported (default is
3337    /// `1000`).
3338    ///
3339    /// This provides an upper-bound on the total size of core instance
3340    /// metadata-related allocations, along with
3341    /// [`PoolingAllocationConfig::max_core_instance_size`]. The upper bound is
3342    ///
3343    /// ```text
3344    /// total_core_instances * max_core_instance_size
3345    /// ```
3346    ///
3347    /// where `max_core_instance_size` is rounded up to the size and alignment of
3348    /// the internal representation of the metadata.
3349    pub fn total_core_instances(&mut self, count: u32) -> &mut Self {
3350        self.config.limits.total_core_instances = count;
3351        self
3352    }
3353
3354    /// The maximum size, in bytes, allocated for a core instance's `VMContext`
3355    /// metadata.
3356    ///
3357    /// The [`Instance`][crate::Instance] type has a static size but its
3358    /// `VMContext` metadata is dynamically sized depending on the module being
3359    /// instantiated. This size limit loosely correlates to the size of the Wasm
3360    /// module, taking into account factors such as:
3361    ///
3362    /// * number of functions
3363    /// * number of globals
3364    /// * number of memories
3365    /// * number of tables
3366    /// * number of function types
3367    ///
3368    /// If the allocated size per instance is too small then instantiation of a
3369    /// module will fail at runtime with an error indicating how many bytes were
3370    /// needed.
3371    ///
3372    /// The default value for this is 1MiB.
3373    ///
3374    /// This provides an upper-bound on the total size of core instance
3375    /// metadata-related allocations, along with
3376    /// [`PoolingAllocationConfig::total_core_instances`]. The upper bound is
3377    ///
3378    /// ```text
3379    /// total_core_instances * max_core_instance_size
3380    /// ```
3381    ///
3382    /// where `max_core_instance_size` is rounded up to the size and alignment of
3383    /// the internal representation of the metadata.
3384    pub fn max_core_instance_size(&mut self, size: usize) -> &mut Self {
3385        self.config.limits.core_instance_size = size;
3386        self
3387    }
3388
3389    /// The maximum number of defined tables for a core module (default is `1`).
3390    ///
3391    /// This value controls the capacity of the `VMTableDefinition` table in
3392    /// each instance's `VMContext` structure.
3393    ///
3394    /// The allocated size of the table will be `tables *
3395    /// sizeof(VMTableDefinition)` for each instance regardless of how many
3396    /// tables are defined by an instance's module.
3397    pub fn max_tables_per_module(&mut self, tables: u32) -> &mut Self {
3398        self.config.limits.max_tables_per_module = tables;
3399        self
3400    }
3401
3402    /// The maximum table elements for any table defined in a module (default is
3403    /// `20000`).
3404    ///
3405    /// If a table's minimum element limit is greater than this value, the
3406    /// module will fail to instantiate.
3407    ///
3408    /// If a table's maximum element limit is unbounded or greater than this
3409    /// value, the maximum will be `table_elements` for the purpose of any
3410    /// `table.grow` instruction.
3411    ///
3412    /// This value is used to reserve the maximum space for each supported
3413    /// table; table elements are pointer-sized in the Wasmtime runtime.
3414    /// Therefore, the space reserved for each instance is `tables *
3415    /// table_elements * sizeof::<*const ()>`.
3416    pub fn table_elements(&mut self, elements: usize) -> &mut Self {
3417        self.config.limits.table_elements = elements;
3418        self
3419    }
3420
3421    /// The maximum number of defined linear memories for a module (default is
3422    /// `1`).
3423    ///
3424    /// This value controls the capacity of the `VMMemoryDefinition` table in
3425    /// each core instance's `VMContext` structure.
3426    ///
3427    /// The allocated size of the table will be `memories *
3428    /// sizeof(VMMemoryDefinition)` for each core instance regardless of how
3429    /// many memories are defined by the core instance's module.
3430    pub fn max_memories_per_module(&mut self, memories: u32) -> &mut Self {
3431        self.config.limits.max_memories_per_module = memories;
3432        self
3433    }
3434
3435    /// The maximum byte size that any WebAssembly linear memory may grow to.
3436    ///
3437    /// This option defaults to 4 GiB meaning that for 32-bit linear memories
3438    /// there is no restrictions. 64-bit linear memories will not be allowed to
3439    /// grow beyond 4 GiB by default.
3440    ///
3441    /// If a memory's minimum size is greater than this value, the module will
3442    /// fail to instantiate.
3443    ///
3444    /// If a memory's maximum size is unbounded or greater than this value, the
3445    /// maximum will be `max_memory_size` for the purpose of any `memory.grow`
3446    /// instruction.
3447    ///
3448    /// This value is used to control the maximum accessible space for each
3449    /// linear memory of a core instance. This can be thought of as a simple
3450    /// mechanism like [`Store::limiter`](crate::Store::limiter) to limit memory
3451    /// at runtime. This value can also affect striping/coloring behavior when
3452    /// used in conjunction with
3453    /// [`memory_protection_keys`](PoolingAllocationConfig::memory_protection_keys).
3454    ///
3455    /// The virtual memory reservation size of each linear memory is controlled
3456    /// by the [`Config::memory_reservation`] setting and this method's
3457    /// configuration cannot exceed [`Config::memory_reservation`].
3458    pub fn max_memory_size(&mut self, bytes: usize) -> &mut Self {
3459        self.config.limits.max_memory_size = bytes;
3460        self
3461    }
3462
3463    /// Configures whether memory protection keys (MPK) should be used for more
3464    /// efficient layout of pool-allocated memories.
3465    ///
3466    /// When using the pooling allocator (see [`Config::allocation_strategy`],
3467    /// [`InstanceAllocationStrategy::Pooling`]), memory protection keys can
3468    /// reduce the total amount of allocated virtual memory by eliminating guard
3469    /// regions between WebAssembly memories in the pool. It does so by
3470    /// "coloring" memory regions with different memory keys and setting which
3471    /// regions are accessible each time executions switches from host to guest
3472    /// (or vice versa).
3473    ///
3474    /// Leveraging MPK requires configuring a smaller-than-default
3475    /// [`max_memory_size`](PoolingAllocationConfig::max_memory_size) to enable
3476    /// this coloring/striping behavior. For example embeddings might want to
3477    /// reduce the default 4G allowance to 128M.
3478    ///
3479    /// MPK is only available on Linux (called `pku` there) and recent x86
3480    /// systems; we check for MPK support at runtime by examining the `CPUID`
3481    /// register. This configuration setting can be in three states:
3482    ///
3483    /// - `auto`: if MPK support is available the guard regions are removed; if
3484    ///   not, the guard regions remain
3485    /// - `enable`: use MPK to eliminate guard regions; fail if MPK is not
3486    ///   supported
3487    /// - `disable`: never use MPK
3488    ///
3489    /// By default this value is `disabled`, but may become `auto` in future
3490    /// releases.
3491    ///
3492    /// __WARNING__: this configuration options is still experimental--use at
3493    /// your own risk! MPK uses kernel and CPU features to protect memory
3494    /// regions; you may observe segmentation faults if anything is
3495    /// misconfigured.
3496    #[cfg(feature = "memory-protection-keys")]
3497    pub fn memory_protection_keys(&mut self, enable: MpkEnabled) -> &mut Self {
3498        self.config.memory_protection_keys = enable;
3499        self
3500    }
3501
3502    /// Sets an upper limit on how many memory protection keys (MPK) Wasmtime
3503    /// will use.
3504    ///
3505    /// This setting is only applicable when
3506    /// [`PoolingAllocationConfig::memory_protection_keys`] is set to `enable`
3507    /// or `auto`. Configuring this above the HW and OS limits (typically 15)
3508    /// has no effect.
3509    ///
3510    /// If multiple Wasmtime engines are used in the same process, note that all
3511    /// engines will share the same set of allocated keys; this setting will
3512    /// limit how many keys are allocated initially and thus available to all
3513    /// other engines.
3514    #[cfg(feature = "memory-protection-keys")]
3515    pub fn max_memory_protection_keys(&mut self, max: usize) -> &mut Self {
3516        self.config.max_memory_protection_keys = max;
3517        self
3518    }
3519
3520    /// Check if memory protection keys (MPK) are available on the current host.
3521    ///
3522    /// This is a convenience method for determining MPK availability using the
3523    /// same method that [`MpkEnabled::Auto`] does. See
3524    /// [`PoolingAllocationConfig::memory_protection_keys`] for more
3525    /// information.
3526    #[cfg(feature = "memory-protection-keys")]
3527    pub fn are_memory_protection_keys_available() -> bool {
3528        crate::runtime::vm::mpk::is_supported()
3529    }
3530
3531    /// The maximum number of concurrent GC heaps supported (default is `1000`).
3532    ///
3533    /// This value has a direct impact on the amount of memory allocated by the
3534    /// pooling instance allocator.
3535    ///
3536    /// The pooling instance allocator allocates a GC heap pool, where each
3537    /// entry in the pool contains the space needed for each GC heap used by a
3538    /// store.
3539    #[cfg(feature = "gc")]
3540    pub fn total_gc_heaps(&mut self, count: u32) -> &mut Self {
3541        self.config.limits.total_gc_heaps = count;
3542        self
3543    }
3544}
3545
3546#[cfg(feature = "std")]
3547fn detect_host_feature(feature: &str) -> Option<bool> {
3548    #[cfg(target_arch = "aarch64")]
3549    {
3550        return match feature {
3551            "lse" => Some(std::arch::is_aarch64_feature_detected!("lse")),
3552            "paca" => Some(std::arch::is_aarch64_feature_detected!("paca")),
3553            "fp16" => Some(std::arch::is_aarch64_feature_detected!("fp16")),
3554
3555            _ => None,
3556        };
3557    }
3558
3559    // `is_s390x_feature_detected` is nightly only for now, so use the
3560    // STORE FACILITY LIST EXTENDED instruction as a temporary measure.
3561    #[cfg(target_arch = "s390x")]
3562    {
3563        let mut facility_list: [u64; 4] = [0; 4];
3564        unsafe {
3565            core::arch::asm!(
3566                "stfle 0({})",
3567                in(reg_addr) facility_list.as_mut_ptr() ,
3568                inout("r0") facility_list.len() as u64 - 1 => _,
3569                options(nostack)
3570            );
3571        }
3572        let get_facility_bit = |n: usize| {
3573            // NOTE: bits are numbered from the left.
3574            facility_list[n / 64] & (1 << (63 - (n % 64))) != 0
3575        };
3576
3577        return match feature {
3578            "mie3" => Some(get_facility_bit(61)),
3579            "mie4" => Some(get_facility_bit(84)),
3580            "vxrs_ext2" => Some(get_facility_bit(148)),
3581            "vxrs_ext3" => Some(get_facility_bit(198)),
3582
3583            _ => None,
3584        };
3585    }
3586
3587    #[cfg(target_arch = "riscv64")]
3588    {
3589        return match feature {
3590            // due to `is_riscv64_feature_detected` is not stable.
3591            // we cannot use it. For now lie and say all features are always
3592            // found to keep tests working.
3593            _ => Some(true),
3594        };
3595    }
3596
3597    #[cfg(target_arch = "x86_64")]
3598    {
3599        return match feature {
3600            "cmpxchg16b" => Some(std::is_x86_feature_detected!("cmpxchg16b")),
3601            "sse3" => Some(std::is_x86_feature_detected!("sse3")),
3602            "ssse3" => Some(std::is_x86_feature_detected!("ssse3")),
3603            "sse4.1" => Some(std::is_x86_feature_detected!("sse4.1")),
3604            "sse4.2" => Some(std::is_x86_feature_detected!("sse4.2")),
3605            "popcnt" => Some(std::is_x86_feature_detected!("popcnt")),
3606            "avx" => Some(std::is_x86_feature_detected!("avx")),
3607            "avx2" => Some(std::is_x86_feature_detected!("avx2")),
3608            "fma" => Some(std::is_x86_feature_detected!("fma")),
3609            "bmi1" => Some(std::is_x86_feature_detected!("bmi1")),
3610            "bmi2" => Some(std::is_x86_feature_detected!("bmi2")),
3611            "avx512bitalg" => Some(std::is_x86_feature_detected!("avx512bitalg")),
3612            "avx512dq" => Some(std::is_x86_feature_detected!("avx512dq")),
3613            "avx512f" => Some(std::is_x86_feature_detected!("avx512f")),
3614            "avx512vl" => Some(std::is_x86_feature_detected!("avx512vl")),
3615            "avx512vbmi" => Some(std::is_x86_feature_detected!("avx512vbmi")),
3616            "lzcnt" => Some(std::is_x86_feature_detected!("lzcnt")),
3617
3618            _ => None,
3619        };
3620    }
3621
3622    #[allow(
3623        unreachable_code,
3624        reason = "reachable or not depending on if a target above matches"
3625    )]
3626    {
3627        let _ = feature;
3628        return None;
3629    }
3630}