Add a bunch of cookbook-style "how do I do X?" examples to the book

This tries to cover things that we repeatedly get questions about on Zulip.

Author: fitzgen

docs/SUMMARY.md

@@ -37,11 +37,17 @@
   - [Profiling WebAssembly](./examples-profiling.md)
     - [Profiling with Perf](./examples-profiling-perf.md)
     - [Profiling with VTune](./examples-profiling-vtune.md)
-    - [Profiling with samply](./examples-profiling-samply.md)
+    - [Profiling with `samply`](./examples-profiling-samply.md)
     - [Cross-platform Profiling](./examples-profiling-guest.md)
+  - [Building a Minimal Embedding](./examples-minimal.md)
+  - [Portable Interpretation](./examples-pulley.md)
+  - [Pre-Compiling Wasm](./examples-pre-compiling-wasm.md)
+  - [Fast Execution](./examples-fast-execution.md)
+  - [Fast Instantiation](./examples-fast-instantiation.md)
+  - [Fast Compilation](./examples-fast-compilation.md)
+  - [Interrupting Execution](./examples-interrupting-wasm.md)
+  - [Deterministic Execution](./examples-deterministic-wasm-execution.md)
   - [Checking Guests' Memory Accesses](./wmemcheck.md)
-  - [Building a minimal embedding](./examples-minimal.md)
-  - [Using Pulley](./examples-pulley.md)
 - [Stability](stability.md)
   - [Release Process](./stability-release.md)
   - [Tiers of support](./stability-tiers.md)

docs/examples-deterministic-wasm-execution.md

@@ -0,0 +1,80 @@
+# Deterministic Wasm Execution
+
+The WebAssembly language is *mostly* deterministic, but there are a few places
+where non-determinism slips in. This page documents how to use Wasmtime to
+execute Wasm programs fully deterministically, even when the Wasm language spec
+allows for non-determinism.
+
+## Make Sure All Imports are Deterministic
+
+Do not give Wasm programs access to non-deterministic host functions.
+
+When using WASI, use
+[`wasi-virt`](https://github.com/bytecodealliance/WASI-Virt) to virtualize
+non-deterministic APIs like clocks and file systems.
+
+## Enable IEEE-754 `NaN` canonicalization
+
+Some Wasm opcodes can result in `NaN` (not-a-number) values. The IEEE-754 spec
+defines a whole range of `NaN` values and the Wasm spec does not require that
+Wasm always generates any particular `NaN` value, it could be any one of
+them. This non-determinism can then be observed by the Wasm program by storing
+the `NaN` value to memory or bitcasting it to an integer. Therefore, Wasmtime
+can be configured to canonicalize all `NaN`s into a particular, canonical `NaN`
+value. The downside is that this adds overhead to Wasm's floating-point
+instructions.
+
+See
+[wasmtime::Config::cranelift_nan_canonicalization](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.cranelift_nan_canonicalization)
+for more details.
+
+## Make the Relaxed SIMD Proposal Deterministic
+
+The relaxed SIMD proposal gives Wasm programs access to SIMD operations that
+cannot be made to execute both identically and performantly across different
+architecures. The proposal gave up determinism across different achitectures in
+order to maintain portable performance.
+
+At the cost of worse runtime performance, Wasmtime can deterministically execute
+this proposal's instructions. See
+[wasmtime::Config::relaxed_simd_deterministic](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.relaxed_simd_deterministic)
+for more details.
+
+Alternatively, you can simply disable the proposal completely. See
+[`wasmtime::Config::wasm_relaxed_simd`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.wasm_relaxed_simd)
+for more details.
+
+## Handling Non-Deterministic Memory and Table Growth
+
+All WebAssembly memories and tables have an associated minimum, or initial, size
+and an optional maximum size. When the maximum size is not present, that means
+"unlimited". If a memory or table is already at its maximum size, then attempts
+to grow them will always fail. If they are below their maximum size, however,
+then the `memory.grow` and `table.grow` instructions are allowed to
+non-deterministicaly succeed or fail (for example, when the host system does not
+have enough memory available to satisfy that growth).
+
+You can make this deterministic in a variety of ways:
+
+* Disallow Wasm programs that use memories and tables via a
+  [limiter](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.limiter)
+  that rejects non-zero-sized memories and tables.
+
+* Use a [custom memory
+  creator](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.with_host_memory)
+  that allocates the maximum size up front so that growth will either always
+  succeed or fail before the program has begun execution.
+
+* Use [the `wasmparser` crate](https://crates.io/crates/wasmparser) to write a
+  little validator program that rejects Wasm modules that use
+  `{memory,table}.grow` instructions or alternatively rejects memories and
+  tables that do not have a maximum size equal to their minimum size (which,
+  again, means that their allocation must happen completely up front, and if
+  allocation fails, it will have failed before the Wasm program began
+  executing).
+
+## Use Deterministic Interruption, If Any
+
+If you are making Wasm execution interruptible, use [deterministic fuel-based
+interruption](./examples-interrupting-wasm.html#deterministic-fuel) rather than
+non-deterministic epoch-based interruption.

docs/examples-fast-compilation.md

@@ -0,0 +1,58 @@
+# Tuning Wasmtime for Fast Compilation
+
+Wasmtime must compile a Wasm program before executing it. This means that, by
+default, Wasm compilation is on your critical path. In most scenarios, you can
+completely remove Wasm compilation from the critical path by [pre-compiling Wasm
+programs](./examples-pre-compiling-wasm.md). That option is not always
+available, however, and this page documents how to tune Wasmtime for fast
+compilation in these alternative scenarios.
+
+## Enable the Compilation Cache
+
+Wasmtime can be configured to use a cache, so that if you attempt to compile a
+Wasm program that has already been compiled previously, it just grabs the cached
+result rather than performing compilation all over again.
+
+See these API docs for more details:
+
+* [`wasmtime::Config::cache_config_load`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.cache_config_load)
+* [`wasmtime::Config::cache_config_load_default`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.cache_config_load_default)
+* [`wasmtime::Config::disable_cache`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.disable_cache)
+* [`wasmtime::CacheStore`](https://docs.rs/wasmtime/latest/wasmtime/trait.CacheStore.html)
+
+## Enable Winch
+
+Winch is Wasmtime's "baseline" compiler: for each Wasm opcode, it emits a canned
+sequence of machine instructions to implement that opcode. This makes
+compilation fast: it performs only a single, quick pass over the Wasm
+code. However, it does not perform optimizations, so the machine code it emits
+will run Wasm programs slower than Cranelift, Wasmtime's optimizing compiler.
+
+See the API docs for
+[`wasmtime::Strategy`](https://docs.rs/wasmtime/latest/wasmtime/enum.Strategy.html)
+and
+[`wasmtime::Config::strategy`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.strategy)
+for more details.
+
+## Enable Parallel Compilation
+
+Wasmtime can compile Wasm programs in parallel, speeding up the compilation
+process more or less depending on how many cores your machine has and the exact
+shape of the Wasm program. Wasmtime will generally enable parallel compilation
+by default, but it does depend on the host platform and cargo features enabled
+when building Wasmtime itself. You can double check that parallel compilation is
+enabled via the setting the
+[`wasmtime::Config::parallel_compilation`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.parallel_compilation)
+configuration option.
+
+## Putting It All Together
+
+```rust,ignore
+{{#include ../examples/fast_compilation.rs}}
+```
+
+## See Also
+
+* [Pre-Compiling Wasm Programs](./examples-pre-compiling-wasm.md)
+* [Tuning Wasmtime for Fast Wasm Instantiation](./examples-fast-instantiation.md)
+* [Tuning Wasmtime for Fast Wasm Execution](./examples-fast-execution.md)

docs/examples-fast-execution.md

@@ -0,0 +1,79 @@
+# Tuning Wasmtime for Fast Wasm Execution
+
+To tune Wasmtime for faster Wasm execution, consider the following tips.
+
+## Enable Cranelift
+
+[Cranelift](https://cranelift.dev/) is an optimizing compiler. Compared to
+alternative strategies like [the Winch "baseline"
+compiler](./examples-fast-compilation.md), it translates Wasm into faster
+machine code, but compilation is slower. Cranelift is similar to the optimizing
+tier of browsers' just-in-time Wasm engines, such as SpiderMonkey's Ion tier or
+V8's TurboFan tier.
+
+See the API docs for
+[`wasmtime::Strategy`](https://docs.rs/wasmtime/latest/wasmtime/enum.Strategy.html)
+and
+[`wasmtime::Config::strategy`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.strategy)
+for more details.
+
+## Configure Wasmtime to Elide Explicit Bounds Checks
+
+Wasm programs are sandboxed and may only access their linear memories. Attempts
+to access beyond the bounds of a linear memory results in a trap, and this
+prevents the Wasm guest from stealing data from host memory, or from another
+concurrently running Wasm instance. Explicitly bounds-checking every linear
+memory operation performed by a Wasm guest is expensive: it has been measured to
+create between a 1.2x to 1.8x slow down, depending on a number of
+factors. Luckily, Wasmtime can usually omit explicit bounds checks by relying on
+virtual memory guard pages. This requires enabling signals-based traps (on by
+default for non-bare-metal builds), running Wasm on a 64-bit host architecture,
+and ensuring that memory reservations and guard pages are appropriately sized
+(again, configured by default for 64-bit architectures).
+
+To elide any explicit bounds checks, Wasm linear memories must have at least a
+4GiB (`1 << 32` bytes) reservation. If a memory instruction has an additional
+static offset immediate, then the bounds check can only be elided when there is
+a memory guard of at least that offset's size. Using a 4GiB guard region allows
+Wasmtime to elide explicit bounds checks regardless of the static memory offset
+immediate. While small static offset immediate values are common, very large
+values are exceedingly rare, so you can get almost all of the benefits while
+consuming less virtual memory address space by using, for example, 32MiB guards.
+
+See the API docs for
+[`wasmtime::Config::signals_based_traps`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.signals_based_traps),
+[`wasmtime::Config::memory_reservation`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.memory_reservation),
+and
+[`wasmtime::Config::memory_reservation`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.memory_guard_size)
+for more details.
+
+## Force-Enable ISA Extensions
+
+This section can be ignored if you are compiling and running Wasm programs on
+the same machine. In this scenario, Wasmtime will automatically detect which ISA
+extensions (such as AVX on x86\_64) are available, and you do not need to
+configure anything yourself.
+
+However, if you are compiling a Wasm program on one machine and then running
+that pre-compiled Wasm program on another machine, then during compilation
+Wasmtime cannot automatically detect which ISA extensions will be available on
+the machine on which you actually execute the pre-compiled Wasm
+program. Configuring which ISA extensions are available on the target
+architecture that will run the pre-compiled Wasm programs can have a large
+impact for certain Wasm programs, particularly those using SIMD instructions.
+
+See the API docs for
+[`wasmtime::Config::detect_host_feature`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.detect_host_feature)
+for more details.
+
+## Putting It All Together
+
+```rust,ignore
+{{#include ../examples/fast_execution.rs}}
+```
+
+## See Also
+
+* [Tuning Wasmtime for Fast Wasm Compilation](./examples-fast-compilation.md)
+* [Tuning Wasmtime for Fast Wasm Instantiation](./examples-fast-instantiation.md)
+* [Pre-Compiling Wasm Programs](./examples-pre-compiling-wasm.md)

docs/examples-fast-instantiation.md

@@ -0,0 +1,68 @@
+# Tuning Wasmtime for Fast Instantiation
+
+Before a WebAssembly module can begin execution, it must first be compiled and
+then instantiated. Compilation can happen [ahead of
+time](./examples-pre-compiling-wasm.md), which removes compilation from the
+critical path. That leaves just instantiation on the critical path. This page
+documents methods for tuning Wasmtime for fast instantiation.
+
+## Enable the Pooling Allocator
+
+By enabling the pooling allocator, you are configuring Wasmtime to up-front and
+ahead-of-time allocate a large pool containing all the resources necessary to
+run the configured maximum number of concurrent instances. Creating a new
+instance doesn't require allocating new Wasm memories and tables on demand, it
+just takes pre-allocated memories and tables from the pool, which is generally
+much faster. Deallocating an instance returns its memories and tables to the
+pool.
+
+See
+[`wasmtime::PoolingAllocationConfig`](https://docs.rs/wasmtime/latest/wasmtime/struct.PoolingAllocationConfig.html),
+[`wasmtime::InstanceAllocationStrategy`](https://docs.rs/wasmtime/latest/wasmtime/enum.InstanceAllocationStrategy.html),
+and
+[`wasmtime::Config::allocation_strategy`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.allocation_strategy)
+for more details.
+
+## Enable Copy-on-Write Heap Images
+
+Initializing a WebAssembly linear memory via a copy-on-write mapping can
+drastically improve instantiation costs because copying memory is deferred from
+instantiation time to when the data is first mutated. When the Wasm module only
+reads the initial data, and never overwrites it, then the copying is completely
+avoided.
+
+See the API docs for
+[`wasmtime::Config::memory_init_cow`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.memory_init_cow)
+for more details.
+
+## Use `InstancePre`
+
+To instantiate a WebAssembly module or component, Wasmtime must look up each of
+the module's imports and check that they are of the expected types. If the
+imports are always the same, this work can be done ahead of time, before
+instantiation. A `wasmtime::InstancePre` represents an instance *just before* it
+is instantiated, after all type-checking and imports have been resolved. The
+only thing left to do for this instance is to actually allocate its memories,
+tables, and internal runtime context, initialize its state, and run its `start`
+function, if any.
+
+See the API docs for
+[`wasmtime::InstancePre`](https://docs.rs/wasmtime/latest/wasmtime/struct.InstancePre.html),
+[`wasmtime::Linker::instantiate_pre`](https://docs.rs/wasmtime/latest/wasmtime/struct.Linker.html#method.instantiate_pre),
+[`wasmtime::component::InstancePre`](https://docs.rs/wasmtime/latest/wasmtime/component/struct.InstancePre.html),
+and
+[`wasmtime::component::Linker::instantiate_pre`](https://docs.rs/wasmtime/latest/wasmtime/component/struct.Linker.html#method.instantiate_pre)
+for more details.
+
+## Putting It All Together
+
+```rust,ignore
+{{#include ../examples/fast_instantiation.rs}}
+```
+
+## See Also
+
+* [Pre-Compiling Wasm Programs](./examples-pre-compiling-wasm.md)
+* [Tuning Wasmtime for Fast Wasm Compilation](./examples-fast-compilation.md)
+* [Tuning Wasmtime for Fast Wasm Execution](./examples-fast-execution.md)
+* [Wizer, the WebAssembly Pre-Initializer](https://github.com/bytecodealliance/wizer)

docs/examples-interrupting-wasm.md

@@ -0,0 +1,66 @@
+# Interrupting Wasm Execution
+
+If you want to interrupt Wasm execution, for example to prevent an infinite loop
+in the Wasm guest from indefinitely blocking the host, Wasmtime provides two
+mechanisms you can choose between. Wasmtime also allows you to choose what
+happens when Wasm execution is interrupted.
+
+## What Happens When Execution is Interrupted
+
+When a Wasm program's execution is interrupted, you can configure Wasmtime to do
+either of the following:
+
+* **Raise a trap:** This terminates the current Wasm program, and it is not
+  resumable.
+
+* **Async yield:** This pauses the current Wasm program, yields control back to
+  the host, and lets the host decide whether to resume execution sometime in the
+  future.
+
+These options are both available regardless of which interruption mechanism you
+employ.
+
+## Interruption Mechanisms
+
+### Deterministic Fuel
+
+Fuel-based interruption is completely deterministic: the same program run with
+the same amount of fuel will always be interrupted at the same location in the
+program (unless it has enough fuel to complete its computation, or there is some
+other form of non-determinism that causes the program to behave differently).
+
+The downside is that fuel-based interruption imposes more overhead on execution,
+slowing down Wasm programs, than epochs do.
+
+```rust,ignore
+{{#include ../examples/fuel.rs}}
+```
+
+See these API docs for more details:
+
+* [`wasmtime::Config::consume_fuel`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.consume_fuel)
+* [`wasmtime::Config::set_fuel`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.set_fuel)
+* [`wasmtime::Config::fuel_async_yield_interval`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.fuel_async_yield_interval)
+
+### Non-Deterministic Epochs
+
+Epoch-based interruption imposes relatively low overhead on Wasm execution; it
+has been measured at around a 10% slowdown. It is faster than fuel-based
+interruption.
+
+The downside is that it is non-deterministic. Running the same program with the
+same inputs for one epoch might result in an interrupt at one location the first
+time, a later location the second time, or even complete successfully another
+time. This is because it is based on wall-time rather than an exact count of how
+many Wasm instructions are executed.
+
+```rust,ignore
+{{#include ../examples/epochs.rs}}
+```
+
+See these API docs for more details:
+
+* [`wasmtime::Config::epoch_interruption`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.epoch_interruption)
+* [`wasmtime::Config::epoch_deadline_trap`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.epoch_deadline_trap)
+* [`wasmtime::Config::epoch_deadline_callback`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.epoch_deadline_callback)
+* [`wasmtime::Config::epoch_deadline_async_yield_and_update`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.epoch_deadline_async_yield_and_update)