Rust event loop state

The loop owns the handler set and the state as two separate values, and passes one into the other. Every rule below follows from this sentence. E0499 in a dispatch loop almost never needs a different line. It needs a different owner.

This skill covers synchronous loops. For runtime behavior under tokio (select!, JoinSet, FuturesUnordered, wakers, cancellation), use the rust-async-internals skill when it is installed. The diagnostics below are from rustc 1.98.1, edition 2024.

Pick the structure from the shape of the handler set

Read the left column first. Stop at the first row that describes your handler set. Each row down costs something concrete, and you pay it whether or not you needed it.

Triage

Do not do this

The first two rows are about re-entrant dispatch inside one synchronous loop. Under a runtime the same shapes read differently: Arc<Mutex<State>> across separate tasks is a valid, serializing choice.

Verify

The change is complete when every row that applies to it is green.

The rust-sanitizers-miri skill, when it is installed, owns the Miri flags and the Stacked Borrows and Tree Borrows policy. Without it, gate on the default Stacked Borrows run and treat MIRIFLAGS="-Zmiri-tree-borrows" as a second opinion.

A re-locked Mutex usually fails as a hang (std may also panic), and an always-enqueuing while let drain fails as a hang. libtest warns after 60 seconds and never ends the test. Build the state and run one tick inside std::thread::spawn. Send () on a std::sync::mpsc channel when the tick returns. Assert rx.recv_timeout(Duration::from_secs(5)).is_ok(). A panic in the thread drops the sender, so the same assert also catches a RefCell panic. If cargo-nextest is installed, slow-timeout = { period = "5s", terminate-after = 1 } under [profile.default] in .config/nextest.toml also ends a hung test.

Read references/review-checklist.md when you review an existing loop. It asks one question per defect class in this skill.

The loop owns both, separately

Put the handler collection inside the state and dispatch &mut State into the handlers, and the call cannot type-check. The iterator holds a mutable borrow of *st for the whole loop body, so the &mut State argument is a second mutable borrow of the same place:

struct Event(u32);
struct State { counter: u32, handlers: Vec<Box<dyn Handler>> }
trait Handler { fn handle(&mut self, st: &mut State, ev: &Event); }

fn tick(st: &mut State, ev: Event) {
    for h in st.handlers.iter_mut() {
        h.handle(st, &ev);
    }
}

No interior mutability fixes this. Move the collection out. Two locals in the loop are two independent owners, so the two borrows are provably disjoint:

struct Event(u32);
struct State { counter: u32 }
trait Handler { fn handle(&mut self, st: &mut State, ev: &Event); }

struct Add;
impl Handler for Add {
    fn handle(&mut self, st: &mut State, ev: &Event) { st.counter += ev.0; }
}
struct Double;
impl Handler for Double {
    fn handle(&mut self, st: &mut State, _ev: &Event) { st.counter *= 2; }
}

fn tick(handlers: &mut [Box<dyn Handler>], st: &mut State, ev: Event) {
    for h in handlers.iter_mut() { h.handle(st, &ev); }
}

fn main() {
    let mut handlers: Vec<Box<dyn Handler>> = vec![Box::new(Add), Box::new(Double)];
    let mut st = State { counter: 0 };
    tick(&mut handlers, &mut st, Event(3));   // (0 + 3) * 2
    tick(&mut handlers, &mut st, Event(4));   // (6 + 4) * 2
    assert_eq!(st.counter, 20);
    println!("counter={}", st.counter);       // counter=20
}

When an existing codebase cannot move the field yet, use one of two repairs:

• Group the rest of the state in a sub-struct, make the handler trait take that sub-struct, and dispatch &mut st.rest. st.handlers and st.rest are disjoint field borrows, so the handler field can stay.
• Use std::mem::take(&mut st.handlers) for the tick only when a handler must also mutate the handler set. The put-back is the trap: a handler that registers a new handler during the tick puts it into the empty field, and a plain assignment drops it. Append the newcomers first. Read the "Migration" section of references/state-partitioning.md for the runnable version and its panic limit.

Drain the queue by value

front() returns a reference tied to *st. The reference is an argument of the dispatch call, so NLL keeps it live across the call, and the whole state stays borrowed (E0502). pop_front() produces an owned Event, so no borrow of the state survives into the handler, and a handler can push more events back:

use std::collections::VecDeque;

struct Event(u32);
struct State { counter: u32, queue: VecDeque<Event> }

fn handle(st: &mut State, ev: Event) {
    st.counter += ev.0;
    if ev.0 > 1 { st.queue.push_back(Event(ev.0 - 1)); }   // handlers may enqueue
}

fn main() {
    let mut st = State { counter: 0, queue: VecDeque::from([Event(3)]) };
    while let Some(ev) = st.queue.pop_front() { handle(&mut st, ev); }
    assert_eq!(st.counter, 6);
    println!("counter={}", st.counter);   // counter=6
}

A handler that enqueues on every event makes that while let spin forever. Read the length first and drain exactly one batch per tick: for _ in 0..st.queue.len() { let Some(ev) = st.queue.pop_front() else { break }; handle(st, ev); }.

A handler stores a key, never a borrow

A handler built from a field of the state carries that borrow into every dispatch, and the &mut State argument is then a second borrow. Caching { cache: &mut st.caches[0] } followed by h.handle(st) is E0499, "first borrow later used by call". Store the slot instead, struct Caching { slot: usize }, and resolve it at the top of each call: st.caches[self.slot].hits += 1. Handler construction then does not touch the state, so one registry serves every tick. A handler that needs two slots at once resolves both keys in one call with st.caches.get_disjoint_mut([a, b]) (Rust 1.86+). An overlapping or out-of-range pair is an Err, not a panic.

A bare usize goes stale with no error when a slot is removed or reused. Use a generational key when slots are freed. Read the "Key-holding handler" section of references/state-partitioning.md for the diagnostic, the runnable version, and the staleness rules.

Generic state, dynamic worlds, and suspendable routines

Read references/generic-and-dynamic-state.md when handlers are reused across states (structure row 2), a context pairs a static state with a dynamic world, or the component set is open at run time (structure row 3).

Read references/suspendable-routines.md when a routine must pause mid-work and continue next tick, or someone proposes async fn(&mut State), a coroutine, or a generator for it.

Related skills

Use these skills when they are installed: