Struct wizer::Wizer

pub struct Wizer { /* private fields */ }

Wizer: the WebAssembly pre-initializer!

Don’t wait for your Wasm module to initialize itself, pre-initialize it! Wizer instantiates your WebAssembly module, executes its initialization function, and then serializes the instance’s initialized state out into a new WebAssembly module. Now you can use this new, pre-initialized WebAssembly module to hit the ground running, without making your users wait for that first-time set up code to complete.

Caveats

• The initialization function may not call any imported functions. Doing so will trigger a trap and wizer will exit.

• The Wasm module may not import globals, tables, or memories.

• Reference types are not supported yet. This is tricky because it would allow the Wasm module to mutate tables, and we would need to be able to snapshot the new table state, but funcrefs and externrefs don’t have identity and aren’t comparable in the Wasm spec, which makes snapshotting difficult.

Implementations

impl Wizer

pub fn new() -> Self

Construct a new Wizer builder.

pub fn init_func(&mut self, init_func: impl Into<String>) -> &mut Self

The export name of the initializer function.

Defaults to "wizer.initialize".

pub fn func_rename( &mut self, new_name: impl Display, old_name: impl Display ) -> &mut Self

Add a function rename to perform.

pub fn allow_wasi(&mut self, allow: bool) -> Result<&mut Self>

Allow WASI imports to be called during initialization?

This can introduce diverging semantics because the initialization can observe nondeterminism that might have gone a different way at runtime than it did at initialization time.

If your Wasm module uses WASI’s get_random to add randomness to something as a security mitigation (e.g. something akin to ASLR or the way Rust’s hash maps incorporate a random nonce) then note that, if the randomization is added during initialization time and you don’t ever re-randomize at runtime, then that randomization will become per-module rather than per-instance.

Defaults to false.

pub fn preload(&mut self, name: &str, filename: &str) -> Result<&mut Self>

Provide an additional preloaded module that is available to the main module.

This allows running a module that depends on imports from another module. Note that the additional module’s state is not snapshotted, nor is its code included in the Wasm snapshot; rather, it is assumed that the resulting snapshot Wasm will also be executed with the same imports available.

The main purpose of this option is to allow “stubs” for certain intrinsics to be included, when these will be provided with different implementations when running or further processing the snapshot.

pub fn preload_bytes( &mut self, name: &str, module_bytes: Vec<u8> ) -> Result<&mut Self>

Provide an additional preloaded module that is available to the main module. Unlike preload(), this method takes an owned vector of bytes as the module’s actual content, rather than a filename. As with preload(), the module may be in Wasm binary format or in WAT text format.

This allows running a module that depends on imports from another module. Note that the additional module’s state is not snapshotted, nor is its code included in the Wasm snapshot; rather, it is assumed that the resulting snapshot Wasm will also be executed with the same imports available.

The main purpose of this option is to allow “stubs” for certain intrinsics to be included, when these will be provided with different implementations when running or further processing the snapshot.

pub fn make_linker( &mut self, make_linker: Option<Rc<dyn Fn(&Engine) -> Result<Linker>>> ) -> Result<&mut Self>

The linker to use during initialization rather than the default wasmtime::Linker.

If you want your Wasm module to be able to import non-WASI functionality (or a subset of WASI) during initialization, you can provide a closure that returns a Linker result. Note, this has the same non-determinism concerns that .allow_wasi(true) does: if the allowed imports interact with the world in some way, the outcome of that interaction will be snapshotted by Wizer during initialization and will yield the same result in every instance of the wizened module.

pub fn inherit_stdio(&mut self, inherit: bool) -> &mut Self

When using WASI during initialization, should stdin, stdout, and stderr be inherited?

Defaults to true.

pub fn inherit_env(&mut self, inherit: bool) -> &mut Self

When using WASI during initialization, should the environment variables be inherited?

Defaults to false.

pub fn keep_init_func(&mut self, keep: bool) -> &mut Self

After initialization, should the Wasm module still export the initialization function?

This is false by default, meaning that the initialization function is no longer exported from the Wasm module.

pub fn dir(&mut self, directory: impl Into<PathBuf>) -> &mut Self

When using WASI during initialization, which file system directories should be made available?

None are available by default.

pub fn map_dir( &mut self, guest_dir: impl Into<PathBuf>, host_dir: impl Into<PathBuf> ) -> &mut Self

When using WASI during initialization, which guest directories should be mapped to a host directory?

The map_dir method differs from dir in that it allows giving a custom guest name to the directory that is different from its name in the host.

None are mapped by default.

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

Enable or disable the Wasm multi-memory proposal.

Defaults to true.

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

Enable or disable the Wasm multi-value proposal.

Defaults to true.

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

Enable or disable Wasm bulk memory operations.

Note that only memory.copy, memory.fill, and memory.init operations are currently supported. Modules which use other instructions, such as table.copy will be rejected.

Defaults to false.

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

Enable or disable the Wasm SIMD128 proposal.

Defaults to true.

pub fn run(&self, wasm: &[u8]) -> Result<Vec<u8>>

Initialize the given Wasm, snapshot it, and return the serialized snapshot as a new, pre-initialized Wasm module.

Trait Implementations

impl Clone for Wizer

fn clone(&self) -> Wizer

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Wizer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.