Struct wiggle::wasmtime_crate::Config

source · [−]

pub struct Config { /* private fields */ }

Expand description

Global configuration options used to create an Engine and customize its behavior.

This structure exposed a builder-like interface and is primarily consumed by Engine::new()

Implementations

source

impl Config

source

pub fn new() -> Config

Creates a new configuration object with the default configuration specified.

source

pub fn debug_info(&mut self, enable: bool) -> &mut Config

Configures whether DWARF debug information will be emitted during compilation.

By default this option is false.

source

pub fn wasm_backtrace(&mut self, enable: bool) -> &mut Config

Configures whether backtraces exist in a Trap.

Enabled by default, this feature builds in support to generate backtraces at runtime for WebAssembly modules. This means that unwinding information is compiled into wasm modules and necessary runtime dependencies are enabled as well.

When disabled, wasm backtrace details are ignored, and crate::Trap::trace() will always return None.

source

pub fn wasm_backtrace_details(
&mut self,
enable: WasmBacktraceDetails
) -> &mut Config

Configures whether backtraces in Trap will parse debug info in the wasm file to have filename/line number information.

When enabled this will causes modules to retain debugging information found in wasm binaries. This debug information will be used when a trap happens to symbolicate each stack frame and attempt to print a filename/line number for each wasm frame in the stack trace.

By default this option is WasmBacktraceDetails::Environment, meaning that wasm will read WASMTIME_BACKTRACE_DETAILS to indicate whether details should be parsed.

source

pub fn consume_fuel(&mut self, enable: bool) -> &mut Config

Configures whether execution of WebAssembly will “consume fuel” to either halt or yield execution as desired.

This can be used to deterministically prevent infinitely-executing WebAssembly code by instrumenting generated code to consume fuel as it executes. When fuel runs out the behavior is defined by configuration within a Store, and by default a trap is raised.

Note that a Store starts with no fuel, so if you enable this option you’ll have to be sure to pour some fuel into Store before executing some code.

By default this option is false.

source

pub fn epoch_interruption(&mut self, enable: bool) -> &mut Config

Enables epoch-based interruption.

When executing code in async mode, we sometimes want to implement a form of cooperative timeslicing: long-running Wasm guest code should periodically yield to the executor loop. This yielding could be implemented by using “fuel” (see consume_fuel). However, fuel instrumentation is somewhat expensive: it modifies the compiled form of the Wasm code so that it maintains a precise instruction count, frequently checking this count against the remaining fuel. If one does not need this precise count or deterministic interruptions, and only needs a periodic interrupt of some form, then It would be better to have a more lightweight mechanism.

Epoch-based interruption is that mechanism. There is a global “epoch”, which is a counter that divides time into arbitrary periods (or epochs). This counter lives on the Engine and can be incremented by calling Engine::increment_epoch. Epoch-based instrumentation works by setting a “deadline epoch”. The compiled code knows the deadline, and at certain points, checks the current epoch against that deadline. It will yield if the deadline has been reached.

The idea is that checking an infrequently-changing counter is cheaper than counting and frequently storing a precise metric (instructions executed) locally. The interruptions are not deterministic, but if the embedder increments the epoch in a periodic way (say, every regular timer tick by a thread or signal handler), then we can ensure that all async code will yield to the executor within a bounded time.

The Store tracks the deadline, and controls what happens when the deadline is reached during execution. Several behaviors are possible:

Trap if code is executing when the epoch deadline is met. See Store::epoch_deadline_trap.
Call an arbitrary function. This function may chose to trap or increment the epoch. See Store::epoch_deadline_callback.
Yield to the executor loop, then resume when the future is next polled. See Store::epoch_deadline_async_yield_and_update.

Trapping is the default. The yielding behaviour may be used for the timeslicing behavior described above.

This feature is available with or without async support. However, without async support, the timeslicing behaviour is not available. This means epoch-based interruption can only serve as a simple external-interruption mechanism.

An initial deadline can be set before executing code by calling Store::set_epoch_deadline.

When to use fuel vs. epochs

In general, epoch-based interruption results in faster execution. This difference is sometimes significant: in some measurements, up to 2-3x. This is because epoch-based interruption does less work: it only watches for a global rarely-changing counter to increment, rather than keeping a local frequently-changing counter and comparing it to a deadline.

Fuel, in contrast, should be used when deterministic yielding or trapping is needed. For example, if it is required that the same function call with the same starting state will always either complete or trap with an out-of-fuel error, deterministically, then fuel with a fixed bound should be used.

pub fn max_wasm_stack(&mut self, size: usize) -> Result<&mut Config, Error>

Configures the maximum amount of stack space available for executing WebAssembly code.

WebAssembly has well-defined semantics on stack overflow. This is intended to be a knob which can help configure how much stack space wasm execution is allowed to consume. Note that the number here is not super-precise, but rather wasm will take at most “pretty close to this much” stack space.

If a wasm call (or series of nested wasm calls) take more stack space than the size specified then a stack overflow trap will be raised.

When the async feature is enabled, this value cannot exceed the async_stack_size option. Be careful not to set this value too close to async_stack_size as doing so may limit how much stack space is available for host functions. Unlike wasm functions that trap on stack overflow, a host function that overflows the stack will abort the process.

By default this option is 512 KiB.

source

pub fn wasm_threads(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly threads proposal will be enabled for compilation.

The WebAssembly threads proposal is not currently fully standardized and is undergoing development. Additionally the support in wasmtime itself is still being worked on. Support for this feature can be enabled through this method for appropriate wasm modules.

This feature gates items such as shared memories and atomic instructions. Note that enabling the threads feature will also enable the bulk memory feature.

This is false by default.

Note: Wasmtime does not implement everything for the wasm threads spec at this time, so bugs, panics, and possibly segfaults should be expected. This should not be enabled in a production setting right now.

source

pub fn wasm_reference_types(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly reference types proposal will be enabled for compilation.

This feature gates items such as the externref and funcref types as well as allowing a module to define multiple tables.

Note that enabling the reference types feature will also enable the bulk memory feature.

This feature is true by default.

source

pub fn wasm_simd(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly SIMD proposal will be enabled for compilation.

The WebAssembly SIMD proposal. This feature gates items such as the v128 type and all of its operators being in a module. Note that this does not enable the relaxed simd proposal as that is not implemented in Wasmtime at this time.

On x86_64 platforms note that enabling this feature requires SSE 4.2 and below to be available on the target platform. Compilation will fail if the compile target does not include SSE 4.2.

This is true by default.

source

pub fn wasm_bulk_memory(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly bulk memory operations proposal will be enabled for compilation.

This feature gates items such as the memory.copy instruction, passive data/table segments, etc, being in a module.

This is true by default.

source

pub fn wasm_multi_value(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly multi-value proposal will be enabled for compilation.

This feature gates functions and blocks returning multiple values in a module, for example.

This is true by default.

source

pub fn wasm_multi_memory(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly multi-memory proposal will be enabled for compilation.

This feature gates modules having more than one linear memory declaration or import.

This is false by default.

source

pub fn wasm_memory64(&mut self, enable: bool) -> &mut Config

Configures whether the WebAssembly memory64 proposal will be enabled for compilation.

Note that this the upstream specification is not finalized and Wasmtime may also have bugs for this feature since it hasn’t been exercised much.

This is false by default.

source

pub fn profiler(
&mut self,
profile: ProfilingStrategy
) -> Result<&mut Config, Error>

Creates a default profiler based on the profiling strategy chosen.

Profiler creation calls the type’s default initializer where the purpose is really just to put in place the type used for profiling.

source

pub fn with_host_memory(
&mut self,
mem_creator: Arc<dyn MemoryCreator + 'static>
) -> &mut Config

Sets a custom memory creator.

Custom memory creators are used when creating host Memory objects or when creating instance linear memories for the on-demand instance allocation strategy.

source

pub fn allocation_strategy(
&mut self,
strategy: InstanceAllocationStrategy
) -> &mut Config

Sets the instance allocation strategy to use.

When using the pooling instance allocation strategy, all linear memories will be created as “static” and the Config::static_memory_maximum_size and Config::static_memory_guard_size options will be used to configure the virtual memory allocations of linear memories.

source

pub fn static_memory_maximum_size(&mut self, max_size: u64) -> &mut Config

Configures the maximum size, in bytes, where a linear memory is considered static, above which it’ll be considered dynamic.

Note: this value has important performance ramifications, be sure to understand what this value does before tweaking it and benchmarking.

This function configures the threshold for wasm memories whether they’re implemented as a dynamically relocatable chunk of memory or a statically located chunk of memory. The max_size parameter here is the size, in bytes, where if the maximum size of a linear memory is below max_size then it will be statically allocated with enough space to never have to move. If the maximum size of a linear memory is larger than max_size then wasm memory will be dynamically located and may move in memory through growth operations.

Specifying a max_size of 0 means that all memories will be dynamic and may be relocated through memory.grow. Also note that if any wasm memory’s maximum size is below max_size then it will still reserve max_size bytes in the virtual memory space.

Static vs Dynamic Memory

Linear memories represent contiguous arrays of bytes, but they can also be grown through the API and wasm instructions. When memory is grown if space hasn’t been preallocated then growth may involve relocating the base pointer in memory. Memories in Wasmtime are classified in two different ways:

static - these memories preallocate all space necessary they’ll ever need, meaning that the base pointer of these memories is never moved. Static memories may take more virtual memory space because of pre-reserving space for memories.
dynamic - these memories are not preallocated and may move during growth operations. Dynamic memories consume less virtual memory space because they don’t need to preallocate space for future growth.

Static memories can be optimized better in JIT code because once the base address is loaded in a function it’s known that we never need to reload it because it never changes, memory.grow is generally a pretty fast operation because the wasm memory is never relocated, and under some conditions bounds checks can be elided on memory accesses.

Dynamic memories can’t be quite as heavily optimized because the base address may need to be reloaded more often, they may require relocating lots of data on memory.grow, and dynamic memories require unconditional bounds checks on all memory accesses.

Should you use static or dynamic memory?

In general you probably don’t need to change the value of this property. The defaults here are optimized for each target platform to consume a reasonable amount of physical memory while also generating speedy machine code.

One of the main reasons you may want to configure this today is if your environment can’t reserve virtual memory space for each wasm linear memory. On 64-bit platforms wasm memories require a 6GB reservation by default, and system limits may prevent this in some scenarios. In this case you may wish to force memories to be allocated dynamically meaning that the virtual memory footprint of creating a wasm memory should be exactly what’s used by the wasm itself.

For 32-bit memories a static memory must contain at least 4GB of reserved address space plus a guard page to elide any bounds checks at all. Smaller static memories will use similar bounds checks as dynamic memories.

Default

The default value for this property depends on the host platform. For 64-bit platforms there’s lots of address space available, so the default configured here is 4GB. WebAssembly linear memories currently max out at 4GB which means that on 64-bit platforms Wasmtime by default always uses a static memory. This, coupled with a sufficiently sized guard region, should produce the fastest JIT code on 64-bit platforms, but does require a large address space reservation for each wasm memory.

For 32-bit platforms this value defaults to 1GB. This means that wasm memories whose maximum size is less than 1GB will be allocated statically, otherwise they’ll be considered dynamic.

Static Memory and Pooled Instance Allocation

When using the pooling instance allocator memories are considered to always be static memories, they are never dynamic. This setting configures the size of linear memory to reserve for each memory in the pooling allocator.

source

pub fn static_memory_forced(&mut self, force: bool) -> &mut Config

Indicates that the “static” style of memory should always be used.

This configuration option enables selecting the “static” option for all linear memories created within this Config. This means that all memories will be allocated up-front and will never move. Additionally this means that all memories are synthetically limited by the Config::static_memory_maximum_size option, irregardless of what the actual maximum size is on the memory’s original type.

For the difference between static and dynamic memories, see the Config::static_memory_maximum_size.

source

pub fn static_memory_guard_size(&mut self, guard_size: u64) -> &mut Config

Configures the size, in bytes, of the guard region used at the end of a static memory’s address space reservation.

Note: this value has important performance ramifications, be sure to understand what this value does before tweaking it and benchmarking.

All WebAssembly loads/stores are bounds-checked and generate a trap if they’re out-of-bounds. Loads and stores are often very performance critical, so we want the bounds check to be as fast as possible! Accelerating these memory accesses is the motivation for a guard after a memory allocation.

Memories (both static and dynamic) can be configured with a guard at the end of them which consists of unmapped virtual memory. This unmapped memory will trigger a memory access violation (e.g. segfault) if accessed. This allows JIT code to elide bounds checks if it can prove that an access, if out of bounds, would hit the guard region. This means that having such a guard of unmapped memory can remove the need for bounds checks in JIT code.

For the difference between static and dynamic memories, see the Config::static_memory_maximum_size.

How big should the guard be?

In general, like with configuring static_memory_maximum_size, you probably don’t want to change this value from the defaults. Otherwise, though, the size of the guard region affects the number of bounds checks needed for generated wasm code. More specifically, loads/stores with immediate offsets will generate bounds checks based on how big the guard page is.

For 32-bit memories a 4GB static memory is required to even start removing bounds checks. A 4GB guard size will guarantee that the module has zero bounds checks for memory accesses. A 2GB guard size will eliminate all bounds checks with an immediate offset less than 2GB. A guard size of zero means that all memory accesses will still have bounds checks.

Default

The default value for this property is 2GB on 64-bit platforms. This allows eliminating almost all bounds checks on loads/stores with an immediate offset of less than 2GB. On 32-bit platforms this defaults to 64KB.

Static vs Dynamic Guard Size

Note that for now the static memory guard size must be at least as large as the dynamic memory guard size, so configuring this property to be smaller than the dynamic memory guard size will have no effect.

source

pub fn dynamic_memory_guard_size(&mut self, guard_size: u64) -> &mut Config

Configures the size, in bytes, of the guard region used at the end of a dynamic memory’s address space reservation.

For the difference between static and dynamic memories, see the Config::static_memory_maximum_size

For more information about what a guard is, see the documentation on Config::static_memory_guard_size.

Note that the size of the guard region for dynamic memories is not super critical for performance. Making it reasonably-sized can improve generated code slightly, but for maximum performance you’ll want to lean towards static memories rather than dynamic anyway.

Also note that the dynamic memory guard size must be smaller than the static memory guard size, so if a large dynamic memory guard is specified then the static memory guard size will also be automatically increased.

Default

This value defaults to 64KB.

source

pub fn dynamic_memory_reserved_for_growth(
&mut self,
reserved: u64
) -> &mut Config

Configures the size, in bytes, of the extra virtual memory space reserved after a “dynamic” memory for growing into.

For the difference between static and dynamic memories, see the Config::static_memory_maximum_size

Dynamic memories can be relocated in the process’s virtual address space on growth and do not always reserve their entire space up-front. This means that a growth of the memory may require movement in the address space, which in the worst case can copy a large number of bytes from one region to another.

This setting configures how many bytes are reserved after the initial reservation for a dynamic memory for growing into. A value of 0 here means that no extra bytes are reserved and all calls to memory.grow will need to relocate the wasm linear memory (copying all the bytes). A value of 1 megabyte, however, means that memory.grow can allocate up to a megabyte of extra memory before the memory needs to be moved in linear memory.

Note that this is a currently simple heuristic for optimizing the growth of dynamic memories, primarily implemented for the memory64 proposal where all memories are currently “dynamic”. This is unlikely to be a one-size-fits-all style approach and if you’re an embedder running into issues with dynamic memories and growth and are interested in having other growth strategies available here please feel free to open an issue on the Wasmtime repository!

Default

For 64-bit platforms this defaults to 2GB, and for 32-bit platforms this defaults to 1MB.

source

pub fn guard_before_linear_memory(&mut self, guard: bool) -> &mut Config

Indicates whether a guard region is present before allocations of linear memory.

Guard regions before linear memories are never used during normal operation of WebAssembly modules, even if they have out-of-bounds loads. The only purpose for a preceding guard region in linear memory is extra protection against possible bugs in code generators like Cranelift. This setting does not affect performance in any way, but will result in larger virtual memory reservations for linear memories (it won’t actually ever use more memory, just use more of the address space).

The size of the guard region before linear memory is the same as the guard size that comes after linear memory, which is configured by Config::static_memory_guard_size and Config::dynamic_memory_guard_size.

Default

This value defaults to true.

source

pub fn module_version(
&mut self,
strategy: ModuleVersionStrategy
) -> Result<&mut Config, Error>

Configure the version information used in serialized and deserialzied crate::Modules. This effects the behavior of [crate::Module::serialize()], as well as crate::Module::deserialize() and related functions.

The default strategy is to use the wasmtime crate’s Cargo package version.

source

pub fn generate_address_map(&mut self, generate: bool) -> &mut Config

Configures whether compiled artifacts will contain information to map native program addresses back to the original wasm module.

This configuration option is true by default and, if enables, generates the appropriate tables in compiled modules to map from native address back to wasm source addresses. This is used for displaying wasm program counters in backtraces as well as generating filenames/line numbers if so configured as well (and the original wasm module has DWARF debugging information present).