From a78e17e1eb14a9cf102c100a4b104f6259bb6cfa Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 9 Jun 2026 20:09:09 +0000 Subject: [PATCH] docs(roadmap): phase 2 done; record the thread-local-guard rule; sharpen the channel fast-follow rationale (cross-thread std MutexGuard release is UB) --- ROADMAP_v0.5.md | 58 +++++++++++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 24 deletions(-) diff --git a/ROADMAP_v0.5.md b/ROADMAP_v0.5.md index fd07975..47446d9 100644 --- a/ROADMAP_v0.5.md +++ b/ROADMAP_v0.5.md @@ -12,6 +12,12 @@ Guiding rules established this cycle: two slot locks at once). Any new lock states its position in this order. - **No unwind inside a runtime critical section.** The stop sentinel only fires at lock-free observation points. +- **Never hold a thread-local guard across a possible switch point.** An + actor can be preempted at any allocation and resume on a different OS + thread; a live `RefCell` borrow (or std `MutexGuard`) then pairs its + acquire/release across two threads' locals — count underflow / UB. + `with_runtime`, `with_shared`, and every `RawMutex` guard disable + preemption for exactly this reason (phase 2 found this the hard way). --- @@ -30,32 +36,32 @@ Split independent concerns out of `SharedState` so the global lock guards less. `SharedState` now holds only: `slots`, `free_list`, `run_queue`, `root_pid`. -## Phase 2 — Slot table split (NEXT, the big correctness step) +## Phase 2 — Slot table split ✅ DONE Make slot lookup lock-free and per-slot state independently mutable. -- [ ] Fixed slab: `Box<[SlotCell; max_actors]>`, slots never move → stable +- [x] Fixed slab: `Box<[Slot]>`, slots never move → stable addresses, lock-free index. **Assert on exhaustion** with a panic message naming `Config::max_actors(n)` as the fix. Default `max_actors = 16_384`. (Mental note: must become unbounded or configurable-bounded later — see "Deferred" below. Do not let the fixed cap calcify into an assumption.) -- [ ] Per-slot `generation: AtomicU32` outside the lock for cheap stale-PID - rejection. -- [ ] Per-slot CAS state machine replacing `state` + `pending_unpark`: - `Parked / Queued / Running / RunningNotified / Done` in one `AtomicU8`. - `unpark` = CAS Parked→Queued (then push) or Running→RunningNotified; - park-return = CAS Running→Parked, else re-queue. Eliminates the - lost-wakeup bool by turning the race window into a state. -- [ ] `sp` → relaxed `AtomicUsize` (happens-before carried by queue - release-push / acquire-pop). -- [ ] Per-slot raw non-poisoning mutex (spin-then-futex, Linux; embedded- - friendlier than `std::sync::Mutex`) for the cold collections: `waiters`, - `monitors`, `links`, `supervisor_channel`, `outcome`, `pending_io_result`, - `outstanding_handles`. Guard enters `NoPreempt`. -- [ ] Free list → its own structure (lock-free Treiber stack or striped). -- [ ] `finalize_actor` link cascade: lock peers one at a time (leaf rule); - write the acyclicity argument next to it. -- [ ] `live_actors` / `io_outstanding` → atomics; termination = both zero + - queue empty. Finalize decrements `live` strictly *after* all wakeups it - produced are enqueued — document this ordering as the correctness crux. +- [x] Generation packed INTO the state word (better than the planned separate + `AtomicU32`): one `AtomicU64 = (gen << 32) | state`, so the gen check is + atomic with every transition — no ABA, no spurious unparks, by CAS. +- [x] Per-slot CAS state machine `Vacant/Queued/Running/RunningNotified/ + Parked/Done` replacing `state` + `pending_unpark`. Also fixed a latent + lost wakeup in the Blocking-IO completion path (result set for a + still-Running actor without a flag). +- [x] `sp` → relaxed `AtomicUsize`; stop flag + first-resume closure as + `AtomicPtr`s — resume path fully lock-free. +- [x] Per-slot raw non-poisoning futex mutex (`src/raw_mutex.rs`) for the + cold collections. Guard enters `NoPreempt`. +- [x] Free list → `RawMutex>` (a leaf lock). Treiber/striped only if + the phase-4 spawn-storm bench shows contention — revisit then. +- [x] `finalize_actor` link cascade locks peers one at a time; acyclicity + argument written at the site. `link()` registers target-first with the + race argument at the site. +- [x] `live_actors` atomic; termination = io_out == 0 (read pre-queue-lock) + && queue empty && live == 0; decrement-last ordering documented as the + correctness crux at the site. ## Phase 3 — Pluggable run queue + bench shootout - [ ] Extract `RunQueue` behind a `type RunQueue = ...` alias selected at @@ -92,9 +98,13 @@ Make slot lookup lock-free and per-slot state independently mutable. - **Channel mutex migration.** `channel::Inner` is `Arc>` of the same poison class as the old shared lock; `recv_match` even runs a user predicate under it. The Phase-1 `check_cancelled` gating already removes the - unwind *source* globally, so channels are safe today — but migrating the - channel to the raw non-poisoning mutex (Phase 2) is a clean follow-up rather - than bundled into the run-path rework. + unwind *source* globally, so channels are poison-safe today — but phase 2 + surfaced a second, sharper reason to migrate: the std `MutexGuard` is held + with preemption ENABLED, so a timeslice switch inside a channel critical + section migrates the actor and unlocks the pthread mutex from a different + OS thread — technically UB (Linux futexes happen to tolerate it). The + `RawMutex` guard disables preemption and is cross-thread-release sound by + construction. Migrate as the first post-v0.5 change. ## Deferred / explicitly out of scope for v0.5 - **Unbounded / configurable-bounded actor count.** v0.5 ships a fixed slab