1*54988febSNick Fitzgerald# Interrupting Wasm Execution 2*54988febSNick Fitzgerald 3*54988febSNick FitzgeraldIf you want to interrupt Wasm execution, for example to prevent an infinite loop 4*54988febSNick Fitzgeraldin the Wasm guest from indefinitely blocking the host, Wasmtime provides two 5*54988febSNick Fitzgeraldmechanisms you can choose between. Wasmtime also allows you to choose what 6*54988febSNick Fitzgeraldhappens when Wasm execution is interrupted. 7*54988febSNick Fitzgerald 8*54988febSNick Fitzgerald## What Happens When Execution is Interrupted 9*54988febSNick Fitzgerald 10*54988febSNick FitzgeraldWhen a Wasm program's execution is interrupted, you can configure Wasmtime to do 11*54988febSNick Fitzgeraldeither of the following: 12*54988febSNick Fitzgerald 13*54988febSNick Fitzgerald* **Raise a trap:** This terminates the current Wasm program, and it is not 14*54988febSNick Fitzgerald resumable. 15*54988febSNick Fitzgerald 16*54988febSNick Fitzgerald* **Async yield:** This pauses the current Wasm program, yields control back to 17*54988febSNick Fitzgerald the host, and lets the host decide whether to resume execution sometime in the 18*54988febSNick Fitzgerald future. 19*54988febSNick Fitzgerald 20*54988febSNick FitzgeraldThese options are both available regardless of which interruption mechanism you 21*54988febSNick Fitzgeraldemploy. 22*54988febSNick Fitzgerald 23*54988febSNick Fitzgerald## Interruption Mechanisms 24*54988febSNick Fitzgerald 25*54988febSNick Fitzgerald### Deterministic Fuel 26*54988febSNick Fitzgerald 27*54988febSNick FitzgeraldFuel-based interruption is completely deterministic: the same program run with 28*54988febSNick Fitzgeraldthe same amount of fuel will always be interrupted at the same location in the 29*54988febSNick Fitzgeraldprogram (unless it has enough fuel to complete its computation, or there is some 30*54988febSNick Fitzgeraldother form of non-determinism that causes the program to behave differently). 31*54988febSNick Fitzgerald 32*54988febSNick FitzgeraldThe downside is that fuel-based interruption imposes more overhead on execution, 33*54988febSNick Fitzgeraldslowing down Wasm programs, than epochs do. 34*54988febSNick Fitzgerald 35*54988febSNick Fitzgerald```rust,ignore 36*54988febSNick Fitzgerald{{#include ../examples/fuel.rs}} 37*54988febSNick Fitzgerald``` 38*54988febSNick Fitzgerald 39*54988febSNick FitzgeraldSee these API docs for more details: 40*54988febSNick Fitzgerald 41*54988febSNick Fitzgerald* [`wasmtime::Config::consume_fuel`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.consume_fuel) 42*54988febSNick Fitzgerald* [`wasmtime::Config::set_fuel`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.set_fuel) 43*54988febSNick Fitzgerald* [`wasmtime::Config::fuel_async_yield_interval`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.fuel_async_yield_interval) 44*54988febSNick Fitzgerald 45*54988febSNick Fitzgerald### Non-Deterministic Epochs 46*54988febSNick Fitzgerald 47*54988febSNick FitzgeraldEpoch-based interruption imposes relatively low overhead on Wasm execution; it 48*54988febSNick Fitzgeraldhas been measured at around a 10% slowdown. It is faster than fuel-based 49*54988febSNick Fitzgeraldinterruption. 50*54988febSNick Fitzgerald 51*54988febSNick FitzgeraldThe downside is that it is non-deterministic. Running the same program with the 52*54988febSNick Fitzgeraldsame inputs for one epoch might result in an interrupt at one location the first 53*54988febSNick Fitzgeraldtime, a later location the second time, or even complete successfully another 54*54988febSNick Fitzgeraldtime. This is because it is based on wall-time rather than an exact count of how 55*54988febSNick Fitzgeraldmany Wasm instructions are executed. 56*54988febSNick Fitzgerald 57*54988febSNick Fitzgerald```rust,ignore 58*54988febSNick Fitzgerald{{#include ../examples/epochs.rs}} 59*54988febSNick Fitzgerald``` 60*54988febSNick Fitzgerald 61*54988febSNick FitzgeraldSee these API docs for more details: 62*54988febSNick Fitzgerald 63*54988febSNick Fitzgerald* [`wasmtime::Config::epoch_interruption`](https://docs.rs/wasmtime/latest/wasmtime/struct.Config.html#method.epoch_interruption) 64*54988febSNick Fitzgerald* [`wasmtime::Config::epoch_deadline_trap`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.epoch_deadline_trap) 65*54988febSNick Fitzgerald* [`wasmtime::Config::epoch_deadline_callback`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.epoch_deadline_callback) 66*54988febSNick Fitzgerald* [`wasmtime::Config::epoch_deadline_async_yield_and_update`](https://docs.rs/wasmtime/latest/wasmtime/struct.Store.html#method.epoch_deadline_async_yield_and_update) 67