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