Wasmtime
config.h File Reference

Wasmtime-specific extensions to wasm_config_t. More...

#include <wasm.h>
#include <wasmtime/conf.h>
#include <wasmtime/error.h>

Go to the source code of this file.

Data Structures

struct  wasmtime_linear_memory
 
struct  wasmtime_memory_creator
 

Typedefs

typedef uint8_t wasmtime_strategy_t
 Specifier for how Wasmtime will compile code, values are in wasmtime_strategy_enum.
 
typedef uint8_t wasmtime_opt_level_t
 Specifier of what optimization level to use for generated JIT code. More...
 
typedef uint8_t wasmtime_profiling_strategy_t
 Different ways wasmtime can enable profiling JIT code. More...
 
typedef uint8_t *(* wasmtime_memory_get_callback_t) (void *env, size_t *byte_size, size_t *byte_capacity)
 
typedef wasmtime_error_t *(* wasmtime_memory_grow_callback_t) (void *env, size_t new_size)
 
typedef struct wasmtime_linear_memory wasmtime_linear_memory_t
 
typedef wasmtime_error_t *(* wasmtime_new_memory_callback_t) (void *env, const wasm_memorytype_t *ty, size_t minimum, size_t maximum, size_t reserved_size_in_bytes, size_t guard_size_in_bytes, wasmtime_linear_memory_t *memory_ret)
 
typedef struct wasmtime_memory_creator wasmtime_memory_creator_t
 

Enumerations

enum  wasmtime_strategy_enum { WASMTIME_STRATEGY_AUTO , WASMTIME_STRATEGY_CRANELIFT }
 Different ways that Wasmtime can compile WebAssembly. More...
 
enum  wasmtime_opt_level_enum { WASMTIME_OPT_LEVEL_NONE , WASMTIME_OPT_LEVEL_SPEED , WASMTIME_OPT_LEVEL_SPEED_AND_SIZE }
 Different ways Wasmtime can optimize generated code. More...
 
enum  wasmtime_profiling_strategy_enum { WASMTIME_PROFILING_STRATEGY_NONE , WASMTIME_PROFILING_STRATEGY_JITDUMP , WASMTIME_PROFILING_STRATEGY_VTUNE , WASMTIME_PROFILING_STRATEGY_PERFMAP }
 Different ways to profile JIT code. More...
 

Functions

void wasmtime_config_debug_info_set (wasm_config_t *, bool)
 Configures whether DWARF debug information is constructed at runtime to describe JIT code. More...
 
void wasmtime_config_consume_fuel_set (wasm_config_t *, bool)
 Whether or not fuel is enabled for generated code. More...
 
void wasmtime_config_epoch_interruption_set (wasm_config_t *, bool)
 Whether or not epoch-based interruption is enabled for generated code. More...
 
void wasmtime_config_max_wasm_stack_set (wasm_config_t *, size_t)
 Configures the maximum stack size, in bytes, that JIT code can use. More...
 
void wasmtime_config_wasm_threads_set (wasm_config_t *, bool)
 Configures whether the WebAssembly threading proposal is enabled. More...
 
void wasmtime_config_wasm_tail_call_set (wasm_config_t *, bool)
 Configures whether the WebAssembly tail call proposal is enabled. More...
 
void wasmtime_config_wasm_reference_types_set (wasm_config_t *, bool)
 Configures whether the WebAssembly reference types proposal is enabled. More...
 
void wasmtime_config_wasm_function_references_set (wasm_config_t *, bool)
 Configures whether the WebAssembly typed function reference types proposal is enabled. More...
 
void wasmtime_config_wasm_gc_set (wasm_config_t *, bool)
 Configures whether the WebAssembly GC proposal is enabled. More...
 
void wasmtime_config_wasm_simd_set (wasm_config_t *, bool)
 Configures whether the WebAssembly SIMD proposal is enabled. More...
 
void wasmtime_config_wasm_relaxed_simd_set (wasm_config_t *, bool)
 Configures whether the WebAssembly relaxed SIMD proposal is enabled. More...
 
void wasmtime_config_wasm_relaxed_simd_deterministic_set (wasm_config_t *, bool)
 Configures whether the WebAssembly relaxed SIMD proposal is in deterministic mode. More...
 
void wasmtime_config_wasm_bulk_memory_set (wasm_config_t *, bool)
 Configures whether the WebAssembly bulk memory proposal is enabled. More...
 
void wasmtime_config_wasm_multi_value_set (wasm_config_t *, bool)
 Configures whether the WebAssembly multi value proposal is enabled. More...
 
void wasmtime_config_wasm_multi_memory_set (wasm_config_t *, bool)
 Configures whether the WebAssembly multi-memory proposal is enabled. More...
 
void wasmtime_config_wasm_memory64_set (wasm_config_t *, bool)
 Configures whether the WebAssembly memory64 proposal is enabled. More...
 
void wasmtime_config_wasm_wide_arithmetic_set (wasm_config_t *, bool)
 Configures whether the WebAssembly wide-arithmetic proposal is enabled. More...
 
void wasmtime_config_strategy_set (wasm_config_t *, wasmtime_strategy_t)
 Configures how JIT code will be compiled. More...
 
void wasmtime_config_parallel_compilation_set (wasm_config_t *, bool)
 Configure whether wasmtime should compile a module using multiple threads. More...
 
void wasmtime_config_cranelift_debug_verifier_set (wasm_config_t *, bool)
 Configures whether Cranelift's debug verifier is enabled. More...
 
void wasmtime_config_cranelift_nan_canonicalization_set (wasm_config_t *, bool)
 Configures whether Cranelift should perform a NaN-canonicalization pass. More...
 
void wasmtime_config_cranelift_opt_level_set (wasm_config_t *, wasmtime_opt_level_t)
 Configures Cranelift's optimization level for JIT code. More...
 
void wasmtime_config_profiler_set (wasm_config_t *, wasmtime_profiling_strategy_t)
 Configures the profiling strategy used for JIT code. More...
 
void wasmtime_config_memory_may_move_set (wasm_config_t *, bool)
 Configures whether memory_reservation is the maximal size of linear memory. More...
 
void wasmtime_config_memory_reservation_set (wasm_config_t *, uint64_t)
 Configures the size, in bytes, of initial memory reservation size for linear memories. More...
 
void wasmtime_config_memory_guard_size_set (wasm_config_t *, uint64_t)
 Configures the guard region size for linear memory. More...
 
void wasmtime_config_memory_reservation_for_growth_set (wasm_config_t *, uint64_t)
 Configures the size, in bytes, of the extra virtual memory space reserved for memories to grow into after being relocated. More...
 
void wasmtime_config_native_unwind_info_set (wasm_config_t *, bool)
 Configures whether to generate native unwind information (e.g. .eh_frame on Linux). More...
 
wasmtime_error_twasmtime_config_cache_config_load (wasm_config_t *, const char *)
 Enables Wasmtime's cache and loads configuration from the specified path. More...
 
wasmtime_error_twasmtime_config_target_set (wasm_config_t *, const char *)
 Configures the target triple that this configuration will produce machine code for. More...
 
void wasmtime_config_cranelift_flag_enable (wasm_config_t *, const char *)
 Enables a target-specific flag in Cranelift. More...
 
void wasmtime_config_cranelift_flag_set (wasm_config_t *, const char *key, const char *value)
 Sets a target-specific flag in Cranelift to the specified value. More...
 
void wasmtime_config_macos_use_mach_ports_set (wasm_config_t *, bool)
 Configures whether, when on macOS, Mach ports are used for exception handling instead of traditional Unix-based signal handling. More...
 
void wasmtime_config_host_memory_creator_set (wasm_config_t *, wasmtime_memory_creator_t *)
 
void wasmtime_config_memory_init_cow_set (wasm_config_t *, bool)
 Configures whether copy-on-write memory-mapped data is used to initialize a linear memory. More...
 

Detailed Description

Wasmtime-specific extensions to wasm_config_t.

Typedef Documentation

◆ wasmtime_linear_memory_t

A LinearMemory instance created from a wasmtime_new_memory_callback_t.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/trait.LinearMemory.html

◆ wasmtime_memory_creator_t

A representation of custom memory creator and methods for an instance of LinearMemory.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/trait.MemoryCreator.html

◆ wasmtime_memory_get_callback_t

typedef uint8_t *(* wasmtime_memory_get_callback_t) (void *env, size_t *byte_size, size_t *byte_capacity)

Return the data from a LinearMemory instance.

The size in bytes as well as the maximum number of bytes that can be allocated should be returned as well.

For more information about see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/trait.LinearMemory.html

◆ wasmtime_memory_grow_callback_t

typedef wasmtime_error_t *(* wasmtime_memory_grow_callback_t) (void *env, size_t new_size)

Grow the memory to the new_size in bytes.

For more information about the parameters see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/trait.LinearMemory.html#tymethod.grow_to

◆ wasmtime_new_memory_callback_t

typedef wasmtime_error_t *(* wasmtime_new_memory_callback_t) (void *env, const wasm_memorytype_t *ty, size_t minimum, size_t maximum, size_t reserved_size_in_bytes, size_t guard_size_in_bytes, wasmtime_linear_memory_t *memory_ret)

A callback to create a new LinearMemory from the specified parameters.

The result should be written to memory_ret and wasmtime will own the values written into that struct.

This callback must be thread-safe.

For more information about the parameters see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/trait.MemoryCreator.html#tymethod.new_memory

◆ wasmtime_opt_level_t

typedef uint8_t wasmtime_opt_level_t

Specifier of what optimization level to use for generated JIT code.

See wasmtime_opt_level_enum for possible values.

◆ wasmtime_profiling_strategy_t

Different ways wasmtime can enable profiling JIT code.

See wasmtime_profiling_strategy_enum for possible values.

Enumeration Type Documentation

◆ wasmtime_opt_level_enum

Different ways Wasmtime can optimize generated code.

The default value is WASMTIME_OPT_LEVEL_SPEED.

Enumerator
WASMTIME_OPT_LEVEL_NONE 

Generated code will not be optimized at all.

WASMTIME_OPT_LEVEL_SPEED 

Generated code will be optimized purely for speed.

WASMTIME_OPT_LEVEL_SPEED_AND_SIZE 

Generated code will be optimized, but some speed optimizations are disabled if they cause the generated code to be significantly larger.

◆ wasmtime_profiling_strategy_enum

Different ways to profile JIT code.

The default is WASMTIME_PROFILING_STRATEGY_NONE.

Enumerator
WASMTIME_PROFILING_STRATEGY_NONE 

No profiling is enabled at runtime.

WASMTIME_PROFILING_STRATEGY_JITDUMP 

Linux's "jitdump" support in perf is enabled and when Wasmtime is run under perf necessary calls will be made to profile generated JIT code.

WASMTIME_PROFILING_STRATEGY_VTUNE 

Support for VTune will be enabled and the VTune runtime will be informed, at runtime, about JIT code.

Note that this isn't always enabled at build time.

WASMTIME_PROFILING_STRATEGY_PERFMAP 

Linux's simple "perfmap" support in perf is enabled and when Wasmtime is run under perf necessary calls will be made to profile generated JIT code.

◆ wasmtime_strategy_enum

Different ways that Wasmtime can compile WebAssembly.

The default value is WASMTIME_STRATEGY_AUTO.

Enumerator
WASMTIME_STRATEGY_AUTO 

Automatically picks the compilation backend, currently always defaulting to Cranelift.

WASMTIME_STRATEGY_CRANELIFT 

Indicates that Wasmtime will unconditionally use Cranelift to compile WebAssembly code.

Function Documentation

◆ wasmtime_config_cache_config_load()

wasmtime_error_t * wasmtime_config_cache_config_load ( wasm_config_t ,
const char *   
)

Enables Wasmtime's cache and loads configuration from the specified path.

By default the Wasmtime compilation cache is disabled. The configuration path here can be NULL to use the default settings, and otherwise the argument here must be a file on the filesystem with TOML configuration - https://bytecodealliance.github.io/wasmtime/cli-cache.html.

An error is returned if the cache configuration could not be loaded or if the cache could not be enabled.

◆ wasmtime_config_consume_fuel_set()

void wasmtime_config_consume_fuel_set ( wasm_config_t ,
bool   
)

Whether or not fuel is enabled for generated code.

This setting is false by default. When enabled it will enable fuel counting meaning that fuel will be consumed every time a wasm instruction is executed, and trap when reaching zero.

◆ wasmtime_config_cranelift_debug_verifier_set()

void wasmtime_config_cranelift_debug_verifier_set ( wasm_config_t ,
bool   
)

Configures whether Cranelift's debug verifier is enabled.

This setting in false by default.

When cranelift is used for compilation this enables expensive debug checks within Cranelift itself to verify it's correct.

◆ wasmtime_config_cranelift_flag_enable()

void wasmtime_config_cranelift_flag_enable ( wasm_config_t ,
const char *   
)

Enables a target-specific flag in Cranelift.

This can be used, for example, to enable SSE4.2 on x86_64 hosts. Settings can be explored with wasmtime settings on the CLI.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.cranelift_flag_enable

◆ wasmtime_config_cranelift_flag_set()

void wasmtime_config_cranelift_flag_set ( wasm_config_t ,
const char *  key,
const char *  value 
)

Sets a target-specific flag in Cranelift to the specified value.

This can be used, for example, to enable SSE4.2 on x86_64 hosts. Settings can be explored with wasmtime settings on the CLI.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.cranelift_flag_set

◆ wasmtime_config_cranelift_nan_canonicalization_set()

void wasmtime_config_cranelift_nan_canonicalization_set ( wasm_config_t ,
bool   
)

Configures whether Cranelift should perform a NaN-canonicalization pass.

When Cranelift is used as a code generation backend this will configure it to replace NaNs with a single canonical value. This is useful for users requiring entirely deterministic WebAssembly computation.

This is not required by the WebAssembly spec, so it is not enabled by default.

The default value for this is false

◆ wasmtime_config_cranelift_opt_level_set()

void wasmtime_config_cranelift_opt_level_set ( wasm_config_t ,
wasmtime_opt_level_t   
)

Configures Cranelift's optimization level for JIT code.

This setting in WASMTIME_OPT_LEVEL_SPEED by default.

◆ wasmtime_config_debug_info_set()

void wasmtime_config_debug_info_set ( wasm_config_t ,
bool   
)

Configures whether DWARF debug information is constructed at runtime to describe JIT code.

This setting is false by default. When enabled it will attempt to inform native debuggers about DWARF debugging information for JIT code to more easily debug compiled WebAssembly via native debuggers. This can also sometimes improve the quality of output when profiling is enabled.

◆ wasmtime_config_epoch_interruption_set()

void wasmtime_config_epoch_interruption_set ( wasm_config_t ,
bool   
)

Whether or not epoch-based interruption is enabled for generated code.

This setting is false by default. When enabled wasm code will check the current epoch periodically and abort if the current epoch is beyond a store-configured limit.

Note that when this setting is enabled all stores will immediately trap and need to have their epoch deadline otherwise configured with wasmtime_context_set_epoch_deadline.

Note that the current epoch is engine-local and can be incremented with wasmtime_engine_increment_epoch.

◆ wasmtime_config_host_memory_creator_set()

void wasmtime_config_host_memory_creator_set ( wasm_config_t ,
wasmtime_memory_creator_t  
)

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.

The config does not take ownership of the wasmtime_memory_creator_t passed in, but instead copies all the values in the struct.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.with_host_memory

◆ wasmtime_config_macos_use_mach_ports_set()

void wasmtime_config_macos_use_mach_ports_set ( wasm_config_t ,
bool   
)

Configures whether, when on macOS, Mach ports are used for exception handling instead of traditional Unix-based signal handling.

This option defaults to true, using Mach ports by default.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.macos_use_mach_ports

◆ wasmtime_config_max_wasm_stack_set()

void wasmtime_config_max_wasm_stack_set ( wasm_config_t ,
size_t   
)

Configures the maximum stack size, in bytes, that JIT code can use.

This setting is 2MB by default. Configuring this setting will limit the amount of native stack space that JIT code can use while it is executing. If you're hitting stack overflow you can try making this setting larger, or if you'd like to limit wasm programs to less stack you can also configure this.

Note that this setting is not interpreted with 100% precision. Additionally the amount of stack space that wasm takes is always relative to the first invocation of wasm on the stack, so recursive calls with host frames in the middle will all need to fit within this setting.

◆ wasmtime_config_memory_guard_size_set()

void wasmtime_config_memory_guard_size_set ( wasm_config_t ,
uint64_t   
)

Configures the guard region size for linear memory.

For more information see the Rust documentation at https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.memory_guard_size.

◆ wasmtime_config_memory_init_cow_set()

void wasmtime_config_memory_init_cow_set ( wasm_config_t ,
bool   
)

Configures whether copy-on-write memory-mapped data is used to initialize a linear memory.

Initializing linear memory via a copy-on-write mapping can drastically improve instantiation costs of a WebAssembly module because copying memory is deferred. Additionally if a page of memory is only ever read from WebAssembly and never written too then the same underlying page of data will be reused between all instantiations of a module meaning that if a module is instantiated many times this can lower the overall memory required needed to run that module.

This option defaults to true.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.memory_init_cow

◆ wasmtime_config_memory_may_move_set()

void wasmtime_config_memory_may_move_set ( wasm_config_t ,
bool   
)

Configures whether memory_reservation is the maximal size of linear memory.

This setting is false by default.

For more information see the Rust documentation at https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.memory_may_move.

◆ wasmtime_config_memory_reservation_for_growth_set()

void wasmtime_config_memory_reservation_for_growth_set ( wasm_config_t ,
uint64_t   
)

Configures the size, in bytes, of the extra virtual memory space reserved for memories to grow into after being relocated.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.memory_reservation_for_growth

◆ wasmtime_config_memory_reservation_set()

void wasmtime_config_memory_reservation_set ( wasm_config_t ,
uint64_t   
)

Configures the size, in bytes, of initial memory reservation size for linear memories.

For more information see the Rust documentation at https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Config.html#method.memory_reservation.

◆ wasmtime_config_native_unwind_info_set()

void wasmtime_config_native_unwind_info_set ( wasm_config_t ,
bool   
)

Configures whether to generate native unwind information (e.g. .eh_frame on Linux).

This option defaults to true.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.native_unwind_info

◆ wasmtime_config_parallel_compilation_set()

void wasmtime_config_parallel_compilation_set ( wasm_config_t ,
bool   
)

Configure whether wasmtime should compile a module using multiple threads.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.parallel_compilation.

◆ wasmtime_config_profiler_set()

void wasmtime_config_profiler_set ( wasm_config_t ,
wasmtime_profiling_strategy_t   
)

Configures the profiling strategy used for JIT code.

This setting in WASMTIME_PROFILING_STRATEGY_NONE by default.

◆ wasmtime_config_strategy_set()

void wasmtime_config_strategy_set ( wasm_config_t ,
wasmtime_strategy_t   
)

Configures how JIT code will be compiled.

This setting is WASMTIME_STRATEGY_AUTO by default.

◆ wasmtime_config_target_set()

wasmtime_error_t * wasmtime_config_target_set ( wasm_config_t ,
const char *   
)

Configures the target triple that this configuration will produce machine code for.

This option defaults to the native host. Calling this method will additionally disable inference of the native features of the host (e.g. detection of SSE4.2 on x86_64 hosts). Native features can be reenabled with the cranelift_flag_{set,enable} properties.

For more information see the Rust documentation at https://docs.wasmtime.dev/api/wasmtime/struct.Config.html#method.config

◆ wasmtime_config_wasm_bulk_memory_set()

void wasmtime_config_wasm_bulk_memory_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly bulk memory proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_function_references_set()

void wasmtime_config_wasm_function_references_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly typed function reference types proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_gc_set()

void wasmtime_config_wasm_gc_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly GC proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_memory64_set()

void wasmtime_config_wasm_memory64_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly memory64 proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_multi_memory_set()

void wasmtime_config_wasm_multi_memory_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly multi-memory proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_multi_value_set()

void wasmtime_config_wasm_multi_value_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly multi value proposal is enabled.

This setting is true by default.

◆ wasmtime_config_wasm_reference_types_set()

void wasmtime_config_wasm_reference_types_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly reference types proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_relaxed_simd_deterministic_set()

void wasmtime_config_wasm_relaxed_simd_deterministic_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly relaxed SIMD proposal is in deterministic mode.

This setting is false by default.

◆ wasmtime_config_wasm_relaxed_simd_set()

void wasmtime_config_wasm_relaxed_simd_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly relaxed SIMD proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_simd_set()

void wasmtime_config_wasm_simd_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly SIMD proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_tail_call_set()

void wasmtime_config_wasm_tail_call_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly tail call proposal is enabled.

This setting is false by default.

◆ wasmtime_config_wasm_threads_set()

void wasmtime_config_wasm_threads_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly threading proposal is enabled.

This setting is false by default.

Note that threads are largely unimplemented in Wasmtime at this time.

◆ wasmtime_config_wasm_wide_arithmetic_set()

void wasmtime_config_wasm_wide_arithmetic_set ( wasm_config_t ,
bool   
)

Configures whether the WebAssembly wide-arithmetic proposal is enabled.

This setting is false by default.