smarm
7746dca69b
While running benchmarks, a hang surfaced in timer-only workloads — actors sleeping with no IO in flight. Tracing it down, the race lives in sleep(): between the call to `timers.insert_sleep` and the subsequent `park_current` yield, the actor is still in State::Runnable. If the timer fires in that window, the old code's `if matches!(slot.state, State::Parked)` guard silently drops the wakeup. The actor then parks normally and never gets re-queued — it sleeps forever. The fix mirrors what scheduler::unpark() and the IO FdReady path already do: when the timer fires and the slot is still Runnable, set `pending_unpark` instead of re-queuing immediately. The upcoming Park yield sees the flag and re-queues the actor rather than suspending it, closing the race without any new synchronisation. Adds a regression test: 100 actors doing pure timer sleeps across ≥2 scheduler threads. The test asserts both correctness (all actors complete) and timeliness (wall time < 2×sleep duration), which is enough signal to catch a stuck actor even on a single-core CI runner.
99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# smarm
|
|
|
|
> SMARM — Smarm, Marks Actor Runtime Machinery. A proof-of-concept green-thread actor runtime for Rust.
|
|
|
|
Implements the core ideas in [`Achitecture.md`](.docs/Architecture.md): green-thread actors on a
|
|
shared heap, scheduled cooperatively, communicating only by `Send` messages.
|
|
Erlang's isolation model without Erlang's copying GC, Rust's zero-copy
|
|
ownership transfers without async's function colouring.
|
|
|
|
The scheduler is multi-threaded — one OS thread per available CPU, all drawing
|
|
from a shared run queue. The single-threaded `run()` entry point is kept as a
|
|
convenience wrapper around `runtime::init(Config::exact(1)).run(f)`.
|
|
|
|
## What's here
|
|
|
|
| Module | What it does |
|
|
|--------------|------------------------------------------------------------------------|
|
|
| `stack` | `mmap`'d growable stack with guard page; SIGSEGV on overflow |
|
|
| `context` | `#[naked]` x86-64 context-switch shims, callee-saved regs only |
|
|
| `preempt` | Allocator-driven preemption; `check!()` macro for no-alloc loops |
|
|
| `pid` | `(index, generation)` PIDs; stale handles are detectable, not silent |
|
|
| `actor` | Trampoline + `catch_unwind` boundary at the actor entry point |
|
|
| `scheduler` | Run queue, slot table, spawn/join, parking, idle path |
|
|
| `channel` | Unbounded MPSC channel; `recv` parks the actor |
|
|
| `mutex` | `Mutex<T>` with mandatory timeout; FIFO waiters; parks the green thread |
|
|
| `timer` | Min-heap of `(deadline, reason)`; `Sleep` and `WaitTimeout` reasons |
|
|
| `io` | `block_on_io` for blocking work; `wait_readable`/`wait_writable` + `read`/`write` via epoll |
|
|
| `supervisor` | `Signal::Exit` / `Signal::Panic` delivered to a parent actor's mailbox |
|
|
|
|
## Quick taste
|
|
|
|
```rust
|
|
use smarm::{run, spawn, channel};
|
|
|
|
run(|| {
|
|
let (tx, rx) = channel::<i64>();
|
|
let h = spawn(move || {
|
|
for _ in 0..3 {
|
|
let v = rx.recv().unwrap();
|
|
println!("got {v}");
|
|
}
|
|
});
|
|
for v in 1..=3i64 {
|
|
tx.send(v).unwrap();
|
|
}
|
|
h.join().unwrap();
|
|
});
|
|
```
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
stack.rs context.rs preempt.rs pid.rs actor.rs
|
|
scheduler.rs channel.rs mutex.rs timer.rs io.rs supervisor.rs
|
|
lib.rs
|
|
tests/
|
|
per-module integration tests
|
|
benches/
|
|
primes.rs fan-out/fan-in compute, vs tokio current_thread
|
|
```
|
|
|
|
## Building and running
|
|
|
|
Standard Cargo. Requires Rust 1.95 or newer (the `#[naked]` attribute went stable
|
|
in 1.88; we use a few unrelated post-1.88 features). x86-64 Linux only —
|
|
ARM64 and macOS are on the deferred list because of the assembly shim and the
|
|
epoll dependency.
|
|
|
|
```sh
|
|
cargo test # all tests
|
|
cargo test --test mutex # one module
|
|
cargo bench # primes benchmark vs tokio
|
|
```
|
|
|
|
## What's not here
|
|
|
|
See the **Defer** section of `Architecture.md`.
|
|
restart-intensity caps, `join!` for handle groups, stack growth via remap,
|
|
hierarchical timer wheel, fd-wait timeouts, `Signal::Timeout`. Each is
|
|
mechanism we know how to add; none belongs in this iteration.
|
|
|
|
## Docs
|
|
|
|
| Document | What it covers |
|
|
|---|---|
|
|
| [`Architecture.md`](./docs/Architecture.md) | Design intent, runtime model, and deferred work |
|
|
| [`smarm - Deep Dive.html`](./docs/smarm%20-%20Deep%20Dive.html) | Generated walkthrough of the system; good starting point |
|
|
| [`BENCHMARKS_AND_TUNING.md`](./docs/BENCHMARKS_AND_TUNING.md) | Where smarm wins and loses vs tokio, preemption knob recommendations |
|
|
| [`benchmarks.md`](./docs/benchmarks.md) | Raw benchmark results, methodology, and tuning experiment log |
|
|
|
|
## Contributing
|
|
|
|
This is a personal proof-of-concept. There's no PR workflow. If you fork it and do something interesting, just send me an email. If it's nice, I'll upstream the changes.
|
|
|
|
---
|
|
|
|
|