Markk116/smarm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: Markk116/smarm:3e9c33377c71b62221669922818c3dadc42751e6
Branches Tags
Markk116/smarm:master Markk116/smarm:arm-port
..
compare: Markk116/smarm:arm-port
Branches Tags
Markk116/smarm:master Markk116/smarm:arm-port
1 Commits
3e9c33377c .. arm-port
Author SHA1 Message Date
smarm-dev 89fb13e29a feat(arch): port context switch + cycle counter to aarch64 
Extract the x86-64-specific context-switch shims, initial-stack layout,
and cycle counter out of context.rs into a target_arch-gated src/arch/
module, and add an aarch64 (AAPCS64) backend.

- src/arch/mod.rs: shared SCHEDULER_SP/ACTOR_SP thread-locals + the
  four-item backend contract (init_actor_stack, switch_to_{actor,
  scheduler}, read_cycle_counter); compile_error! on other arches.
- src/arch/x86_64.rs: existing implementation verbatim, plus the rdtsc
  cycle counter relocated here from preempt.rs.
- src/arch/aarch64.rs: x19-x30 stp/ldp context switch, lr-based return,
  CNTVCT_EL0 cycle counter (isb-serialised).
- context.rs: now a thin facade re-exporting crate::arch; public surface
  unchanged for scheduler/preempt/tests.
- preempt.rs: read_cycle_counter delegates to crate::arch; per-arch
  DEFAULT_TIMESLICE_CYCLES (TSC and CNTVCT have different units).
- tests/context.rs: cfg-gate the x86 callee-saved-register probe and add
  the aarch64 x23-x26 sibling.
- .cargo/config.toml: aarch64-unknown-linux-gnu cross linker.

No functional change on x86-64: arch/x86_64.rs is byte-for-byte the old
context.rs body, and tests/preempt.rs (incl. the XMM-not-saved guard from
14dc7a7) is untouched.
 2026-06-07 21:54:28 +00:00
71 changed files with 2210 additions and 15430 deletions
Expand all files Collapse all files
.cargo/config.toml
+2
View File
@@ -0,0 +1,2 @@
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
.githooks/pre-commit
-8
View File
@@ -1,8 +0,0 @@
#!/bin/sh
# smarm pre-commit gate: clippy the library (src/) with warnings as errors.
# unwrap_used / expect_used are denied (Cargo.toml [lints.clippy]): library
# code must not hide a panic behind unwrap/expect. Tests/examples are not gated.
set -eu
[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"
cd "$(git rev-parse --show-toplevel)"
cargo clippy --lib -- -D warnings
.gitignore
-3
View File
@@ -1,6 +1,3 @@
target target
Cargo.lock Cargo.lock
smarm_trace.json smarm_trace.json
/bench_results/
__pycache__/
*.pyc
Cargo.toml
-48
View File
@@ -4,43 +4,12 @@ version = "0.4.0"
edition = "2021" edition = "2021"
rust-version = "1.95" rust-version = "1.95"
[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ["cfg(loom)"] }
[lints.clippy]
# Library code must never hide a panic behind unwrap/expect. Both are denied; an
# intentional panic is written explicitly as `match { Err(e) => panic!(..) }`.
# panic!/unreachable! are deliberately left un-linted as the blessed explicit
# form. Enforced on the library target only (`cargo clippy --lib`); tests and
# examples unwrap freely and are not gated.
unwrap_used = "deny"
expect_used = "deny"
[features] [features]
default = ["rq-mutex"]
smarm-trace = [] smarm-trace = []
# RFC 016 Chunk 2: cycle-accurate per-actor time-budget accounting. Off by
# default — it costs two extra RDTSC reads per actor resume on the hot path
# (D6). The `ActorInfo.budget_cycles` field exists regardless; it just stays 0
# unless this is enabled.
budget-accounting = []
# RFC 016 Chunk 4: the live observer gen_server (src/observer.rs). Off by
# default (DECISION D10) — the read primitive (Chunks 1–3) is always present
# and unflagged; only the optional gen_server transport sits behind this, so a
# release build pays nothing for an observer it never starts.
observer = []
# Run-queue selection: exactly one, compile-time (see src/run_queue.rs).
# Non-default variants need --no-default-features (features are additive).
rq-mutex = []
rq-mpmc = []
rq-striped = []
[dependencies] [dependencies]
libc = "0.2" libc = "0.2"
[target.'cfg(loom)'.dependencies]
loom = "0.7"
[dev-dependencies] [dev-dependencies]
libc = "0.2" libc = "0.2"
tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros", "sync", "time"] } tokio = { version = "1", features = ["rt", "rt-multi-thread", "macros", "sync", "time"] }
@@ -72,20 +41,3 @@ harness = false
[[bench]] [[bench]]
name = "tokio_favored" name = "tokio_favored"
harness = false harness = false
[[bench]]
name = "rq_micro"
harness = false
[[bench]]
name = "rq_runtime"
harness = false
[[bench]]
name = "switch_cost"
harness = false
# RFC 016 Chunk 4 — the live observer dump. Needs the optional gen_server.
[[example]]
name = "observer"
required-features = ["observer"]
README.md
+2 -3
View File
@@ -21,15 +21,14 @@ convenience wrapper around `runtime::init(Config::exact(1)).run(f)`.
| `pid` | `(index, generation)` PIDs; stale handles are detectable, not silent | | `pid` | `(index, generation)` PIDs; stale handles are detectable, not silent |
| `actor` | Trampoline + `catch_unwind` boundary at the actor entry point | | `actor` | Trampoline + `catch_unwind` boundary at the actor entry point |
| `scheduler` | Run queue, slot table, spawn/join, parking, idle path | | `scheduler` | Run queue, slot table, spawn/join, parking, idle path |
| `channel` | Unbounded MPSC channel; `recv` parks the actor; `recv_timeout` bounds it; `select`/`select_timeout` park on many receivers at once (ready-index, priority order) | | `channel` | Unbounded MPSC channel; `recv` parks the actor |
| `mutex` | `Mutex<T>` with mandatory timeout; FIFO waiters; parks the green thread | | `mutex` | `Mutex<T>` with mandatory timeout; FIFO waiters; parks the green thread |
| `timer` | Min-heap of `(deadline, reason)`; `Sleep` and `WaitTimeout` reasons | | `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 | | `io` | `block_on_io` for blocking work; `wait_readable`/`wait_writable` + `read`/`write` via epoll |
| `supervisor` | `Signal::Exit`/`Panic`/`Stopped` funnelled to a parent; `OneForOne`/`OneForAll`/`RestForOne` strategies + restart-intensity cap | | `supervisor` | `Signal::Exit`/`Panic`/`Stopped` funnelled to a parent; `OneForOne`/`OneForAll`/`RestForOne` strategies + restart-intensity cap |
| `monitor` | `monitor(pid)` → `Monitor { id, target, rx }`; one-shot `Down` via `rx`; `demonitor(&m)` tears one registration down; unidirectional death notice | | `monitor` | `monitor(pid)` → `Monitor { id, target, rx }`; one-shot `Down` via `rx`; `demonitor(&m)` tears one registration down; unidirectional death notice |
| `link` | bidirectional `link`/`unlink`; abnormal death propagates (cooperative stop, or an `ExitSignal` message under `trap_exit`) | | `link` | bidirectional `link`/`unlink`; abnormal death propagates (cooperative stop, or an `ExitSignal` message under `trap_exit`) |
| `gen_server` | `call`/`call_timeout` (sync request-reply) / `cast` (async) over one inbox; `handle_info` over static info arms + `handle_down` via `Watcher`-fed monitors, selected ahead of the inbox; `ServerRef`/`ServerBuilder` + `init`/`terminate` hooks; server-down via channel closure | | `gen_server` | `call` (sync request-reply) / `cast` (async) over one inbox; `ServerRef` + `init`/`terminate` hooks; server-down via channel closure |
| `registry` | `register`/`whereis`/`name_of`: name ↔ pid bimap; lazy generation-checked cleanup |
## Quick taste ## Quick taste
ROADMAP.md
-306
View File
@@ -1,306 +0,0 @@
# smarm — Roadmap
## Shipped (compacted — full cycle plans and deviation records live in git history)
Cycles before v0.8 (v0.4 actor primitives, v0.5 runtime decomposition &
pluggable run queue, v0.6 actor ergonomics, v0.7 select on epoch-stamped
consuming wakes): see `git log ROADMAP.md`.
### v0.8 — gen_server: handle_info / handle_down + io fd hygiene ✅
Spent `select` on the server loop: static info arms (`type Info`,
`ServerBuilder::with_info`) and dynamic monitor forwarding
(`ServerCtx`/`Watcher` + a control arm), priority downs → control → infos →
inbox. Closed the v0.2 fd hole: a drop guard in `wait_fd` DELs the kernel
registration on unwind (the leak was worse than documented — a stale waiters
entry permanently poisoned the fd). Deviation: the plain-inbox fast path
narrowed; servers holding a `Watcher` select forever.
Commits `e5d1b3b`, `24b95c9`, `f6969e5`.
### v0.9 — Wake-path latency ✅
Attacked per-wake latency with the RFC 005 **wake slot**: a per-scheduler,
thread-local, capacity-one wake cache checked before the shared queue, pushed
only from actor context, slot-then-shared pop with the waker's residual slice
as the starvation bound (`slot_hits`/`slot_displacements`). Benched via the
slot on/off dimension of `rq_runtime` — ping-pong-pairs (win), yield-storm
(regression guard), spawn-storm (neutrality); results annotated in RFC 005.
The RFC 004 spinning-workers experiment, originally scoped here, was evaluated
and **excised** (not worth the code cost; preserved on branch
`rfc-004-spinning`). Also a false-sharing fix (`align(64)` on `SchedulerStats`)
and a termination wake for idle siblings.
Commits `2708042`, `37d9319`, `eddf3fe`.
---
## Decision record — queue topology 🔒 CLOSED (2026-06-10)
The run-queue shootout (harness `6d9f369`, 24-core sweep 1–24 schedulers,
report `bench_report_rq_shootout.html`) landed in **RFC 005's World 3**: the
three queue variants are within 10–15% of each other in `rq_runtime` at every
scheduler count ≥ 4, on all three workloads.
Consequences:
- **`rq-mutex` stays the default** — simplest correct, no capacity
constraints, locking model already integrated.
- **Feature plumbing stays as is.** All three variants keep compiling in
every build; `rq-mpmc`/`rq-striped` remain selectable for benching.
- **Reopening is benchmark-driven only.** The report documents the
conditional upgrade paths if a future workload qualifies: mpmc for
message-passing-dominant loads at N ≤ 8; striped for high-contention balanced push/pop at N ≥ 16. Neither is a scheduler workload as measured.
- **Effort redirects to the wake path**: RFC 005 (billed as a latency patch,
per its own World 3 framing), RFC 004, and eventually per-switch cost.
---
## Typed addressable mailboxes ✅ SHIPPED (RFC 013 + RFC 014)
The unblocker several later items quietly assumed: a `Pid` is now messageable.
RFC 013 reworked `registry.rs` from a name↔pid *bimap* into a name→**live
mailbox** directory off the cold leaf; RFC 014 layered the typed addressing and
producers on top. Two addressing modes — `Pid<A>` (direct, identity-bound) and
`Name<M>` (durable, re-resolving, location-transparent) — compile-time typing
preserved via phantom tokens over *contained* `Box<dyn Any>` erasure (the
global-enum alternative was rejected: it breaks library-extensibility for
out-of-crate actors). Channel store keyed by message `TypeId` in every path.
Delivered surface:
- **Sends:** `send_to` (`Pid<A>`), `send` (`Name<M>`), `send_dyn` (bare-pid
escape hatch, names the message type) — earlier 014 phases.
- **Producers & discovery** (final phase, `a866e34`): `spawn_addr` (typed-path
producer; parent-side inbox publish so an immediate `send_to` resolves, no
race on the body); `lookup_as` / `pick_as` / `members_as` (unchecked-but-sound
re-type of an erased pid — a wrong `A` degrades to `NoChannel`, never
misdelivery); `dispatch` (pick-a-live-member-and-send, `SendError::NoMember`
on empty pool).
- **By-name gen_servers** (final phase): `ServerName<G>` over the existing
typed-channel store (keyed by `TypeId::of::<Envelope<G>>()`, so `Envelope`
stays private and no separate directory is needed); type-state
`NamedServerBuilder<G>` (fallible `start`, `NameTaken`) leaving the infallible
`ServerBuilder::start` untouched; free `call` / `cast` / `whereis_server`;
`ServerRef::shutdown` + free `shutdown` as the sys-style synchronous stop.
- **Root-exit teardown** (final phase): the run's initial actor is the root;
when it exits, the scheduler's idle verdict stops the parked-forever remainder
(deferred past the queue drain, so actors with in-flight work finish rather
than unwinding on the stop). Closes the "app actor blocks AllDone" stall — see
Look into, below.
Extends — does not retire — the "select exists; a unified per-process mailbox
still does not" invariant: 014 adds addressable *delivery*, not a unified inbox;
multi-port stays `select` composition over named channels. Examples:
`examples/{typed_actor,named_genserver,worker_pool}.rs`. Earlier-phase commits
and the full 013/014 history in git.
---
## gen_server time-related patterns ✅ SHIPPED (RFC 015)
*(layer 2; seven commits `47d75d1`→`f454a91`, each a reviewable chunk. Builds on
the `send_after` substrate below.)*
The OTP time vocabulary against the v0.8 server loop, with **no handler-signature
change** — the capability is a handle stashed on `self` (the `Watcher` pattern),
not a return-directive or a `&ctx` threaded through handlers. New trait surface:
`type Timer` (server's own scheduled payload, `()` if unused, kept distinct from
the external `type Info`), `handle_timer`, `handle_idle` (both no-op defaults).
- **One-shot / debounce / retry-backoff** — `ctx.timer()` hands out a clonable
`TimerHandle`; `arm_after(d, msg)` arms, `cancel(id)` carries the substrate's
race bool. Debounce/backoff are just arm-and-`cancel` against the latest event
(no special mechanism).
- **Periodic tick / heartbeat** — `tick_every(d, msg)`: loop-managed sugar over
the one-shot substrate (re-arm at `now + d`), one stable id, `cancel` stops the
re-arm *and* the pending instance. Requires `Timer: Clone` (method-level bound
only); the loop re-delivers via a stored factory, so the bound never leaks onto
`type Timer` or the loop.
- **Idle / receive timeout** — *not* a channel: it is the timeout on the loop's
`select_timeout` / `recv_timeout`. `ctx.idle_after(d)` (set once in `init`)
fixes the window; reset on any dispatched message; `None` from the wait ⇒
`handle_idle`; re-arms steady. No generation-tag race — there is no token.
Mechanics: control (monitor intake) + armed timers fold into one loop-internal
`Sys` channel selected above the inbox, so **armed timers outrank infos** (a
heartbeat can't be starved). One substrate addition — `send_after_to` (a
channel-targeting sibling of `send_after`, lands the fire on the loop's own arm).
Exit is leak-free: the drop guard (same one that runs `terminate`) drains and
cancels every live timer id, then `debug_assert!`s none survive. `call_timeout`
is unchanged — it's a *client-side* call deadline, disambiguated in docs from the
server-side idle timeout (same word, two axes). `gen_statem` state timeouts
(deferred, Low) will reuse the loop-owned idle deadline.
---
## Process groups — the primitive pubsub & channels should have sat on ✅ SHIPPED (RFC 012)
*(`src/pg.rs`, four commits `b78311b`→`56f2fc5`; see HANDOFF + git history. Context retained below.)*
Context: urus is a webserver written on top of smarm to provide a testing target.
A named pid→multiset map with monitor-backed removal: `registry.rs` generalised
from name↔pid *bimap* to name→*multiset*, the death hook reused verbatim. Local
first. The point is that urus pubsub collapses into a pg consumer (`subscribe` =
join, `broadcast` = send-to-members) instead of being a bespoke mechanism, and the
same group set reads two ways — fan-out (all members) vs discovery/pool (one
member), with different netsplit consequences. Urus shipped pubsub/channels predate this
and want reframing on top of it. Foundational, so early in the post-v0.9 stack.
Needs an RFC.
---
## Later
### Highest priority
#### Per-switch cost (context shims, epoch protocol)
The shootout's residual: per-wake latency is 0.16–0.18 µs at N=1 and
0.8–1.2 µs at N=8+, dominated by the context-switch shims and the epoch
protocol, not the queue. On current evidence this is the larger constant —
"the whole game" alongside the v0.9 work — but there is no spec yet. Needs a
profiling spike (where do the cycles actually go per park/unpark round-trip)
and then an RFC before it can be scheduled.
#### send_after / cancel_timer
✅ SHIPPED (`61520bf`) — message-delivery timer on the `timer.rs` min-heap:
deliver a value to an address (`Pid<A>` via `send_to`, `Name<M>` via `send`),
resolved *on fire* so a dead target / restarted name is observed at fire time;
failed resolve dropped (Erlang `erlang:send_after`). `Reason::Send { fire }`
carries delivery type-erased; cancellation is an `armed` set keyed on entry
`seq` (only `Send` uses it — `Sleep`/`WaitTimeout` stay inert-stale), exposed as
an opaque `TimerId`; `cancel` is unscoped and returns the race signal.
`peek_deadline` relaxed to "≤ true next deadline" for a future timing wheel. The
gen_server time layer (RFC 015, shipped above) lands on this, adding only the
channel-targeting `send_after_to` sibling.
#### Introspection — process_info / get_state / tree dump
✅ SHIPPED (RFC 016) — runtime introspection & observability, superseding the
RFC 000 / 006 / 009 sketches. The mechanism is an internal synchronous read,
not a C ABI: `snapshot()` / `actor_info(pid)` return owned data (pid, names,
fine scheduling state, parent edge, trap, monitor/link/joiner counts, mailbox
depth) carrying `SNAPSHOT_FORMAT_VERSION` (Chunk 1, ps-semantics tearing);
`tree()` folds that into a parentage forest with orphan re-rooting (Chunk 3).
Per-actor counters — timeslice overruns, messages-received, and a feature-gated
approximate time budget — ride hot `AtomicU64` slot fields (Chunk 2). The live
`observer` gen_server is the read transport over that primitive, behind the
off-by-default `observer` feature (Chunk 4); it is the read half of the future
RFC 003 control plane. Wedged-runtime dumps stay gdb's job, and park-reason
detail / C ABI are explicit non-goals.
#### Worker pool behaviour
Supervised, interchangeable workers with restart semantics over a shared inbox
(poolboy / NimblePool shape) — distinct from connection pools (bb8/deadpool), which
pool *resources*, not *supervised processes*. Sits on `supervisor.rs` +
`gen_server.rs`. Needs an RFC.
### Medium Priority
#### Demand-driven pipelines — GenStage / Broadway shape
Supervised producer/consumer stages where consumers signal demand upstream, with
batching, ack, partitioning. The clearest thing hex has and crates.io lacks (stream
combinators and bounded channels are not a supervised demand-contract stage graph),
and the natural fit for ingestion-shaped workloads. Builds on channels + gen_server
+ supervisor. Needs an RFC.
#### Unwakeable idle sleep when io is absent (terminal-wake residual)
The `(Some(deadline), None)` idle branch — timers pending, io subsystem never
initialized — blocks in `thread::sleep` with no wake mechanism at all. The
terminal wake (writes the wake pipe at AllDone) cannot reach it: no io, no
pipe. Same stall as the fixed bug, in any no-io runtime: a sibling that
blocked on an orphaned deadline sleeps it out in full after everything else
finished. Candidates, mutually exclusive: (a) clamp the sleep (cheap, but
turns idle into periodic wakeups), or (b) park the branch on a condvar/futex
the AllDone path signals — and at that point consider making the condvar the
idle primitive for the no-io runtime generally (a cross-thread unpark could
signal it too, see below). Decide before any no-io deployment.
#### Cross-thread unpark
`RuntimeInner::enqueue` does not wake idle sibling schedulers — only io
completions write the wake pipe. Mid-flight this is masked (the enqueuing
thread is awake and eats the work itself), but it costs parallelism: work
enqueued by a busy thread waits until the sibling's idle poll times out. Needs bench evidence (does the shared-queue handoff latency actually show up?) before a mechanism is picked.
#### Unbounded / configurable-bounded actor count
Fixed slab with a loud assert (`Config::max_actors(n)`, default 16 384).
Revisit with a segmented slab (array of `AtomicPtr<Segment>`, doubling segment
sizes, append-only) once the cap is actually hit. Do not let it calcify.
#### arm-port validation & merge
`arm-port` branch carries an AAPCS64 context-switch backend, never run on
hardware. Build + run full test suite on an aarch64 device; check
`chained_spawn` / `yield_many` bench medians; merge and update README.
### Low priority
#### gen_statem — postponement + state timeouts only
A thin layer over gen_server, not a new behaviour. The (state, event) dispatch
matrix is free from the type system and not worth porting. The two mechanisms that
are: event **postponement** (defer events in the wrong state, replay on transition
— selective receive, codified) and **state timeouts** (auto-cancel on state
change). Device-connection FSMs are the canonical use. Wants send_after underneath.
Needs an RFC.
#### Clustering — distribution epic
Sequenced deliberately after v0.9 and the per-switch-cost spike. A fat stack of
RFCs, not one. Spine settled in discussion; decisions still open:
- **Explicit remote boundary, never transparency.** Serialization colours *edges*
(channel types), not functions — local edges stay zero-copy `Send`, only remote
edges take a `RemoteRef<T: Serialize + DeserializeOwned>`. No hidden latency when
a peer migrates; the refactor is visible by construction.
- **One binary, role as runtime config** (`ROLE=… REGION=… SEEDS=…`); a build-hash
handshake enforces same-binary type identity and sidesteps cross-version type
agreement. Roles select which supervision subtree mounts.
- **Distributed pg falls out of local pg + a membership/gossip layer**, and
distributed pubsub falls out of that for free; per-member metadata (region, load)
enables fly-style nearest-member routing.
- **Migratable gen_servers** as a sub-layer: only behaviours migrate (a raw actor's
stack is opaque; a gen_server *between callbacks* is just its `State`), gated by
`Serialize` bounds + an `on_arrive` reacquire hook, addressed by name not pid. The
BEAM can't do this — leaning on the behaviour layer is what buys it. Requires `State` to be serializable, so should probaby spec a `trait MigratableGenServer: GenServer where Self::State: Migratable` , or something to that extent, so we can lean on the type system to make sure we don't accidentally make state that cannot be serialised. (The "addressed by name not pid" half is RFC 013's `Name<M>` durable address — its local form is the foundation this remote layer extends.)
- **CRDT presence** is the high-value, genuinely-hard layer above distributed pg,
kept *out* of the pg primitive (the pg2 strong-consistency lesson). Furthest out. Can maybe defer to rust ecosystem
---
## Look into
### app actors block AllDone; no external stop path — ADDRESSED (RFC 014 root-exit teardown)
Agent working on urus (see same git server as smarm) reported a lazily spawned actor never returning, blocking program shutdown. Maybe we should do something about it. Agent worked around it by giving the actor an atomic bool to spin on. See urus example crud for exact impl.
**Update (RFC 014):** root-exit teardown stops the parked-forever remainder when
the root actor exits, so a lazily spawned daemon no longer wedges shutdown on
`live_actors > 0`; `ServerRef::shutdown` (+ free `shutdown`) is the explicit stop
path the atomic-bool workaround stood in for. Re-check the urus crud repro to
confirm the workaround can be retired (the teardown is cooperative — an actor in
a tight loop with no observation point still can't be stopped).
---
## Invariants & gotchas (respect these across all cycles)
- **Shared mutex is non-reentrant.** `Sender::send` can call `unpark` →
`with_shared`. Never send on a channel while holding the shared lock. Pattern:
`mem::take` data under the lock, send after releasing. See `finalize_actor`.
- **`finalize_actor` order:** take stack/waiters/monitors under lock + set
Done/outcome → recycle stack → deliver supervisor Signal + monitor Downs →
unpark joiners → reclaim slot if `outstanding_handles==0`. Death notifications
always precede reclamation.
- **Slot lifecycle reset in THREE places:** `Slot::vacant()`, `reclaim_slot()`
(runtime.rs), slot-init block in `spawn_under` (scheduler.rs). Any new `Slot`
field must be reset in all three.
- **Pid = (index, generation).** Stale handles caught by generation mismatch in
`slot()/slot_mut()`. The monitor `NoProc` path relies on this.
- **The only wildcard wake is `request_stop`, and it is terminal.** Every
registration-based waker (channel sends, mutex grants, wait-timers, io
completions, joiner wakes, `select` arms) carries the wait's park-epoch
and wakes through `unpark_at`; every successful wake consumes the epoch.
Wakes are therefore *meaningful*: one-shot park sites interpret them
without loops, and `select` needs no cancellation pass. When adding a new
waker, decide which form it is — if its registration handle can outlive
the wait it was created for, it MUST be epoch-stamped; a wait that can
exit without parking MUST `retire_wait` first (see slot_state.rs).
- **`select` exists; a unified per-process mailbox still does not.** The
supervisor keeps its single `supervisor_channel` funnel; `recv_match`
stays per-channel. `select` composes channels at the wait, not into one
queue — gen_server's `handle_info`/`handle_down` (v0.8) are built on
exactly that composition, with documented arm priority (downs → control
→ infos → inbox) instead of mailbox FIFO. A hot higher-priority arm
starves lower ones by design; that's the contract.
- **Cooperative-only.** Preemption and cancellation both depend on the actor
reaching `check!()`/yield/alloc/blocking points.
- **Lock order is Leaf → Channel, one of each at most** (debug-asserted in
`raw_mutex.rs`). Leaf = cold locks / free list / stack pool / registry,
mutual leaves. A channel lock may be taken under a Leaf (finalize/monitor
clone senders living in slots); nothing may be locked under a channel lock.
- **Queue ops require preemption disabled.** A producer suspended mid-publish
stalls every consumer — livelock. `with_runtime`, `with_shared`, and
`RawMutex` guards all disable preemption for their span.
- **`run()` is single-thread** (`Config::exact(1)`); tests rely on deterministic
single-thread ordering. Multi-thread via `runtime::init(Config…)`.
benches/README.md
-89
View File
@@ -1,89 +0,0 @@
# Benches
Two families live here: **comparison benches** (smarm vs tokio, predating
v0.5) and the **run-queue shootout** (v0.5 phase 4). All are plain binaries
(`harness = false` in `Cargo.toml`), so `cargo bench` just builds in release
and runs `main()` — no criterion, no magic.
```
cargo bench --bench <name> # one bench
cargo bench # all of them (slow; rarely what you want)
```
## Catalog
| file | what it measures |
|---|---|
| `primes.rs` | Compute fan-out/fan-in: counts primes across W workers. Pure compute throughput + spawn/join/channel cost. |
| `multi_scheduler.rs` | The original cross-runtime matrix: smarm (1 thread / N threads) vs tokio (current_thread / multi_thread) on compute, ping-pong, and spawn throughput. |
| `general.rs` | Workloads where neither runtime has a structural edge. Large gaps here mean real per-task/per-yield overhead differences — watch these for regressions. |
| `smarm_favored.rs` | Workloads the stackful green-thread model is built for. Single-thread numbers isolate per-switch cost from contention. |
| `tokio_favored.rs` | Workloads tokio's model is built for. Expect to lose; the value is knowing *by how much* and catching the gap widening. |
| `rq_micro.rs` | Run-queue **structures** in isolation (no runtime, no actors): push/pop throughput sweeping thread count × producer:consumer ratio. Covers all three queue types in one binary — the types compile in every build; only the runtime's alias is feature-selected. |
| `rq_runtime.rs` | The **whole scheduler** with the compile-time-selected queue: yield-storm (pure queue churn), ping-pong-pairs (park/unpark latency), spawn-storm (slab + free list + queue churn), sweeping scheduler count. Comparing variants requires rebuilding per `rq-*` feature. |
## The run-queue shootout
One command; it rebuilds `rq_runtime` once per queue variant, runs `rq_micro`
once, and aggregates:
```
./scripts/bench_rq.sh
# on a big box:
SMARM_BENCH_THREADS="1 2 4 8 16 20" ./scripts/bench_rq.sh
```
Outputs land in `bench_results/` (gitignored): one full log per run, plus
`summary.csv` assembled from the machine-readable `RQCSV,...` lines every
config prints alongside the human table.
Manual single-variant runs need the feature dance (features are additive, so
the default `rq-mutex` must be switched off):
```
cargo bench --bench rq_runtime --no-default-features --features rq-striped
```
### Knobs (env vars, all optional)
| var | default | used by |
|---|---|---|
| `SMARM_BENCH_THREADS` | `"1 2 4"` | both — space-separated sweep |
| `SMARM_BENCH_RUNS` | `5` | both — repetitions; the **median** is reported |
| `SMARM_BENCH_ITEMS` | `200000` | `rq_micro` — items per measurement |
| `SMARM_BENCH_YIELD_ACTORS` / `_YIELDS` | `200` / `500` | `rq_runtime` yield-storm |
| `SMARM_BENCH_PAIRS` / `_ROUNDTRIPS` | `32` / `1000` | `rq_runtime` ping-pong |
| `SMARM_BENCH_SPAWNS` | `5000` | `rq_runtime` spawn-storm |
## Reading the numbers honestly
- **Core count is the experiment.** On a 1-core machine (CI, sandboxes) the
sweep only validates the harness and catches gross pathologies —
oversubscribed schedulers measure context-switch noise, not contention.
Variant decisions come from a many-core box.
- The striped queue *should lose* at low thread counts (ticket overhead with
no contention to amortize) — that's expected, not a bug.
- Medians over `SMARM_BENCH_RUNS` absorb scheduling noise but not thermal /
turbo drift; for publishable numbers, pin the CPU governor and run a warmup
pass first.
- `spawn-storm` batches joins (1024 at a time) to stay well under the slab
cap; if you raise `SMARM_BENCH_SPAWNS` massively, that batching is why it
still works.
## Adding a bench
1. `benches/<name>.rs` with a plain `main()`; print the house table (see any
existing bench) and, if it belongs to a sweep, a greppable CSV line with a
distinctive prefix (`RQCSV,` for the shootout family).
2. Register it in `Cargo.toml`:
```toml
[[bench]]
name = "<name>"
harness = false
```
3. Take parameters from `SMARM_BENCH_*` env vars with modest defaults — the
defaults must finish in seconds on one core, the env scales them up on
real hardware.
4. Report **medians**, and keep one measurement = one fresh runtime
(`init(Config::exact(t))` inside the measured closure constructor, the
`run()` inside the timed region) so runs don't contaminate each other.
benches/baseline.json
+142 -142
View File
@@ -2,313 +2,313 @@
"chained_spawn": { "chained_spawn": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 1000, "result": 1000,
"median": 413, "median": 266,
"min": 410, "min": 242,
"max": 439 "max": 351
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 1000, "result": 1000,
"median": 909, "median": 742,
"min": 888, "min": 696,
"max": 951 "max": 860
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 1000, "result": 1000,
"median": 62, "median": 62,
"min": 61, "min": 61,
"max": 62 "max": 68
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 1000, "result": 1000,
"median": 197, "median": 190,
"min": 194, "min": 169,
"max": 210 "max": 207
} }
}, },
"yield_many": { "yield_many": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 200000, "result": 200000,
"median": 16475, "median": 19071,
"min": 16393, "min": 18776,
"max": 16732 "max": 19396
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 200000, "result": 200000,
"median": 148708, "median": 172454,
"min": 111213, "min": 166246,
"max": 156462 "max": 174230
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 200000, "result": 200000,
"median": 4751, "median": 4737,
"min": 4740, "min": 4644,
"max": 5259 "max": 5065
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 200000, "result": 200000,
"median": 8320, "median": 8738,
"min": 7862, "min": 7852,
"max": 8882 "max": 9770
} }
}, },
"fan_out_compute": { "fan_out_compute": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 33860, "result": 33860,
"median": 13453, "median": 13234,
"min": 13305, "min": 13196,
"max": 15077 "max": 13390
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 33860, "result": 33860,
"median": 2451, "median": 2244,
"min": 2330, "min": 2162,
"max": 2520 "max": 2380
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 33860, "result": 33860,
"median": 14019, "median": 14049,
"min": 12339, "min": 14035,
"max": 14045 "max": 14300
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 33860, "result": 33860,
"median": 1500, "median": 1474,
"min": 1426, "min": 1285,
"max": 1600 "max": 1823
} }
}, },
"ping_pong_oneshot": { "ping_pong_oneshot": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 1000, "result": 1000,
"median": 898, "median": 751,
"min": 782, "min": 727,
"max": 920 "max": 913
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 1000, "result": 1000,
"median": 1494, "median": 1308,
"min": 1489, "min": 1227,
"max": 1546 "max": 1396
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 1000, "result": 1000,
"median": 396, "median": 407,
"min": 389, "min": 400,
"max": 409 "max": 444
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 1000, "result": 1000,
"median": 10382, "median": 10869,
"min": 9559, "min": 8683,
"max": 10924 "max": 11688
} }
}, },
"spawn_storm_busy": { "spawn_storm_busy": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 10000, "result": 10000,
"median": 106232, "median": 112045,
"min": 105627, "min": 99936,
"max": 107693 "max": 117329
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 10000, "result": 10000,
"median": 49198, "median": 137105,
"min": 48894, "min": 130852,
"max": 52606 "max": 147707
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 10000, "result": 10000,
"median": 1140, "median": 1128,
"min": 1018, "min": 1123,
"max": 1169 "max": 1435
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 10000, "result": 10000,
"median": 18650, "median": 19674,
"min": 16486, "min": 16013,
"max": 19396 "max": 27234
} }
}, },
"mpsc_contention": { "mpsc_contention": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 320000, "result": 320000,
"median": 6173, "median": 3667,
"min": 5446, "min": 3608,
"max": 6226 "max": 4126
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 320000, "result": 320000,
"median": 36329, "median": 45681,
"min": 35121, "min": 31908,
"max": 37590 "max": 51287
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 320000, "result": 320000,
"median": 5563, "median": 6228,
"min": 5527, "min": 6210,
"max": 6239 "max": 6514
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 320000, "result": 320000,
"median": 63966, "median": 66173,
"min": 59972, "min": 42208,
"max": 67534 "max": 83255
} }
}, },
"many_timers": { "many_timers": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 10000, "result": 10000,
"median": 107826, "median": 119988,
"min": 107093, "min": 107308,
"max": 119034 "max": 123557
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 10000, "result": 10000,
"median": 96539, "median": 218842,
"min": 95413, "min": 182009,
"max": 97804 "max": 256988
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 10000, "result": 10000,
"median": 12584, "median": 12432,
"min": 12539, "min": 12308,
"max": 12627 "max": 13468
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 10000, "result": 10000,
"median": 16183, "median": 16311,
"min": 16024, "min": 15026,
"max": 16541 "max": 16897
} }
}, },
"multi_thread_scaling": { "multi_thread_scaling": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 33860, "result": 33860,
"median": 15083, "median": 14908,
"min": 15071, "min": 14857,
"max": 15283 "max": 15218
}, },
"smarm 2-thread": { "smarm 2-thread": {
"result": 33860, "result": 33860,
"median": 8070, "median": 7834,
"min": 8003, "min": 7717,
"max": 8096 "max": 8033
}, },
"smarm 4-thread": { "smarm 4-thread": {
"result": 33860, "result": 33860,
"median": 4460, "median": 4393,
"min": 4454, "min": 4326,
"max": 4516 "max": 4435
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 33860, "result": 33860,
"median": 2333, "median": 2173,
"min": 2294, "min": 2068,
"max": 2348 "max": 2405
}, },
"tokio multi 1-thread": { "tokio multi 1-thread": {
"result": 33860, "result": 33860,
"median": 14504, "median": 14432,
"min": 14193, "min": 14219,
"max": 14562 "max": 14763
}, },
"tokio multi 2-thread": { "tokio multi 2-thread": {
"result": 33860, "result": 33860,
"median": 7297, "median": 7333,
"min": 7289, "min": 7222,
"max": 7398 "max": 7477
}, },
"tokio multi 4-thread": { "tokio multi 4-thread": {
"result": 33860, "result": 33860,
"median": 3795, "median": 3741,
"min": 3756, "min": 3681,
"max": 3799 "max": 3876
}, },
"tokio multi 24-thread": { "tokio multi 24-thread": {
"result": 33860, "result": 33860,
"median": 1544, "median": 1513,
"min": 1520, "min": 1375,
"max": 1610 "max": 1979
} }
}, },
"deep_recursion": { "deep_recursion": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 1, "result": 1,
"median": 226, "median": 102,
"min": 222, "min": 96,
"max": 243 "max": 123
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 1, "result": 1,
"median": 745, "median": 597,
"min": 744, "min": 576,
"max": 776 "max": 682
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 1, "result": 1,
"median": 11, "median": 13,
"min": 10, "min": 11,
"max": 13 "max": 35
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 1, "result": 1,
"median": 53, "median": 56,
"min": 53, "min": 46,
"max": 57 "max": 65
} }
}, },
"yield_in_hot_loop": { "yield_in_hot_loop": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 1000000, "result": 1000000,
"median": 64849, "median": 80680,
"min": 64396, "min": 80308,
"max": 65283 "max": 81845
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 1000000, "result": 1000000,
"median": 68507, "median": 72606,
"min": 62018, "min": 72154,
"max": 72341 "max": 77206
} }
}, },
"uncontended_channel": { "uncontended_channel": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 1000000, "result": 1000000,
"median": 11949, "median": 9257,
"min": 11928, "min": 9223,
"max": 13596 "max": 12049
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 1000000, "result": 1000000,
"median": 15083, "median": 16925,
"min": 15038, "min": 16848,
"max": 16994 "max": 17019
} }
}, },
"catch_unwind_panics": { "catch_unwind_panics": {
"smarm 1-thread": { "smarm 1-thread": {
"result": 10000, "result": 10000,
"median": 110932, "median": 116821,
"min": 110182, "min": 111345,
"max": 124147 "max": 128261
}, },
"smarm 24-thread": { "smarm 24-thread": {
"result": 10000, "result": 10000,
"median": 13665, "median": 117487,
"min": 13172, "min": 107011,
"max": 13784 "max": 129307
}, },
"tokio current_thread": { "tokio current_thread": {
"result": 10000, "result": 10000,
"median": 10431, "median": 10425,
"min": 9346, "min": 10141,
"max": 10915 "max": 10604
}, },
"tokio multi-thread": { "tokio multi-thread": {
"result": 10000, "result": 10000,
"median": 6171, "median": 6418,
"min": 5626, "min": 3715,
"max": 6555 "max": 7144
} }
} }
} }
benches/bench_rq.sh
-46
View File
@@ -1,46 +0,0 @@
#!/usr/bin/env bash
# Run-queue shootout driver (ROADMAP_v0.5 phase 4; RFC 005 slot dimension
# added for the v0.9 slot shootout).
#
# Rebuilds the runtime bench once per rq-* feature and runs the raw-structure
# microbench once (it covers all structures in a single binary). The RFC 005
# wake slot is a runtime Config knob, NOT a feature — each rq_runtime binary
# sweeps slot off/on internally (SMARM_BENCH_SLOT, default "0 1"). Results
# land in bench_results/ as full logs; the RQCSV lines are aggregated into
# bench_results/summary.csv and the RQSLOT counter lines (slot hits /
# displacements, slot-on configs only) into bench_results/slot_counters.csv.
#
# Tune the sweep for the box, e.g. on the 20-core machine:
# SMARM_BENCH_THREADS="1 2 4 8 16 20" ./scripts/bench_rq.sh
# Slot-only re-run against the frozen rq-mutex substrate:
# SMARM_BENCH_SLOT="0 1" cargo bench --bench rq_runtime
set -euo pipefail
cd "$(dirname "$0")/.."
OUT=bench_results
mkdir -p "$OUT"
: "${SMARM_BENCH_THREADS:=1 2 4}"
: "${SMARM_BENCH_SLOT:=0 1}"
export SMARM_BENCH_THREADS SMARM_BENCH_SLOT
echo "== raw structures (one binary, all variants) =="
cargo bench --bench rq_micro 2>&1 | tee "$OUT/micro.txt"
for v in rq-mutex rq-mpmc rq-striped; do
echo "== runtime benches: $v (slot sweep: $SMARM_BENCH_SLOT) =="
cargo bench --bench rq_runtime --no-default-features --features "$v" \
2>&1 | tee "$OUT/runtime-$v.txt"
done
# runtime rows: kind,variant,slot,bench,threads,work,median_us,ops_per_s
# micro rows: kind,structure,threads,p:c,items,median_us,items_per_s (one
# column narrower, as before — split on kind when plotting)
echo "kind,a,b,c,d,e,median_us,ops_per_s" > "$OUT/summary.csv"
grep -h '^RQCSV,' "$OUT"/*.txt | sed 's/^RQCSV,//' >> "$OUT/summary.csv"
echo "variant,bench,threads,slot_hits,slot_displacements" > "$OUT/slot_counters.csv"
grep -h '^RQSLOT,' "$OUT"/*.txt | sed 's/^RQSLOT,//' >> "$OUT/slot_counters.csv" || true
echo
echo "Summary: $OUT/summary.csv ($(($(wc -l < "$OUT/summary.csv") - 1)) rows)"
echo "Slot counters: $OUT/slot_counters.csv ($(($(wc -l < "$OUT/slot_counters.csv") - 1)) rows)"
benches/general.rs
+3 -14
View File
@@ -29,13 +29,6 @@ fn available_threads() -> usize {
std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1) std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1)
} }
fn env_sets() -> u32 {
std::env::var("SMARM_BENCH_SETS")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(5)
}
fn print_header(title: &str) { fn print_header(title: &str) {
println!("\n{}", "=".repeat(80)); println!("\n{}", "=".repeat(80));
println!(" {title}"); println!(" {title}");
@@ -48,18 +41,15 @@ fn print_header(title: &str) {
} }
fn run_n<F: FnMut() -> (u64, u128)>(name: &str, n: u32, mut f: F) { fn run_n<F: FnMut() -> (u64, u128)>(name: &str, n: u32, mut f: F) {
let sets = env_sets(); let mut times = Vec::new();
let mut times = Vec::with_capacity((n * sets) as usize);
let mut last = 0u64; let mut last = 0u64;
// One warmup before all sets, discarded. // One warmup iteration, discarded.
let _ = f(); let _ = f();
for _ in 0..sets {
for _ in 0..n { for _ in 0..n {
let (v, t) = f(); let (v, t) = f();
times.push(t); times.push(t);
last = v; last = v;
} }
}
times.sort_unstable(); times.sort_unstable();
let median = times[times.len() / 2]; let median = times[times.len() / 2];
let min = *times.iter().min().unwrap(); let min = *times.iter().min().unwrap();
@@ -416,8 +406,7 @@ fn main() {
let n = available_threads(); let n = available_threads();
println!("smarm general benchmarks"); println!("smarm general benchmarks");
println!("available parallelism: {n} threads"); println!("available parallelism: {n} threads");
let sets = env_sets(); println!("ITERS={ITERS} (+1 warmup, discarded)");
println!("ITERS={ITERS}×{sets} sets = {} samples (+1 warmup, discarded)", ITERS * sets);
println!( println!(
"CHAIN_DEPTH={CHAIN_DEPTH}, YIELD_TASKS={YIELD_TASKS}×{YIELD_ROUNDS}, \ "CHAIN_DEPTH={CHAIN_DEPTH}, YIELD_TASKS={YIELD_TASKS}×{YIELD_ROUNDS}, \
PRIME_N={PRIME_N}/{PRIME_WORKERS} workers, PP_ROUNDS={PP_ROUNDS}" PRIME_N={PRIME_N}/{PRIME_WORKERS} workers, PP_ROUNDS={PP_ROUNDS}"
benches/rq_micro.rs
-186
View File
@@ -1,186 +0,0 @@
//! Raw run-queue microbench (ROADMAP_v0.5 phase 4).
//!
//! Benches the three queue STRUCTURES directly — no runtime, no actors — to
//! isolate the data structure under contention. All three types compile in
//! every build, so this binary covers the whole matrix in one run; it does
//! NOT need the rq-* feature rebuild dance (that's `rq_runtime`).
//!
//! Sweeps thread count × producer:consumer ratio. Queues are sized to the
//! item count, so the occupancy contract holds trivially and producers never
//! block on capacity.
//!
//! Knobs (env):
//! SMARM_BENCH_THREADS space-separated sweep, default "1 2 4"
//! SMARM_BENCH_ITEMS items per measurement, default 200_000
//! SMARM_BENCH_RUNS repetitions per config (median reported), default 5
//!
//! Output: the house table, plus one machine-readable line per config:
//! RQCSV,micro,<structure>,<threads>,<p:c>,<items>,<median_us>,<items_per_s>
//!
//! NOTE: numbers from a 1-core sandbox only validate the harness; real
//! contention curves come from the many-core box (scripts/bench_rq.sh).
use smarm::pid::Pid;
use smarm::run_queue::{MpmcRing, MutexQueue, StripedRing};
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
use std::time::Instant;
fn env_usize(key: &str, default: usize) -> usize {
std::env::var(key).ok().and_then(|v| v.parse().ok()).unwrap_or(default)
}
fn env_threads() -> Vec<usize> {
std::env::var("SMARM_BENCH_THREADS")
.map(|v| v.split_whitespace().filter_map(|t| t.parse().ok()).collect())
.unwrap_or_else(|_| vec![1, 2, 4])
}
/// Generic driver: `producers` threads push `items` total, `consumers`
/// threads pop until everything is accounted for. Returns elapsed µs.
fn drive<Q: Send + Sync + 'static>(
q: Arc<Q>,
push: fn(&Q, Pid),
pop: fn(&Q) -> Option<Pid>,
producers: usize,
consumers: usize,
items: usize,
) -> u128 {
let remaining = Arc::new(AtomicUsize::new(items));
let start = Instant::now();
let mut hs = Vec::new();
let per = items / producers;
for p in 0..producers {
let q = q.clone();
// Give the last producer the remainder.
let n = if p == producers - 1 { items - per * (producers - 1) } else { per };
hs.push(std::thread::spawn(move || {
let pid = Pid::new(p as u32, 0);
for _ in 0..n {
push(&q, pid);
}
}));
}
for _ in 0..consumers {
let q = q.clone();
let remaining = remaining.clone();
hs.push(std::thread::spawn(move || loop {
// Claim-then-pop so consumers exit promptly when the budget hits
// zero; the claim is backed out on a miss.
let r = remaining.load(Ordering::Relaxed);
if r == 0 {
return;
}
if pop(&q).is_some() {
remaining.fetch_sub(1, Ordering::Relaxed);
} else {
std::hint::spin_loop();
}
}));
}
for h in hs {
h.join().unwrap();
}
start.elapsed().as_micros()
}
/// Single-thread alternating push/pop (the T = 1 case).
fn drive_single<Q>(q: &Q, push: fn(&Q, Pid), pop: fn(&Q) -> Option<Pid>, items: usize) -> u128 {
let pid = Pid::new(0, 0);
let start = Instant::now();
for _ in 0..items {
push(q, pid);
assert!(pop(q).is_some());
}
start.elapsed().as_micros()
}
struct Case {
structure: &'static str,
threads: usize,
producers: usize,
consumers: usize,
}
fn ratios_for(threads: usize) -> Vec<(usize, usize)> {
if threads < 2 {
return vec![(1, 1)]; // label only; T=1 runs the alternating driver
}
let mut v = vec![(threads / 2, threads - threads / 2)]; // balanced
if threads >= 4 {
v.push((3 * threads / 4, threads - 3 * threads / 4)); // producer-heavy
v.push((threads / 4, threads - threads / 4)); // consumer-heavy
}
v
}
fn main() {
let threads_sweep = env_threads();
let items = env_usize("SMARM_BENCH_ITEMS", 200_000);
let runs = env_usize("SMARM_BENCH_RUNS", 5);
println!("\n{}", "=".repeat(86));
println!(" run-queue raw structures — items={items}, runs={runs} (median)");
println!("{}", "=".repeat(86));
println!(
"{:>10} | {:>7} | {:>7} | {:>10} | {:>14}",
"structure", "threads", "p:c", "median µs", "items/s"
);
println!("{}", "-".repeat(86));
let mut cases = Vec::new();
for &t in &threads_sweep {
for (p, c) in ratios_for(t) {
for s in ["mutex", "mpmc", "striped"] {
cases.push(Case { structure: s, threads: t, producers: p, consumers: c });
}
}
}
for case in cases {
let mut times: Vec<u128> = (0..runs)
.map(|_| {
// Fresh queue per run; capacity = items so pushes never stall.
match case.structure {
"mutex" => {
let q = Arc::new(MutexQueue::new(case.threads, items));
if case.threads < 2 {
drive_single(&*q, MutexQueue::push, MutexQueue::pop, items)
} else {
drive(q, MutexQueue::push, MutexQueue::pop, case.producers, case.consumers, items)
}
}
"mpmc" => {
let q = Arc::new(MpmcRing::with_capacity(items));
if case.threads < 2 {
drive_single(&*q, MpmcRing::push, MpmcRing::pop, items)
} else {
drive(q, MpmcRing::push, MpmcRing::pop, case.producers, case.consumers, items)
}
}
"striped" => {
let q = Arc::new(StripedRing::new(case.threads.max(1), items));
if case.threads < 2 {
drive_single(&*q, StripedRing::push, StripedRing::pop, items)
} else {
drive(q, StripedRing::push, StripedRing::pop, case.producers, case.consumers, items)
}
}
_ => unreachable!(),
}
})
.collect();
times.sort_unstable();
let median = times[times.len() / 2];
let per_s = (items as f64 / (median as f64 / 1e6)) as u64;
let ratio = format!("{}:{}", case.producers, case.consumers);
println!(
"{:>10} | {:>7} | {:>7} | {:>10} | {:>14}",
case.structure, case.threads, ratio, median, per_s
);
println!(
"RQCSV,micro,{},{},{},{},{},{}",
case.structure, case.threads, ratio, items, median, per_s
);
}
}
benches/rq_runtime.rs
-252
View File
@@ -1,252 +0,0 @@
//! Runtime-level run-queue benches (ROADMAP_v0.5 phase 4; slot dimension
//! added for the v0.9 slot shootout, RFC 005).
//!
//! These exercise the WHOLE scheduler with the compile-time-selected queue,
//! so comparing variants means rebuilding per rq-* feature — that's what
//! scripts/bench_rq.sh does. The RFC 005 wake slot is a *runtime* Config
//! knob, so one binary benches both arms; the slot on/off sweep happens
//! inside this binary. Workloads:
//!
//! yield-storm — N actors yield K times each. Pure queue churn:
//! every yield is a push + pop with nothing in between.
//! Slot role: REGRESSION GUARD — yields never touch the
//! slot, any slot-on delta is pop-path overhead.
//! ping-pong-pairs — P channel pairs, M roundtrips each. Park/unpark
//! latency through the queue.
//! Slot role: TARGET METRIC — every send-wake is an
//! actor-context unpark, the slot's home pattern.
//! spawn-storm — S spawn+join of trivial actors. Slab + queue + free
//! list under churn.
//! Slot role: NEUTRALITY CHECK — spawns bypass the slot
//! by policy; join wakes fire from finalize (scheduler
//! context), also shared.
//!
//! Knobs (env):
//! SMARM_BENCH_THREADS scheduler-count sweep, default "1 2 4"
//! SMARM_BENCH_SLOT wake-slot sweep, default "0 1" (off then on)
//! SMARM_BENCH_RUNS repetitions per config (median), default 5
//! SMARM_BENCH_YIELD_ACTORS / _YIELDS default 200 / 500
//! SMARM_BENCH_PAIRS / _ROUNDTRIPS default 32 / 1000
//! SMARM_BENCH_SPAWNS default 5000
//!
//! Output: house table + one line per config:
//! RQCSV,runtime,<variant>,<slot>,<bench>,<threads>,<work>,<median_us>,<ops_per_s>
//! plus, for slot-on configs, the RFC 005 observability counters:
//! RQSLOT,<variant>,<bench>,<threads>,<slot_hits>,<slot_displacements>
//! (hits/displacements are taken from the same run as the median time).
//!
//! NOTE: a 1-core sandbox validates the harness, not the scaling story;
//! real curves come from the many-core box.
use smarm::runtime::{init, Config};
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::Instant;
fn variant() -> &'static str {
if cfg!(feature = "rq-mpmc") {
"rq-mpmc"
} else if cfg!(feature = "rq-striped") {
"rq-striped"
} else {
"rq-mutex"
}
}
fn env_usize(key: &str, default: usize) -> usize {
std::env::var(key).ok().and_then(|v| v.parse().ok()).unwrap_or(default)
}
fn env_threads() -> Vec<usize> {
std::env::var("SMARM_BENCH_THREADS")
.map(|v| v.split_whitespace().filter_map(|t| t.parse().ok()).collect())
.unwrap_or_else(|_| vec![1, 2, 4])
}
fn env_slots() -> Vec<bool> {
std::env::var("SMARM_BENCH_SLOT")
.map(|v| {
v.split_whitespace()
.filter_map(|t| match t {
"0" | "off" | "false" => Some(false),
"1" | "on" | "true" => Some(true),
_ => None,
})
.collect()
})
.unwrap_or_else(|_| vec![false, true])
}
/// One measured run: (total_ops, elapsed_µs, slot_hits, slot_displacements).
struct Sample {
ops: u64,
us: u128,
hits: u64,
displacements: u64,
}
fn yield_storm(threads: usize, slot: bool, actors: usize, yields: usize) -> Sample {
let rt = init(Config::exact(threads).wake_slot(slot));
let start = Instant::now();
rt.run(move || {
let handles: Vec<_> = (0..actors)
.map(|_| {
smarm::spawn(move || {
for _ in 0..yields {
smarm::yield_now();
}
})
})
.collect();
for h in handles {
let _ = h.join();
}
});
let us = start.elapsed().as_micros();
let stats = rt.stats();
Sample {
ops: (actors * yields) as u64,
us,
hits: stats.slot_hits(),
displacements: stats.slot_displacements(),
}
}
fn ping_pong_pairs(threads: usize, slot: bool, pairs: usize, roundtrips: usize) -> Sample {
let rt = init(Config::exact(threads).wake_slot(slot));
let total = Arc::new(AtomicU64::new(0));
let t2 = total.clone();
let start = Instant::now();
rt.run(move || {
let handles: Vec<_> = (0..pairs)
.map(|_| {
let total = t2.clone();
smarm::spawn(move || {
let (tx_ab, rx_ab) = smarm::channel::channel::<u64>();
let (tx_ba, rx_ba) = smarm::channel::channel::<u64>();
let n = roundtrips as u64;
let echo = smarm::spawn(move || {
for _ in 0..n {
let v = rx_ab.recv().expect("echo recv");
tx_ba.send(v + 1).expect("echo send");
}
});
for i in 0..n {
tx_ab.send(i).expect("ping send");
let v = rx_ba.recv().expect("ping recv");
assert_eq!(v, i + 1);
}
let _ = echo.join();
total.fetch_add(n, Ordering::Relaxed);
})
})
.collect();
for h in handles {
let _ = h.join();
}
});
let us = start.elapsed().as_micros();
let stats = rt.stats();
Sample {
ops: total.load(Ordering::Relaxed),
us,
hits: stats.slot_hits(),
displacements: stats.slot_displacements(),
}
}
fn spawn_storm(threads: usize, slot: bool, spawns: usize) -> Sample {
let rt = init(Config::exact(threads).wake_slot(slot));
let start = Instant::now();
rt.run(move || {
// Batches bound simultaneous liveness well below the slab cap.
const BATCH: usize = 1024;
let mut left = spawns;
while left > 0 {
let n = left.min(BATCH);
let handles: Vec<_> = (0..n).map(|_| smarm::spawn(|| {})).collect();
for h in handles {
let _ = h.join();
}
left -= n;
}
});
let us = start.elapsed().as_micros();
let stats = rt.stats();
Sample {
ops: spawns as u64,
us,
hits: stats.slot_hits(),
displacements: stats.slot_displacements(),
}
}
fn main() {
let threads_sweep = env_threads();
let slot_sweep = env_slots();
let runs = env_usize("SMARM_BENCH_RUNS", 5);
let ya = env_usize("SMARM_BENCH_YIELD_ACTORS", 200);
let yy = env_usize("SMARM_BENCH_YIELDS", 500);
let pp = env_usize("SMARM_BENCH_PAIRS", 32);
let pr = env_usize("SMARM_BENCH_ROUNDTRIPS", 1000);
let ss = env_usize("SMARM_BENCH_SPAWNS", 5000);
println!("\n{}", "=".repeat(106));
println!(
" runtime benches — variant={}, runs={runs} (median)",
variant()
);
println!("{}", "=".repeat(106));
println!(
"{:>16} | {:>7} | {:>4} | {:>16} | {:>10} | {:>14} | {:>10} | {:>9}",
"bench", "threads", "slot", "work", "median µs", "ops/s", "slot hits", "displaced"
);
println!("{}", "-".repeat(106));
type Bench = (&'static str, String, Box<dyn Fn(usize, bool) -> Sample>);
let benches: Vec<Bench> = vec![
(
"yield-storm",
format!("{ya}x{yy}"),
Box::new(move |t, s| yield_storm(t, s, ya, yy)),
),
(
"ping-pong-pairs",
format!("{pp}x{pr}"),
Box::new(move |t, s| ping_pong_pairs(t, s, pp, pr)),
),
(
"spawn-storm",
format!("{ss}"),
Box::new(move |t, s| spawn_storm(t, s, ss)),
),
];
for (name, work, f) in &benches {
for &t in &threads_sweep {
for &slot in &slot_sweep {
let mut samples: Vec<Sample> = (0..runs).map(|_| f(t, slot)).collect();
// Median by elapsed time; report the counters from that
// same run so hits/time stay paired.
samples.sort_unstable_by_key(|s| s.us);
let mid = &samples[samples.len() / 2];
let per_s = (mid.ops as f64 / (mid.us as f64 / 1e6)) as u64;
let slot_str = if slot { "on" } else { "off" };
println!(
"{:>16} | {:>7} | {:>4} | {:>16} | {:>10} | {:>14} | {:>10} | {:>9}",
name, t, slot_str, work, mid.us, per_s, mid.hits, mid.displacements
);
println!(
"RQCSV,runtime,{},{},{},{},{},{},{}",
variant(), slot_str, name, t, work, mid.us, per_s
);
if slot {
println!(
"RQSLOT,{},{},{},{},{}",
variant(), name, t, mid.hits, mid.displacements
);
}
}
}
}
}
benches/smarm_favored.rs
+3 -15
View File
@@ -40,13 +40,6 @@ fn available_threads() -> usize {
std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1) std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1)
} }
fn env_sets() -> u32 {
std::env::var("SMARM_BENCH_SETS")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(5)
}
fn print_header(title: &str) { fn print_header(title: &str) {
println!("\n{}", "=".repeat(80)); println!("\n{}", "=".repeat(80));
println!(" {title}"); println!(" {title}");
@@ -59,18 +52,14 @@ fn print_header(title: &str) {
} }
fn run_n<F: FnMut() -> (u64, u128)>(name: &str, n: u32, mut f: F) { fn run_n<F: FnMut() -> (u64, u128)>(name: &str, n: u32, mut f: F) {
let sets = env_sets(); let mut times = Vec::new();
let mut times = Vec::with_capacity((n * sets) as usize);
let mut last = 0u64; let mut last = 0u64;
// One warmup before all sets, discarded. let _ = f(); // warmup
let _ = f();
for _ in 0..sets {
for _ in 0..n { for _ in 0..n {
let (v, t) = f(); let (v, t) = f();
times.push(t); times.push(t);
last = v; last = v;
} }
}
times.sort_unstable(); times.sort_unstable();
let median = times[times.len() / 2]; let median = times[times.len() / 2];
let min = *times.iter().min().unwrap(); let min = *times.iter().min().unwrap();
@@ -396,8 +385,7 @@ fn main() {
let n = available_threads(); let n = available_threads();
println!("smarm smarm-favored benchmarks"); println!("smarm smarm-favored benchmarks");
println!("available parallelism: {n} threads"); println!("available parallelism: {n} threads");
let sets = env_sets(); println!("ITERS={ITERS} (+1 warmup, discarded)");
println!("ITERS={ITERS}×{sets} sets = {} samples (+1 warmup, discarded)", ITERS * sets);
println!( println!(
"RECURSE_DEPTH={RECURSE_DEPTH}, HOT_YIELDS={HOT_YIELDS}×2, \ "RECURSE_DEPTH={RECURSE_DEPTH}, HOT_YIELDS={HOT_YIELDS}×2, \
UNCONT_MSGS={UNCONT_MSGS}, PANIC_TASKS={PANIC_TASKS}" UNCONT_MSGS={UNCONT_MSGS}, PANIC_TASKS={PANIC_TASKS}"
benches/sweep.py
+5 -137
View File
@@ -50,11 +50,6 @@ SWEEP_GRID = [
(128, 1_200_000), (128, 1_200_000),
] ]
# Number of independent cargo bench processes per measurement point.
# Each process is a fully isolated run (fresh warmup, cold caches, new PID),
# so the final median is a median of independent samples — robust to OS noise.
BENCH_SETS = 5
# Regression threshold: warn if median is more than this % worse than baseline. # Regression threshold: warn if median is more than this % worse than baseline.
REGRESSION_THRESHOLD_PCT = 10 REGRESSION_THRESHOLD_PCT = 10
@@ -108,12 +103,9 @@ def parse_output(text: str) -> dict[str, dict[str, dict]]:
# Running # Running
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
def run_benches_once(env_extra: dict[str, str] | None = None) -> dict[str, dict[str, dict]]: def run_benches(env_extra: dict[str, str] | None = None) -> dict[str, dict[str, dict]]:
"""Run all BENCHES once and return merged parsed results.""" """Run all BENCHES and return merged parsed results."""
env = os.environ.copy() env = os.environ.copy()
# Each process does exactly one set of ITERS samples — no within-process
# accumulation; the caller handles multi-set aggregation.
env["SMARM_BENCH_SETS"] = "1"
if env_extra: if env_extra:
env.update(env_extra) env.update(env_extra)
@@ -137,45 +129,6 @@ def run_benches_once(env_extra: dict[str, str] | None = None) -> dict[str, dict[
return all_results return all_results
def run_benches(env_extra: dict[str, str] | None = None, sets: int = BENCH_SETS) -> dict[str, dict[str, dict]]:
"""Run BENCH_SETS independent processes and return median-of-medians per label.
Each set is a separate cargo bench invocation with its own warmup and OS
context, so samples are statistically independent. The final median and
min/max are computed over the per-set medians.
"""
# Accumulate per-set medians: {bench: {label: [median_set1, median_set2, ...]}}
accumulated: dict[str, dict[str, list[int]]] = {}
last_result: dict[str, dict[str, int]] = {}
for i in range(sets):
print(f" set {i + 1}/{sets}…", flush=True)
set_results = run_benches_once(env_extra)
for bench, labels in set_results.items():
accumulated.setdefault(bench, {})
last_result.setdefault(bench, {})
for label, data in labels.items():
accumulated[bench].setdefault(label, [])
accumulated[bench][label].append(data["median"])
last_result[bench][label] = data["result"]
# Collapse to final stats.
final: dict[str, dict[str, dict]] = {}
for bench, labels in accumulated.items():
final[bench] = {}
for label, medians in labels.items():
medians.sort()
mid = medians[len(medians) // 2]
final[bench][label] = {
"result": last_result[bench][label],
"median": mid,
"min": medians[0],
"max": medians[-1],
}
return final
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# Baseline JSON # Baseline JSON
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
@@ -243,90 +196,6 @@ def check_regressions(current: dict, baseline: dict) -> bool:
# Pretty print # Pretty print
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
def _threads(label: str) -> int | None:
"""Worker-thread count implied by a runtime label.
tokio's `current_thread` is a single-threaded executor (1); an explicit
`multi N-thread` is N; a bare `multi-thread` has no count (None) — tokio's
default work-stealing pool, paired against smarm's widest config.
"""
if "current_thread" in label:
return 1
m = re.search(r"(\d+)-thread", label)
return int(m.group(1)) if m else None
def vs_tokio(results: dict) -> list[tuple]:
"""Per bench, like-for-like smarm-vs-tokio rows matched by thread count.
Exact thread-count matches are paired directly (smarm 1-thread vs tokio
current_thread, smarm 4-thread vs tokio multi 4-thread, …). tokio's bare
`multi-thread` (no explicit count) is paired against the widest unmatched
smarm multi-thread config. Lower median µs = faster; ratio = tokio_med /
smarm_med, so ratio > 1 means smarm is that many times faster.
Returns rows of (bench, smarm_label, smarm_med, tokio_label, tokio_med,
ratio, winner). Benches without a comparable pair are skipped.
"""
rows: list[tuple] = []
for bench, runtimes in sorted(results.items()):
smarm: dict[int, tuple[str, int]] = {}
tokio: dict[int, tuple[str, int]] = {}
tokio_default: tuple[str, int] | None = None # bare 'multi-thread'
for label, data in runtimes.items():
n = _threads(label)
if label.startswith("smarm"):
if n is not None:
smarm[n] = (label, data["median"])
elif label.startswith("tokio"):
if n is None:
tokio_default = (label, data["median"])
else:
tokio[n] = (label, data["median"])
def row(s: tuple[str, int], t: tuple[str, int]):
s_label, s_med = s
t_label, t_med = t
if s_med == 0:
return None
ratio = t_med / s_med
return (bench, s_label, s_med, t_label, t_med, ratio,
"smarm" if ratio >= 1.0 else "tokio")
matched: set[int] = set()
for n in sorted(set(smarm) & set(tokio)):
r = row(smarm[n], tokio[n])
if r:
rows.append(r)
matched.add(n)
# tokio's default multi pool vs the widest smarm config not already paired.
if tokio_default is not None:
rem = [n for n in smarm if n not in matched and n > 1]
if rem:
r = row(smarm[max(rem)], tokio_default)
if r:
rows.append(r)
return rows
def print_vs_tokio(results: dict) -> None:
"""Human summary + greppable VSTOKIO lines (best smarm vs best tokio)."""
rows = vs_tokio(results)
if not rows:
return
print("\n vs tokio (like-for-like by thread count; ratio>1 = smarm faster, lower µs better)")
print(f" {'-'*78}")
for bench, s_label, s_med, t_label, t_med, ratio, winner in rows:
print(
f" {bench:<22} {s_label} {s_med}µs vs {t_label} {t_med}µs"
f" → {ratio:.2f}x ({winner})"
)
# Machine-readable, one line per bench:
# VSTOKIO,<bench>,<smarm_label>,<smarm_us>,<tokio_label>,<tokio_us>,<ratio>,<winner>
for bench, s_label, s_med, t_label, t_med, ratio, winner in rows:
print(f"VSTOKIO,{bench},{s_label},{s_med},{t_label},{t_med},{ratio:.3f},{winner}")
def print_results(results: dict, label: str = "") -> None: def print_results(results: dict, label: str = "") -> None:
if label: if label:
print(f"\n{'='*70}") print(f"\n{'='*70}")
@@ -341,7 +210,6 @@ def print_results(results: dict, label: str = "") -> None:
f" {rt_label:>28} | {data['result']:>10} | " f" {rt_label:>28} | {data['result']:>10} | "
f"{data['median']:>10} | {data['min']:>8} | {data['max']:>8}" f"{data['median']:>10} | {data['min']:>8} | {data['max']:>8}"
) )
print_vs_tokio(results)
def print_sweep_table(sweep_results: list[tuple[int, int, dict]]) -> None: def print_sweep_table(sweep_results: list[tuple[int, int, dict]]) -> None:
@@ -384,7 +252,7 @@ def cmd_run(args) -> None:
["cargo", "build", "--release", "--benches"], ["cargo", "build", "--release", "--benches"],
cwd=REPO, check=True, capture_output=True, cwd=REPO, check=True, capture_output=True,
) )
print(f"Running benches ({BENCH_SETS} independent sets)…") print("Running benches…")
results = run_benches() results = run_benches()
print_results(results, "Results (default knobs)") print_results(results, "Results (default knobs)")
if args.save_baseline: if args.save_baseline:
@@ -398,7 +266,7 @@ def cmd_regress(args) -> None:
["cargo", "build", "--release", "--benches"], ["cargo", "build", "--release", "--benches"],
cwd=REPO, check=True, capture_output=True, cwd=REPO, check=True, capture_output=True,
) )
print(f"Running benches ({BENCH_SETS} independent sets)…") print("Running benches…")
current = run_benches() current = run_benches()
print_results(current, "Current results") print_results(current, "Current results")
print(f"\nRegression check (threshold: >{REGRESSION_THRESHOLD_PCT}% slower than baseline)") print(f"\nRegression check (threshold: >{REGRESSION_THRESHOLD_PCT}% slower than baseline)")
@@ -420,7 +288,7 @@ def cmd_sweep(args) -> None:
for interval, cycles in SWEEP_GRID: for interval, cycles in SWEEP_GRID:
tag = f"alloc_interval={interval}, timeslice_cycles={cycles}" tag = f"alloc_interval={interval}, timeslice_cycles={cycles}"
print(f" Running: {tag} ({BENCH_SETS} sets)…", flush=True) print(f" Running: {tag} …", flush=True)
env_extra = { env_extra = {
"SMARM_ALLOC_INTERVAL": str(interval), "SMARM_ALLOC_INTERVAL": str(interval),
"SMARM_TIMESLICE_CYCLES": str(cycles), "SMARM_TIMESLICE_CYCLES": str(cycles),
benches/switch_cost.rs
-256
View File
@@ -1,256 +0,0 @@
//! Per-switch (context-switch) cost microbench — the profiling-spike harness
//! for the ROADMAP "Per-switch cost (context shims, epoch protocol)" item.
//!
//! The spin work (RFC 004) is closed; the next perf target is the per-switch
//! cost itself. Shootout evidence: per-wake latency is ~0.16–0.18µs at N=1 but
//! ~0.8–1.2µs at N=8+, and the residual is attributed to the context-switch
//! shims (`src/context.rs`) and the epoch protocol — NOT the queue. This binary
//! isolates that round-trip so the cycles can be attributed under `perf` and an
//! rdtsc bracket, feeding the RFC.
//!
//! WHAT THE ROUND-TRIP IS
//!
//! `yield_now()` from inside an actor does exactly one park/unpark round-trip
//! with nothing else attached:
//!
//! actor: switch_to_scheduler ──► scheduler re-queues the actor (slot-word
//! (context.rs shim) epoch/state transition, run_queue push),
//! pops it straight back, switch_to_actor
//! actor resumes ◄──────────────────────────────────────────────────────
//!
//! No IO thread traffic, no channel, no timer, no cross-thread wake. On a
//! single-scheduler runtime the re-queue+repop never leaves this core, so the
//! sample is the *pure* shim + epoch + queue-op cost with zero coherency
//! traffic. That is the `local` baseline; a `remote` mode (wake straddling two
//! schedulers, to expose the N=1→N=8 coherency/TLS-mode jump) is a deliberate
//! follow-up and is NOT in this file yet — local first, per the spike plan.
//!
//! TWO LENSES ON THE SAME LOOP
//!
//! wall — `Instant` bracket per round-trip. Source of truth for µs, directly
//! comparable to the shootout's per-wake latency numbers.
//! cycles — `rdtsc` bracket per round-trip. Source of truth for the cycle
//! budget the RFC will reason in (the spin budget is in cycles too).
//!
//! Reporting both lets us *derive* the effective TSC frequency (cycles/ns) from
//! the same samples instead of hardcoding a nominal 3.7GHz — the spin_sweep
//! lesson was that nominal-vs-actual TSC drift is exactly what produces
//! red-herring numbers. If the derived freq matches the box's known base clock,
//! the two lenses corroborate; if not, that mismatch is itself a finding.
//!
//! Knobs (env):
//! SMARM_SWITCH_ROUNDS round-trips timed per run default 200000
//! SMARM_SWITCH_WARMUP untimed warmup round-trips default 10000
//! SMARM_SWITCH_RUNS runs (pooled latency, median) default 5
//!
//! Output: house table + one greppable line per run-set:
//! SWITCHCSV,<variant>,<mode>,<rounds>,<runs>,<n>,<p50_ns>,<p90_ns>,<p99_ns>,
//! <min_ns>,<max_ns>,<mean_ns>,<mean_cyc>,<derived_ghz>
//!
//! NOTE: a single yielding actor is the cooperative-scheduling tightest loop —
//! it never parks on a futex (the work is always immediately re-queued), so
//! this measures the switch+epoch+queue path, NOT the futex park. That is
//! intentional: the futex park is the spin work's territory (RFC 004), already
//! characterised. The unattributed constant the shootout flagged lives in the
//! switch itself, which is what this loop hammers.
use smarm::runtime::{init, Config};
use smarm::{run, spawn, yield_now};
use std::sync::{Arc, Mutex};
// --------------------------------------------------------------------------
// env helpers (house style, matching spin_sweep.rs / rq_runtime.rs)
// --------------------------------------------------------------------------
fn variant() -> &'static str {
if cfg!(feature = "rq-mpmc") {
"rq-mpmc"
} else if cfg!(feature = "rq-striped") {
"rq-striped"
} else {
"rq-mutex"
}
}
fn env_usize(key: &str, default: usize) -> usize {
std::env::var(key).ok().and_then(|v| v.parse().ok()).unwrap_or(default)
}
// --------------------------------------------------------------------------
// rdtsc — serialised so the bracket actually fences the round-trip.
//
// Plain `rdtsc` can be reordered around the work by an out-of-order core, which
// would smear the bracket. `rdtscp` retires prior instructions before reading
// the counter, and the trailing `lfence` blocks later instructions from
// climbing above the second read. Pair = (rdtscp; lfence) … work … (rdtscp;
// lfence): a standard cycle-accurate bracket. We read TSC_AUX too but ignore
// it; the point is the ordering guarantee, not the core id.
// --------------------------------------------------------------------------
#[inline(always)]
fn rdtsc_serialised() -> u64 {
#[cfg(target_arch = "x86_64")]
unsafe {
let mut aux = 0u32;
let t = core::arch::x86_64::__rdtscp(&mut aux);
core::arch::x86_64::_mm_lfence();
t
}
#[cfg(not(target_arch = "x86_64"))]
{
// Non-x86 fallback: nanosecond clock standing in for cycles. The derived
// "GHz" column then reads ~1.0 and is meaningless, but the wall lens and
// the harness still work. The spike target box is x86-64.
use std::time::Instant;
thread_local! { static T0: Instant = Instant::now(); }
T0.with(|t0| t0.elapsed().as_nanos() as u64)
}
}
// --------------------------------------------------------------------------
// percentile / median helpers (verbatim house idiom from spin_sweep.rs)
// --------------------------------------------------------------------------
/// Nearest-rank percentile over an already-sorted slice. `p` in [0, 100].
fn pct(sorted: &[u64], p: f64) -> u64 {
if sorted.is_empty() {
return 0;
}
let idx = ((p / 100.0) * (sorted.len() - 1) as f64).round() as usize;
sorted[idx.min(sorted.len() - 1)]
}
// --------------------------------------------------------------------------
// one run: a single actor yields ROUNDS times; we bracket each yield from
// inside the actor (the only vantage point — the actor is suspended during the
// scheduler half, so an external timer can't see a single round-trip).
//
// Per iteration we capture BOTH a wall-ns delta and a TSC-cycle delta around
// the same `yield_now()`. The loop overhead (two clock reads + a Vec push +
// the branch) rides along in every sample equally; we subtract an empty-loop
// self-calibration below so the reported number is the round-trip, not the
// instrumentation.
// --------------------------------------------------------------------------
struct RunSample {
lat_ns: Vec<u64>,
cyc: Vec<u64>,
}
fn one_run(threads: usize, rounds: usize, warmup: usize) -> RunSample {
let out: Arc<Mutex<Option<RunSample>>> = Arc::new(Mutex::new(None));
let out2 = out.clone();
let cfg = Config::exact(threads);
init(cfg);
run(move || {
let h = spawn(move || {
// Warmup: let the actor's stack/queue slot go hot, JIT-free but
// cache-warm, before any sample is kept.
for _ in 0..warmup {
yield_now();
}
let mut lat_ns = Vec::with_capacity(rounds);
let mut cyc = Vec::with_capacity(rounds);
for _ in 0..rounds {
let w0 = std::time::Instant::now();
let c0 = rdtsc_serialised();
yield_now();
let c1 = rdtsc_serialised();
let w1 = w0.elapsed();
cyc.push(c1.saturating_sub(c0));
lat_ns.push(w1.as_nanos() as u64);
}
*out2.lock().unwrap() = Some(RunSample { lat_ns, cyc });
});
let _ = h.join();
});
let sample = out.lock().unwrap().take().expect("actor stored a sample");
sample
}
/// Empty-loop self-calibration: the same bracket with the `yield_now()` removed,
/// run inline (no runtime). Gives the floor cost of two serialised clock reads +
/// the push, in both lenses, to subtract from the round-trip samples.
fn calibrate(rounds: usize) -> (u64, u64) {
let mut lat_ns = Vec::with_capacity(rounds);
let mut cyc = Vec::with_capacity(rounds);
let mut sink = 0u64;
for _ in 0..rounds {
let w0 = std::time::Instant::now();
let c0 = rdtsc_serialised();
// no yield — measure the bracket itself
let c1 = rdtsc_serialised();
let w1 = w0.elapsed();
sink ^= c1;
cyc.push(c1.saturating_sub(c0));
lat_ns.push(w1.as_nanos() as u64);
}
std::hint::black_box(sink);
cyc.sort_unstable();
lat_ns.sort_unstable();
// Use the medians as the floor — robust to the occasional interrupt.
(pct(&lat_ns, 50.0), pct(&cyc, 50.0))
}
fn main() {
let rounds = env_usize("SMARM_SWITCH_ROUNDS", 200_000);
let warmup = env_usize("SMARM_SWITCH_WARMUP", 10_000);
let runs = env_usize("SMARM_SWITCH_RUNS", 5);
let mode = "local";
// Calibrate the instrumentation floor once, with a healthy sample.
let (floor_ns, floor_cyc) = calibrate(rounds.min(50_000).max(10_000));
let mut pooled_ns: Vec<u64> = Vec::new();
let mut pooled_cyc: Vec<u64> = Vec::new();
for _ in 0..runs {
let s = one_run(1, rounds, warmup);
// Subtract the instrumentation floor; saturating so a sub-floor outlier
// (clock granularity) clamps to 0 rather than wrapping.
pooled_ns.extend(s.lat_ns.iter().map(|&v| v.saturating_sub(floor_ns)));
pooled_cyc.extend(s.cyc.iter().map(|&v| v.saturating_sub(floor_cyc)));
}
pooled_ns.sort_unstable();
pooled_cyc.sort_unstable();
let n = pooled_ns.len();
let mean_ns = pooled_ns.iter().map(|&v| v as f64).sum::<f64>() / n.max(1) as f64;
let mean_cyc = pooled_cyc.iter().map(|&v| v as f64).sum::<f64>() / n.max(1) as f64;
// Derived effective frequency: cycles per ns = GHz. Cross-checks the two
// lenses against the box's known base clock.
let derived_ghz = if mean_ns > 0.0 { mean_cyc / mean_ns } else { 0.0 };
let p50 = pct(&pooled_ns, 50.0);
let p90 = pct(&pooled_ns, 90.0);
let p99 = pct(&pooled_ns, 99.0);
let lo = *pooled_ns.first().unwrap_or(&0);
let hi = *pooled_ns.last().unwrap_or(&0);
// House table.
println!();
println!("per-switch cost — {} mode, variant={}", mode, variant());
println!(
" rounds={} warmup={} runs={} (instrumentation floor: {} ns / {} cyc, subtracted)",
rounds, warmup, runs, floor_ns, floor_cyc
);
println!(" {:<10} {:<10} {:<10} {:<10} {:<10}", "p50 ns", "p90 ns", "p99 ns", "min ns", "max ns");
println!(" {:<10} {:<10} {:<10} {:<10} {:<10}", p50, p90, p99, lo, hi);
println!(
" mean {:.1} ns | mean {:.0} cyc | derived {:.3} GHz",
mean_ns, mean_cyc, derived_ghz
);
// Greppable line — same spirit as SPINCSV.
println!(
"SWITCHCSV,{},{},{},{},{},{},{},{},{},{},{:.1},{:.0},{:.3}",
variant(), mode, rounds, runs, n, p50, p90, p99, lo, hi, mean_ns, mean_cyc, derived_ghz
);
}
benches/tokio_favored.rs
+3 -15
View File
@@ -39,13 +39,6 @@ fn available_threads() -> usize {
std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1) std::thread::available_parallelism().map(|n| n.get()).unwrap_or(1)
} }
fn env_sets() -> u32 {
std::env::var("SMARM_BENCH_SETS")
.ok()
.and_then(|v| v.parse().ok())
.unwrap_or(5)
}
fn print_header(title: &str) { fn print_header(title: &str) {
println!("\n{}", "=".repeat(80)); println!("\n{}", "=".repeat(80));
println!(" {title}"); println!(" {title}");
@@ -58,18 +51,14 @@ fn print_header(title: &str) {
} }
fn run_n<F: FnMut() -> (u64, u128)>(name: &str, n: u32, mut f: F) { fn run_n<F: FnMut() -> (u64, u128)>(name: &str, n: u32, mut f: F) {
let sets = env_sets(); let mut times = Vec::new();
let mut times = Vec::with_capacity((n * sets) as usize);
let mut last = 0u64; let mut last = 0u64;
// One warmup before all sets, discarded. let _ = f(); // warmup
let _ = f();
for _ in 0..sets {
for _ in 0..n { for _ in 0..n {
let (v, t) = f(); let (v, t) = f();
times.push(t); times.push(t);
last = v; last = v;
} }
}
times.sort_unstable(); times.sort_unstable();
let median = times[times.len() / 2]; let median = times[times.len() / 2];
let min = *times.iter().min().unwrap(); let min = *times.iter().min().unwrap();
@@ -445,8 +434,7 @@ fn main() {
let n = available_threads(); let n = available_threads();
println!("smarm tokio-favored benchmarks"); println!("smarm tokio-favored benchmarks");
println!("available parallelism: {n} threads"); println!("available parallelism: {n} threads");
let sets = env_sets(); println!("ITERS={ITERS} (+1 warmup, discarded)");
println!("ITERS={ITERS}×{sets} sets = {} samples (+1 warmup, discarded)", ITERS * sets);
println!( println!(
"STORM_BACKGROUND={STORM_BACKGROUND}, STORM_SPAWN={STORM_SPAWN}, \ "STORM_BACKGROUND={STORM_BACKGROUND}, STORM_SPAWN={STORM_SPAWN}, \
MPSC={MPSC_PRODUCERS}×{MPSC_PER_PRODUCER}, \ MPSC={MPSC_PRODUCERS}×{MPSC_PER_PRODUCER}, \
docs/perswitch-profile-n1.md
-87
View File
@@ -1,87 +0,0 @@
# Per-switch cost — N=1 local profile (spike findings)
Measured with `benches/switch_cost.rs` (local mode: one actor, one scheduler,
tight `yield_now()` loop = one park/unpark round-trip with no IO/channel/timer
and no cross-core traffic). Sandbox: 1 core, kernel 6.18, **no PMU** (hardware
counters unavailable), so attribution is from `perf record -e task-clock`
(software timer sampling) plus the bench's own rdtsc/wall brackets.
> **Provenance (post-excision).** This profile was captured against the
> spin-enabled build (the pre-excision HEAD, with the RFC 004 spinning workers
> live in `src/runtime.rs`). The RFC 004 spinning experiment has since been
> excised from `master`; idle schedulers are back to the historical
> `thread::sleep` wait. The `futex_wake` attribution below therefore reflects
> spinning machinery that is **no longer present on current master** — see the
> per-row and per-finding notes. The shim, `schedule_loop`, and run-queue
> findings are spin-independent and remain valid.
## Numbers (stable across runs)
- Round-trip p50 ≈ **303 ns ≈ 828 cyc** (instrumentation floor subtracted).
- Derived effective clock ≈ **2.73 GHz** (rdtsc cyc / wall ns — the two lenses
corroborate, so the cycle counts are trustworthy).
- p90 316 ns, p99 472 ns; max is a multi-ms OS-deschedule outlier (1 shared
core) — ignore the max, trust the percentiles (the harness pools them).
## Attribution (perf task-clock, self-time, 28.6k samples / 12M round-trips)
| share | symbol | bucket |
|------:|--------|--------|
| 24.8% | `runtime::schedule_loop` | scheduler logic (slot-word/epoch + dispatch) |
| 8.6% | `MutexQueue::push`/`pop`/`len` | run-queue ops |
| ~12% | `do_syscall_64`+`syscall`+`futex_*` | **futex_wake on the hot path** — spinning submit-rule wake; removed by the RFC 004 excision (not on current master) |
| 3.5% | `IoThread::drain_completions` | the always-on IO thread (`run()` starts one) |
| ~30% | `main` + `clock_gettime`/Timespec + `quicksort` | **instrumentation** (timing + percentile sort) |
| ~1% | `switch_to_scheduler`+`switch_to_actor_asm`+ sp accessors | **the context shims + TLS** |
## Headline finding — revises the handoff hypothesis
The handoff named the **context shims** (`context.rs`: two `call`s into the
TLS sp accessors per switch) as the prime suspect for the per-switch cost.
**At N=1 that is not where the time goes — the shims + TLS are ~1% of
self-time.** The N=1 cost is dominated by:
1. **`schedule_loop` + run-queue ops (~33%)** — the epoch/slot-word transition
and the mutex run-queue push/pop on every re-queue.
2. **A `futex_wake` syscall (~12%)** fired on the hot path even though nothing
was parked. This was the spinning **submit-rule wake** introduced by the RFC
004 experiment — a parallelism/latency optimisation, not a liveness guard. In
a single-scheduler always-runnable loop it was pure cost (no one was ever
parked to wake). The RFC 004 excision removed this wake with the rest of the
spinning machinery: on current master idle schedulers use `thread::sleep`
again, so the N=1 hot path no longer makes this syscall.
## What this does and does NOT show
- The handoff's shim hypothesis was a **many-core** hypothesis: its evidence was
the N=1→N=8 jump (0.18→1.2µs), attributed to TLS access mode (`__tls_get_addr`
vs `#[thread_local]`) and cross-core coherency on the sp/epoch words. **None of
that is observable at N=1 on one core.** This profile does NOT refute it; it
establishes that the shim is cheap *until cores contend*.
- So the spike question sharpens into two separable costs:
- **N=1 floor:** scheduler logic (`schedule_loop` + run-queue ops). The
futex_wake component was spinning machinery and is gone post-excision, so the
remaining N=1 floor is the scheduler core itself.
- **N→8 slope:** the shim/TLS/coherency cost. Needs the many-core box + a
`remote` bench mode (wake straddling two schedulers) + hardware PMU counters
(cache-misses, `MEM_LOAD…HITM` for coherency) — none available in this sandbox.
## Reproduce
```sh
. "$HOME/.cargo/env"
cargo build --release --bench switch_cost
BIN=$(ls -t target/release/deps/switch_cost-* | grep -v '\.d$' | head -1)
PERF=/usr/lib/linux-tools-6.8.0-124/perf # 6.8 perf on 6.18 kernel; sw events only here
# bench alone (numbers):
SMARM_SWITCH_ROUNDS=3000000 SMARM_SWITCH_WARMUP=50000 SMARM_SWITCH_RUNS=4 "$BIN"
# attribution (sw task-clock; HW counters need a real PMU / the 5900X):
SMARM_SWITCH_ROUNDS=3000000 "$PERF" record -F 4000 -g --call-graph fp -o /tmp/switch.data -- "$BIN"
"$PERF" report -i /tmp/switch.data --stdio --no-children
```
On the 5900X with a real PMU, drop `-e task-clock` for `-e cycles,instructions,
cache-misses,mem_load_retired.l3_miss` to get the coherency picture the N=8 case
needs.
docs/smarm - Deep Dive.html
+432 -870
View File
File diff suppressed because it is too large Load Diff
examples/gen_statem_expanded.rs
-308
View File
@@ -1,308 +0,0 @@
//! The hand-written **expansion target** of the `gen_statem!` macro: the same
//! machine as `examples/gen_statem_macro.rs`, written out in full so the
//! primitives can be judged standing on their own. The macro generates exactly
//! this shape; nothing here needs the macro to be correct or safe.
//!
//! The design:
//!
//! * States and events are real enums. An invalid state is unrepresentable;
//! there are no bitflags, no `u32` superpositions, no unsafe unions.
//!
//! * The dispatch `match (state, event)` IS the transition table. It is
//! *total* — no catch-all `_` arm — so:
//! - a forgotten (state, event) pair is a non-exhaustive `match` (E0004),
//! - a duplicated/conflicting row is `unreachable_patterns` (denied below).
//!
//! * Single-target rows name their target in the table; the handler (if any)
//! is side-effect-only. The table owns the target, so it cannot be wrong.
//!
//! * Branching rows have the handler return a per-row *successor enum*. A
//! target outside that enum is E0599; a missing one is E0004. (See
//! `UnlockOutcome` and `on_unlock`.)
//!
//! * Handlers are module-private. The only way to reach one is through the
//! actor's message interface via this table, so a handler that is never
//! wired in is dead code — and dead_code is denied below, making an orphan
//! handler a compile error.
//!
//! * Drops onto the `Machine` / `Resolution` / `Cx` primitives with no change
//! to `src/gen_statem.rs`.
//!
//! Default build is clean and runs. A BREAK-CASE MENU at the bottom documents
//! how to make each of the four guarantees fire.
//!
//! Run: `cargo run --example gen_statem_expanded`
#![deny(dead_code, unreachable_patterns)]
use smarm::run;
use smarm::gen_statem::{spawn, Cx, Machine, Reply, Resolution, Step, GenStatemRef};
// === user types ============================================================
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Door {
Open,
Closed,
Locked,
}
struct Data {
enters: u32, // total state entries (incl. initial)
pushes: u32, // times a push closed the door
knocks: u32, // knocks answered (a Locked knock is postponed, then counted)
}
enum Cast {
Push,
Pull,
Lock,
Unlock(u32), // carries a key
Knock, // counted when the door is reachable; postponed while Locked
}
enum Call {
GetState(Reply<Door>),
GetEnters(Reply<u32>),
GetPushes(Reply<u32>),
GetKnocks(Reply<u32>),
}
enum Ev {
Cast(Cast),
Call(Call),
// The runtime's internal events. `Info` is out-of-band (here unused, so
// `()`); `StateTimeout` / `Timeout` are timer fires the loop feeds back in.
Info(()),
StateTimeout,
Timeout(&'static str),
}
const CODE: u32 = 1234;
// === per-row successor enum for the one branching row ======================
// `Locked + Unlock` may end in Closed (right key) or Locked (wrong key) — and
// nothing else. This type IS that declared set; `on_unlock` cannot name Open.
enum UnlockOutcome {
Closed,
Locked,
}
impl From<UnlockOutcome> for Door {
fn from(o: UnlockOutcome) -> Door {
match o {
UnlockOutcome::Closed => Door::Closed,
UnlockOutcome::Locked => Door::Locked,
}
}
}
// === module-private handlers (side effects / branch choice only) ===========
// Reachable solely through the table below. Orphan one and it is dead_code.
fn on_push(data: &mut Data) {
data.pushes += 1;
}
fn on_unlock(key: u32) -> UnlockOutcome {
if key == CODE {
UnlockOutcome::Closed
} else {
UnlockOutcome::Locked // wrong key: caller will see this == current -> stay
}
}
// === the machine ===========================================================
struct DoorSm {
state: Door,
data: Data,
}
impl DoorSm {
fn start(init: Door) -> GenStatemRef<DoorSm> {
spawn(DoorSm {
state: init,
data: Data { enters: 0, pushes: 0, knocks: 0 },
})
}
fn enter(&mut self, cx: &mut Cx<Ev>) {
self.data.enters += 1;
// A state-timeout: an Open door auto-closes after a quiet window. The
// loop auto-resets it on any transition, so it fires only if the door is
// still Open when it elapses.
if self.state == Door::Open {
cx.state_timeout(std::time::Duration::from_millis(5));
}
}
}
impl Machine for DoorSm {
type Ev = Ev;
fn state_timeout_ev() -> Ev {
Ev::StateTimeout
}
fn timeout_ev(name: &'static str) -> Ev {
Ev::Timeout(name)
}
fn on_start(&mut self, cx: &mut Cx<Ev>) {
self.enter(cx);
}
fn handle(&mut self, ev: Ev, cx: &mut Cx<Ev>) -> Step<Ev> {
let prev = self.state;
// ---- phase 1: postpone routing (borrow-only) ----------------------
// A deferred event is handed back untouched for the loop's postpone
// queue; no handler code runs on it. Here: a knock at a locked door.
// (The macro emits this as a `match (state, &ev)` yielding a bool; the
// hand-written form can just test directly.)
if let (Door::Locked, Ev::Cast(Cast::Knock)) = (prev, &ev) {
return Step::Postponed(ev);
}
// ---- phase 2: the consuming transition table ----------------------
// Total over (Door, Ev). Read it as the declared graph: each `=> To(x)`
// is an edge, each `=> Unhandled` an explicit refusal. The postponed
// pair above reappears as `unreachable!` so the match stays total.
let res: Resolution<Door> = match (self.state, ev) {
// --- Open -------------------------------------------------------
(Door::Open, Ev::Cast(Cast::Push)) => {
on_push(&mut self.data);
Resolution::To(Door::Closed)
}
(Door::Open, Ev::Cast(Cast::Knock)) => {
self.data.knocks += 1;
Resolution::To(prev)
}
(Door::Open, Ev::Cast(Cast::Pull | Cast::Lock | Cast::Unlock(_))) => {
Resolution::Unhandled
}
// --- Closed -----------------------------------------------------
(Door::Closed, Ev::Cast(Cast::Pull)) => Resolution::To(Door::Open),
(Door::Closed, Ev::Cast(Cast::Lock)) => Resolution::To(Door::Locked),
(Door::Closed, Ev::Cast(Cast::Knock)) => {
self.data.knocks += 1;
Resolution::To(prev)
}
(Door::Closed, Ev::Cast(Cast::Push | Cast::Unlock(_))) => Resolution::Unhandled,
// --- Locked (branching row: handler picks within UnlockOutcome) -
(Door::Locked, Ev::Cast(Cast::Unlock(key))) => {
Resolution::To(on_unlock(key).into())
}
// Routed out in phase 1; listed only to keep this match total.
(Door::Locked, Ev::Cast(Cast::Knock)) => {
unreachable!("postponed event is replayed, not dispatched here")
}
(Door::Locked, Ev::Cast(Cast::Push | Cast::Pull | Cast::Lock)) => {
Resolution::Unhandled
}
// --- state-independent queries (reply, then stay) ---------------
(_, Ev::Call(Call::GetState(r))) => {
r.reply(prev);
Resolution::To(prev)
}
(_, Ev::Call(Call::GetEnters(r))) => {
r.reply(self.data.enters);
Resolution::To(prev)
}
(_, Ev::Call(Call::GetPushes(r))) => {
r.reply(self.data.pushes);
Resolution::To(prev)
}
(_, Ev::Call(Call::GetKnocks(r))) => {
r.reply(self.data.knocks);
Resolution::To(prev)
}
// --- timeouts: an Open door auto-closes; others have none armed --
(Door::Open, Ev::StateTimeout) => Resolution::To(Door::Closed),
(_, Ev::StateTimeout) => Resolution::Unhandled,
(_, Ev::Timeout(name)) => {
// No named timeout is armed in this run; a real handler would
// dispatch on `name`. Acknowledge it to exercise the field.
let _ = name;
Resolution::Unhandled
}
// --- out-of-band info: silent drop (the gen_server default) ------
(_, Ev::Info(_)) => Resolution::Unhandled,
};
// ---- apply the resolution -----------------------------------------
match res {
Resolution::To(s) if s == prev => Step::Stayed, // stay: no enter
Resolution::To(s) => {
self.state = s; // sole writer of the state cell
cx.__reset_state_timeout(); // auto-reset across transitions
self.enter(cx);
Step::Transitioned
}
Resolution::Unhandled => {
cx.on_unhandled();
Step::Stayed
}
}
}
}
fn main() {
run(|| {
let door = DoorSm::start(Door::Closed);
door.send(Ev::Cast(Cast::Lock)).unwrap(); // Closed -> Locked
door.send(Ev::Cast(Cast::Knock)).unwrap(); // Locked: postponed (not yet counted)
door.send(Ev::Cast(Cast::Push)).unwrap(); // Locked: Push invalid -> Unhandled
door.send(Ev::Cast(Cast::Unlock(0))).unwrap(); // Locked: wrong key -> stay (knock still deferred)
door.send(Ev::Cast(Cast::Unlock(CODE))).unwrap(); // Locked -> Closed; deferred Knock replays here
door.send(Ev::Cast(Cast::Push)).unwrap(); // Closed: Push invalid -> Unhandled
door.send(Ev::Cast(Cast::Pull)).unwrap(); // Closed -> Open (arms 5ms auto-close)
door.send(Ev::Info(())).unwrap(); // out-of-band: silently dropped
// Wait past the auto-close window: the state-timeout fires and the door
// closes itself, with no further input. (`smarm::sleep` parks the actor
// without blocking a worker thread, so the timer wheel keeps turning.)
smarm::sleep(std::time::Duration::from_millis(40));
let st = door.call(|r| Ev::Call(Call::GetState(r))).unwrap();
let enters = door.call(|r| Ev::Call(Call::GetEnters(r))).unwrap();
let pushes = door.call(|r| Ev::Call(Call::GetPushes(r))).unwrap();
let knocks = door.call(|r| Ev::Call(Call::GetKnocks(r))).unwrap();
println!("state={st:?} enters={enters} pushes={pushes} knocks={knocks}");
assert_eq!(st, Door::Closed); // auto-closed by the state-timeout
assert_eq!(enters, 5); // Closed(start) + Locked + Closed + Open + Closed
assert_eq!(pushes, 0); // no push ever closed it this run
assert_eq!(knocks, 1); // the locked-door knock, replayed once unlocked
println!("ok");
});
}
// ===========================================================================
// BREAK-CASE MENU — each makes one compile-time guarantee fire.
//
// 1. ORPHAN HANDLER (dead_code -> error):
// add `fn on_slam(_d: &mut Data) {}` and don't reference it.
// => error: function `on_slam` is never used
//
// 2. CONFLICTING ROW (unreachable_patterns -> error):
// duplicate an arm, e.g. add a second
// `(Door::Open, Ev::Cast(Cast::Push)) => Resolution::Unhandled,`
// => error: unreachable pattern
//
// 3. MISSING PAIR (non-exhaustive match, E0004):
// delete the `(Door::Locked, Ev::Cast(Cast::Push | Cast::Pull | Cast::Lock))`
// arm.
// => error[E0004]: non-exhaustive patterns: ... not covered
//
// 4. OUT-OF-SET TARGET (E0599):
// in `on_unlock`, return `UnlockOutcome::Open`.
// => error[E0599]: no variant ... named `Open` found for enum `UnlockOutcome`
// ===========================================================================
examples/gen_statem_macro.rs
-187
View File
@@ -1,187 +0,0 @@
//! The **same** machine as `examples/gen_statem_expanded.rs`, written through the
//! `gen_statem!` macro. Diff this file against that one to see exactly what the
//! macro buys: every `// ===` section there that was boilerplate (the `Ev`
//! enum, the `DoorSm` struct, `start`, the whole `Machine` impl, the `enter`
//! dispatch, the stay/transition apply-tail) collapses into the invocation
//! below. What stays hand-written is what carries meaning: the four types, the
//! per-state successor enum, and the handler fns.
//!
//! The point of the exercise is that the macro is *pure sugar*: the four
//! compile-time guarantees the hand-written form demonstrates are properties of
//! the emitted code, not of the macro, so they survive expansion unchanged. The
//! BREAK-CASE MENU at the bottom is the same four cases, re-expressed against
//! the macro surface — flip any one on and the compiler fires identically.
//!
//! Run: `cargo run --example gen_statem_macro`
#![deny(dead_code)] // guarantee #3 (orphan handlers); the macro denies the
// dispatch's own unreachable_patterns internally.
use smarm::gen_statem;
use smarm::run;
use smarm::gen_statem::Reply;
// === user types (identical to gen_statem_expanded.rs) =========================
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Door {
Open,
Closed,
Locked,
}
struct Data {
enters: u32, // total state entries (incl. initial)
pushes: u32, // times a push closed the door
knocks: u32, // knocks answered (a Locked knock is postponed, then counted)
}
enum Cast {
Push,
Pull,
Lock,
Unlock(u32), // carries a key
Knock, // counted when the door is reachable; postponed while Locked
}
enum Call {
GetState(Reply<Door>),
GetEnters(Reply<u32>),
GetPushes(Reply<u32>),
GetKnocks(Reply<u32>),
}
const CODE: u32 = 1234;
// === per-row successor enum for the one branching row ======================
// `Locked + Unlock` may end in Closed (right key) or Locked (wrong key) — and
// nothing else. This type IS that declared set; `on_unlock` cannot name Open.
enum UnlockOutcome {
Closed,
Locked,
}
impl From<UnlockOutcome> for Door {
fn from(o: UnlockOutcome) -> Door {
match o {
UnlockOutcome::Closed => Door::Closed,
UnlockOutcome::Locked => Door::Locked,
}
}
}
// === module-private handlers (side effects / branch choice only) ===========
// Reachable solely through the table below. Orphan one and it is dead_code.
fn on_push(data: &mut Data) {
data.pushes += 1;
}
fn on_unlock(key: u32) -> UnlockOutcome {
if key == CODE {
UnlockOutcome::Closed
} else {
UnlockOutcome::Locked // wrong key: caller will see this == current -> stay
}
}
// === the machine ===========================================================
// Everything below — Ev, DoorSm, start, Machine, enter — is generated.
gen_statem! {
machine: DoorSm { state: Door, data: Data };
event: Ev { cast: Cast, call: Call, info: () };
// You name the bindings the bodies use; the macro can't lend you its own
// `self`/`cx` across macro hygiene. `data` = &mut Data, `prev` = current
// state tag, `cx` = context handle (unused here).
context(data, prev, cx);
enter {
_ => data.enters += 1,
}
on Door::Open => {
cast Cast::Push => { on_push(data); Door::Closed },
cast Cast::Knock => { data.knocks += 1; prev },
cast Cast::Pull | Cast::Lock | Cast::Unlock(_) => unhandled,
}
on Door::Closed => {
cast Cast::Pull => Door::Open,
cast Cast::Lock => Door::Locked,
cast Cast::Knock => { data.knocks += 1; prev },
cast Cast::Push | Cast::Unlock(_) => unhandled,
}
on Door::Locked => {
cast Cast::Unlock(key) => on_unlock(key), // branch -> UnlockOutcome
// A knock at a locked door waits: defer it until the door is reachable,
// where the replay counts it.
cast Cast::Knock => postpone,
cast Cast::Push | Cast::Pull | Cast::Lock => unhandled,
}
// state-independent queries (reply, then stay via `prev`)
on _ => {
call Call::GetState(r) => { r.reply(prev); prev },
call Call::GetEnters(r) => { r.reply(data.enters); prev },
call Call::GetPushes(r) => { r.reply(data.pushes); prev },
call Call::GetKnocks(r) => { r.reply(data.knocks); prev },
// This machine arms no timeouts, so refuse them everywhere. (Info has a
// built-in silent-drop default, so it needs no row.)
state_timeout => unhandled,
timeout _ => unhandled,
}
}
fn main() {
run(|| {
let door = DoorSm::start(Door::Closed, Data { enters: 0, pushes: 0, knocks: 0 });
door.send(Ev::Cast(Cast::Lock)).unwrap(); // Closed -> Locked
door.send(Ev::Cast(Cast::Knock)).unwrap(); // Locked: postponed (not yet counted)
door.send(Ev::Cast(Cast::Push)).unwrap(); // Locked: Push invalid -> Unhandled
door.send(Ev::Cast(Cast::Unlock(0))).unwrap(); // Locked: wrong key -> stay (knock still deferred)
door.send(Ev::Cast(Cast::Unlock(CODE))).unwrap(); // Locked -> Closed; deferred Knock replays here
door.send(Ev::Cast(Cast::Pull)).unwrap(); // Closed -> Open
door.send(Ev::Cast(Cast::Push)).unwrap(); // Open -> Closed (pushes=1)
let st = door.call(|r| Ev::Call(Call::GetState(r))).unwrap();
let enters = door.call(|r| Ev::Call(Call::GetEnters(r))).unwrap();
let pushes = door.call(|r| Ev::Call(Call::GetPushes(r))).unwrap();
let knocks = door.call(|r| Ev::Call(Call::GetKnocks(r))).unwrap();
println!("state={st:?} enters={enters} pushes={pushes} knocks={knocks}");
assert_eq!(st, Door::Closed);
assert_eq!(enters, 5); // Closed(start) + Locked + Closed + Open + Closed
assert_eq!(pushes, 1);
assert_eq!(knocks, 1); // the locked-door knock, replayed once unlocked
println!("ok");
});
}
// ===========================================================================
// BREAK-CASE MENU — the four guarantees, through the macro. Each fires exactly
// as it does in the hand-written gen_statem_expanded.rs.
//
// 1. ORPHAN HANDLER (dead_code -> error):
// add `fn on_slam(_d: &mut Data) {}` and don't reference it.
// => error: function `on_slam` is never used
//
// 2. CONFLICTING ROW (unreachable_patterns):
// duplicate a row, e.g. add a second
// `cast Cast::Push => unhandled,` under `on Door::Open`.
// NOTE: this example is a separate crate from `smarm`, so rustc's
// in_external_macro rule SILENCES this lint here even though the macro
// denies it — the duplicate compiles. The guarantee is real only for
// machines defined inside the `smarm` crate itself. This is the documented
// macro_rules! limitation.
//
// 3. MISSING PAIR (non-exhaustive match, E0004):
// delete the `cast Cast::Push | Cast::Pull | Cast::Lock => unhandled,`
// row under `on Door::Locked`.
// => error[E0004]: non-exhaustive patterns: ... not covered
//
// 4. OUT-OF-SET TARGET (E0599):
// in `on_unlock`, return `UnlockOutcome::Open`.
// => error[E0599]: no variant ... named `Open` found for enum `UnlockOutcome`
// ===========================================================================
examples/named_genserver.rs
-69
View File
@@ -1,69 +0,0 @@
//! Addressing a gen_server by a durable name.
//!
//! A gen_server is multi-message (call / cast over one inbox), so it is named
//! by the *server* type rather than by a single message type. Registering it
//! under a [`GenServerName`] lets clients `call` and `cast` by name, resolving on
//! every use — so the address keeps working across a supervised restart, with
//! no stale [`GenServerRef`] to refresh.
use smarm::{call, cast, run, whereis_server, GenServer, GenServerBuilder, GenServerName, GenServerRef};
/// A counter server: synchronous `Get`, asynchronous `Inc` / `Add`.
struct Counter {
n: u64,
}
enum Query {
Get,
}
enum Update {
Inc,
Add(u64),
}
impl GenServer for Counter {
type Call = Query;
type Reply = u64;
type Cast = Update;
type Info = ();
type Timer = ();
fn handle_call(&mut self, q: Query) -> u64 {
match q {
Query::Get => self.n,
}
}
fn handle_cast(&mut self, u: Update) {
match u {
Update::Inc => self.n += 1,
Update::Add(k) => self.n += k,
}
}
}
/// A durable name typed by the server, so by-name `call` / `cast` check against
/// `Counter`'s `Call` / `Cast` / `Reply`.
const COUNTER: GenServerName<Counter> = GenServerName::new("counter");
fn main() {
run(|| {
// Start the server and bind its name in one step. A named start is
// fallible: the name may already be held by another live server.
GenServerBuilder::new(Counter { n: 0 })
.named(COUNTER)
.start()
.unwrap();
// Address it purely by name. Each call/cast resolves through the
// registry, so a server restarted under the same name is reached
// transparently.
cast(COUNTER, Update::Inc).unwrap();
cast(COUNTER, Update::Add(41)).unwrap();
assert_eq!(call(COUNTER, Query::Get).unwrap(), 42);
// When you want a handle to hold or pass on rather than resolve per
// call, recover a typed `GenServerRef` from the name.
let svc: Option<GenServerRef<Counter>> = whereis_server(COUNTER);
if let Some(svc) = svc {
let _ = svc.call(Query::Get);
}
});
}
examples/observer.rs
-150
View File
@@ -1,150 +0,0 @@
//! The live observer (RFC 016 Chunk 4) producing an OTP `observer`-flavoured
//! dump of a running system.
//!
//! Run it with the feature on:
//!
//! ```text
//! cargo run --example observer --features observer
//! ```
//!
//! It stands up a tiny tree — a named service plus two workers parked on a gate
//! — starts the [`observer`](smarm::observer) gen_server, then asks it for a
//! snapshot and a tree over the call channel and renders both. The observer is
//! pure transport: every line below is the Chunk-1 read
//! ([`snapshot`](smarm::snapshot) / [`tree`](smarm::tree)) marshalled across a
//! `call`, nothing more.
use smarm::observer::{self, ObserverReply, ObserverRequest};
use smarm::{channel, register, run, spawn, ActorState, Name, RuntimeSnapshot, RuntimeTree, TreeNode};
const ECHO: Name<u64> = Name::new("echo");
fn state_glyph(s: ActorState) -> &'static str {
match s {
ActorState::Queued => "queued",
ActorState::Running => "running",
ActorState::Notified => "notified",
ActorState::Parked => "parked",
ActorState::Done => "done",
}
}
/// A `ps`-style table over the flat snapshot.
fn print_snapshot(snap: &RuntimeSnapshot) {
println!("snapshot (format v{}, {} actors)", snap.format_version, snap.actors.len());
println!(
" {:<10} {:<9} {:<10} {:>4} {:>4} {:>4} {:>4} {:>5} {}",
"pid", "state", "parent", "mon", "lnk", "joi", "mbox", "msgs", "names"
);
for a in &snap.actors {
let parent = if a.supervisor.index() == u32::MAX {
"<root>".to_string()
} else {
format!("{}.{}", a.supervisor.index(), a.supervisor.generation())
};
println!(
" {:<10} {:<9} {:<10} {:>4} {:>4} {:>4} {:>4} {:>5} {}",
format!("{}.{}", a.pid.index(), a.pid.generation()),
state_glyph(a.state),
parent,
a.monitors,
a.links,
a.joiners,
a.mailbox_depth,
a.messages_received,
if a.names.is_empty() { "-".to_string() } else { a.names.join(",") },
);
}
}
/// The parentage forest, indented.
fn print_tree(t: &RuntimeTree) {
println!("tree (format v{})", t.format_version);
fn walk(node: &TreeNode, depth: usize) {
let indent = " ".repeat(depth + 1);
let flag = if node.orphaned { " [orphaned]" } else { "" };
let names = if node.info.names.is_empty() {
String::new()
} else {
format!(" ({})", node.info.names.join(","))
};
println!(
"{indent}{}.{} {}{names}{flag}",
node.info.pid.index(),
node.info.pid.generation(),
state_glyph(node.info.state),
);
for child in &node.children {
walk(child, depth + 1);
}
}
for root in &t.roots {
walk(root, 0);
}
}
fn main() {
run(|| {
// A named echo service and two anonymous workers, all parked on a gate
// so the system holds still while we observe it. Each gets its own gate
// receiver (a Receiver is single-consumer); we keep the senders to
// release them at the end.
let (ready_tx, ready_rx) = channel::<()>();
let mut gates = Vec::new();
let svc = {
let (gate_tx, gate_rx) = channel::<()>();
gates.push(gate_tx);
let ready_tx = ready_tx.clone();
spawn(move || {
let (cmd_tx, cmd_rx) = channel::<u64>();
register(ECHO, cmd_tx).unwrap();
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
drop(cmd_rx);
})
};
let workers: Vec<_> = (0..2)
.map(|_| {
let (gate_tx, gate_rx) = channel::<()>();
gates.push(gate_tx);
let ready_tx = ready_tx.clone();
spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
})
})
.collect();
// Wait until all three have announced and parked.
for _ in 0..3 {
ready_rx.recv().unwrap();
}
// Queue two commands at the echo service so its mailbox depth is visible.
smarm::send(ECHO, 1).unwrap();
smarm::send(ECHO, 2).unwrap();
// Start the observer and dump the system through it.
let obs = observer::start();
let ObserverReply::Snapshot(snap) = obs.call(ObserverRequest::Snapshot).unwrap() else {
unreachable!()
};
let ObserverReply::Tree(t) = obs.call(ObserverRequest::Tree).unwrap() else {
unreachable!()
};
print_snapshot(&snap);
println!();
print_tree(&t);
// Release everyone and drain.
for gate_tx in gates {
gate_tx.send(()).unwrap();
}
svc.join().unwrap();
for w in workers {
w.join().unwrap();
}
});
}
examples/typed_actor.rs
-78
View File
@@ -1,78 +0,0 @@
//! Addressing a single-message actor two ways: by identity and by name.
//!
//! A single-message actor (one implementing [`Addressable`]) is reachable
//! through either of smarm's two address kinds:
//!
//! - [`Pid<A>`] — identity-bound. Names the exact incarnation, never
//! redirects, and stops resolving once that actor dies.
//! - [`Name<M>`] — durable. Re-resolves through the registry on every send,
//! so it always reaches whoever currently holds the name.
//!
//! A name is typed by the *message* it carries; a pid by the *actor* type
//! (whose [`Addressable::Msg`] is that message).
use smarm::{
channel, lookup_as, register, run, send, send_to, spawn, spawn_addr, Addressable, Name, Pid,
Receiver,
};
/// A single-message actor. Its one message type is what a `Pid<Echo>` delivers.
struct Echo;
impl Addressable for Echo {
type Msg = EchoMsg;
}
enum EchoMsg {
Say(String),
Stop,
}
/// A durable, message-typed name. Declared as a constant and shared freely.
const ECHO: Name<EchoMsg> = Name::new("echo");
fn main() {
run(|| {
// --- Identity-bound: Pid<A> ---------------------------------------
//
// `spawn_addr` makes the actor's inbox, hands the body its receiver,
// installs the sender, and returns a typed `Pid<Echo>`. The inbox is
// published before the pid is returned, so the address is live the
// instant we hold it — an immediate `send_to` always resolves.
let echo: Pid<Echo> = spawn_addr::<Echo>(|rx: Receiver<EchoMsg>| {
while let Ok(msg) = rx.recv() {
match msg {
EchoMsg::Say(s) => println!("echo: {s}"),
EchoMsg::Stop => break,
}
}
});
send_to(echo, EchoMsg::Say("hello".into())).unwrap();
send_to(echo, EchoMsg::Stop).unwrap();
// --- Durable: Name<M> ---------------------------------------------
//
// An actor claims a name for its own inbox; senders resolve it on every
// send, so the binding outlives any single holder.
let (ready_tx, ready_rx) = channel::<()>();
spawn(move || {
let (tx, rx) = channel::<EchoMsg>();
register(ECHO, tx).unwrap();
ready_tx.send(()).unwrap();
while let Ok(msg) = rx.recv() {
match msg {
EchoMsg::Say(s) => println!("named echo: {s}"),
EchoMsg::Stop => break,
}
}
});
ready_rx.recv().unwrap(); // the actor has claimed the name
send(ECHO, EchoMsg::Say("by name".into())).unwrap();
// Recover a typed pid from the name when you want identity-bound sends:
// `lookup_as` re-types the registry's erased pid as `Pid<Echo>`, so you
// drop back onto the compile-checked `send_to`.
if let Some(p) = lookup_as::<Echo>("echo") {
send_to(p, EchoMsg::Stop).unwrap();
}
});
}
examples/worker_pool.rs
-95
View File
@@ -1,95 +0,0 @@
//! A typed worker pool over process groups (`pg`).
//!
//! Workers enroll in a named group; the dispatcher reaches them through it.
//! Because the pool is homogeneous — every member is a `Worker` — the group's
//! typed reads (`pick_as` / `members_as`) and the `dispatch` combinator hand
//! members back as `Pid<Worker>`, so every send is an ordinary compile-checked
//! `send_to` rather than the untyped escape hatch. The untyped reads
//! (`members` / `pick` + `send_dyn`) stay available for identity-only use —
//! counting, logging, monitoring — where the message type isn't known.
//!
//! The pool drains itself: each worker retires on a sentinel and reports its
//! tally back, and the dispatcher waits the pool out before returning. (A pool
//! left running would be stopped anyway when the root actor exits, but draining
//! explicitly keeps the example deterministic.)
use smarm::{
channel, dispatch, join, members, members_as, pick, pick_as, run, send_dyn, send_to,
spawn_addr, Addressable, Pid,
};
/// The pool's worker actor. One message type, carried by `Pid<Worker>`.
struct Worker;
impl Addressable for Worker {
type Msg = Job;
}
/// A unit of work, or the sentinel that retires a worker.
enum Job {
Task { id: u64 },
Retire,
}
const POOL: &str = "pool";
const WORKERS: u64 = 4;
fn main() {
run(|| {
// Mint four typed workers and enroll them. `spawn_addr` yields a
// `Pid<Worker>`; `join` takes a typed pid directly, erasing internally.
// Each worker reports how many tasks it handled over a shared channel,
// so the dispatcher can wait the pool out at the end.
let (done_tx, done_rx) = channel::<(u64, u64)>();
for id in 0..WORKERS {
let done_tx = done_tx.clone();
let w: Pid<Worker> = spawn_addr::<Worker>(move |rx| {
let mut handled = 0;
while let Ok(job) = rx.recv() {
match job {
Job::Task { id: job } => {
println!("worker {id} handling job {job}");
handled += 1;
}
Job::Retire => break,
}
}
done_tx.send((id, handled)).unwrap();
});
join(POOL, w);
}
drop(done_tx); // from here only the workers hold senders
// Pick one live member and hand it a job — typed end to end.
if let Some(w) = pick_as::<Worker>(POOL) {
send_to(w, Job::Task { id: 1 }).unwrap();
}
// `dispatch` rolls pick-a-live-member-and-send into one call, returning
// the member it reached (or handing the job back if the pool is empty).
let _ = dispatch::<Worker>(POOL, Job::Task { id: 2 });
// Fan a job out to the whole pool — typed, so each send is `send_to`.
for w in members_as::<Worker>(POOL) {
let _ = send_to(w, Job::Task { id: 3 });
}
// The untyped reads stay available for identity-only use. To message a
// member reached this way, the explicit `send_dyn` escape hatch names
// the message type.
println!("pool size: {}", members(POOL).len());
if let Some(any) = pick(POOL) {
let _ = send_dyn::<Job>(any, Job::Task { id: 4 });
}
// Retire every worker, then drain their tallies so the program winds
// down on its own.
for w in members_as::<Worker>(POOL) {
let _ = send_to(w, Job::Retire);
}
for _ in 0..WORKERS {
if let Ok((id, handled)) = done_rx.recv() {
println!("worker {id} retired after {handled} jobs");
}
}
});
}
src/actor.rs
+4 -6
View File
@@ -93,10 +93,8 @@ pub fn take_last_outcome() -> Option<Outcome> {
/// unwinding to cross the boundary, but `catch_unwind` here means unwinding /// unwinding to cross the boundary, but `catch_unwind` here means unwinding
/// never actually does. /// never actually does.
pub extern "C-unwind" fn trampoline() { pub extern "C-unwind" fn trampoline() {
let b = match CURRENT_ACTOR_BOX.with(|c| c.borrow_mut().take()) { let b = CURRENT_ACTOR_BOX.with(|c| c.borrow_mut().take())
Some(b) => b, .expect("trampoline entered without a closure set");
None => panic!("smarm: trampoline entered without a closure set (core corrupt)"),
};
let outcome = match panic::catch_unwind(panic::AssertUnwindSafe(b)) { let outcome = match panic::catch_unwind(panic::AssertUnwindSafe(b)) {
Ok(()) => Outcome::Exit, Ok(()) => Outcome::Exit,
@@ -124,9 +122,9 @@ pub struct Actor {
/// The PID this actor was assigned at spawn time. /// The PID this actor was assigned at spawn time.
pub pid: Pid, pub pid: Pid,
/// The stack the actor runs on. Dropped (munmap'd) when the actor dies. /// The stack the actor runs on. Dropped (munmap'd) when the actor dies.
/// (The saved stack pointer lives on the `Slot` as an atomic, not here:
/// it is hot scheduling state, read/written without the cold lock.)
pub stack: Stack, pub stack: Stack,
/// The saved stack pointer. Updated on every yield.
pub sp: usize,
/// The PID of this actor's supervisor. Used to deliver `Signal` on death. /// The PID of this actor's supervisor. Used to deliver `Signal` on death.
pub supervisor: Pid, pub supervisor: Pid,
/// Cooperative-cancellation flag. `request_stop` sets it (and unparks a /// Cooperative-cancellation flag. `request_stop` sets it (and unparks a
src/arch/aarch64.rs
+165
View File
@@ -0,0 +1,165 @@
//! Cooperative context switching and cycle counter, aarch64 (AAPCS64).
//!
//! The aarch64 mirror of the x86-64 backend. The protocol is identical — save
//! callee-saved state, swap stack pointers via the shared `*_SP` thread-locals,
//! restore, return — but the mechanics differ from x86 in two ways worth
//! stating up front, because they drive the stack layout:
//!
//! 1. **Return is via the link register, not the stack.** x86 `ret` pops the
//! return address off the stack; aarch64 `ret` jumps to whatever is in
//! `x30` (lr). So the entry point is parked in the saved-`x30` slot, and
//! the shim restores `x30` and `ret`s to it. There is no "ret target word"
//! sitting on the stack the way there is on x86.
//!
//! 2. **sp must be 16-byte aligned at all times**, not just at call entry.
//! We save 12 registers (x19–x28, x29, x30) = 96 bytes, already a multiple
//! of 16, so the frame is aligned by construction.
//!
//! FP/SIMD registers (v8–v15, whose low 64 bits are callee-saved under AAPCS64)
//! are NOT saved, for the same reason the x86 backend skips XMM: every yield
//! goes through a Rust call boundary, so the compiler has already spilled any
//! live vector state. If we ever yield from a non-call-boundary, this breaks.
use super::{get_actor_sp, get_scheduler_sp, set_actor_sp, set_scheduler_sp};
// ---------------------------------------------------------------------------
// Initial stack layout
//
// Twelve 8-byte slots, all zero except the x30 slot which holds `entry`. The
// first `switch_to_actor` loads x19–x28/x29/x30 back and `ret`s to x30,
// landing at the top of `entry` with sp 16-aligned (the AAPCS64 requirement).
//
// Layout (high → low), relative to aligned_top = top & ~15:
//
// aligned_top - 8 : x30 = entry ← `ret` jumps here.
// aligned_top - 16 : x29 = 0 (fp)
// aligned_top - 24 : x28 = 0
// aligned_top - 32 : x27 = 0
// aligned_top - 40 : x26 = 0
// aligned_top - 48 : x25 = 0
// aligned_top - 56 : x24 = 0
// aligned_top - 64 : x23 = 0
// aligned_top - 72 : x22 = 0
// aligned_top - 80 : x21 = 0
// aligned_top - 88 : x20 = 0
// aligned_top - 96 : x19 = 0 ← initial sp (16-aligned)
//
// The restore order in the shim (ldp pairs, low→high) must match this exactly.
// ---------------------------------------------------------------------------
pub fn init_actor_stack(top: *mut u8, entry: extern "C-unwind" fn()) -> usize {
unsafe {
let aligned_top = top as usize & !15;
let mut sp = aligned_top;
sp -= 8; (sp as *mut usize).write(entry as usize); // x30 (lr) → entry
sp -= 8; (sp as *mut usize).write(0); // x29 (fp)
sp -= 8; (sp as *mut usize).write(0); // x28
sp -= 8; (sp as *mut usize).write(0); // x27
sp -= 8; (sp as *mut usize).write(0); // x26
sp -= 8; (sp as *mut usize).write(0); // x25
sp -= 8; (sp as *mut usize).write(0); // x24
sp -= 8; (sp as *mut usize).write(0); // x23
sp -= 8; (sp as *mut usize).write(0); // x22
sp -= 8; (sp as *mut usize).write(0); // x21
sp -= 8; (sp as *mut usize).write(0); // x20
sp -= 8; (sp as *mut usize).write(0); // x19 ← initial sp
sp
}
}
// ---------------------------------------------------------------------------
// Context switch shims
//
// Each shim:
// 1. Pushes x19–x28, x29, x30 as six 16-byte stp pairs (sp pre-decrement).
// 2. Moves sp into x0 and calls the Rust helper that stores it.
// 3. Calls the Rust helper that returns the *other* side's saved sp.
// 4. Moves that into sp.
// 5. Restores the twelve registers and rets (to the restored x30).
//
// The helper calls clobber x30 themselves, but that's fine: the outgoing x30
// was already saved to the stack in step 1, and step 5 restores the incoming
// side's x30 before `ret`. The push/pop register order is paired so that the
// `ldp` sequence reverses the `stp` sequence exactly.
// ---------------------------------------------------------------------------
#[unsafe(naked)]
unsafe extern "C" fn switch_to_actor_asm() {
core::arch::naked_asm!(
"stp x19, x20, [sp, #-96]!",
"stp x21, x22, [sp, #16]",
"stp x23, x24, [sp, #32]",
"stp x25, x26, [sp, #48]",
"stp x27, x28, [sp, #64]",
"stp x29, x30, [sp, #80]",
"mov x0, sp",
"bl {set_sched_sp}",
"bl {get_actor_sp}",
"mov sp, x0",
"ldp x21, x22, [sp, #16]",
"ldp x23, x24, [sp, #32]",
"ldp x25, x26, [sp, #48]",
"ldp x27, x28, [sp, #64]",
"ldp x29, x30, [sp, #80]",
"ldp x19, x20, [sp], #96",
"ret",
set_sched_sp = sym set_scheduler_sp,
get_actor_sp = sym get_actor_sp,
);
}
/// Resume the actor whose sp is in `ACTOR_SP`. Returns when the actor yields.
pub unsafe fn switch_to_actor() {
unsafe { switch_to_actor_asm() };
}
#[unsafe(naked)]
pub unsafe extern "C" fn switch_to_scheduler() {
core::arch::naked_asm!(
"stp x19, x20, [sp, #-96]!",
"stp x21, x22, [sp, #16]",
"stp x23, x24, [sp, #32]",
"stp x25, x26, [sp, #48]",
"stp x27, x28, [sp, #64]",
"stp x29, x30, [sp, #80]",
"mov x0, sp",
"bl {set_actor_sp}",
"bl {get_sched_sp}",
"mov sp, x0",
"ldp x21, x22, [sp, #16]",
"ldp x23, x24, [sp, #32]",
"ldp x25, x26, [sp, #48]",
"ldp x27, x28, [sp, #64]",
"ldp x29, x30, [sp, #80]",
"ldp x19, x20, [sp], #96",
"ret",
set_actor_sp = sym set_actor_sp,
get_sched_sp = sym get_scheduler_sp,
);
}
// ---------------------------------------------------------------------------
// Cycle counter
//
// CNTVCT_EL0 is the virtual count register, readable from EL0 on Linux. `isb`
// serialises so we don't sample the counter before prior instructions retire
// (the aarch64 analogue of x86's `lfence` before rdtsc).
//
// Unit: CNTVCT ticks, whose frequency is CNTFRQ_EL0 — typically 1–50 MHz,
// NOT the CPU clock. This is a different and much coarser unit than the x86
// TSC, which is why `TIMESLICE_CYCLES` must be tuned separately for aarch64.
// ---------------------------------------------------------------------------
#[inline(always)]
pub fn read_cycle_counter() -> u64 {
let cnt: u64;
unsafe {
core::arch::asm!(
"isb",
"mrs {cnt}, cntvct_el0",
cnt = out(reg) cnt,
options(nostack, nomem),
);
}
cnt
}
src/arch/mod.rs
+54
View File
@@ -0,0 +1,54 @@
//! Architecture abstraction layer.
//!
//! Everything that depends on the target ISA lives behind this module: the
//! cooperative context-switch shims, the initial-stack layout, and the
//! cycle counter used by the preemption timeslice. The rest of the runtime
//! talks only to the API re-exported here and never names a register.
//!
//! Each backend (`x86_64`, `aarch64`) exposes the same four items:
//!
//! - `init_actor_stack(top, entry) -> usize`
//! Build a fresh actor stack so the first `switch_to_actor` lands
//! inside `entry` with the ABI-correct stack alignment.
//! - `switch_to_actor()`
//! Resume the actor whose sp is in `ACTOR_SP`; returns when it yields.
//! - `switch_to_scheduler()`
//! Yield from the current actor back to its scheduler thread.
//! - `read_cycle_counter() -> u64`
//! Monotonic per-core cycle counter for the timeslice clock. The unit
//! is ISA-defined (x86 TSC ticks vs. aarch64 virtual-counter ticks),
//! so `TIMESLICE_CYCLES` must be tuned per-arch — see `preempt`.
//!
//! The `SCHEDULER_SP` / `ACTOR_SP` thread-locals are shared across backends
//! and live here, since the saved-stack-pointer protocol is identical
//! regardless of which registers the shim happens to push.
use std::cell::Cell;
thread_local! {
static SCHEDULER_SP: Cell<usize> = const { Cell::new(0) };
static ACTOR_SP: Cell<usize> = const { Cell::new(0) };
}
// Used by the naked shims (via `sym`) and by the scheduler/tests through the
// re-exports below. `pub` because the asm references them as symbols.
pub(crate) fn get_scheduler_sp() -> usize { SCHEDULER_SP.with(|c| c.get()) }
pub(crate) fn set_scheduler_sp(v: usize) { SCHEDULER_SP.with(|c| c.set(v)) }
pub fn get_actor_sp() -> usize { ACTOR_SP.with(|c| c.get()) }
pub fn set_actor_sp(v: usize) { ACTOR_SP.with(|c| c.set(v)) }
#[cfg(target_arch = "x86_64")]
mod x86_64;
#[cfg(target_arch = "x86_64")]
pub use x86_64::{init_actor_stack, read_cycle_counter, switch_to_actor, switch_to_scheduler};
#[cfg(target_arch = "aarch64")]
mod aarch64;
#[cfg(target_arch = "aarch64")]
pub use aarch64::{init_actor_stack, read_cycle_counter, switch_to_actor, switch_to_scheduler};
#[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
compile_error!(
"smarm's context-switch and cycle-counter layer supports only x86_64 and \
aarch64. Add a backend in src/arch/ for this target."
);
src/arch/x86_64.rs
+118
View File
@@ -0,0 +1,118 @@
//! Cooperative context switching and cycle counter, x86-64 (SysV AMD64).
//!
//! Two naked-asm functions move execution between a scheduler thread and an
//! actor running on its own mmap'd stack. The compiler cannot do this; the
//! whole point of `#[unsafe(naked)]` is that we control every instruction.
//!
//! `init_actor_stack` builds the initial stack so that the first
//! `switch_to_actor` lands inside the entry function with `rsp % 16 == 8`
//! (the x86-64 ABI requirement at function entry).
use super::{get_actor_sp, get_scheduler_sp, set_actor_sp, set_scheduler_sp};
// ---------------------------------------------------------------------------
// Initial stack layout
//
// We start from aligned_top = top & ~15, then bias by 8 and push seven 8-byte
// slots (downward). The first `switch_to_actor` pops r15..rbx and `ret`s —
// landing in `entry` with rsp % 16 == 8 (the x86-64 ABI state at the point
// just after a `call`, which is what `entry` is compiled to expect).
//
// Layout (high → low), relative to aligned_top = top & ~15. Note the entry
// slot is at aligned_top - 16, NOT aligned_top - 8: the function does
// `(top & ~15) - 8` and *then* a `-= 8` before the first write, so the first
// stored word lands at aligned_top - 16. Verified by single-stepping the
// `ret` under llmdbg: entry sits at an address with %16 == 0, so the post-ret
// rsp is %16 == 8.
//
// aligned_top - 8 : (unused padding; keeps entry's slot %16 == 0)
// aligned_top - 16 : entry ptr ← `ret` target. Post-ret: rsp % 16 == 8.
// aligned_top - 24 : rbx = 0
// aligned_top - 32 : rbp = 0
// aligned_top - 40 : r12 = 0
// aligned_top - 48 : r13 = 0
// aligned_top - 56 : r14 = 0
// aligned_top - 64 : r15 = 0 ← initial rsp
// ---------------------------------------------------------------------------
pub fn init_actor_stack(top: *mut u8, entry: extern "C-unwind" fn()) -> usize {
unsafe {
let mut sp = (top as usize & !15) - 8;
sp -= 8; (sp as *mut usize).write(entry as usize); // ret target
sp -= 8; (sp as *mut usize).write(0); // rbx
sp -= 8; (sp as *mut usize).write(0); // rbp
sp -= 8; (sp as *mut usize).write(0); // r12
sp -= 8; (sp as *mut usize).write(0); // r13
sp -= 8; (sp as *mut usize).write(0); // r14
sp -= 8; (sp as *mut usize).write(0); // r15
sp
}
}
// ---------------------------------------------------------------------------
// Context switch shims
//
// Each shim:
// 1. Pushes the six callee-saved integer registers.
// 2. Snaps rsp into rdi and calls the Rust helper that stores it.
// 3. Calls the Rust helper that returns the *other* side's saved rsp.
// 4. Moves that into rsp.
// 5. Pops the six registers and rets.
//
// XMM registers are NOT saved here. We rely on every yield happening through
// a Rust call site, which means the compiler has spilled any live XMM state
// to the stack before we get here. (This is the same argument the compiler
// uses internally — callee-saved regs are what survive a `call`, and the
// SysV AMD64 ABI says XMM0–15 are all caller-saved.) If we ever yield from
// a place that isn't a Rust call boundary, this assumption breaks.
// ---------------------------------------------------------------------------
#[unsafe(naked)]
unsafe extern "C" fn switch_to_actor_asm() {
core::arch::naked_asm!(
"push rbx", "push rbp", "push r12", "push r13", "push r14", "push r15",
"mov rdi, rsp",
"call {set_sched_sp}",
"call {get_actor_sp}",
"mov rsp, rax",
"pop r15", "pop r14", "pop r13", "pop r12", "pop rbp", "pop rbx",
"ret",
set_sched_sp = sym set_scheduler_sp,
get_actor_sp = sym get_actor_sp,
);
}
/// Resume the actor whose sp is in `ACTOR_SP`. Returns when the actor yields.
pub unsafe fn switch_to_actor() {
unsafe { switch_to_actor_asm() };
}
#[unsafe(naked)]
pub unsafe extern "C" fn switch_to_scheduler() {
core::arch::naked_asm!(
"push rbx", "push rbp", "push r12", "push r13", "push r14", "push r15",
"mov rdi, rsp",
"call {set_actor_sp}",
"call {get_sched_sp}",
"mov rsp, rax",
"pop r15", "pop r14", "pop r13", "pop r12", "pop rbp", "pop rbx",
"ret",
set_actor_sp = sym set_actor_sp,
get_sched_sp = sym get_scheduler_sp,
);
}
// ---------------------------------------------------------------------------
// Cycle counter
//
// `lfence` serialises the instruction stream so we don't measure time before
// prior instructions retire. Unit: TSC ticks (≈ CPU base clock).
// ---------------------------------------------------------------------------
#[inline(always)]
pub fn read_cycle_counter() -> u64 {
unsafe {
core::arch::asm!("lfence", options(nostack, nomem, preserves_flags));
core::arch::x86_64::_rdtsc()
}
}
src/channel.rs
+32 -526
View File
@@ -1,23 +1,9 @@
//! Unbounded MPSC channels. //! Unbounded MPSC channels.
//! //!
//! Inner state is `Arc<RawMutex<Inner<T>>>` so channels can be sent across OS //! Inner state is `Arc<Mutex<Inner<T>>>` so channels can be sent across OS
//! threads (required for the multi-scheduler runtime where a sender and //! threads (required for the multi-scheduler runtime where a sender and
//! receiver may run on different scheduler threads simultaneously). //! receiver may run on different scheduler threads simultaneously).
//! //!
//! ## Why `RawMutex` (Channel class), not `std::sync::Mutex`
//!
//! An actor holding a guard with preemption *enabled* can be timesliced
//! inside the critical section and resume on a different OS thread — the
//! pthread mutex would then be released from a thread that didn't lock it,
//! which is UB (Linux futexes happen to tolerate it, but it's not
//! guaranteed). `RawMutex` disables preemption for the guard's span and is
//! cross-thread-release sound by construction, closing the hole. It also
//! cannot poison. Channel locks form their own [`LockClass::Channel`]
//! (raw_mutex.rs): they may be taken under a cold (Leaf) lock — finalize and
//! `monitor()` clone senders that live in slots — but nothing may be locked
//! under them, which the debug build enforces. `recv_match` runs its user
//! predicate under this lock: keep it cheap, pure, and channel-free.
//!
//! Semantics: //! Semantics:
//! - Senders are clonable; the last sender drop closes the channel. //! - Senders are clonable; the last sender drop closes the channel.
//! - `Receiver::recv` on an empty open channel parks the receiver. //! - `Receiver::recv` on an empty open channel parks the receiver.
@@ -29,12 +15,11 @@
//! parked, the receiver is unparked. //! parked, the receiver is unparked.
use crate::pid::Pid; use crate::pid::Pid;
use crate::raw_mutex::RawMutex;
use std::collections::VecDeque; use std::collections::VecDeque;
use std::sync::Arc; use std::sync::{Arc, Mutex};
pub fn channel<T>() -> (Sender<T>, Receiver<T>) { pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
let inner = Arc::new(RawMutex::new_channel(Inner { let inner = Arc::new(Mutex::new(Inner {
queue: VecDeque::new(), queue: VecDeque::new(),
parked_receiver: None, parked_receiver: None,
senders: 1, senders: 1,
@@ -45,24 +30,17 @@ pub fn channel<T>() -> (Sender<T>, Receiver<T>) {
struct Inner<T> { struct Inner<T> {
queue: VecDeque<T>, queue: VecDeque<T>,
/// The parked receiver's `(pid, park-epoch)`. The epoch is the slot parked_receiver: Option<Pid>,
/// word's runtime-wide wait identity (see slot_state.rs): wakers call
/// `unpark_at(pid, epoch)`, so an entry left over from an already-woken
/// wait — a `select` loser arm, a satisfied `recv_timeout`'s timer — is
/// inert: the wake fails the word's epoch CAS and no-ops. This replaces
/// the old per-channel `cur_wait`/`next_wait_seq`/`timed_out` trio: wait
/// identity now exists exactly once, in the slot word.
parked_receiver: Option<(Pid, u32)>,
senders: usize, senders: usize,
receiver_alive: bool, receiver_alive: bool,
} }
pub struct Sender<T> { pub struct Sender<T> {
inner: Arc<RawMutex<Inner<T>>>, inner: Arc<Mutex<Inner<T>>>,
} }
pub struct Receiver<T> { pub struct Receiver<T> {
inner: Arc<RawMutex<Inner<T>>>, inner: Arc<Mutex<Inner<T>>>,
} }
#[derive(Debug, PartialEq, Eq)] #[derive(Debug, PartialEq, Eq)]
@@ -79,30 +57,9 @@ impl std::fmt::Display for RecvError {
impl std::error::Error for RecvError {} impl std::error::Error for RecvError {}
/// Returned by [`Receiver::recv_timeout`].
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum RecvTimeoutError {
/// The deadline passed with no message available.
Timeout,
/// All senders dropped with no message available — the bounded analogue
/// of [`RecvError`].
Disconnected,
}
impl std::fmt::Display for RecvTimeoutError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
RecvTimeoutError::Timeout => write!(f, "recv timed out"),
RecvTimeoutError::Disconnected => write!(f, "channel closed"),
}
}
}
impl std::error::Error for RecvTimeoutError {}
impl<T> Clone for Sender<T> { impl<T> Clone for Sender<T> {
fn clone(&self) -> Self { fn clone(&self) -> Self {
self.inner.lock().senders += 1; self.inner.lock().unwrap().senders += 1;
Sender { inner: self.inner.clone() } Sender { inner: self.inner.clone() }
} }
} }
@@ -110,7 +67,7 @@ impl<T> Clone for Sender<T> {
impl<T> Drop for Sender<T> { impl<T> Drop for Sender<T> {
fn drop(&mut self) { fn drop(&mut self) {
let unpark = { let unpark = {
let mut g = self.inner.lock(); let mut g = self.inner.lock().unwrap();
g.senders -= 1; g.senders -= 1;
// Wake the parked receiver on the last sender drop regardless of // Wake the parked receiver on the last sender drop regardless of
// whether the queue is empty. A plain `recv` only ever parks on an // whether the queue is empty. A plain `recv` only ever parks on an
@@ -124,39 +81,31 @@ impl<T> Drop for Sender<T> {
None None
} }
}; };
if let Some((pid, epoch)) = unpark { if let Some(pid) = unpark {
crate::scheduler::unpark_at(pid, epoch); crate::scheduler::unpark(pid);
} }
} }
} }
impl<T> Drop for Receiver<T> { impl<T> Drop for Receiver<T> {
fn drop(&mut self) { fn drop(&mut self) {
self.inner.lock().receiver_alive = false; self.inner.lock().unwrap().receiver_alive = false;
} }
} }
impl<T> Sender<T> { impl<T> Sender<T> {
/// Number of messages currently queued behind this channel. Introspection
/// only (RFC 016 mailbox depth); takes the channel lock, so callers reach
/// it under the registry Leaf (Leaf → Channel) via the erased probe in
/// `registry.rs`, never on a hot path.
pub(crate) fn queued_len(&self) -> usize {
self.inner.lock().queue.len()
}
pub fn send(&self, value: T) -> Result<(), SendError<T>> { pub fn send(&self, value: T) -> Result<(), SendError<T>> {
let unpark = { let unpark = {
let mut g = self.inner.lock(); let mut g = self.inner.lock().unwrap();
if !g.receiver_alive { if !g.receiver_alive {
return Err(SendError(value)); return Err(SendError(value));
} }
g.queue.push_back(value); g.queue.push_back(value);
g.parked_receiver.take() g.parked_receiver.take()
}; };
if let Some((pid, epoch)) = unpark { if let Some(pid) = unpark {
crate::te!(crate::trace::Event::Send { sender: crate::actor::current_pid().unwrap_or(crate::pid::Pid::new(u32::MAX, u32::MAX)), receiver: Some(pid) }); crate::te!(crate::trace::Event::Send { sender: crate::actor::current_pid().unwrap_or(crate::pid::Pid::new(u32::MAX, u32::MAX)), receiver: Some(pid) });
crate::scheduler::unpark_at(pid, epoch); crate::scheduler::unpark(pid);
} else { } else {
crate::te!(crate::trace::Event::Send { sender: crate::actor::current_pid().unwrap_or(crate::pid::Pid::new(u32::MAX, u32::MAX)), receiver: None }); crate::te!(crate::trace::Event::Send { sender: crate::actor::current_pid().unwrap_or(crate::pid::Pid::new(u32::MAX, u32::MAX)), receiver: None });
} }
@@ -168,114 +117,29 @@ impl<T> Receiver<T> {
pub fn recv(&self) -> Result<T, RecvError> { pub fn recv(&self) -> Result<T, RecvError> {
loop { loop {
{ {
let mut g = self.inner.lock(); let mut g = self.inner.lock().unwrap();
if let Some(v) = g.queue.pop_front() { if let Some(v) = g.queue.pop_front() {
crate::preempt::note_message_received();
return Ok(v); return Ok(v);
} }
if g.senders == 0 { if g.senders == 0 {
return Err(RecvError); return Err(RecvError);
} }
let me = match crate::actor::current_pid() { let me = crate::actor::current_pid()
Some(me) => me, .expect("recv() called outside an actor");
None => panic!("smarm: recv() called outside an actor"),
};
debug_assert!( debug_assert!(
g.parked_receiver.is_none_or(|(p, _)| p == me), g.parked_receiver.is_none(),
"channel has more than one receiver" "channel has more than one receiver"
); );
// begin_wait is lock-free — legal under the Channel lock; g.parked_receiver = Some(me);
// registering in the same critical section makes the epoch
// atomic with the senders' view of the registration.
g.parked_receiver = Some((me, crate::scheduler::begin_wait()));
crate::te!(crate::trace::Event::RecvPark(me)); crate::te!(crate::trace::Event::RecvPark(me));
} }
// Release the lock before parking — the unparker will need it. // Release the lock before parking — the unparker will need it.
crate::scheduler::park_current(); crate::scheduler::park_current();
// Woken up — record it before looping to check the queue. // Woken up — record it before looping to check the queue.
crate::te!(crate::trace::Event::RecvWake(match crate::actor::current_pid() { crate::te!(crate::trace::Event::RecvWake(crate::actor::current_pid().unwrap()));
Some(p) => p,
None => panic!("smarm: RecvWake outside an actor (core corrupt)"),
}));
} }
} }
/// Bounded receive: like [`recv`](Self::recv), but gives up once
/// `timeout` has elapsed, returning [`RecvTimeoutError::Timeout`].
///
/// Built on the same timer machinery as `Mutex::lock_timeout`: the wait
/// registers a `WaitTimeout` entry stamped with the wait's park-epoch;
/// on expiry the channel (as the
/// [`TimerTarget`](crate::timer::TimerTarget)) checks whether *this*
/// wait is still parked and, only then, cancels it. A wake that races
/// the deadline resolves message-first: if a message is available when
/// the receiver runs, it is delivered even if the timer had already
/// fired. A satisfied or abandoned wait leaves its timer entry to expire
/// as a no-op (registration gone; epoch consumed), per the
/// no-cancellation convention in `timer.rs`.
///
/// The wake is classified from state alone — wakes are precise (the only
/// stamped wakers of this wait are a send, the last-sender drop, and the
/// timer; a stop wake unwinds out of `park_current` and never reaches
/// the classification), so: message queued → `Ok`; `senders == 0` →
/// `Disconnected`; neither → it was the timer → `Timeout`.
///
/// `Duration::ZERO` is a valid timeout: it parks until the immediately-
/// due timer is drained, then reports `Timeout` unless a message was
/// already queued.
pub fn recv_timeout(&self, timeout: std::time::Duration) -> Result<T, RecvTimeoutError>
where
T: Send + 'static,
{
let me = match crate::actor::current_pid() {
Some(me) => me,
None => panic!("smarm: recv_timeout() called outside an actor"),
};
// Fast path + wait registration, one critical section.
let epoch;
{
let mut g = self.inner.lock();
if let Some(v) = g.queue.pop_front() {
crate::preempt::note_message_received();
return Ok(v);
}
if g.senders == 0 {
return Err(RecvTimeoutError::Disconnected);
}
debug_assert!(
g.parked_receiver.is_none_or(|(p, _)| p == me),
"channel has more than one receiver"
);
epoch = crate::scheduler::begin_wait();
g.parked_receiver = Some((me, epoch));
crate::te!(crate::trace::Event::RecvPark(me));
}
// Arm the timer after releasing the channel lock (insert takes the
// timers lock; never nest under a Channel lock). A send or even the
// timer itself may unpark us before we park — the RunningNotified
// protocol makes the park below return immediately in that case.
let deadline = crate::timer::deadline_from_now(timeout);
let target: std::sync::Arc<dyn crate::timer::TimerTarget> = self.inner.clone();
crate::scheduler::insert_wait_timer(deadline, me, target, epoch);
crate::scheduler::park_current();
crate::te!(crate::trace::Event::RecvWake(match crate::actor::current_pid() {
Some(p) => p,
None => panic!("smarm: RecvWake outside an actor (core corrupt)"),
}));
let mut g = self.inner.lock();
if let Some(v) = g.queue.pop_front() {
crate::preempt::note_message_received();
return Ok(v);
}
if g.senders == 0 {
return Err(RecvTimeoutError::Disconnected);
}
Err(RecvTimeoutError::Timeout)
}
/// Selective receive: remove and return the first queued message for which /// Selective receive: remove and return the first queued message for which
/// `pred` holds, leaving the rest in arrival order. If no queued message /// `pred` holds, leaving the rest in arrival order. If no queued message
/// matches, parks and re-scans on every send (a selective receiver may park /// matches, parks and re-scans on every send (a selective receiver may park
@@ -292,37 +156,27 @@ impl<T> Receiver<T> {
{ {
loop { loop {
{ {
let mut g = self.inner.lock(); let mut g = self.inner.lock().unwrap();
if let Some(i) = g.queue.iter().position(&pred) { if let Some(i) = g.queue.iter().position(|v| pred(v)) {
// position() found it, so remove() returns Some. // position() found it, so remove() returns Some.
crate::preempt::note_message_received(); return Ok(g.queue.remove(i).unwrap());
let v = match g.queue.remove(i) {
Some(v) => v,
None => panic!("smarm: channel queue.remove after position (logic bug)"),
};
return Ok(v);
} }
if g.senders == 0 { if g.senders == 0 {
// Closed and nothing queued can ever match. // Closed and nothing queued can ever match.
return Err(RecvError); return Err(RecvError);
} }
let me = match crate::actor::current_pid() { let me = crate::actor::current_pid()
Some(me) => me, .expect("recv_match() called outside an actor");
None => panic!("smarm: recv_match() called outside an actor"),
};
debug_assert!( debug_assert!(
g.parked_receiver.is_none_or(|(p, _)| p == me), g.parked_receiver.is_none(),
"channel has more than one receiver" "channel has more than one receiver"
); );
g.parked_receiver = Some((me, crate::scheduler::begin_wait())); g.parked_receiver = Some(me);
crate::te!(crate::trace::Event::RecvPark(me)); crate::te!(crate::trace::Event::RecvPark(me));
} }
// Release the lock before parking — the unparker will need it. // Release the lock before parking — the unparker will need it.
crate::scheduler::park_current(); crate::scheduler::park_current();
crate::te!(crate::trace::Event::RecvWake(match crate::actor::current_pid() { crate::te!(crate::trace::Event::RecvWake(crate::actor::current_pid().unwrap()));
Some(p) => p,
None => panic!("smarm: RecvWake outside an actor (core corrupt)"),
}));
} }
} }
@@ -334,14 +188,9 @@ impl<T> Receiver<T> {
where where
F: Fn(&T) -> bool, F: Fn(&T) -> bool,
{ {
let mut g = self.inner.lock(); let mut g = self.inner.lock().unwrap();
if let Some(i) = g.queue.iter().position(&pred) { if let Some(i) = g.queue.iter().position(|v| pred(v)) {
crate::preempt::note_message_received(); return Ok(Some(g.queue.remove(i).unwrap()));
let v = match g.queue.remove(i) {
Some(v) => v,
None => panic!("smarm: channel queue.remove after position (logic bug)"),
};
return Ok(Some(v));
} }
if g.senders == 0 { if g.senders == 0 {
return Err(RecvError); return Err(RecvError);
@@ -352,9 +201,8 @@ impl<T> Receiver<T> {
/// Non-blocking. `Ok(Some(v))` if a message was available, `Ok(None)` if /// Non-blocking. `Ok(Some(v))` if a message was available, `Ok(None)` if
/// the channel is empty but open, `Err(RecvError)` if closed and drained. /// the channel is empty but open, `Err(RecvError)` if closed and drained.
pub fn try_recv(&self) -> Result<Option<T>, RecvError> { pub fn try_recv(&self) -> Result<Option<T>, RecvError> {
let mut g = self.inner.lock(); let mut g = self.inner.lock().unwrap();
if let Some(v) = g.queue.pop_front() { if let Some(v) = g.queue.pop_front() {
crate::preempt::note_message_received();
return Ok(Some(v)); return Ok(Some(v));
} }
if g.senders == 0 { if g.senders == 0 {
@@ -363,345 +211,3 @@ impl<T> Receiver<T> {
Ok(None) Ok(None)
} }
} }
// ---------------------------------------------------------------------------
// TimerTarget — the expiry half of recv_timeout
// ---------------------------------------------------------------------------
impl<T: Send + 'static> crate::timer::TimerTarget for RawMutex<Inner<T>> {
fn on_timeout(&self, pid: Pid, epoch: u32) {
// Cancel the wait only if THIS wait (epoch match) is still
// registered. If a sender already took `parked_receiver`, the
// receiver is waking with a message — message wins, the timer
// no-ops. If a later wait by the same receiver is registered, the
// epoch mismatches — stale entry, no-op. (The unpark_at would fail
// its word CAS in either case anyway; checking under the lock keeps
// the registration bookkeeping exact.)
let unpark = {
let mut g = self.lock();
if g.parked_receiver == Some((pid, epoch)) {
g.parked_receiver = None;
true
} else {
false
}
};
// Unpark outside the channel lock — it may take the run-queue lock;
// legal under a Channel lock, but pointless to nest.
if unpark {
crate::scheduler::unpark_at(pid, epoch);
}
}
}
// ---------------------------------------------------------------------------
// select — ready-index wait over multiple receivers
// ---------------------------------------------------------------------------
pub(crate) mod sealed {
pub trait Sealed {}
}
impl<T> sealed::Sealed for Receiver<T> {}
/// An arm of a [`select`]. Implemented by [`Receiver`]; sealed, because the
/// registration contract below is part of the runtime's wake protocol.
///
/// Contract (all under the arm's own lock): `sel_register` checks-or-
/// registers atomically — if the arm is ready it does NOT register and
/// returns `Ok(false)`; otherwise it publishes `(pid, epoch)` where its
/// wakers will find it and returns `Ok(true)`. "Ready" means a receive
/// would not park: a message is queued, or the arm is closed. `Err` means
/// the arm could not register at all (only fd arms can fail; channel
/// registration is infallible) — the wait must be retired and earlier
/// eager-cleanup arms unregistered.
pub trait Selectable: sealed::Sealed {
#[doc(hidden)]
fn sel_register(&self, pid: Pid, epoch: u32) -> std::io::Result<bool>;
#[doc(hidden)]
fn sel_ready(&self) -> bool;
/// Remove this arm's `(pid, epoch)` registration if — and only if — it
/// is still in place. Default no-op: a losing channel arm's stale
/// registration is inert (its wakers die at the epoch CAS; the next
/// wait overwrites the slot). Fd arms override this: their staleness
/// poisons the fd (waiters entry + kernel-side ONESHOT registration)
/// and needs an eager cleanup pass.
#[doc(hidden)]
fn sel_unregister(&self, _pid: Pid, _epoch: u32) {}
/// Whether this arm requires the eager cleanup pass at all. Gates the
/// post-wake `sel_unregister` sweep so channel-only selects keep
/// today's zero-cancellation hot path.
#[doc(hidden)]
fn sel_eager_cleanup(&self) -> bool {
false
}
}
impl<T> Selectable for Receiver<T> {
fn sel_register(&self, pid: Pid, epoch: u32) -> std::io::Result<bool> {
let mut g = self.inner.lock();
if !g.queue.is_empty() || g.senders == 0 {
return Ok(false);
}
debug_assert!(
g.parked_receiver.is_none_or(|(p, _)| p == pid),
"channel has more than one receiver"
);
g.parked_receiver = Some((pid, epoch));
Ok(true)
}
fn sel_ready(&self) -> bool {
let g = self.inner.lock();
!g.queue.is_empty() || g.senders == 0
}
}
/// Park on every arm at once; return the index of the first ready one.
///
/// "Ready" means a receive on that arm would not park: a message is queued,
/// or the arm is **closed** (so the caller's `try_recv` observes the
/// disconnect — a dead arm is an event, not a hang). The caller consumes the
/// arm itself, typically via [`Receiver::try_recv`]; single-receiver
/// channels guarantee nothing can steal the message in between.
///
/// A closed arm stays ready *forever*: once its disconnect has been
/// observed, drop it from the arm set — under priority order it would
/// otherwise win every subsequent call and starve every higher-indexed arm.
///
/// Arms are scanned **in order**: index 0 is the highest priority, both on
/// the immediate-ready path and after a wake. This is a documented
/// guarantee (compose like BEAM receive clauses: put control channels
/// first), not an accident — and therefore there is NO fairness promise; a
/// saturated arm 0 starves arm 1 by design.
///
/// One actor may select on a channel and later `recv` on it (or select on
/// overlapping sets) freely. What stays illegal is what was always illegal:
/// two *different* actors receiving on one channel.
///
/// Built on the consuming-wake protocol (see slot_state.rs): all arms are
/// registered under one wait epoch; the winning wake consumes it, so losing
/// arms' registrations are inert and need no cancellation pass — they
/// self-clean at their wakers' failed CAS, or get overwritten by this
/// receiver's next wait on that channel.
///
/// Panics if `arms` is empty, when called outside an actor, or if an fd
/// arm fails to register (EBADF, EMFILE, a second waiter on one fd —
/// see [`try_select`] for the fallible form; channel-only selects cannot
/// fail).
pub fn select(arms: &[&dyn Selectable]) -> usize {
match try_select(arms) {
Ok(i) => i,
Err(e) => panic!("smarm: select() fd arm failed to register (use try_select): {e}"),
}
}
/// [`select`], fallible: `Err` when an arm fails to register (only fd
/// arms can — EBADF, EMFILE on the epoll set, or a second waiter on an
/// fd that already has one). On `Err` the wait is fully retired and no
/// registration is left behind: every arm registered before the failing
/// one has been unregistered.
pub fn try_select(arms: &[&dyn Selectable]) -> std::io::Result<usize> {
assert!(!arms.is_empty(), "select() on an empty arm list");
let me = match crate::actor::current_pid() {
Some(me) => me,
None => panic!("smarm: select() called outside an actor"),
};
loop {
let epoch = crate::scheduler::begin_wait();
if let Some(i) = register_arms(me, epoch, arms)? {
return Ok(i);
}
// Stale fd registrations are not harmless (a losing fd arm's
// waiters entry poisons the fd with AlreadyExists and its
// kernel-side ONESHOT registration can fire arbitrarily late), so
// selects containing fd arms run an eager cleanup pass after the
// park — including when a terminal stop unwinds out of it, via
// the guard. Channel-only selects skip all of it: `eager` is
// false, the guard is disarmed, and the loser-arm self-cleaning
// story is unchanged.
let eager = arms.iter().any(|a| a.sel_eager_cleanup());
let mut guard = UnregisterGuard { arms, me, epoch, armed: eager };
crate::scheduler::park_current();
if eager {
unregister_arms(arms, me, epoch);
}
guard.armed = false;
drop(guard);
// Woken precisely: an arm's send (message) or last-sender drop
// (closure) consumed our epoch, and both leave their arm ready —
// return the first one, in priority order (which may be a
// different, higher-priority arm than the one that woke us; its
// message stays queued and re-reports ready on the next call).
// Fd arms classify by a fresh zero-timeout poll, so they too are
// a pure function of state — independent of the registration the
// cleanup pass just removed.
for (i, arm) in arms.iter().enumerate() {
if arm.sel_ready() {
return Ok(i);
}
}
// Unreachable by protocol (a stop wake unwinds out of
// park_current). Defensive: re-open the wait and re-register —
// stale own-registrations are overwritten (channels) or were
// removed by the cleanup pass above (fds).
}
}
/// Eager-cleanup sweep: remove every fd arm's registration that is still
/// ours. No-op per channel arm (one virtual call); one io-lock visit per
/// fd arm.
fn unregister_arms(arms: &[&dyn Selectable], me: Pid, epoch: u32) {
for arm in arms {
if arm.sel_eager_cleanup() {
arm.sel_unregister(me, epoch);
}
}
}
/// Stop-unwind twin of the explicit cleanup pass: a terminal stop unwinds
/// out of `park_current`, and a registered fd arm must not outlive its
/// actor (the generalization of `wait_fd`'s `Dereg`). Disarmed on the
/// normal path after the explicit pass runs; never armed when no fd arm
/// registered, keeping the channel-only path guard-free in effect.
struct UnregisterGuard<'a> {
arms: &'a [&'a dyn Selectable],
me: Pid,
epoch: u32,
armed: bool,
}
impl Drop for UnregisterGuard<'_> {
fn drop(&mut self) {
if self.armed {
unregister_arms(self.arms, self.me, self.epoch);
}
}
}
/// The registration pass shared by [`select`] and [`select_timeout`]:
/// check-or-register each arm, in priority order, each atomically under its
/// own lock. Cross-arm atomicity is unnecessary: an arm becoming ready
/// right after its registration wakes the caller through the protocol (the
/// prep-to-park window is closed by RunningNotified).
///
/// `Ok(Some(i))` = arm `i` was ready, the pass stopped, and the wait has
/// been RETIRED (no park may follow): earlier arms hold live-epoch
/// registrations, so earlier *fd* arms are unregistered eagerly, then the
/// epoch is bumped, a landed notification eaten, and a pending stop
/// re-observed — without which a stale arm wake could fault a later
/// one-shot park. `Err` = an arm failed to register; identical unwind
/// (earlier fd arms unregistered, wait retired). `Ok(None)` = every arm
/// registered; the caller parks.
fn register_arms(
me: Pid,
epoch: u32,
arms: &[&dyn Selectable],
) -> std::io::Result<Option<usize>> {
for (i, arm) in arms.iter().enumerate() {
let registered = match arm.sel_register(me, epoch) {
Ok(r) => r,
Err(e) => {
unregister_arms(&arms[..i], me, epoch);
crate::scheduler::retire_wait();
return Err(e);
}
};
if !registered {
unregister_arms(&arms[..i], me, epoch);
crate::scheduler::retire_wait();
return Ok(Some(i));
}
}
Ok(None)
}
/// The [`select_timeout`] timer target: stateless, because precise wakes
/// make classification a pure function of channel state. The entry is
/// stamped with the select's epoch; if an arm already won, this unpark dies
/// at the word's epoch CAS (the no-cancellation convention in `timer.rs`).
struct SelectTimeout;
impl crate::timer::TimerTarget for SelectTimeout {
fn on_timeout(&self, pid: Pid, epoch: u32) {
crate::scheduler::unpark_at(pid, epoch);
}
}
/// [`select`] with a deadline: returns `Some(index)` like `select`, or
/// `None` once `timeout` elapses with no arm ready.
///
/// All of `select`'s semantics carry over (priority order, closed arms
/// permanently ready, no fairness promise). The timeout is one more stamped
/// waker on the same wait epoch — nothing is registered in any arm for it,
/// so there is nothing to cancel or leak: an arm winning leaves the timer
/// entry to expire as a stale-epoch no-op; the timer winning leaves the
/// arms' registrations to self-clean exactly as a `select` loser's would.
///
/// The wake is classified from state alone (wakes are precise): some arm
/// ready → `Some` of the first, in priority order; none ready → the timer
/// was the only remaining stamped waker → `None`. A message that races the
/// deadline resolves message-first, as `recv_timeout` does.
///
/// `Duration::ZERO` is a valid timeout: it parks until the immediately-due
/// timer is drained, then reports `None` unless an arm was already ready.
///
/// Panics if `arms` is empty, when called outside an actor, or if an fd
/// arm fails to register (see [`try_select_timeout`] for the fallible
/// form; channel-only selects cannot fail).
pub fn select_timeout(
arms: &[&dyn Selectable],
timeout: std::time::Duration,
) -> Option<usize> {
match try_select_timeout(arms, timeout) {
Ok(r) => r,
Err(e) => panic!(
"smarm: select_timeout() fd arm failed to register (use try_select_timeout): {e}"
),
}
}
/// [`select_timeout`], fallible: `Err` when an arm fails to register
/// (only fd arms can). On `Err` the wait is fully retired and no
/// registration — arm-side or kernel-side — is left behind.
pub fn try_select_timeout(
arms: &[&dyn Selectable],
timeout: std::time::Duration,
) -> std::io::Result<Option<usize>> {
assert!(!arms.is_empty(), "select_timeout() on an empty arm list");
let me = match crate::actor::current_pid() {
Some(me) => me,
None => panic!("smarm: select_timeout() called outside an actor"),
};
let epoch = crate::scheduler::begin_wait();
if let Some(i) = register_arms(me, epoch, arms)? {
return Ok(Some(i)); // ready now: the timer was never armed
}
// Arm the timer after the registration pass, outside every Channel
// lock (insert takes the timers lock).
let deadline = crate::timer::deadline_from_now(timeout);
let target: std::sync::Arc<dyn crate::timer::TimerTarget> = std::sync::Arc::new(SelectTimeout);
crate::scheduler::insert_wait_timer(deadline, me, target, epoch);
// Same eager-cleanup story as `try_select`: the timer arm needs none
// (stateless, stale entries die at the epoch CAS), channel arms need
// none, fd arms do — and a timer win in particular leaves every fd
// arm's registration behind, which without this pass would poison
// those fds until a kernel event happened to fire.
let eager = arms.iter().any(|a| a.sel_eager_cleanup());
let mut guard = UnregisterGuard { arms, me, epoch, armed: eager };
crate::scheduler::park_current();
if eager {
unregister_arms(arms, me, epoch);
}
guard.armed = false;
drop(guard);
// Woken precisely: an arm (ready below) or the timer (nothing ready).
Ok(arms.iter().position(|arm| arm.sel_ready()))
}
src/context.rs
+11 -129
View File
@@ -1,132 +1,14 @@
//! Cooperative context switching, x86-64. //! Cooperative context switching — public façade over the arch backend.
//! //!
//! Two naked-asm functions move execution between a scheduler thread and an //! The real implementation lives in `crate::arch`, selected per `target_arch`.
//! actor running on its own mmap'd stack. The compiler cannot do this; the //! This module re-exports the stable surface (`init_actor_stack`, the two
//! whole point of `#[unsafe(naked)]` is that we control every instruction. //! `switch_to_*` shims, and the `*_actor_sp` accessors) so the scheduler,
//! `preempt`, and the `tests/context.rs` integration tests keep importing
//! `smarm::context::{...}` unchanged regardless of which ISA is built.
//! //!
//! `SCHEDULER_SP` and `ACTOR_SP` are thread-locals holding each side's saved //! See `crate::arch` for the contract every backend implements, and
//! stack pointer. `init_actor_stack` builds the initial stack so that the //! `crate::arch::{x86_64, aarch64}` for the per-ISA register choreography.
//! first `switch_to_actor` lands inside the entry function with `rsp % 16 == 8`
//! (the x86-64 ABI requirement at function entry).
use std::cell::Cell; pub use crate::arch::{
get_actor_sp, init_actor_stack, set_actor_sp, switch_to_actor, switch_to_scheduler,
thread_local! { };
static SCHEDULER_SP: Cell<usize> = const { Cell::new(0) };
static ACTOR_SP: Cell<usize> = const { Cell::new(0) };
}
fn get_scheduler_sp() -> usize { SCHEDULER_SP.with(|c| c.get()) }
fn set_scheduler_sp(v: usize) { SCHEDULER_SP.with(|c| c.set(v)) }
pub fn get_actor_sp() -> usize { ACTOR_SP.with(|c| c.get()) }
pub fn set_actor_sp(v: usize) { ACTOR_SP.with(|c| c.set(v)) }
// ---------------------------------------------------------------------------
// Initial stack layout
//
// We start from aligned_top = top & ~15, then bias by 8 and push seven 8-byte
// slots (downward). The first `switch_to_actor` pops r15..rbx and `ret`s —
// landing in `entry` with rsp % 16 == 8 (the x86-64 ABI state at the point
// just after a `call`, which is what `entry` is compiled to expect).
//
// Layout (high → low), relative to aligned_top = top & ~15. Note the entry
// slot is at aligned_top - 16, NOT aligned_top - 8: the function does
// `(top & ~15) - 8` and *then* a `-= 8` before the first write, so the first
// stored word lands at aligned_top - 16. Verified by single-stepping the
// `ret` under llmdbg: entry sits at an address with %16 == 0, so the post-ret
// rsp is %16 == 8.
//
// aligned_top - 8 : (unused padding; keeps entry's slot %16 == 0)
// aligned_top - 16 : entry ptr ← `ret` target. Post-ret: rsp % 16 == 8.
// aligned_top - 24 : rbx = 0
// aligned_top - 32 : rbp = 0
// aligned_top - 40 : r12 = 0
// aligned_top - 48 : r13 = 0
// aligned_top - 56 : r14 = 0
// aligned_top - 64 : r15 = 0 ← initial rsp
// ---------------------------------------------------------------------------
pub fn init_actor_stack(top: *mut u8, entry: extern "C-unwind" fn()) -> usize {
unsafe {
let mut sp = (top as usize & !15) - 8;
sp -= 8; (sp as *mut usize).write(entry as usize); // ret target
sp -= 8; (sp as *mut usize).write(0); // rbx
sp -= 8; (sp as *mut usize).write(0); // rbp
sp -= 8; (sp as *mut usize).write(0); // r12
sp -= 8; (sp as *mut usize).write(0); // r13
sp -= 8; (sp as *mut usize).write(0); // r14
sp -= 8; (sp as *mut usize).write(0); // r15
sp
}
}
// ---------------------------------------------------------------------------
// Context switch shims
//
// Each shim:
// 1. Pushes the six callee-saved integer registers.
// 2. Snaps rsp into rdi and calls the Rust helper that stores it.
// 3. Calls the Rust helper that returns the *other* side's saved rsp.
// 4. Moves that into rsp.
// 5. Pops the six registers and rets.
//
// XMM registers are NOT saved here. We rely on every yield happening through
// a Rust call site, which means the compiler has spilled any live XMM state
// to the stack before we get here. (This is the same argument the compiler
// uses internally — callee-saved regs are what survive a `call`, and the
// SysV AMD64 ABI says XMM0–15 are all caller-saved.) If we ever yield from
// a place that isn't a Rust call boundary, this assumption breaks.
// ---------------------------------------------------------------------------
#[unsafe(naked)]
unsafe extern "C" fn switch_to_actor_asm() {
core::arch::naked_asm!(
"push rbx", "push rbp", "push r12", "push r13", "push r14", "push r15",
"mov rdi, rsp",
"call {set_sched_sp}",
"call {get_actor_sp}",
"mov rsp, rax",
"pop r15", "pop r14", "pop r13", "pop r12", "pop rbp", "pop rbx",
"ret",
set_sched_sp = sym set_scheduler_sp,
get_actor_sp = sym get_actor_sp,
);
}
/// Resume the actor whose sp is in `ACTOR_SP`. Returns when the actor yields.
///
/// # Safety
///
/// The caller must be running on a scheduler thread with a valid actor stack
/// pointer installed in `ACTOR_SP` — either by `init_actor_stack` (first
/// resume) or by a prior `switch_to_scheduler` (subsequent resumes). Resuming
/// with an unset or stale `ACTOR_SP` transfers control to an arbitrary address.
/// Must not be called from within an actor (only the scheduler side may resume).
pub unsafe fn switch_to_actor() {
unsafe { switch_to_actor_asm() };
}
/// Yield from the running actor back to its scheduler thread. Returns when the
/// actor is next resumed via [`switch_to_actor`].
///
/// # Safety
///
/// The caller must be running on an actor stack that was entered through
/// [`switch_to_actor`], so that `SCHEDULER_SP` holds the live saved stack
/// pointer of the scheduler side. Calling this from the scheduler thread, or
/// before any actor has been resumed, transfers control to an arbitrary
/// address.
#[unsafe(naked)]
pub unsafe extern "C" fn switch_to_scheduler() {
core::arch::naked_asm!(
"push rbx", "push rbp", "push r12", "push r13", "push r14", "push r15",
"mov rdi, rsp",
"call {set_actor_sp}",
"call {get_sched_sp}",
"mov rsp, rax",
"pop r15", "pop r14", "pop r13", "pop r12", "pop rbp", "pop rbx",
"ret",
set_actor_sp = sym set_actor_sp,
get_sched_sp = sym get_scheduler_sp,
);
}
src/gen_server.rs
+77 -981
View File
File diff suppressed because it is too large Load Diff
src/gen_statem.rs
-1024
View File
File diff suppressed because it is too large Load Diff
src/introspect.rs
-289
View File
@@ -1,289 +0,0 @@
//! RFC 016 — runtime introspection (Chunk 1: the read primitive).
//!
//! A synchronous, internal read of the slab that returns *owned* data. This is
//! the mechanism the whole RFC hangs off: tests, the future observer
//! gen_server (Chunk 4), and a later control plane (RFC 003) are all consumers
//! of [`snapshot`] / [`actor_info`], never of the runtime internals directly.
//!
//! ## Consistency (DECISION D2 — per-slot tearing, `ps` semantics)
//!
//! [`snapshot`] is point-in-time and mildly racy *across* actors: each slot's
//! scheduling state is a lock-free word load, so an actor reported `Running`
//! may already be `Parked`, and an actor can die mid-scan. This is the cheap,
//! useful model (a coherent stop-the-world cut is expensive and rarely wanted).
//! [`actor_info`] is coherent for the single actor it names.
//!
//! ## Locking
//!
//! The lock order is **Leaf → Channel, at most one of each** (`raw_mutex.rs`);
//! cold locks, the registry, and the free list are all Leaves, so we may never
//! hold two at once. The read is therefore phased: first a single registry-leaf
//! pass for names and mailbox depth (the per-channel length read is a Channel
//! lock taken under that Leaf — legal), released before the slab scan takes any
//! per-slot cold Leaf.
use crate::pid::Pid;
use crate::registry::MailboxInfo;
use crate::runtime::{Slot, ROOT_PID};
use crate::scheduler::with_runtime;
use crate::slot_state::{
word_gen, word_state, ST_DONE, ST_PARKED, ST_QUEUED, ST_RUNNING, ST_RUNNING_NOTIFIED,
};
use std::collections::HashMap;
/// Snapshot wire-format version (DECISION D1). [`RuntimeSnapshot`] is treated as
/// a stable type from day one: it becomes the observer protocol (Chunk 4) and
/// crosses a version boundary the moment a remote observer attaches (RFC 011),
/// so the version travels with the data from the start.
pub const SNAPSHOT_FORMAT_VERSION: u16 = 1;
/// Fine-grained scheduling state, mapped from the packed slot word with no new
/// storage. `RunningNotified` collapses into `Notified` — a wake landed while
/// the actor was on-CPU and it will re-queue when it yields.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ActorState {
Queued,
Running,
Notified,
Parked,
Done,
}
/// Classify a packed state word. `None` for a Vacant slot (skipped by the scan)
/// — the only state that is not an actor.
fn classify(w: u64) -> Option<ActorState> {
Some(match word_state(w) {
ST_QUEUED => ActorState::Queued,
ST_RUNNING => ActorState::Running,
ST_RUNNING_NOTIFIED => ActorState::Notified,
ST_PARKED => ActorState::Parked,
ST_DONE => ActorState::Done,
_ => return None, // ST_VACANT
})
}
/// Owned, point-in-time view of one actor — no borrows of runtime internals, so
/// it is safe to hand to any consumer.
#[derive(Debug, Clone)]
pub struct ActorInfo {
pub pid: Pid,
/// Registered names, inverted from the registry (usually 0 or 1).
pub names: Vec<&'static str>,
pub state: ActorState,
/// Spawn-time parent edge (DECISION D9): `spawn_under` sets it to the
/// supervisor, plain `spawn` to the spawning actor — so it is parentage,
/// not necessarily a supervision relationship. `ROOT_PID` for the run's
/// root actor and for `Done` tombstones (whose `Actor` is already gone).
pub supervisor: Pid,
pub trap_exit: bool,
pub monitors: u32,
pub links: u32,
pub joiners: u32,
/// Queued messages summed over the actor's *published* channels (register /
/// install / spawn_addr / gen_server). 0 for an actor that holds only a
/// private `channel()` receiver — those are invisible to the registry.
pub mailbox_depth: u32,
/// Timeslice overruns tallied for this incarnation (RFC 016 Chunk 2): how
/// many times the actor was preempted for exceeding its slice. Resets on
/// restart (per-incarnation, D7).
pub overruns: u64,
/// Messages this actor has received (dequeued) this incarnation (RFC 016
/// Chunk 2) — answers "is this actor a hotspot / draining slower than its
/// mailbox fills." Counts received, not sent (D4). Per-incarnation (D7).
pub messages_received: u64,
/// Approximate on-CPU cycles this incarnation has consumed (RFC 016 Chunk 2)
/// — a reductions-like work metric for relative comparison. Always 0 unless
/// the `budget-accounting` feature is enabled (it costs an RDTSC per resume,
/// D6). Per-incarnation (D7).
pub budget_cycles: u64,
}
/// A whole-runtime snapshot. See the module docs for the D2 tearing model.
#[derive(Debug, Clone)]
pub struct RuntimeSnapshot {
pub format_version: u16,
pub actors: Vec<ActorInfo>,
}
/// Snapshot every live (and `Done`-but-not-yet-reclaimed) actor on the slab.
/// O(n) over the slot table, running with preemption disabled (like every
/// runtime primitive) but holding no lock across the scan. Panics outside
/// `Runtime::run()`; callable from actor code and the run thread.
pub fn snapshot() -> RuntimeSnapshot {
with_runtime(|inner| {
// Phase A: one registry-leaf pass for names + mailbox depth, released
// before any cold leaf (no two Leaves at once).
let mail = inner.registry.lock().introspect_map();
// Phase B: lock-free slab scan; per-slot cold leaf only to copy cold
// fields. Tearing across slots is intentional (D2).
let mut actors = Vec::new();
for (idx, slot) in inner.slots.iter().enumerate() {
let idx = idx as u32;
if let Some(info) = read_slot(slot, idx, mail.get(&idx)) {
actors.push(info);
}
}
RuntimeSnapshot { format_version: SNAPSHOT_FORMAT_VERSION, actors }
})
}
/// Coherent view of a single actor, or `None` if the pid is stale, out of
/// range, or names a Vacant slot.
pub fn actor_info(pid: Pid) -> Option<ActorInfo> {
with_runtime(|inner| {
let slot = inner.slot_at(pid)?;
let mail = inner.registry.lock().introspect_one(pid.index());
let info = read_slot(slot, pid.index(), mail.as_ref())?;
// read_slot keys on the slab's *current* generation; reject if that
// isn't the incarnation the caller asked about.
(info.pid.generation() == pid.generation()).then_some(info)
})
}
/// Build one `ActorInfo` for slot `idx`, or `None` if Vacant or
/// racing-reclaimed. State is classified from a lock-free word load (the torn
/// read); the cold lock then pins the generation (reclaim bumps it under that
/// same lock) so the cold fields are coherent for this incarnation. `mail` is
/// this slot's registry entry, if any.
fn read_slot(slot: &Slot, idx: u32, mail: Option<&MailboxInfo>) -> Option<ActorInfo> {
let w = slot.state_word();
let state = classify(w)?;
let gen = word_gen(w);
let pid = Pid::new(idx, gen);
let cold = slot.cold.lock();
// If the generation moved between the lock-free load and acquiring the cold
// lock, the slot was reclaimed (and maybe reused) — drop it rather than mix
// one incarnation's state with another's cold data. (ps semantics: a racing
// actor may simply be missed mid-scan.)
if word_gen(slot.state_word()) != gen {
return None;
}
let (supervisor, trap_exit) = match cold.actor.as_ref() {
// Live incarnation: parent + trap live on the Actor.
Some(actor) => (actor.supervisor, actor.trap.is_some()),
// Done tombstone: the Actor was taken at finalize and the collections
// cleared, so report it root-less with empty counts.
None => (ROOT_PID, false),
};
let monitors = cold.monitors.len() as u32;
let links = cold.links.len() as u32;
let joiners = cold.waiters.len() as u32;
drop(cold);
// Counters are hot-region atomics, read lock-free (RFC 016 Chunk 2).
let overruns = slot.overruns();
let messages_received = slot.messages_received();
let budget_cycles = slot.budget_cycles();
// Names + depth belong to this incarnation only if the registry mailbox's
// pid matches the slab generation; a stale registry entry (dead prior
// occupant, not yet pruned) contributes nothing.
let (names, mailbox_depth) = match mail {
Some(mi) if mi.pid.generation() == gen => (mi.names.clone(), mi.depth),
_ => (Vec::new(), 0),
};
Some(ActorInfo {
pid,
names,
state,
supervisor,
trap_exit,
monitors,
links,
joiners,
mailbox_depth,
overruns,
messages_received,
budget_cycles,
})
}
// ---------------------------------------------------------------------------
// Chunk 3 — tree view (pure derivation over a Chunk-1 snapshot)
// ---------------------------------------------------------------------------
/// One node in the parentage forest. `children` are the actors whose recorded
/// parent edge points at this node's pid.
#[derive(Debug, Clone)]
pub struct TreeNode {
pub info: ActorInfo,
/// The actor's recorded parent was absent from the snapshot (already
/// Done/Vacant, or itself a tombstone), so it was re-rooted under the forest
/// sentinel rather than dropped — the tree stays total (DECISION D8).
pub orphaned: bool,
pub children: Vec<TreeNode>,
}
/// The parentage forest. Roots are actors parented at `ROOT_PID` (genuine
/// roots) plus re-rooted orphans. The edge is *spawned-by / parent*, not
/// necessarily supervision (DECISION D9) — see [`ActorInfo::supervisor`].
#[derive(Debug, Clone)]
pub struct RuntimeTree {
pub format_version: u16,
pub roots: Vec<TreeNode>,
}
/// Take a live [`snapshot`] and fold it into the parentage forest.
pub fn tree() -> RuntimeTree {
tree_from(snapshot())
}
/// Fold an existing snapshot into a forest by grouping each actor under its
/// parent pid — a single O(n) pass, no new reads. Exposed separately so a
/// consumer that already holds a snapshot (or a synthetic one, in tests) can
/// derive the tree without a second scan.
pub fn tree_from(snap: RuntimeSnapshot) -> RuntimeTree {
let RuntimeSnapshot { format_version, actors } = snap;
let mut index_of: HashMap<Pid, usize> = HashMap::with_capacity(actors.len());
for (i, a) in actors.iter().enumerate() {
index_of.insert(a.pid, i);
}
// Group children under their present parent; everything else is a root.
// Scan order is preserved within each parent's child list.
let mut children_of: HashMap<Pid, Vec<usize>> = HashMap::new();
let mut roots: Vec<usize> = Vec::new();
let mut orphaned = vec![false; actors.len()];
for (i, a) in actors.iter().enumerate() {
let parent = a.supervisor;
if parent != ROOT_PID && index_of.contains_key(&parent) {
children_of.entry(parent).or_default().push(i);
} else {
// Parent is the forest sentinel (genuine root) or absent from the
// snapshot (orphan, D8) — either way a root of the forest.
orphaned[i] = parent != ROOT_PID;
roots.push(i);
}
}
// `take()` each actor as it is placed, which also guards against a
// (constructionally impossible) parentage cycle re-entering a node.
let mut slots: Vec<Option<ActorInfo>> = actors.into_iter().map(Some).collect();
let root_nodes = roots
.into_iter()
.filter_map(|i| build_node(i, &children_of, &orphaned, &mut slots))
.collect();
RuntimeTree { format_version, roots: root_nodes }
}
fn build_node(
i: usize,
children_of: &HashMap<Pid, Vec<usize>>,
orphaned: &[bool],
slots: &mut [Option<ActorInfo>],
) -> Option<TreeNode> {
let info = slots[i].take()?; // already placed → cycle guard / no double-attach
let children = children_of
.get(&info.pid)
.map(|kids| {
kids.iter()
.filter_map(|&c| build_node(c, children_of, orphaned, slots))
.collect()
})
.unwrap_or_default();
Some(TreeNode { info, orphaned: orphaned[i], children })
}
src/io.rs
+23 -44
View File
@@ -44,13 +44,11 @@
//! //!
//! Fd hygiene //! Fd hygiene
//! ========== //! ==========
//! An actor stopped while waiting on an fd unwinds out of `wait_fd`'s park; //! If an actor dies while waiting on an fd, the registration is leaked
//! a drop guard there (armed after a successful register, forgotten on a //! (the fd stays in the epollfd, armed). EPOLLONESHOT bounds the damage:
//! normal wake) removes the `waiters` entry iff it is still that wait's //! at most one stale wakeup, after which the kernel disarms. The stale
//! `(pid, epoch)` and only then `EPOLL_CTL_DEL`s the fd — an entry already //! wakeup hits a dead pid in `waiters` and is dropped. Acceptable for v0.2;
//! consumed by a racing `FdReady` means the fd may carry someone else's //! a future pass should DEL on actor death.
//! fresh registration, which must be left alone. `epoll_register` keeps a
//! defensive bare DEL before ADD as belt-and-braces.
//! //!
//! Buffers used with `read`/`write` should be on fds opened with //! Buffers used with `read`/`write` should be on fds opened with
//! `O_NONBLOCK`. If they aren't, the syscall may block the scheduler //! `O_NONBLOCK`. If they aren't, the syscall may block the scheduler
@@ -86,9 +84,6 @@ use std::thread::JoinHandle as OsJoinHandle;
pub type IoResult = Result<Box<dyn Any + Send>, Box<dyn Any + Send>>; pub type IoResult = Result<Box<dyn Any + Send>, Box<dyn Any + Send>>;
struct Request { struct Request {
/// The submitter's park-epoch — carried through to the `Blocking`
/// completion so the wake is epoch-matched.
epoch: u32,
pid: Pid, pid: Pid,
/// The work to perform. Returns the wire-form result directly. /// The work to perform. Returns the wire-form result directly.
work: Box<dyn FnOnce() -> IoResult + Send>, work: Box<dyn FnOnce() -> IoResult + Send>,
@@ -98,7 +93,7 @@ struct Request {
pub enum Completion { pub enum Completion {
/// A `block_on_io` closure has finished (Ok = return value, Err = panic /// A `block_on_io` closure has finished (Ok = return value, Err = panic
/// payload). /// payload).
Blocking { pid: Pid, epoch: u32, result: IoResult }, Blocking { pid: Pid, result: IoResult },
/// An fd registered via `wait_readable`/`wait_writable` is ready. The /// An fd registered via `wait_readable`/`wait_writable` is ready. The
/// scheduler looks up the parked pid in `waiters`, unparks it, and /// scheduler looks up the parked pid in `waiters`, unparks it, and
/// removes the entry. `pid` isn't in this variant because the epoll /// removes the entry. `pid` isn't in this variant because the epoll
@@ -136,7 +131,7 @@ pub struct IoThread {
/// One parked actor per registered fd. Populated by `wait_readable` / /// One parked actor per registered fd. Populated by `wait_readable` /
/// `wait_writable` and drained by the scheduler when a `FdReady` /// `wait_writable` and drained by the scheduler when a `FdReady`
/// completion is processed. /// completion is processed.
pub waiters: HashMap<RawFd, (Pid, u32)>, pub waiters: HashMap<RawFd, Pid>,
// ----- Threads ----- // ----- Threads -----
@@ -236,22 +231,19 @@ impl IoThread {
} }
/// Hand a request to the pool. Increments `outstanding`. /// Hand a request to the pool. Increments `outstanding`.
pub fn submit(&mut self, pid: Pid, epoch: u32, work: Box<dyn FnOnce() -> IoResult + Send>) { pub fn submit(&mut self, pid: Pid, work: Box<dyn FnOnce() -> IoResult + Send>) {
self.outstanding += 1; self.outstanding += 1;
// Send can only fail if the pool has hung up, which only happens // Send can only fail if the pool has hung up, which only happens
// on shutdown. submit during shutdown is a bug. // on shutdown. submit during shutdown is a bug.
if self.tx.send(Request { pid, epoch, work }).is_err() { self.tx
panic!("smarm: io pool hung up unexpectedly (submit during shutdown)"); .send(Request { pid, work })
} .expect("io pool hung up unexpectedly");
} }
/// Drain every available completion. Caller (the scheduler) routes the /// Drain every available completion. Caller (the scheduler) routes the
/// results and updates `outstanding` / `waiters` accordingly. /// results and updates `outstanding` / `waiters` accordingly.
pub fn drain_completions(&mut self) -> Vec<Completion> { pub fn drain_completions(&mut self) -> Vec<Completion> {
let mut q = match self.completions.lock() { let mut q = self.completions.lock().unwrap();
Ok(g) => g,
Err(e) => panic!("smarm: io completions lock poisoned (core corrupt): {e}"),
};
let mut out = Vec::with_capacity(q.len()); let mut out = Vec::with_capacity(q.len());
while let Some(c) = q.pop_front() { while let Some(c) = q.pop_front() {
out.push(c); out.push(c);
@@ -263,15 +255,6 @@ impl IoThread {
self.wake_read self.wake_read
} }
/// Write the wake pipe directly: rouse every scheduler thread blocked in
/// its idle `poll_wake`. Used by the terminal (AllDone) path — an idle
/// sibling may be blocked on a snapshot that nothing will ever refresh
/// (an orphaned timer deadline, or `io_outstanding` from a waiter that
/// was stop-cancelled and so never produces a completion).
pub fn wake(&self) {
wake_scheduler(self.wake_write);
}
/// Register interest in `fd` becoming readable/writable; record `pid` /// Register interest in `fd` becoming readable/writable; record `pid`
/// as the parked waiter. The epoll thread will push a `FdReady` /// as the parked waiter. The epoll thread will push a `FdReady`
/// completion when the kernel signals. /// completion when the kernel signals.
@@ -282,7 +265,6 @@ impl IoThread {
&mut self, &mut self,
fd: RawFd, fd: RawFd,
pid: Pid, pid: Pid,
epoch: u32,
readable: bool, readable: bool,
writable: bool, writable: bool,
) -> io::Result<()> { ) -> io::Result<()> {
@@ -296,10 +278,10 @@ impl IoThread {
)); ));
} }
// Belt-and-braces: the unwind guard in `wait_fd` is responsible for // Defensive cleanup: if a previous actor died while waiting on this
// cleaning up a stopped waiter's registration, but a bare DEL is // fd, the kernel-side registration was leaked (we don't walk all
// harmless if the fd isn't registered (ENOENT) and removes any leak // waiters on actor death). A bare DEL is harmless if the fd isn't
// a path we haven't thought of might leave behind. // registered (ENOENT), and removes any leak.
unsafe { unsafe {
libc::epoll_ctl(self.epollfd, libc::EPOLL_CTL_DEL, fd, std::ptr::null_mut()); libc::epoll_ctl(self.epollfd, libc::EPOLL_CTL_DEL, fd, std::ptr::null_mut());
} }
@@ -321,7 +303,7 @@ impl IoThread {
if r < 0 { if r < 0 {
return Err(io::Error::last_os_error()); return Err(io::Error::last_os_error());
} }
self.waiters.insert(fd, (pid, epoch)); self.waiters.insert(fd, pid);
Ok(()) Ok(())
} }
@@ -387,15 +369,15 @@ fn pool_loop(
completions: Arc<Mutex<VecDeque<Completion>>>, completions: Arc<Mutex<VecDeque<Completion>>>,
wake_write: RawFd, wake_write: RawFd,
) { ) {
while let Ok(Request { pid, epoch, work }) = rx.recv() { while let Ok(Request { pid, work }) = rx.recv() {
let result: IoResult = match panic::catch_unwind(panic::AssertUnwindSafe(work)) { let result: IoResult = match panic::catch_unwind(panic::AssertUnwindSafe(work)) {
Ok(r) => r, Ok(r) => r,
Err(payload) => Err(payload), Err(payload) => Err(payload),
}; };
match completions.lock() { completions
Ok(mut g) => g.push_back(Completion::Blocking { pid, epoch, result }), .lock()
Err(e) => panic!("smarm: io completions lock poisoned (core corrupt): {e}"), .unwrap()
} .push_back(Completion::Blocking { pid, result });
wake_scheduler(wake_write); wake_scheduler(wake_write);
} }
} }
@@ -438,10 +420,7 @@ fn epoll_loop(
let mut shutdown_requested = false; let mut shutdown_requested = false;
let mut pushed_any = false; let mut pushed_any = false;
{ {
let mut q = match completions.lock() { let mut q = completions.lock().unwrap();
Ok(g) => g,
Err(e) => panic!("smarm: io completions lock poisoned (core corrupt): {e}"),
};
for ev in events.iter().take(n as usize) { for ev in events.iter().take(n as usize) {
if ev.u64 == SHUTDOWN_EPOLL_TOKEN { if ev.u64 == SHUTDOWN_EPOLL_TOKEN {
shutdown_requested = true; shutdown_requested = true;
src/lib.rs
+6 -39
View File
@@ -11,6 +11,7 @@
//! //!
//! See `LOOM.md` for the design intent and the deferred-for-later list. //! See `LOOM.md` for the design intent and the deferred-for-later list.
pub mod arch;
pub mod stack; pub mod stack;
pub mod context; pub mod context;
pub mod preempt; pub mod preempt;
@@ -23,20 +24,9 @@ pub mod timer;
pub mod io; pub mod io;
pub mod mutex; pub mod mutex;
pub mod monitor; pub mod monitor;
pub mod registry;
pub mod pg;
pub mod link; pub mod link;
pub mod gen_server; pub mod gen_server;
pub mod gen_statem;
pub mod introspect;
#[cfg(feature = "observer")]
pub mod observer;
pub mod runtime; pub mod runtime;
pub(crate) mod raw_mutex;
pub(crate) mod slot_state;
pub(crate) mod sync_shim;
#[doc(hidden)] // pub only so benches/rq_micro.rs can drive the raw structures
pub mod run_queue;
pub mod trace; pub mod trace;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -50,41 +40,18 @@ static ALLOCATOR: preempt::PreemptingAllocator = preempt::PreemptingAllocator;
// Public API re-exports // Public API re-exports
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
pub use channel::{ pub use channel::{channel, Receiver, RecvError, Sender};
channel, select, select_timeout, try_select, try_select_timeout, Receiver, RecvError, pub use gen_server::{CallError, CastError, GenServer, ServerRef};
RecvTimeoutError, Selectable, Sender,
};
pub use gen_server::{
call, cast, shutdown, whereis_server, CallError, CallTimeoutError, CastError, GenServer,
NamedGenServerBuilder, GenServerBuilder, GenServerCtx, GenServerName, GenServerRef, TimerHandle, Watcher,
};
pub use gen_statem::{
CallError as GenStatemCallError, Cx, Machine, Reply, Resolution, SendError as GenStatemSendError,
GenStatemRef,
};
pub use introspect::{
actor_info, snapshot, tree, tree_from, ActorInfo, ActorState, RuntimeSnapshot, RuntimeTree,
TreeNode, SNAPSHOT_FORMAT_VERSION,
};
#[cfg(feature = "observer")]
pub use observer::{ObserverReply, ObserverRequest};
pub use link::{link, trap_exit, unlink, ExitSignal}; pub use link::{link, trap_exit, unlink, ExitSignal};
pub use monitor::{demonitor, monitor, Down, DownReason, Monitor, MonitorId}; pub use monitor::{demonitor, monitor, Down, DownReason, Monitor, MonitorId};
pub use mutex::{LockTimeout, Mutex, MutexGuard}; pub use mutex::{LockTimeout, Mutex, MutexGuard};
pub use pid::{Addressable, Erased, Name, Pid, RawPid}; pub use pid::Pid;
pub use pg::{dispatch, join, leave, members, members_as, pick, pick_as, Incarnation, Member, NodeId};
pub use registry::{
install, lookup_as, register, send, send_dyn, send_to, unregister, whereis, RegisterError,
SendError,
};
pub use runtime::{init, Config, Runtime}; pub use runtime::{init, Config, Runtime};
pub use scheduler::{ pub use scheduler::{
block_on_io, cancel_timer, request_stop, run, self_pid, send_after, send_after_named, sleep, block_on_io, request_stop, run, self_pid, sleep, spawn, spawn_under, wait_readable,
spawn, spawn_addr, spawn_under, wait_readable, wait_readable_timeout, wait_writable, wait_writable, yield_now, JoinError, JoinHandle,
wait_writable_timeout, yield_now, FdArm, JoinError, JoinHandle,
}; };
pub use supervisor::{ChildSpec, OneForOne, Restart, Signal, Strategy}; pub use supervisor::{ChildSpec, OneForOne, Restart, Signal, Strategy};
pub use timer::TimerId;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// check!() // check!()
src/link.rs
+45 -72
View File
@@ -49,9 +49,10 @@
//! [`Down`]: crate::monitor::Down //! [`Down`]: crate::monitor::Down
//! [`request_stop`]: crate::scheduler::request_stop //! [`request_stop`]: crate::scheduler::request_stop
use crate::channel::{channel, Receiver}; use crate::channel::{channel, Receiver, Sender};
use crate::monitor::DownReason; use crate::monitor::DownReason;
use crate::pid::Pid; use crate::pid::Pid;
use crate::runtime::State;
use crate::scheduler::{request_stop, self_pid, with_runtime}; use crate::scheduler::{request_stop, self_pid, with_runtime};
/// A linked peer's death, delivered to a trapping actor's inbox. /// A linked peer's death, delivered to a trapping actor's inbox.
@@ -77,13 +78,11 @@ pub fn trap_exit() -> Receiver<ExitSignal> {
let (tx, rx) = channel::<ExitSignal>(); let (tx, rx) = channel::<ExitSignal>();
let me = self_pid(); let me = self_pid();
with_runtime(|inner| { with_runtime(|inner| {
if let Some(slot) = inner.slot_at(me) { inner.with_shared(|s| {
let mut cold = slot.cold.lock(); if let Some(actor) = s.slot_mut(me).and_then(|slot| slot.actor.as_mut()) {
// Own slot: generation is necessarily current (we're running).
if let Some(actor) = cold.actor.as_mut() {
actor.trap = Some(tx); actor.trap = Some(tx);
} }
} })
}); });
rx rx
} }
@@ -95,71 +94,51 @@ pub fn trap_exit() -> Receiver<ExitSignal> {
/// this delivers an immediate [`DownReason::NoProc`] exit signal to the caller /// this delivers an immediate [`DownReason::NoProc`] exit signal to the caller
/// (a message if trapping, otherwise a cooperative stop). Linking yourself, or /// (a message if trapping, otherwise a cooperative stop). Linking yourself, or
/// re-linking an existing peer, is a no-op. /// re-linking an existing peer, is a no-op.
pub fn link<A>(target: Pid<A>) { pub fn link(target: Pid) {
let target = target.erase();
let me = self_pid(); let me = self_pid();
if target == me { if target == me {
return; return;
} }
// Cold locks are leaves: never hold two at once. The link is recorded one // Under the lock: if the target is live, record the link both ways and
// side at a time, TARGET FIRST — that ordering is what makes the race // return `None`. If it is gone, return the caller's trap sender (if any)
// window sound: // so we can deliver the NoProc signal after releasing the lock.
// let dead_action: Option<Option<Sender<ExitSignal>>> = with_runtime(|inner| {
// - Once `me` is in `target.links`, the target's death always reaches us inner.with_shared(|s| {
// (its finalize cascade walks that list). So after step 1 succeeds, the let target_live = matches!(
// link semantics are already live. s.slot(target),
// - If the target dies between step 1 and step 2, its cascade removes Some(slot) if slot.actor.is_some() && !matches!(slot.state, State::Done)
// `target` from OUR links (a no-op, we haven't added it yet) and );
// delivers the exit signal — correct, the link was established. Our if target_live {
// subsequent step-2 insert leaves a stale `target` entry in `me.links`; if let Some(slot) = s.slot_mut(me) {
// stale entries are benign by construction (every cascade walk if !slot.links.contains(&target) {
// re-verifies the peer's word; `unlink` removes them like any other). slot.links.push(target);
//
// The reverse order would be unsound: target dying in the window would
// walk its links WITHOUT us — a silently dead link that we believe is live.
let registered_on_target = with_runtime(|inner| match inner.slot_at(target) {
Some(slot) => {
let mut cold = slot.cold.lock();
if slot.is_live_for(target) && cold.actor.is_some() {
if !cold.links.contains(&me) {
cold.links.push(me);
} }
true }
if let Some(slot) = s.slot_mut(target) {
if !slot.links.contains(&me) {
slot.links.push(me);
}
}
None
} else { } else {
false // Grab our own trap sender so the NoProc delivery (below)
// doesn't need a second lock acquisition.
Some(
s.slot(me)
.and_then(|slot| slot.actor.as_ref())
.and_then(|a| a.trap.clone()),
)
} }
}
None => false,
});
if registered_on_target {
with_runtime(|inner| {
let slot = match inner.slot_at(me) {
Some(s) => s,
None => panic!("smarm: link own slot vanished (core corrupt)"),
};
let mut cold = slot.cold.lock();
if !cold.links.contains(&target) {
cold.links.push(target);
}
});
return;
}
// Target already gone: deliver NoProc to ourselves — as a message if
// trapping, otherwise as a cooperative stop.
let my_trap = with_runtime(|inner| {
inner.slot_at(me).and_then(|slot| {
let cold = slot.cold.lock();
cold.actor.as_ref().and_then(|a| a.trap.clone())
}) })
}); });
match my_trap {
Some(tx) => { match dead_action {
None => {} // linked successfully
Some(Some(tx)) => {
let _ = tx.send(ExitSignal { from: target, reason: DownReason::NoProc }); let _ = tx.send(ExitSignal { from: target, reason: DownReason::NoProc });
} }
None => request_stop(me), Some(None) => request_stop(me),
} }
} }
@@ -167,25 +146,19 @@ pub fn link<A>(target: Pid<A>) {
/// ///
/// After this, neither actor's death propagates to the other. A no-op if the /// After this, neither actor's death propagates to the other. A no-op if the
/// two were not linked. /// two were not linked.
pub fn unlink<A>(target: Pid<A>) { pub fn unlink(target: Pid) {
let target = target.erase();
let me = self_pid(); let me = self_pid();
if target == me { if target == me {
return; return;
} }
with_runtime(|inner| { with_runtime(|inner| {
// One cold lock at a time (leaf rule). Order is immaterial here: inner.with_shared(|s| {
// a half-removed link is just a stale entry on one side, and stale if let Some(slot) = s.slot_mut(me) {
// entries are benign (re-verified on every cascade walk). slot.links.retain(|p| *p != target);
if let Some(slot) = inner.slot_at(me) {
let mut cold = slot.cold.lock();
cold.links.retain(|p| *p != target);
}
if let Some(slot) = inner.slot_at(target) {
let mut cold = slot.cold.lock();
if slot.generation() == target.generation() {
cold.links.retain(|p| *p != me);
} }
if let Some(slot) = s.slot_mut(target) {
slot.links.retain(|p| *p != me);
} }
})
}); });
} }
src/monitor.rs
+24 -28
View File
@@ -47,6 +47,7 @@
use crate::channel::{channel, Receiver, Sender}; use crate::channel::{channel, Receiver, Sender};
use crate::pid::Pid; use crate::pid::Pid;
use crate::runtime::State;
use crate::scheduler::with_runtime; use crate::scheduler::with_runtime;
/// Why a monitored actor went down. /// Why a monitored actor went down.
@@ -106,30 +107,27 @@ pub struct Monitor {
/// If `target` is still live, the `Down` arrives when it terminates. If /// If `target` is still live, the `Down` arrives when it terminates. If
/// `target` is already gone, a [`DownReason::NoProc`] `Down` is queued /// `target` is already gone, a [`DownReason::NoProc`] `Down` is queued
/// immediately so the caller's `rx.recv()` returns without parking. /// immediately so the caller's `rx.recv()` returns without parking.
pub fn monitor<A>(target: Pid<A>) -> Monitor { pub fn monitor(target: Pid) -> Monitor {
let target = target.erase();
let (tx, rx) = channel::<Down>(); let (tx, rx) = channel::<Down>();
// Register under the target's cold lock. `tx.clone()` takes the channel's // Register under the shared lock. We allocate the id and (if the target is
// own lock — a Channel-class RawMutex, explicitly permitted *under* a Leaf // live) clone the sender into its monitor list, keeping the original `tx`
// (cold) lock by the lock order (see raw_mutex.rs). We must still not // for the NoProc fallback. `tx.clone()` only touches the channel's own
// *send* under the lock, as `Sender::send` can unpark a parked receiver, // mutex, never the shared runtime mutex, so it is safe under the lock — but
// and there's no reason to nest that. // we must not *send* here, as `Sender::send` can call back in to unpark a
// parked receiver and the shared mutex is not reentrant.
let (id, registered) = with_runtime(|inner| { let (id, registered) = with_runtime(|inner| {
let id = inner.alloc_monitor_id(); inner.with_shared(|s| {
let registered = match inner.slot_at(target) { let id = s.alloc_monitor_id();
Some(slot) => { let registered = match s.slot_mut(target) {
let mut cold = slot.cold.lock(); Some(slot) if !matches!(slot.state, State::Done) => {
if slot.is_live_for(target) { slot.monitors.push((id, tx.clone()));
cold.monitors.push((id, tx.clone()));
true true
} else {
false
} }
} _ => false,
None => false,
}; };
(id, registered) (id, registered)
})
}); });
if !registered { if !registered {
@@ -149,18 +147,16 @@ pub fn monitor<A>(target: Pid<A>) -> Monitor {
/// dropping the [`Monitor`] closes its receiver and the queued notice goes with /// dropping the [`Monitor`] closes its receiver and the queued notice goes with
/// it — the analogue of Erlang's `demonitor(Ref, [flush])`. /// it — the analogue of Erlang's `demonitor(Ref, [flush])`.
pub fn demonitor(m: &Monitor) -> Option<MonitorId> { pub fn demonitor(m: &Monitor) -> Option<MonitorId> {
// Remove the registration under the target's cold lock, but move the // Remove the registration under the lock, but move the `Sender` *out* and
// `Sender` *out* and let it drop only after the lock is released: // let it drop only after the lock is released: dropping the last sender
// dropping the last sender runs `Sender::drop`, which may unpark a parked // runs `Sender::drop`, which may unpark a parked receiver → `with_shared`,
// receiver — legal under a cold lock, but pointless to nest. // and the shared mutex is not reentrant.
let removed: Option<(MonitorId, Sender<Down>)> = with_runtime(|inner| { let removed: Option<(MonitorId, Sender<Down>)> = with_runtime(|inner| {
let slot = inner.slot_at(m.target)?; inner.with_shared(|s| {
let mut cold = slot.cold.lock(); let slot = s.slot_mut(m.target)?;
if slot.generation() != m.target.generation() { let pos = slot.monitors.iter().position(|(mid, _)| *mid == m.id)?;
return None; // slot reused; the Down already fired Some(slot.monitors.remove(pos))
} })
let pos = cold.monitors.iter().position(|(mid, _)| *mid == m.id)?;
Some(cold.monitors.remove(pos))
}); });
// `removed`'s sender drops here, outside the lock. // `removed`'s sender drops here, outside the lock.
removed.map(|(id, _sender)| id) removed.map(|(id, _sender)| id)
src/mutex.rs
+42 -111
View File
@@ -33,15 +33,13 @@ impl std::error::Error for LockTimeout {}
struct Wait { struct Wait {
pid: Pid, pid: Pid,
/// The wait's park-epoch (slot-word wait identity, see slot_state.rs). seq: u64,
/// Grants and timeouts wake via `unpark_at(pid, epoch)`; a stale entry
/// can neither be granted by mistake nor wake the wrong wait.
epoch: u32,
} }
struct MutexState { struct MutexState {
holder: Option<Pid>, holder: Option<Pid>,
waiters: VecDeque<Wait>, waiters: VecDeque<Wait>,
next_seq: u64,
default_timeout: Duration, default_timeout: Duration,
} }
@@ -55,6 +53,7 @@ impl MutexCore {
state: StdMutex::new(MutexState { state: StdMutex::new(MutexState {
holder: None, holder: None,
waiters: VecDeque::new(), waiters: VecDeque::new(),
next_seq: 0,
default_timeout, default_timeout,
}), }),
} }
@@ -62,29 +61,26 @@ impl MutexCore {
} }
impl TimerTarget for MutexCore { impl TimerTarget for MutexCore {
fn on_timeout(&self, pid: Pid, epoch: u32) { fn on_timeout(&self, pid: Pid, wait_seq: u64) {
let unpark = { let unpark = {
let mut st = match self.state.lock() { let mut st = self.state.lock().unwrap();
Ok(g) => g, // Remove from waiters only if still there with matching seq.
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
};
// Remove from waiters only if still there with matching epoch.
// If the lock was already granted (holder == Some(pid)), the // If the lock was already granted (holder == Some(pid)), the
// timer fired after the grant — treat as no-op; the actor // timer fired after the grant — treat as no-op; the actor
// will see `is_holder == true` and return Ok. // will see `is_holder == true` and return Ok.
if st.holder == Some(pid) { if st.holder == Some(pid) {
return; return;
} }
match st.waiters.iter().position(|w| w.pid == pid && w.epoch == epoch) { let pos = st.waiters.iter().position(|w| w.pid == pid && w.seq == wait_seq);
Some(pos) => { if pos.is_some() {
st.waiters.remove(pos); st.waiters.remove(pos.unwrap());
true true
} } else {
None => false, false
} }
}; };
if unpark { if unpark {
scheduler::unpark_at(pid, epoch); scheduler::unpark(pid);
} }
} }
} }
@@ -108,17 +104,11 @@ impl<T> Mutex<T> {
} }
pub fn set_default_timeout(&self, timeout: Duration) { pub fn set_default_timeout(&self, timeout: Duration) {
match self.core.state.lock() { self.core.state.lock().unwrap().default_timeout = timeout;
Ok(mut st) => st.default_timeout = timeout,
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
}
} }
pub fn lock(&self) -> Result<MutexGuard<'_, T>, LockTimeout> { pub fn lock(&self) -> Result<MutexGuard<'_, T>, LockTimeout> {
let timeout = match self.core.state.lock() { let timeout = self.core.state.lock().unwrap().default_timeout;
Ok(st) => st.default_timeout,
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
};
self.lock_timeout(timeout) self.lock_timeout(timeout)
} }
@@ -131,62 +121,36 @@ impl<T> Mutex<T> {
// Fast path: nobody holds it. // Fast path: nobody holds it.
{ {
let mut st = match self.core.state.lock() { let mut st = self.core.state.lock().unwrap();
Ok(g) => g,
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
};
if st.holder.is_none() { if st.holder.is_none() {
st.holder = Some(me); st.holder = Some(me);
drop(st); drop(st);
let taken = match self.value.lock() { let value = self.value.lock().unwrap().take()
Ok(mut g) => g.take(), .expect("Mutex: value missing on free fast path");
Err(e) => panic!("smarm: mutex value lock poisoned (core corrupt): {e}"),
};
let value = match taken {
Some(v) => v,
None => panic!("smarm: Mutex value missing on free fast path (core corrupt)"),
};
return Ok(MutexGuard { mutex: self, value: Some(value) }); return Ok(MutexGuard { mutex: self, value: Some(value) });
} }
} }
// Slow path: register as a waiter, set timeout, park. // Slow path: register as a waiter, set timeout, park.
let _np = scheduler::NoPreempt::enter(); let _np = scheduler::NoPreempt::enter();
let epoch = { let seq = {
let mut st = match self.core.state.lock() { let mut st = self.core.state.lock().unwrap();
Ok(g) => g, let seq = st.next_seq;
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"), st.next_seq = st.next_seq.wrapping_add(1);
}; st.waiters.push_back(Wait { pid: me, seq });
// begin_wait is lock-free — legal under the state lock; this seq
// makes the epoch atomic with the registration's visibility to
// grants and timeouts.
let epoch = scheduler::begin_wait();
st.waiters.push_back(Wait { pid: me, epoch });
epoch
}; };
let target: Arc<dyn TimerTarget> = self.core.clone(); let target: Arc<dyn TimerTarget> = self.core.clone();
let deadline = timer::deadline_from_now(timeout); let deadline = timer::deadline_from_now(timeout);
scheduler::insert_wait_timer(deadline, me, target, epoch); scheduler::insert_wait_timer(deadline, me, target, seq);
scheduler::park_current(); scheduler::park_current();
// Resumed — precisely: only our grant or our timer can wake this // Resumed. Are we the holder?
// wait (both epoch-stamped; a stop wake unwinds out of let is_holder = self.core.state.lock().unwrap().holder == Some(me);
// park_current). The one-shot interpretation below is therefore
// exhaustive. Are we the holder?
let is_holder = match self.core.state.lock() {
Ok(st) => st.holder == Some(me),
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
};
if is_holder { if is_holder {
let taken = match self.value.lock() { let value = self.value.lock().unwrap().take()
Ok(mut g) => g.take(), .expect("Mutex: value missing after grant");
Err(e) => panic!("smarm: mutex value lock poisoned (core corrupt): {e}"),
};
let value = match taken {
Some(v) => v,
None => panic!("smarm: Mutex value missing after grant (core corrupt)"),
};
Ok(MutexGuard { mutex: self, value: Some(value) }) Ok(MutexGuard { mutex: self, value: Some(value) })
} else { } else {
Err(LockTimeout) Err(LockTimeout)
@@ -195,23 +159,14 @@ impl<T> Mutex<T> {
pub fn try_lock(&self) -> Option<MutexGuard<'_, T>> { pub fn try_lock(&self) -> Option<MutexGuard<'_, T>> {
let me = crate::actor::current_pid()?; let me = crate::actor::current_pid()?;
let mut st = match self.core.state.lock() { let mut st = self.core.state.lock().unwrap();
Ok(g) => g,
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
};
if st.holder.is_some() { if st.holder.is_some() {
return None; return None;
} }
st.holder = Some(me); st.holder = Some(me);
drop(st); drop(st);
let taken = match self.value.lock() { let value = self.value.lock().unwrap().take()
Ok(mut g) => g.take(), .expect("Mutex: value missing on try_lock free path");
Err(e) => panic!("smarm: mutex value lock poisoned (core corrupt): {e}"),
};
let value = match taken {
Some(v) => v,
None => panic!("smarm: Mutex value missing on try_lock free path (core corrupt)"),
};
Some(MutexGuard { mutex: self, value: Some(value) }) Some(MutexGuard { mutex: self, value: Some(value) })
} }
@@ -222,10 +177,7 @@ impl<T> Mutex<T> {
// tracking and just grab the value mutex directly. This is safe because // tracking and just grab the value mutex directly. This is safe because
// outside the runtime there are no green threads competing. // outside the runtime there are no green threads competing.
let value = loop { let value = loop {
let v = match self.value.lock() { let v = self.value.lock().unwrap().take();
Ok(mut g) => g.take(),
Err(e) => panic!("smarm: mutex value lock poisoned (core corrupt): {e}"),
};
if let Some(v) = v { break v; } if let Some(v) = v { break v; }
std::thread::yield_now(); std::thread::yield_now();
}; };
@@ -254,55 +206,34 @@ pub struct MutexGuard<'a, T> {
impl<T> std::ops::Deref for MutexGuard<'_, T> { impl<T> std::ops::Deref for MutexGuard<'_, T> {
type Target = T; type Target = T;
fn deref(&self) -> &T { fn deref(&self) -> &T { self.value.as_ref().expect("MutexGuard: value missing") }
match self.value.as_ref() {
Some(v) => v,
None => panic!("smarm: MutexGuard value missing (core corrupt)"),
}
}
} }
impl<T> std::ops::DerefMut for MutexGuard<'_, T> { impl<T> std::ops::DerefMut for MutexGuard<'_, T> {
fn deref_mut(&mut self) -> &mut T { fn deref_mut(&mut self) -> &mut T {
match self.value.as_mut() { self.value.as_mut().expect("MutexGuard: value missing")
Some(v) => v,
None => panic!("smarm: MutexGuard value missing (core corrupt)"),
}
} }
} }
impl<T: std::fmt::Debug> std::fmt::Debug for MutexGuard<'_, T> { impl<T: std::fmt::Debug> std::fmt::Debug for MutexGuard<'_, T> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let value = match self.value.as_ref() {
Some(v) => v,
None => panic!("smarm: MutexGuard value missing (core corrupt)"),
};
f.debug_tuple("MutexGuard") f.debug_tuple("MutexGuard")
.field(value) .field(self.value.as_ref().expect("MutexGuard: value missing"))
.finish() .finish()
} }
} }
impl<T> Drop for MutexGuard<'_, T> { impl<T> Drop for MutexGuard<'_, T> {
fn drop(&mut self) { fn drop(&mut self) {
let v = match self.value.take() { let v = self.value.take().expect("MutexGuard: double drop");
Some(v) => v, *self.mutex.value.lock().unwrap() = Some(v);
None => panic!("smarm: MutexGuard double drop (core corrupt)"),
};
match self.mutex.value.lock() {
Ok(mut g) => *g = Some(v),
Err(e) => panic!("smarm: mutex value lock poisoned (core corrupt): {e}"),
}
let next = { let next_pid = {
let mut st = match self.mutex.core.state.lock() { let mut st = self.mutex.core.state.lock().unwrap();
Ok(g) => g,
Err(e) => panic!("smarm: mutex state lock poisoned (core corrupt): {e}"),
};
match st.waiters.pop_front() { match st.waiters.pop_front() {
Some(w) => { Some(w) => {
st.holder = Some(w.pid); st.holder = Some(w.pid);
Some((w.pid, w.epoch)) Some(w.pid)
} }
None => { None => {
st.holder = None; st.holder = None;
@@ -310,8 +241,8 @@ impl<T> Drop for MutexGuard<'_, T> {
} }
} }
}; };
if let Some((pid, epoch)) = next { if let Some(pid) = next_pid {
scheduler::unpark_at(pid, epoch); scheduler::unpark(pid);
} }
} }
} }
src/observer.rs
-114
View File
@@ -1,114 +0,0 @@
//! RFC 016 — runtime observability (Chunk 4: the observer gen_server).
//!
//! A thin [`GenServer`] that consumes the Chunk-1 read primitive
//! ([`snapshot`](crate::snapshot) / [`tree`](crate::tree) /
//! [`actor_info`](crate::actor_info)) over a message interface — the live
//! `observer` process, in the OTP sense. It is a *transport*, not the
//! mechanism: the synchronous internal read stays the primitive, and the
//! observer is just one more consumer of it alongside the test suite. This is
//! also the read half of the future RFC 003 control plane — the same actor
//! gains write verbs there rather than a second consumer being spun up
//! (DECISION D12).
//!
//! ## Why it is feature-gated (DECISION D10)
//!
//! The read primitive (Chunks 1–3) is always present and unflagged: it is pure
//! reads and the test suite leans on it. The *gen_server* sits behind the
//! `observer` Cargo feature, off by default, matching RFC 003's dev-only
//! feature-flag stance — a release build pays nothing for a live observer it
//! never starts.
//!
//! ## The protocol is the contract (DECISION D11)
//!
//! [`ObserverRequest`] / [`ObserverReply`] *are* the wire contract. They carry
//! no version field of their own because the payloads already do:
//! [`RuntimeSnapshot`](crate::RuntimeSnapshot) and
//! [`RuntimeTree`](crate::RuntimeTree) each carry
//! [`SNAPSHOT_FORMAT_VERSION`](crate::SNAPSHOT_FORMAT_VERSION) (D1). The owned
//! snapshot — a potentially large `Vec<ActorInfo>` — travels over the call
//! channel by value; that is intended, it is exactly what a remote observer
//! (RFC 011) will serialize across a node boundary.
use crate::gen_server::{GenServer, GenServerBuilder, GenServerRef};
use crate::introspect::{actor_info, snapshot, tree};
use crate::introspect::{ActorInfo, RuntimeSnapshot, RuntimeTree};
use crate::pid::Pid;
/// A read-only request to the observer. Each verb maps one-to-one onto a
/// Chunk-1 read; there are deliberately no mutating verbs here (those are RFC
/// 003, D12).
#[derive(Debug, Clone)]
pub enum ObserverRequest {
/// Whole-runtime [`snapshot`].
Snapshot,
/// Parentage forest, folded from a snapshot ([`tree`]).
Tree,
/// Coherent view of one actor ([`actor_info`]); `None` reply if the pid is
/// stale, forged, or names a vacant slot.
ActorInfo(Pid),
}
/// The observer's reply, tagged to match the [`ObserverRequest`] verb. Each
/// variant wraps the owned Chunk-1 read result unchanged — the observer adds no
/// interpretation, it is pure transport.
#[derive(Debug, Clone)]
pub enum ObserverReply {
Snapshot(RuntimeSnapshot),
Tree(RuntimeTree),
ActorInfo(Option<ActorInfo>),
}
/// The observer server. Stateless by construction (a ZST): every reply is
/// derived freshly from the live runtime on each call, so there is nothing to
/// keep between requests.
pub struct Observer;
impl GenServer for Observer {
type Call = ObserverRequest;
type Reply = ObserverReply;
/// No async verbs: the observer is request/reply only. `Infallible` is
/// uninhabited, so a `cast` can never be constructed and
/// [`handle_cast`](GenServer::handle_cast) is statically unreachable.
type Cast = core::convert::Infallible;
type Info = ();
type Timer = ();
fn handle_call(&mut self, request: ObserverRequest) -> ObserverReply {
match request {
ObserverRequest::Snapshot => ObserverReply::Snapshot(snapshot()),
ObserverRequest::Tree => ObserverReply::Tree(tree()),
ObserverRequest::ActorInfo(pid) => ObserverReply::ActorInfo(actor_info(pid)),
}
}
fn handle_cast(&mut self, request: core::convert::Infallible) {
// Uninhabited: this match has no arms because `Cast` cannot be
// constructed. It documents at the type level that the observer takes
// no fire-and-forget traffic.
match request {}
}
}
/// Spawn the observer under the current actor and hand back its [`GenServerRef`].
/// Shorthand for `GenServerBuilder::new(Observer).start()`; use the builder
/// directly (e.g. `.under(sup)`) to slot it into a supervision tree.
///
/// ```
/// use smarm::run;
/// use smarm::observer::{self, ObserverRequest, ObserverReply};
///
/// run(|| {
/// let obs = observer::start();
///
/// // Ask for a whole-runtime snapshot over the call channel.
/// let ObserverReply::Snapshot(snap) = obs.call(ObserverRequest::Snapshot).unwrap()
/// else { panic!("snapshot verb must reply with a snapshot") };
///
/// // The observer is itself a scheduled actor, so it appears in the very
/// // snapshot it produced — transport over the same read every consumer sees.
/// assert!(snap.actors.iter().any(|a| a.pid == obs.pid()));
/// });
/// ```
pub fn start() -> GenServerRef<Observer> {
GenServerBuilder::new(Observer).start()
}
src/pg.rs
-656
View File
@@ -1,656 +0,0 @@
//! Process groups: one name, many actors.
//!
//! A process group is a named set of actors that you can look up, fan out to,
//! or pick a worker from. It is the natural home for a *worker pool* (several
//! interchangeable actors doing the same job), for *service discovery* (find
//! everyone currently offering some capability), and for *broadcast* (reach
//! every member of a group at once).
//!
//! The set is *live*: members [`join`] it, and a member that dies is removed
//! automatically. You never deregister a dead actor — there is no bookkeeping
//! to get wrong, and [`members`] / [`pick`] never hand you an actor that has
//! already gone.
//!
//! ## Joining and reading a group
//!
//! ```
//! use smarm::{channel, join, leave, members, pick, run, spawn};
//!
//! run(|| {
//! let (tx1, rx1) = channel::<()>();
//! let (tx2, rx2) = channel::<()>();
//! let w1 = spawn(move || { rx1.recv().unwrap(); });
//! let w2 = spawn(move || { rx2.recv().unwrap(); });
//!
//! // Workers join the group; `members` is the live view of it.
//! join("pool", w1.pid());
//! join("pool", w2.pid());
//! assert_eq!(members("pool").len(), 2);
//!
//! // One worker dies. Nothing tells the group — smarm evicts it
//! // automatically, so it is gone from `members` and never picked.
//! tx1.send(()).unwrap();
//! w1.join().unwrap();
//! assert_eq!(members("pool"), vec![w2.pid()]);
//! assert_eq!(pick("pool"), Some(w2.pid()));
//!
//! // Voluntary departure works too.
//! leave("pool", w2.pid());
//! assert!(pick("pool").is_none());
//!
//! tx2.send(()).unwrap();
//! w2.join().unwrap();
//! });
//! ```
//!
//! [`members`] returns every live member in the order they joined; [`pick`]
//! returns one of them, or `None` when the group is empty. The same actor can
//! belong to any number of groups at once, and joining a group it is already in
//! is a harmless no-op.
//!
//! ## Membership ends on its own
//!
//! You do not have to clean up after a member that dies. When an actor exits —
//! for any reason — it is removed from every group it had joined, before any
//! later read or send can observe it. [`leave`] is only for *voluntary*
//! departure, when a still-living actor wants out of a group.
//!
//! This is the main difference from keeping your own `Vec<Pid>`: a plain list
//! goes stale the instant a member dies, and you would have to notice and prune
//! it yourself. A group prunes itself.
//!
//! ## Sending to a group
//!
//! For a worker pool you usually want to hand a job to *one* available member.
//! [`dispatch`] picks a live member and sends it a message in a single step,
//! returning the member it reached:
//!
//! ```ignore
//! use smarm::{dispatch, join, Addressable};
//!
//! struct Job(String);
//! struct Worker;
//! impl Addressable for Worker { type Msg = Job; }
//!
//! // Each worker has published a `Pid<Worker>` inbox and joined the pool.
//! join("workers", worker_a);
//! join("workers", worker_b);
//!
//! // Route one job to whichever live worker `pick` lands on.
//! match dispatch::<Worker>("workers", Job("resize image".into())) {
//! Ok(who) => println!("sent to {who:?}"),
//! Err(returned) => println!("no worker took it: {returned:?}"),
//! }
//! ```
//!
//! When you want the pids themselves rather than to send right away, [`pick_as`]
//! and [`members_as`] return typed [`Pid<A>`](Pid)s for a homogeneous group, so
//! the follow-up send stays compile-checked. The untyped [`pick`] and
//! [`members`] are for mixed groups, where all you can rely on is identity.
//!
//! ## Groups vs. the registry
//!
//! A group is the many-actors counterpart to the [`registry`](crate::registry).
//! The registry binds a name to *at most one* actor and re-resolves it on every
//! send — what you want for a single well-known service. A group binds a name to
//! *many* actors, and one actor may sit in many groups. Reach for the registry
//! when there is exactly one of something; reach for a group when there is a set.
//!
//! ## Identity and clustering
//!
//! A group member is described by a [`Member`] — a [`Pid`] plus a [`NodeId`] and
//! an [`Incarnation`]. Today everything is single-node, those two fields are
//! fixed defaults, and you only ever pass and receive a plain [`Pid`]: the extra
//! identity is carried so this API will not have to change when groups learn to
//! span a cluster.
//!
//! ## Running context
//!
//! Every function here addresses the current runtime, so each must be called
//! from inside [`run`](crate::run) (that is, on an actor thread). Calling one
//! from outside a running runtime panics.
use crate::monitor::{demonitor, monitor, Monitor};
use crate::pid::{assert_type, Addressable, Pid};
use crate::registry::{send_to, SendError};
use crate::scheduler::with_runtime;
use std::collections::HashMap;
/// A cluster node handle. A `u32` integer handle, *not* an interned atom — the
/// single deliberate divergence from the BEAM wire shape.
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
pub struct NodeId(u32);
impl NodeId {
#[inline]
pub const fn new(v: u32) -> Self {
Self(v)
}
#[inline]
pub const fn get(self) -> u32 {
self.0
}
}
impl From<u32> for NodeId {
#[inline]
fn from(v: u32) -> Self {
Self(v)
}
}
/// A node's incarnation epoch — the BEAM `Creation` field adopted verbatim: it
/// separates a crashed node from its restart. Fixed for the life of a run
/// until clustering supplies a real one.
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
pub struct Incarnation(u32);
impl Incarnation {
#[inline]
pub const fn new(v: u32) -> Self {
Self(v)
}
#[inline]
pub const fn get(self) -> u32 {
self.0
}
}
impl From<u32> for Incarnation {
#[inline]
fn from(v: u32) -> Self {
Self(v)
}
}
/// The fixed single-node identity used until clustering supplies real values.
/// Carried like `wake_slot` so the public API never has to change to acquire it.
pub const DEFAULT_NODE_ID: NodeId = NodeId(0);
/// The fixed incarnation for the single-node default. Non-zero so it never
/// collides with a BEAM "any creation" wildcard at interop time.
pub const DEFAULT_INCARNATION: Incarnation = Incarnation(1);
/// A group member's full identity: `(node, incarnation, pid)`.
///
/// Deliberately a field-for-field image of a modern BEAM pid (`NEW_PID_EXT`).
/// In memory it is a plain struct — no wire packing; the packed representation
/// belongs to the remote-reference boundary, not here.
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
pub struct Member {
/// Which node the pid lives on. `DEFAULT_NODE_ID` while single-node.
pub node: NodeId,
/// The node's incarnation epoch at the time of joining.
pub incarnation: Incarnation,
/// Pure local slot identity — unchanged; cluster identity is layered
/// *around* it here rather than overloading `Pid::generation`.
pub pid: Pid,
}
/// One membership: a [`Member`] and the [`Monitor`] that watches its liveness.
/// The monitor lives *alongside* the group entry so a group is
/// self-contained: draining the membership tells us whether the member is
/// still alive, and dropping the membership drops its monitor.
struct Membership {
member: Member,
monitor: Monitor,
}
/// The store: `name → multiset<Member>`. Within a single group a `Member`
/// appears at most once (`join` is idempotent); the *multiset* framing is for
/// cluster-readiness — the same pid is freely a member of many groups, and the
/// width admits multiples in general.
///
/// Locking discipline. Held under one Leaf-class `RawMutex` on `RuntimeInner`,
/// mirroring the registry, and never held together with another Leaf lock (it
/// never touches the registry or a slot's cold lock). The two operations that
/// do need another lock are kept off the group-lock path:
///
/// - `monitor()` / `demonitor()` take the target's cold lock (also Leaf), so
/// they run *before* / *after* the group lock, never under it.
/// - draining a monitor with `try_recv` takes the channel's Channel-class
/// lock, which the lock order permits *under* a Leaf; a channel critical
/// section only does the lock-free unpark protocol, so no Leaf ever nests
/// under it.
///
/// Evicted and rejected [`Monitor`]s are therefore dropped only *after* the
/// group lock is released, so a receiver-drop never runs a wakeup under the
/// lock — the same discipline as `demonitor`.
pub(crate) struct ProcessGroups {
groups: HashMap<String, Vec<Membership>>,
}
impl ProcessGroups {
pub(crate) fn new() -> Self {
Self { groups: HashMap::new() }
}
/// Insert `ms` into `group`. Idempotent on the *member*: if the member is
/// already present the new membership is handed back (`Some`) so the caller
/// can tear its now-redundant monitor down outside the lock; `None` means
/// it was inserted.
fn join(&mut self, group: &str, ms: Membership) -> Option<Membership> {
let v = self.groups.entry(group.to_owned()).or_default();
if v.iter().any(|e| e.member == ms.member) {
return Some(ms);
}
v.push(ms);
None
}
/// Remove `member`'s membership from `group`, returning it (so the caller
/// can `demonitor` it outside the lock). An emptied group is pruned.
fn leave(&mut self, group: &str, member: Member) -> Option<Membership> {
let v = self.groups.get_mut(group)?;
let pos = v.iter().position(|e| e.member == member)?;
let removed = v.remove(pos);
if v.is_empty() {
self.groups.remove(group);
}
Some(removed)
}
/// The one dumb eviction primitive: drop every member matching `pred` from
/// every group, pruning emptied groups, and return the evicted memberships'
/// monitors for the caller to drop outside the lock. The primitive does not
/// know *why* a member leaves; that is the caller's concern. Its callers are
/// the death hook (`reap_group`) and, once clustering lands, an
/// incarnation-eviction sweep — both over this same predicate path, which is
/// the whole reason to shape eviction as a predicate. Insertion order within
/// a group is preserved (`members` / `pick` are order-stable).
fn remove_where(&mut self, mut pred: impl FnMut(&Member) -> bool) -> Vec<Monitor> {
let mut evicted = Vec::new();
self.groups.retain(|_, v| {
let mut i = 0;
while i < v.len() {
if pred(&v[i].member) {
evicted.push(v.remove(i).monitor);
} else {
i += 1;
}
}
!v.is_empty()
});
evicted
}
/// Drain-on-contact death hook. The registry can prune a stale binding
/// lazily, on contact, because it only ever resolves one binding at a time;
/// a group is *iterated* — `members` fans out to everyone — so it must not
/// carry a dead member across a broadcast. Every group operation reaps the
/// group it touches first.
///
/// Drains every membership monitor in `group` with a non-blocking
/// `try_recv`: a delivered `Down` (any reason) or a closed channel means
/// that member is dead. On the first death detected, sweep *all* of the
/// dead pids out of *every* group via [`remove_where`] — a death is removed
/// from each group it joined, not just the one being touched. Returns the
/// evicted monitors to drop outside the lock.
fn reap_group(&mut self, group: &str) -> Vec<Monitor> {
let dead: Vec<Pid> = {
let Some(v) = self.groups.get(group) else {
return Vec::new();
};
v.iter()
.filter_map(|e| match e.monitor.rx.try_recv() {
// A Down arrived, or the channel closed and drained: dead.
Ok(Some(_)) | Err(_) => Some(e.member.pid),
// Empty but open — the sender still lives in the slot: alive.
Ok(None) => None,
})
.collect()
};
if dead.is_empty() {
return Vec::new();
}
self.remove_where(|m| dead.contains(&m.pid))
}
/// Raw enumeration of a group's members — no liveness filtering. Used by
/// tests to assert storage state independently of the read-path backstop.
#[cfg(test)]
fn members_of(&self, group: &str) -> Vec<Member> {
self.groups
.get(group)
.map(|v| v.iter().map(|e| e.member).collect())
.unwrap_or_default()
}
/// Live members of `group`, in insertion order. The `is_live` oracle is the
/// read-path backstop: a member whose slot is already dead is
/// dropped from the *result* even if its `Down` has not been drained yet.
/// Backstop only — the entry stays in storage; eviction is the monitor's
/// job (`reap_group`).
fn members_where(&self, group: &str, mut is_live: impl FnMut(Pid) -> bool) -> Vec<Pid> {
self.groups
.get(group)
.map(|v| v.iter().map(|e| e.member.pid).filter(|&p| is_live(p)).collect())
.unwrap_or_default()
}
/// The first live member of `group` in insertion order — stateless
/// first-live `pick`, with the same read-path backstop as `members_where`.
fn first_member_where(&self, group: &str, mut is_live: impl FnMut(Pid) -> bool) -> Option<Pid> {
self.groups.get(group)?.iter().map(|e| e.member.pid).find(|&p| is_live(p))
}
}
/// Build the full member identity for `pid` from runtime identity.
fn member_for(inner: &crate::runtime::RuntimeInner, pid: Pid) -> Member {
Member { node: inner.node_id, incarnation: inner.incarnation, pid }
}
/// Is `pid` a live actor right now? Generation-checked atomic slot-word read,
/// no lock — identical to the registry's guard. The read-path backstop: a
/// generation is never reused, so a dead member is detectable independently of
/// whether its monitor `Down` has been drained yet.
fn live(inner: &crate::runtime::RuntimeInner, pid: Pid) -> bool {
inner.slot_at(pid).is_some_and(|s| s.is_live_for(pid))
}
/// Add `pid` to `group`. The same pid may join many groups; within one group a
/// pid is a member at most once (idempotent). Returns `true` if this call newly
/// added the membership, `false` if it was already a member.
///
/// Installs a monitor on `pid` so the actor's death evicts it from the group
/// automatically — you never have to remove a dead member yourself. A redundant
/// (idempotent) join tears its extra monitor back down.
///
/// Panics if called outside `Runtime::run()`.
pub fn join<A>(group: impl Into<String>, pid: Pid<A>) -> bool {
let group = group.into();
let pid = pid.erase();
// Install the monitor BEFORE taking the group lock: monitor() acquires the
// target's cold lock (Leaf), and two Leaf locks are never held at once. The
// registration races `finalize_actor` under that cold lock exactly as every
// other monitor does, so no death can slip between the join and the monitor
// being in place.
let mon = monitor(pid);
let (rejected, reaped) = with_runtime(|inner| {
let ms = Membership { member: member_for(inner, pid), monitor: mon };
let mut pg = inner.process_groups.lock();
let reaped = pg.reap_group(&group);
let rejected = pg.join(&group, ms);
(rejected, reaped)
});
// Outside the group lock: drop the reaped (dead) monitors, and if this join
// was redundant, demonitor + drop the extra monitor we just installed.
drop(reaped);
match rejected {
Some(dup) => {
demonitor(&dup.monitor);
false
}
None => true,
}
}
/// Drop `pid`'s membership of `group`. Returns whether a membership was
/// removed. The membership's monitor is demonitored and dropped.
///
/// Panics if called outside `Runtime::run()`.
pub fn leave<A>(group: &str, pid: Pid<A>) -> bool {
let pid = pid.erase();
let (removed, reaped) = with_runtime(|inner| {
let member = member_for(inner, pid);
let mut pg = inner.process_groups.lock();
let reaped = pg.reap_group(group);
let removed = pg.leave(group, member);
(removed, reaped)
});
drop(reaped);
match removed {
Some(ms) => {
demonitor(&ms.monitor);
true
}
None => false,
}
}
/// Every live member of `group`, in the order they joined. Returns an empty
/// vector if the group does not exist or has no live members.
///
/// Dead members are never returned: the group is pruned of anything that has
/// died before the read, and as a backstop a member whose slot is already dead
/// is dropped from the result even in the brief window before its death has
/// been fully processed.
///
/// Panics if called outside `Runtime::run()`.
pub fn members(group: &str) -> Vec<Pid> {
let (pids, reaped) = with_runtime(|inner| {
let mut pg = inner.process_groups.lock();
let reaped = pg.reap_group(group);
let pids = pg.members_where(group, |pid| live(inner, pid));
(pids, reaped)
});
drop(reaped);
pids
}
/// One live member of `group`, or `None` if the group is empty (or every
/// member has died). Selection is a stateless first-live scan in join order,
/// with the same dead-member backstop as [`members`]; smarter, load-aware
/// routing is a later, clustered concern.
///
/// Panics if called outside `Runtime::run()`.
pub fn pick(group: &str) -> Option<Pid> {
let (picked, reaped) = with_runtime(|inner| {
let mut pg = inner.process_groups.lock();
let reaped = pg.reap_group(group);
let picked = pg.first_member_where(group, |pid| live(inner, pid));
(picked, reaped)
});
drop(reaped);
picked
}
/// Typed [`pick`]: one live member of `group` as a [`Pid<A>`](Pid).
/// For a homogeneous pool every member is an `A`, so the picked member comes
/// back typed and dispatch is an ordinary compile-checked [`send_to`] rather
/// than the [`send_dyn`](crate::send_dyn) escape hatch. Re-types via the
/// unchecked `assert_type` primitive — a wrong `A` degrades to
/// [`SendError::NoChannel`] on the next send, never a misdelivery.
///
/// Panics if called outside `Runtime::run()`.
pub fn pick_as<A: Addressable>(group: &str) -> Option<Pid<A>> {
pick(group).map(assert_type::<A>)
}
/// Typed `members`: every live member of `group` as a [`Pid<A>`], same
/// unchecked re-type as [`pick_as`]. Fan-out stays compile-checked end to end.
///
/// Panics if called outside `Runtime::run()`.
pub fn members_as<A: Addressable>(group: &str) -> Vec<Pid<A>> {
members(group).into_iter().map(assert_type::<A>).collect()
}
/// Pick a live member of `group` and send it `msg` in one step, returning the
/// member it reached on success. The pick-a-live-member-and-send combinator
/// over [`pick_as`] + [`send_to`].
///
/// Errors hand `msg` back undelivered: [`SendError::NoMember`] if the pool is
/// empty (or all-dead), otherwise whatever the underlying [`send_to`] returns
/// (e.g. the picked member died in the window between pick and send →
/// [`SendError::Dead`]).
///
/// Panics if called outside `Runtime::run()`.
pub fn dispatch<A: Addressable>(group: &str, msg: A::Msg) -> Result<Pid<A>, SendError<A::Msg>> {
match pick_as::<A>(group) {
Some(pid) => send_to::<A>(pid, msg).map(|()| pid),
None => Err(SendError::NoMember(msg)),
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::channel::{channel, Sender};
use crate::monitor::{Down, DownReason, MonitorId};
fn member(index: u32, generation: u32) -> Member {
Member {
node: DEFAULT_NODE_ID,
incarnation: DEFAULT_INCARNATION,
pid: Pid::new(index, generation),
}
}
/// A synthetic membership with a real (but slot-less) monitor channel. The
/// returned `Sender` stands in for the slot's `Down` sender: hold it to
/// keep the member "alive" (`try_recv` → `Ok(None)`), `send` a `Down` to
/// simulate death, or `drop` it to simulate a drained/closed channel.
fn synth(index: u32, generation: u32) -> (Membership, Sender<Down>) {
let pid = Pid::new(index, generation);
let (tx, rx) = channel::<Down>();
let ms = Membership {
member: member(index, generation),
monitor: Monitor { id: MonitorId(0), target: pid, rx },
};
(ms, tx)
}
#[test]
fn join_is_idempotent_within_a_group() {
let mut pg = ProcessGroups::new();
let (a, _ta) = synth(1, 0);
let (b, _tb) = synth(1, 0);
assert!(pg.join("workers", a).is_none(), "first join inserts");
assert!(pg.join("workers", b).is_some(), "second identical join is handed back");
assert_eq!(pg.members_of("workers"), vec![member(1, 0)]);
}
#[test]
fn same_pid_in_many_groups_is_independent() {
let mut pg = ProcessGroups::new();
let (a, _ta) = synth(1, 0);
let (b, _tb) = synth(1, 0);
let (c, _tc) = synth(2, 0);
pg.join("a", a);
pg.join("b", b);
pg.join("b", c);
assert_eq!(pg.members_of("a"), vec![member(1, 0)]);
assert_eq!(pg.members_of("b"), vec![member(1, 0), member(2, 0)]);
}
#[test]
fn distinct_generations_are_distinct_members() {
// ABA guard: same slot index, different generation = different actor.
let mut pg = ProcessGroups::new();
let (a, _ta) = synth(1, 0);
let (b, _tb) = synth(1, 1);
assert!(pg.join("g", a).is_none());
assert!(pg.join("g", b).is_none(), "different generation is a distinct member");
assert_eq!(pg.members_of("g"), vec![member(1, 0), member(1, 1)]);
}
#[test]
fn leave_removes_one_membership_and_prunes_empty_groups() {
let mut pg = ProcessGroups::new();
let (a, _ta) = synth(1, 0);
let (b, _tb) = synth(2, 0);
pg.join("g", a);
pg.join("g", b);
assert!(pg.leave("g", member(1, 0)).is_some());
assert_eq!(pg.members_of("g"), vec![member(2, 0)]);
assert!(pg.leave("g", member(1, 0)).is_none(), "second leave finds nothing");
assert!(pg.leave("g", member(2, 0)).is_some());
assert!(pg.members_of("g").is_empty(), "group is now empty");
assert!(pg.leave("never", member(9, 0)).is_none(), "leaving an unknown group is a no-op");
}
#[test]
fn remove_where_sweeps_every_group() {
let mut pg = ProcessGroups::new();
for (g, (m, _t)) in [("a", synth(1, 0)), ("a", synth(2, 0)), ("b", synth(1, 0)), ("c", synth(3, 0))] {
pg.join(g, m);
}
// Death of pid index 1 (any generation) evicts it everywhere.
let evicted = pg.remove_where(|mem| mem.pid.index() == 1);
assert_eq!(evicted.len(), 2, "pid 1 was in a and b");
assert_eq!(pg.members_of("a"), vec![member(2, 0)]);
assert!(pg.members_of("b").is_empty(), "b held only pid 1; pruned");
assert_eq!(pg.members_of("c"), vec![member(3, 0)]);
}
#[test]
fn remove_where_can_match_an_incarnation_sweep() {
// Shape check for the later evict_incarnation(node, inc) caller.
let mut pg = ProcessGroups::new();
let pid = Pid::new(1, 0);
let (tx, rx) = channel::<Down>();
let dead = Membership {
member: Member { node: DEFAULT_NODE_ID, incarnation: Incarnation::new(7), pid },
monitor: Monitor { id: MonitorId(0), target: pid, rx },
};
let _keep = tx;
let (live, _tl) = synth(2, 0);
pg.join("g", dead);
pg.join("g", live);
let evicted = pg.remove_where(|mem| mem.incarnation == Incarnation::new(7));
assert_eq!(evicted.len(), 1);
assert_eq!(pg.members_of("g"), vec![member(2, 0)]);
}
#[test]
fn reap_keeps_live_members() {
let mut pg = ProcessGroups::new();
let (a, _ta) = synth(1, 0); // sender held: member stays alive
pg.join("a", a);
assert!(pg.reap_group("a").is_empty(), "no deaths");
assert_eq!(pg.members_of("a"), vec![member(1, 0)]);
}
#[test]
fn reap_evicts_a_dead_member_and_sweeps_all_its_groups() {
let mut pg = ProcessGroups::new();
let (a1, ta1) = synth(1, 0); // pid 1 in group a
let (a2, _ta2) = synth(2, 0); // pid 2 in group a (stays alive)
let (b1, _tb1) = synth(1, 0); // pid 1 in group b
pg.join("a", a1);
pg.join("a", a2);
pg.join("b", b1);
// pid 1 dies: its group-a monitor receives a Down. Its group-b monitor
// has not — reap must still sweep pid 1 out of b by the pid predicate.
ta1.send(Down { pid: Pid::new(1, 0), reason: DownReason::Exit }).unwrap();
let evicted = pg.reap_group("a");
assert_eq!(evicted.len(), 2, "pid 1's memberships in both a and b are evicted");
assert_eq!(pg.members_of("a"), vec![member(2, 0)]);
assert!(pg.members_of("b").is_empty(), "swept from b too; pruned");
}
#[test]
fn reap_treats_a_closed_channel_as_dead() {
let mut pg = ProcessGroups::new();
let (a, ta) = synth(1, 0);
pg.join("a", a);
drop(ta); // sender gone, queue empty → try_recv = Err(RecvError) = dead
let evicted = pg.reap_group("a");
assert_eq!(evicted.len(), 1);
assert!(pg.members_of("a").is_empty());
}
#[test]
fn read_backstop_hides_a_member_the_monitor_has_not_yet_reaped() {
let mut pg = ProcessGroups::new();
// Both senders held: reap_group would see Ok(None) and evict neither.
let (a, _ta) = synth(1, 0);
let (b, _tb) = synth(2, 0);
pg.join("g", a);
pg.join("g", b);
// The slot-word oracle already reports pid 1 dead (finalize window),
// ahead of any Down delivery.
let dead = Pid::new(1, 0);
let oracle = |pid: Pid| pid != dead;
assert_eq!(pg.members_where("g", oracle), vec![Pid::new(2, 0)], "dead pid filtered from read");
assert_eq!(pg.first_member_where("g", oracle), Some(Pid::new(2, 0)), "pick skips the dead first member");
// Backstop does not evict — that stays the monitor's job; raw storage
// still holds both until reap runs.
assert_eq!(pg.members_of("g"), vec![member(1, 0), member(2, 0)]);
}
}
src/pid.rs
+13 -260
View File
@@ -1,285 +1,38 @@
//! Process identifiers. //! Process identifiers.
//! //!
//! Identity is `(index, generation)`: the index is a slot in the scheduler's //! A `Pid` is `(index, generation)`. The index is a slot in the scheduler's
//! actor table, the generation increments every time that slot is reused, so a //! actor table; the generation increments every time that slot is reused.
//! stale id (right index, wrong generation) is a *detectable* error rather than //! A stale `Pid` (correct index, wrong generation) is a detectable error,
//! a silent misdirection — the ABA problem solved without exhausting the id //! not a silent misdirection — solves the ABA problem without exhausting
//! space. Those raw numbers live in [`RawPid`]. //! the PID space.
//!
//! The public identity is the *typed* [`Pid<A>`] (RFC 014): `RawPid` plus a
//! phantom actor type, so a pid is simultaneously an identity and a direct,
//! identity-bound address. `Pid<Erased>` — the default — is the untyped pid
//! used for identity-only plumbing and for actors with no single message type
//! (raw `spawn`, gen_servers). Resolving a name yields the durable, re-resolving
//! [`Name`] instead.
use std::marker::PhantomData;
/// The raw identity numbers, with no actor type. The key for everything that
/// only cares about *which* actor: slab indexing, generation checks, and the
/// heterogeneous monitor / link / pg tables (which hold actors of every type at
/// once, so they cannot be parameterised by one).
#[derive(Copy, Clone, PartialEq, Eq, Hash)] #[derive(Copy, Clone, PartialEq, Eq, Hash)]
pub struct RawPid { pub struct Pid {
index: u32, index: u32,
generation: u32, generation: u32,
} }
impl RawPid { impl Pid {
#[inline] #[inline]
pub const fn new(index: u32, generation: u32) -> Self { pub const fn new(index: u32, generation: u32) -> Self {
Self { index, generation } Self { index, generation }
} }
#[inline] #[inline]
pub const fn index(self) -> u32 { pub const fn index(self) -> u32 { self.index }
self.index
}
#[inline] #[inline]
pub const fn generation(self) -> u32 { pub const fn generation(self) -> u32 { self.generation }
self.generation
}
} }
impl std::fmt::Debug for RawPid { impl std::fmt::Debug for Pid {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "Pid({}.{})", self.index, self.generation) write!(f, "Pid({}.{})", self.index, self.generation)
} }
} }
impl std::fmt::Display for RawPid { impl std::fmt::Display for Pid {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "<{}.{}>", self.index, self.generation) write!(f, "<{}.{}>", self.index, self.generation)
} }
} }
/// Phantom actor type for a pid that has no single message type: raw `spawn`
/// actors, gen_servers (intrinsically multi-message, addressed via `GenServerRef`),
/// and every identity-only context. Deliberately **not** [`Addressable`], so a
/// typed `send` to a `Pid<Erased>` does not compile; the runtime-checked
/// `send_dyn` escape hatch (RFC 014 §4.6) is the sanctioned bare-pid path.
pub enum Erased {}
/// A process identifier parameterised by the actor's type `A` (default
/// [`Erased`]). Wraps the raw `(index, generation)` plus a zero-sized phantom,
/// so a `Pid<A>` is both an identity and a direct, identity-bound address: when
/// `A: Addressable`, a `send` delivers `A::Msg` to exactly the incarnation this
/// pid names — no redirect (contrast the re-resolving [`Name`]).
///
/// Equality, hashing, and formatting are the raw identity's; the phantom is
/// `fn() -> A`, so `Pid<A>` is unconditionally `Copy + Send + Sync` and borrows
/// nothing from `A`. The trait impls are hand-written so no `A: Trait` bound
/// leaks in from a `#[derive]`.
pub struct Pid<A = Erased> {
raw: RawPid,
_marker: PhantomData<fn() -> A>,
}
impl Pid<Erased> {
/// Build an untyped pid from raw numbers. The runtime mints identities
/// here; typing happens at typed-actor boundaries via [`Pid::from_raw`].
#[inline]
pub const fn new(index: u32, generation: u32) -> Self {
Self { raw: RawPid::new(index, generation), _marker: PhantomData }
}
}
impl<A> Pid<A> {
/// Wrap a raw identity as a typed pid. Crate-internal: minting a typed pid
/// from raw numbers asserts an actor's type *unchecked*, which is exactly
/// what the typed API exists to avoid outside the runtime's own spawn /
/// resolution paths.
#[inline]
pub(crate) const fn from_raw(raw: RawPid) -> Self {
Self { raw, _marker: PhantomData }
}
/// The raw identity, dropping the actor type — the key for identity-only
/// tables and internal plumbing.
#[inline]
pub const fn raw(self) -> RawPid {
self.raw
}
/// Forget the actor type.
#[inline]
pub const fn erase(self) -> Pid<Erased> {
Pid::from_raw(self.raw)
}
/// Slot index in the actor table.
#[inline]
pub const fn index(self) -> u32 {
self.raw.index()
}
/// Reuse generation of the slot (ABA guard).
#[inline]
pub const fn generation(self) -> u32 {
self.raw.generation()
}
}
/// Re-type an erased pid as `Pid<A>` *unchecked* — the one shared primitive
/// behind `lookup_as` / `pick_as` / `members_as` (RFC 014 §4.4). The registry
/// and pg stores are heterogeneous in `A` (they hold actors of every type at
/// once), so resolving them yields a bare [`Pid`]; recovering the typed address
/// is necessarily an assertion the store cannot make for us.
///
/// **Not unsound.** Delivery routes on the message's [`TypeId`](std::any::TypeId)
/// (every send path keys the channel store by it), so a wrong `A` here does not
/// mis-deliver: the next [`send_to`](crate::send_to) finds no channel for
/// `A::Msg` on that actor and returns [`SendError::NoChannel`](crate::SendError::NoChannel).
/// A mistyped pid degrades to a clean send error, never a silent misroute.
#[inline]
pub(crate) fn assert_type<A>(pid: Pid) -> Pid<A> {
Pid::from_raw(pid.raw())
}
impl<A> Copy for Pid<A> {}
impl<A> Clone for Pid<A> {
fn clone(&self) -> Self {
*self
}
}
impl<A> PartialEq for Pid<A> {
fn eq(&self, other: &Self) -> bool {
self.raw == other.raw
}
}
impl<A> Eq for Pid<A> {}
impl<A> std::hash::Hash for Pid<A> {
fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
self.raw.hash(state);
}
}
impl<A> std::fmt::Debug for Pid<A> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
std::fmt::Debug::fmt(&self.raw, f)
}
}
impl<A> std::fmt::Display for Pid<A> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
std::fmt::Display::fmt(&self.raw, f)
}
}
/// An actor type with a single associated message type, so a [`Pid<Self>`] is a
/// typed address. The raw channel layer has no such trait (actors are closures
/// over channels) and `GenServer` is intrinsically multi-message (addressed via
/// its own `GenServerRef`); this is the minimal hook that lets the single-message
/// actors carry their message type in their pid. (RFC 014 §4.2.)
pub trait Addressable: 'static {
/// The message this actor receives. A `Pid<Self>` delivers `Self::Msg`.
type Msg: Send + 'static;
}
/// A durable, re-resolving address: a static name plus a phantom message type
/// `M` (RFC 014's `Name<M>`). Declared as a constant and shared freely:
///
/// ```ignore
/// const COUNTER: Name<CounterMsg> = Name::new("counter");
/// ```
///
/// Unlike a [`Pid`], a `Name` is resolved through the registry on *every* send,
/// so it always reaches whoever currently holds the name.
pub struct Name<M> {
name: &'static str,
_marker: PhantomData<fn() -> M>,
}
impl<M> Name<M> {
/// Bind a static string as a typed name. `const`, so names live as
/// associated constants at call sites.
#[inline]
pub const fn new(name: &'static str) -> Self {
Self { name, _marker: PhantomData }
}
/// The underlying registry key.
#[inline]
pub const fn as_str(self) -> &'static str {
self.name
}
}
impl<M> Copy for Name<M> {}
impl<M> Clone for Name<M> {
fn clone(&self) -> Self {
*self
}
}
impl<M> PartialEq for Name<M> {
fn eq(&self, other: &Self) -> bool {
self.name == other.name
}
}
impl<M> Eq for Name<M> {}
impl<M> std::hash::Hash for Name<M> {
fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
self.name.hash(state);
}
}
impl<M> std::fmt::Debug for Name<M> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "Name<{}>({:?})", std::any::type_name::<M>(), self.name)
}
}
#[cfg(test)]
mod typed_pid_tests {
use super::*;
// A stand-in actor type with one message type, exercising `Addressable`.
struct Counter;
struct CounterMsg; // used only as a phantom key; no variants needed
impl Addressable for Counter {
type Msg = CounterMsg;
}
fn msg_type_name<A: Addressable>() -> &'static str {
std::any::type_name::<A::Msg>()
}
#[test]
fn typed_pid_is_a_copyable_identity() {
let p = Pid::<Counter>::from_raw(RawPid::new(3, 1));
let q = p; // Copy, not move
assert_eq!(p.index(), 3);
assert_eq!(p.generation(), 1);
assert_eq!(p, q);
// Same index, different generation = different incarnation.
assert_ne!(p, Pid::<Counter>::from_raw(RawPid::new(3, 2)));
assert!(format!("{p:?}").starts_with("Pid("));
}
#[test]
fn erase_drops_the_type_but_keeps_identity() {
let p = Pid::<Counter>::from_raw(RawPid::new(7, 4));
assert_eq!(p.erase(), Pid::new(7, 4)); // Pid<Erased>
assert_eq!(p.raw(), RawPid::new(7, 4));
}
#[test]
fn name_is_a_copyable_string_token() {
const COUNTER: Name<CounterMsg> = Name::new("counter");
let n = COUNTER; // Copy
assert_eq!(n.as_str(), "counter");
assert_eq!(n, COUNTER);
assert_ne!(n, Name::<CounterMsg>::new("other"));
assert!(format!("{n:?}").contains("\"counter\""));
}
#[test]
fn addressable_exposes_the_message_type() {
assert!(msg_type_name::<Counter>().ends_with("CounterMsg"));
}
// Identity tokens must be usable across threads.
#[test]
fn tokens_are_send_sync_without_key_bounds() {
fn assert_send_sync<T: Send + Sync>() {}
assert_send_sync::<Pid<Counter>>();
assert_send_sync::<Pid<Erased>>();
assert_send_sync::<Name<CounterMsg>>();
}
}
src/preempt.rs
+18 -85
View File
@@ -30,7 +30,17 @@ use std::cell::Cell;
use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::atomic::{AtomicBool, Ordering};
pub const DEFAULT_ALLOC_INTERVAL: u32 = 128; pub const DEFAULT_ALLOC_INTERVAL: u32 = 128;
// The timeslice is measured in `rdtsc()` ticks, and the tick *unit* differs by
// ISA (see `crate::arch::read_cycle_counter`). Both constants target ~100µs.
// x86-64 : TSC ≈ CPU base clock; 300_000 ticks ≈ 100µs on a 3 GHz core.
// aarch64: CNTVCT runs at CNTFRQ_EL0, commonly ~24 MHz; 2_400 ticks ≈ 100µs.
// A real implementation would read the frequency at startup and compute this;
// for now the constant is calibrated per-arch. Tune on-device if needed.
#[cfg(target_arch = "x86_64")]
pub const DEFAULT_TIMESLICE_CYCLES: u64 = 300_000; // ≈ 100µs on a 3 GHz CPU pub const DEFAULT_TIMESLICE_CYCLES: u64 = 300_000; // ≈ 100µs on a 3 GHz CPU
#[cfg(target_arch = "aarch64")]
pub const DEFAULT_TIMESLICE_CYCLES: u64 = 2_400; // ≈ 100µs at a 24 MHz CNTVCT
thread_local! { thread_local! {
/// While `false`, the allocator hook is a no-op. /// While `false`, the allocator hook is a no-op.
@@ -58,16 +68,6 @@ thread_local! {
/// resume path free of atomic ref-count traffic; see `check_cancelled` for /// resume path free of atomic ref-count traffic; see `check_cancelled` for
/// the safety argument. /// the safety argument.
static CURRENT_STOP: Cell<*const AtomicBool> = const { Cell::new(std::ptr::null()) }; static CURRENT_STOP: Cell<*const AtomicBool> = const { Cell::new(std::ptr::null()) };
/// Raw pointer to the on-CPU actor's slot, set/cleared by the scheduler on
/// the same resume/return boundary as `CURRENT_STOP` (RFC 016 Chunk 2).
/// Lets the rare slice-expiry site bump that actor's overrun counter with
/// one TLS load and no runtime lookup. Null while no actor is on-CPU. The
/// slot lives in the fixed slab and is never reclaimed while the actor is
/// running, so the pointer is valid for the whole resume (same lifetime
/// argument as `CURRENT_STOP`).
static CURRENT_SLOT: Cell<*const crate::runtime::Slot> =
const { Cell::new(std::ptr::null()) };
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -87,46 +87,6 @@ pub(crate) fn clear_current_stop() {
CURRENT_STOP.with(|c| c.set(std::ptr::null())); CURRENT_STOP.with(|c| c.set(std::ptr::null()));
} }
/// Bind the on-CPU actor's slot. Called by the scheduler immediately before
/// `switch_to_actor`, beside `set_current_stop`.
pub(crate) fn set_current_slot(slot: *const crate::runtime::Slot) {
CURRENT_SLOT.with(|c| c.set(slot));
}
/// Unbind the slot pointer on the return path, beside `clear_current_stop`.
pub(crate) fn clear_current_slot() {
CURRENT_SLOT.with(|c| c.set(std::ptr::null()));
}
/// Tally a timeslice overrun against the on-CPU actor (RFC 016 Chunk 2). A
/// no-op if no actor is bound (the scheduler's own stack). Reached only from
/// the slice-expiry branch, which is already the yield path, so its cost is
/// irrelevant.
#[inline]
fn note_overrun() {
let p = CURRENT_SLOT.with(|c| c.get());
// SAFETY: `p` is null (no actor on-CPU) or a pointer to the on-CPU actor's
// slot in the fixed slab. The slot is not reclaimed while the actor runs
// (finalize/reclaim happen only after it yields back), so the deref is
// valid for the whole resume — the same argument as `check_cancelled`.
if !p.is_null() {
unsafe { (*p).record_overrun() };
}
}
/// Tally one received message against the on-CPU actor (RFC 016 Chunk 2),
/// called from the channel receive path on each successful dequeue. A no-op
/// outside an actor (null slot). One TLS load + one Relaxed load/store on a
/// cache line the receiving thread already owns — no atomic RMW, no lock. Same
/// slot-lifetime safety argument as `note_overrun`.
#[inline]
pub(crate) fn note_message_received() {
let p = CURRENT_SLOT.with(|c| c.get());
if !p.is_null() {
unsafe { (*p).record_message() };
}
}
/// Observation point for cooperative cancellation. If the on-CPU actor has /// Observation point for cooperative cancellation. If the on-CPU actor has
/// been flagged for stop, raise the sentinel panic so the trampoline's /// been flagged for stop, raise the sentinel panic so the trampoline's
/// `catch_unwind` tears the stack down (running Drop) and reports /// `catch_unwind` tears the stack down (running Drop) and reports
@@ -166,24 +126,12 @@ pub fn reset_timeslice() {
TIMESLICE_START.with(|c| c.set(rdtsc())); TIMESLICE_START.with(|c| c.set(rdtsc()));
} }
/// Cycles elapsed since the current slice started (RFC 016 Chunk 2, /// Per-core cycle counter for the timeslice clock. Delegates to the active
/// `budget-accounting`). Read by the scheduler right after an actor yields back, /// arch backend (`rdtsc` on x86-64, `CNTVCT_EL0` on aarch64). The tick unit
/// on the same thread that armed `TIMESLICE_START`. Approximate for wake-slot /// is ISA-defined, so `DEFAULT_TIMESLICE_CYCLES` is calibrated per-arch below.
/// resumes, which inherit the slice (see `Slot::add_budget`).
#[cfg(feature = "budget-accounting")]
#[inline]
pub(crate) fn elapsed_slice_cycles() -> u64 {
rdtsc().saturating_sub(TIMESLICE_START.with(|c| c.get()))
}
#[inline(always)] #[inline(always)]
pub fn rdtsc() -> u64 { pub fn rdtsc() -> u64 {
unsafe { crate::arch::read_cycle_counter()
// SAFETY: x86-64 only. `lfence` serialises the instruction stream so
// we don't measure time before prior instructions retire.
core::arch::asm!("lfence", options(nostack, nomem, preserves_flags));
core::arch::x86_64::_rdtsc()
}
} }
pub struct PreemptingAllocator; pub struct PreemptingAllocator;
@@ -231,28 +179,13 @@ pub fn maybe_preempt() {
let n = c.get(); let n = c.get();
if n == 0 { if n == 0 {
c.set(CONFIGURED_ALLOC_INTERVAL.with(|i| i.get())); c.set(CONFIGURED_ALLOC_INTERVAL.with(|i| i.get()));
if PREEMPTION_ENABLED.with(|e| e.get()) { // Cooperative cancellation shares the amortised cadence with the
// Cooperative cancellation shares the amortised cadence with // timeslice check. Observe a pending stop first: if we are being
// the timeslice check, and shares its gate: while preemption // cancelled there is no point yielding, we unwind instead.
// is disabled (`NoPreempt`, `with_shared`, channel critical
// sections) the stop sentinel must NOT be raised, because an
// allocation-triggered unwind inside a region holding a
// `std::sync::Mutex` would poison it — one `request_stop` at
// the wrong moment would then cascade `lock().unwrap()`
// panics through every later user of that lock. Observation
// is merely deferred to the next enabled allocation or the
// wakeup side of the next park/yield, both of which are
// lock-free points by construction.
//
// Observe a pending stop first: if we are being cancelled
// there is no point yielding, we unwind instead.
check_cancelled(); check_cancelled();
if PREEMPTION_ENABLED.with(|e| e.get()) {
let start = TIMESLICE_START.with(|s| s.get()); let start = TIMESLICE_START.with(|s| s.get());
if rdtsc().saturating_sub(start) > CONFIGURED_TIMESLICE_CYCLES.with(|t| t.get()) { if rdtsc().saturating_sub(start) > CONFIGURED_TIMESLICE_CYCLES.with(|t| t.get()) {
// Tally the overrun (RFC 016 Chunk 2) before handing back —
// this is the slice-expiry site RFC 006 wanted, and it's
// already the yield path, so the counter is near-free.
note_overrun();
// SAFETY: reachable only inside an actor (the scheduler // SAFETY: reachable only inside an actor (the scheduler
// sets PREEMPTION_ENABLED on resume and clears it on // sets PREEMPTION_ENABLED on resume and clears it on
// return). The scheduler stack is therefore valid. // return). The scheduler stack is therefore valid.
src/raw_mutex.rs
-360
View File
@@ -1,360 +0,0 @@
//! A minimal futex-based mutex that cannot poison.
//!
//! `std::sync::Mutex` poisons on unwind, turning one panic into a cascade of
//! `lock().unwrap()` panics in every later user. The runtime's internal
//! critical sections must never unwind anyway (the stop sentinel is gated
//! behind `PREEMPTION_ENABLED`, and the guard below disables preemption), so
//! poisoning buys nothing and costs a failure mode. This mutex has no poison
//! state by construction.
//!
//! Two further properties the runtime wants:
//!
//! - **The guard enters `NoPreempt`.** A timeslice switch while holding an OS
//! mutex would suspend the actor with the lock held, stalling every other
//! OS thread that touches it until the actor is resumed. Disabling
//! preemption for the (short) critical section keeps lock hold times
//! bounded. It also closes the unwind hole structurally: with
//! `PREEMPTION_ENABLED` false, `maybe_preempt` neither yields nor raises
//! the stop sentinel, so no allocation inside the critical section can
//! unwind it.
//! - **No std machinery.** One `AtomicU32` and two futex syscalls; friendlier
//! to an eventual embedded port than `std::sync::Mutex` (swap the futex for
//! a spin or WFE backend).
//!
//! Algorithm: the classic three-state futex mutex (Drepper, "Futexes Are
//! Tricky", mutex3). 0 = unlocked, 1 = locked, 2 = locked with (possible)
//! waiters. Uncontended lock/unlock is one CAS / one swap, no syscall.
//!
//! Lock-order position — two classes (see [`LockClass`]):
//!
//! - **Leaf**: slot cold locks, the free list, the stack pool, the name
//! registry. Mutual leaves — never hold two at once.
//! - **Channel**: a channel's internal lock. May be acquired *under* a Leaf
//! (finalize clones the supervisor/trap senders, and `monitor()` clones the
//! Down sender, all under a cold lock — structural, the sender lives in the
//! slot), but nothing may be acquired under a Channel lock: channel
//! critical sections call only the lock-free unpark protocol.
//!
//! So the total order is Leaf → Channel, one of each at most. Holding either
//! while pushing to the run queue is permitted (unpark from inside a cold or
//! channel section); the reverse — taking any `RawMutex` from inside a
//! run-queue op — cannot arise (queue ops call nothing).
use std::cell::UnsafeCell;
use std::ops::{Deref, DerefMut};
use std::sync::atomic::{AtomicU32, Ordering};
const UNLOCKED: u32 = 0;
const LOCKED: u32 = 1;
const CONTENDED: u32 = 2;
/// How many `pause` spins to burn before falling back to the futex. Critical
/// sections under this lock are tens of nanoseconds (push to a Vec, clone a
/// sender), so a short spin almost always avoids the syscall.
const SPIN_LIMIT: u32 = 64;
/// Which rung of the two-rung lock order a `RawMutex` occupies. Debug builds
/// enforce the order mechanically (see the module docs); release builds carry
/// no state and no checks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum LockClass {
/// Runtime cold data: slot cold locks, free list, stack pool, registry.
/// Mutual leaves among themselves; a Channel lock may be taken under one.
Leaf,
/// A channel's internal lock. One at a time, nothing acquired under it;
/// may itself be acquired under a Leaf.
Channel,
}
// The ordering rules, mechanically enforced (debug builds): a deadlock from a
// violated order is a hang waiting for the right interleaving, so fail at the
// acquisition that violates it, not in the eventual hang.
#[cfg(debug_assertions)]
thread_local! {
static LEAVES_HELD: std::cell::Cell<u32> = const { std::cell::Cell::new(0) };
static CHANNELS_HELD: std::cell::Cell<u32> = const { std::cell::Cell::new(0) };
}
#[inline]
fn order_check_acquire(class: LockClass) {
#[cfg(debug_assertions)]
match class {
LockClass::Leaf => LEAVES_HELD.with(|l| {
debug_assert_eq!(
l.get(),
0,
"lock order violated: acquiring a Leaf RawMutex while already \
holding one (cold locks / free list / stack pool / registry \
are mutual leaves)"
);
CHANNELS_HELD.with(|c| {
debug_assert_eq!(
c.get(),
0,
"lock order violated: acquiring a Leaf RawMutex under a \
channel lock (order is Leaf -> Channel, never the reverse)"
);
});
l.set(l.get() + 1);
}),
LockClass::Channel => CHANNELS_HELD.with(|c| {
debug_assert_eq!(
c.get(),
0,
"lock order violated: acquiring a channel lock while already \
holding one (channel locks are mutual leaves)"
);
c.set(c.get() + 1);
}),
}
#[cfg(not(debug_assertions))]
let _ = class;
}
#[inline]
fn order_check_release(class: LockClass) {
#[cfg(debug_assertions)]
match class {
LockClass::Leaf => LEAVES_HELD.with(|c| c.set(c.get() - 1)),
LockClass::Channel => CHANNELS_HELD.with(|c| c.set(c.get() - 1)),
}
#[cfg(not(debug_assertions))]
let _ = class;
}
pub(crate) struct RawMutex<T> {
state: AtomicU32,
class: LockClass,
data: UnsafeCell<T>,
}
// SAFETY: standard mutex argument — exclusive access to `data` is mediated by
// `state`; `T: Send` suffices for both because `&RawMutex` only ever hands out
// access to one thread at a time.
unsafe impl<T: Send> Send for RawMutex<T> {}
unsafe impl<T: Send> Sync for RawMutex<T> {}
impl<T> RawMutex<T> {
/// A Leaf-class mutex — the default for runtime cold data.
pub(crate) const fn new(data: T) -> Self {
Self::with_class(data, LockClass::Leaf)
}
/// A Channel-class mutex — for channel internals only.
pub(crate) const fn new_channel(data: T) -> Self {
Self::with_class(data, LockClass::Channel)
}
pub(crate) const fn with_class(data: T, class: LockClass) -> Self {
Self {
state: AtomicU32::new(UNLOCKED),
class,
data: UnsafeCell::new(data),
}
}
#[inline]
pub(crate) fn lock(&self) -> RawMutexGuard<'_, T> {
// Enter NoPreempt *before* acquiring, so a preemption can't fire
// between acquisition and guard construction.
let prev_preempt = crate::preempt::PREEMPTION_ENABLED.with(|c| c.replace(false));
order_check_acquire(self.class);
if self
.state
.compare_exchange(UNLOCKED, LOCKED, Ordering::Acquire, Ordering::Relaxed)
.is_err()
{
self.lock_slow();
}
RawMutexGuard { m: self, prev_preempt }
}
#[cold]
fn lock_slow(&self) {
// Bounded spin first: the expected hold time is far below the cost of
// a futex round trip.
let mut spins = 0;
loop {
let s = self.state.load(Ordering::Relaxed);
if s == UNLOCKED
&& self
.state
.compare_exchange_weak(UNLOCKED, LOCKED, Ordering::Acquire, Ordering::Relaxed)
.is_ok()
{
return;
}
spins += 1;
if spins >= SPIN_LIMIT {
break;
}
std::hint::spin_loop();
}
// Futex path. Mark contended and sleep until woken; on wake, retake
// by swapping to CONTENDED (we cannot know whether other waiters
// remain, so we must conservatively keep the contended marker).
while self.state.swap(CONTENDED, Ordering::Acquire) != UNLOCKED {
futex_wait(&self.state, CONTENDED);
}
}
#[inline]
fn unlock(&self) {
if self.state.swap(UNLOCKED, Ordering::Release) == CONTENDED {
futex_wake(&self.state, 1);
}
}
}
pub(crate) struct RawMutexGuard<'a, T> {
m: &'a RawMutex<T>,
prev_preempt: bool,
}
impl<T> Deref for RawMutexGuard<'_, T> {
type Target = T;
#[inline]
fn deref(&self) -> &T {
// SAFETY: guard existence implies exclusive ownership of the lock.
unsafe { &*self.m.data.get() }
}
}
impl<T> DerefMut for RawMutexGuard<'_, T> {
#[inline]
fn deref_mut(&mut self) -> &mut T {
// SAFETY: as above, plus &mut self.
unsafe { &mut *self.m.data.get() }
}
}
impl<T> Drop for RawMutexGuard<'_, T> {
#[inline]
fn drop(&mut self) {
self.m.unlock();
order_check_release(self.m.class);
// Restore preemption only after the lock is released.
crate::preempt::PREEMPTION_ENABLED.with(|c| c.set(self.prev_preempt));
}
}
// ---------------------------------------------------------------------------
// futex (x86-64 Linux; master is x86-only, see arm-port branch)
// ---------------------------------------------------------------------------
fn futex_wait(state: &AtomicU32, expected: u32) {
// SAFETY: `state` is a valid, aligned u32 for the duration of the call.
// Spurious wakeups and EAGAIN (value already changed) are both handled by
// the caller's retry loop.
unsafe {
libc::syscall(
libc::SYS_futex,
state.as_ptr(),
libc::FUTEX_WAIT | libc::FUTEX_PRIVATE_FLAG,
expected,
std::ptr::null::<libc::timespec>(),
);
}
}
fn futex_wake(state: &AtomicU32, n: i32) {
// SAFETY: as above.
unsafe {
libc::syscall(
libc::SYS_futex,
state.as_ptr(),
libc::FUTEX_WAKE | libc::FUTEX_PRIVATE_FLAG,
n,
);
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Arc;
#[test]
fn uncontended_lock_unlock() {
let m = RawMutex::new(0u64);
for _ in 0..1000 {
*m.lock() += 1;
}
assert_eq!(*m.lock(), 1000);
}
#[test]
fn contended_counter_is_exact() {
const THREADS: usize = 8;
const PER: u64 = 50_000;
let m = Arc::new(RawMutex::new(0u64));
let hs: Vec<_> = (0..THREADS)
.map(|_| {
let m = m.clone();
std::thread::spawn(move || {
for _ in 0..PER {
*m.lock() += 1;
}
})
})
.collect();
for h in hs {
h.join().unwrap();
}
assert_eq!(*m.lock(), THREADS as u64 * PER);
}
#[test]
fn no_poison_on_unwind() {
let m = Arc::new(RawMutex::new(0u64));
let m2 = m.clone();
let _ = std::thread::spawn(move || {
let _g = m2.lock();
panic!("unwind while holding");
})
.join();
// A std Mutex would now be poisoned; this one just works.
*m.lock() += 1;
assert_eq!(*m.lock(), 1);
}
#[test]
fn channel_lock_nests_under_leaf() {
// The permitted ordering: Leaf -> Channel (finalize/monitor clone a
// sender under a cold lock). Must not trip the order check.
let leaf = RawMutex::new(0u64);
let chan = RawMutex::new_channel(0u64);
let _l = leaf.lock();
let _c = chan.lock();
}
#[cfg(debug_assertions)]
#[test]
#[should_panic(expected = "lock order violated")]
fn leaf_under_channel_is_rejected() {
let leaf = RawMutex::new(0u64);
let chan = RawMutex::new_channel(0u64);
let _c = chan.lock();
let _l = leaf.lock(); // Channel -> Leaf: forbidden
}
#[cfg(debug_assertions)]
#[test]
#[should_panic(expected = "lock order violated")]
fn two_leaves_are_rejected() {
let a = RawMutex::new(0u64);
let b = RawMutex::new(0u64);
let _ga = a.lock();
let _gb = b.lock(); // leaves are mutual: forbidden
}
#[cfg(debug_assertions)]
#[test]
#[should_panic(expected = "lock order violated")]
fn two_channel_locks_are_rejected() {
let a = RawMutex::new_channel(0u64);
let b = RawMutex::new_channel(0u64);
let _ga = a.lock();
let _gb = b.lock(); // channel locks are mutual leaves: forbidden
}
}
src/registry.rs
-570
View File
@@ -1,570 +0,0 @@
//! Named mailbox registry — resolve a name (or pid) to a *messageable* actor.
//!
//! ## What changed (RFC 014)
//!
//! The old registry was a `name <-> pid` bimap: `whereis` handed back a `Pid`
//! you could not send to, because a pid is just `(index, generation)` with no
//! delivery endpoint. This rework makes resolution yield something messageable.
//!
//! Two facts shape the structure:
//!
//! 1. **A name resolves to a single actor.** Many actors under one label is
//! what *process groups* (`pg`) are for; the registry is one-name-one-actor
//! (several names *may* point at the same actor).
//! 2. **Channels are typed**, so an actor has no single untyped mailbox. An
//! actor instead owns a *set* of typed channels — one [`Sender`] per message
//! type it accepts. So the registry maps name/pid to a [`Mailbox`]: a small
//! structure holding that actor's pid plus all of its typed channels, keyed
//! by message [`TypeId`].
//!
//! Resolution is therefore: `name -> pid` (single actor) `-> Mailbox -> the
//! channel for message type M`. A `Name<Cmd>` and a `Name<Admin>` on the *same*
//! actor select *different* channels purely by their type parameter, so
//! capability separation (RFC 014 §4.7) needs no extra machinery.
//!
//! ## Type erasure is contained
//!
//! Each stored channel is a `Box<dyn Any + Send>` that is concretely a
//! `Sender<M>`, filed under `TypeId::of::<M>()`. A resolve for `M` looks up
//! that exact `TypeId` and downcasts to `Sender<M>` — keyed by the very type we
//! downcast to, so the downcast cannot fail on correct data; a failure is a
//! smarm bug, asserted in debug. The phantom `M` on [`Name`] re-imposes the
//! type at the call site, so callers never touch the erasure.
//!
//! ## Cleanup is lazy (prune-on-contact)
//!
//! As before, there is no `finalize` hook and no name field on the slot. Every
//! operation that touches a binding checks the target pid's liveness via the
//! generation-checked slot word; a binding to a dead actor behaves as absent
//! and is pruned on contact (its [`Mailbox`] and every name pointing at it are
//! dropped). The cost is a dead binding lingering until something looks at it;
//! the payoff is zero coupling to the actor lifecycle.
//!
//! ## Locking
//!
//! One `RawMutex` (Leaf class) in `RuntimeInner`, exactly like the old
//! registry. The fold (name index *and* handles under the one lock) is what
//! keeps a name-addressed `send` on a single Leaf — `raw_mutex` panics on a
//! second Leaf acquired while one is held. The send path clones the `Sender`
//! **under** the Leaf lock (a `Sender::clone` takes a Channel lock, permitted
//! under a Leaf), then **releases** the Leaf and only *then* sends — a send can
//! unpark a receiver, and wakeup-bearing work runs outside the Leaf. Order is
//! **Leaf -> Channel**, as `pg`/`finalize`.
use crate::channel::Sender;
use crate::pid::{Addressable, Name, Pid};
use crate::scheduler::{self_pid, with_runtime};
use std::any::{type_name, Any, TypeId};
use std::collections::HashMap;
/// Why a [`register`] call was rejected.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RegisterError {
/// The name is bound to a different, still-live actor.
NameTaken { holder: Pid },
/// The caller is not a live actor (cannot happen for `self`, kept for
/// symmetry / future explicit-pid registration).
NoProc,
}
impl std::fmt::Display for RegisterError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
RegisterError::NameTaken { holder } => {
write!(f, "name is already registered to live actor {holder}")
}
RegisterError::NoProc => write!(f, "caller is not a live actor"),
}
}
}
impl std::error::Error for RegisterError {}
/// Why a name-addressed [`send`] did not deliver. Carries the message back so
/// the caller never loses it (mirrors [`crate::channel::SendError`]).
///
/// `Debug`/`Display` are hand-written so neither demands `M: Debug` — the
/// payload is returned, not printed.
pub enum SendError<M> {
/// No live actor is currently registered under this name. Name-addressed
/// [`send`] only; the pid-addressed counterpart is [`SendError::Dead`].
Unresolved(M),
/// The pid-addressed actor is no longer the live incarnation this pid names
/// — it has died, even if its slot now holds a *different* actor (a direct
/// `Pid<A>` send never redirects; contrast name-addressed [`send`]). Pid
/// paths ([`send_to`] / [`send_dyn`]) only.
Dead(M),
/// The actor is live but exposes no channel for this message type.
NoChannel(M),
/// The actor's channel for this message type is closed (its receiver is gone).
Closed(M),
/// No live member to deliver to — a [`dispatch`](crate::dispatch) over an
/// empty (or all-dead) process group. Group-addressed dispatch only; the
/// name-addressed counterpart is [`SendError::Unresolved`]. The message is
/// handed back undelivered.
NoMember(M),
}
impl<M> SendError<M> {
/// Recover the undelivered message.
pub fn into_inner(self) -> M {
match self {
SendError::Unresolved(m)
| SendError::Dead(m)
| SendError::NoChannel(m)
| SendError::Closed(m)
| SendError::NoMember(m) => m,
}
}
fn variant(&self) -> &'static str {
match self {
SendError::Unresolved(_) => "Unresolved",
SendError::Dead(_) => "Dead",
SendError::NoChannel(_) => "NoChannel",
SendError::Closed(_) => "Closed",
SendError::NoMember(_) => "NoMember",
}
}
}
impl<M> std::fmt::Debug for SendError<M> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "SendError::{}", self.variant())
}
}
impl<M> std::fmt::Display for SendError<M> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
SendError::Unresolved(_) => write!(f, "no live actor registered under that name"),
SendError::Dead(_) => write!(f, "the addressed actor is no longer the live incarnation"),
SendError::NoChannel(_) => write!(f, "actor has no channel for this message type"),
SendError::Closed(_) => write!(f, "the actor's channel for this type is closed"),
SendError::NoMember(_) => write!(f, "no live member in the process group"),
}
}
}
impl<M> std::error::Error for SendError<M> {}
/// A registry-stored channel, type-erased over its message type. The stored
/// object must serve two readers: `clone_sender` (downcast back to the concrete
/// `Sender<M>`) and the RFC 016 snapshot (queued length without knowing `M`).
/// A bare `Box<dyn Any>` gives the first but not the second, so we erase behind
/// this small trait instead.
trait ErasedSender: Send {
fn as_any(&self) -> &dyn Any;
fn queued_len(&self) -> usize;
}
impl<M: Send + 'static> ErasedSender for Sender<M> {
fn as_any(&self) -> &dyn Any {
self
}
fn queued_len(&self) -> usize {
Sender::queued_len(self)
}
}
/// One typed channel of an actor, type-erased. Concretely a `Sender<M>` filed
/// under `TypeId::of::<M>()`; `msg_type` is `type_name::<M>()`, kept for
/// observers (RFC 014 §4.5) and as the debug cross-check on the downcast.
struct Channel {
sender: Box<dyn ErasedSender>,
msg_type: &'static str,
}
/// An actor's messageable surface: its identity plus every typed channel it has
/// published, keyed by message [`TypeId`]. Stored once per live actor; reached
/// by pid (directly) or by any name pointing at that pid.
struct Mailbox {
pid: Pid,
channels: HashMap<TypeId, Channel>,
}
impl Mailbox {
fn new(pid: Pid) -> Self {
Self { pid, channels: HashMap::new() }
}
/// Clone the `Sender<M>` for this actor, if it has one. Called **under the
/// registry Leaf lock**: `Sender::clone` takes a Channel lock, which is
/// legal under a Leaf (Leaf -> Channel).
fn clone_sender<M: Send + 'static>(&self) -> Option<Sender<M>> {
let ch = self.channels.get(&TypeId::of::<M>())?;
let tx = match ch.sender.as_any().downcast_ref::<Sender<M>>() {
Some(tx) => tx,
None => panic!(
"smarm: channel keyed by TypeId but downcast to its own type failed (core corrupt)"
),
};
debug_assert_eq!(ch.msg_type, type_name::<M>(), "msg_type / TypeId disagree");
Some(tx.clone())
}
}
/// Per-actor registry view handed to RFC 016 introspection: registered names
/// and summed mailbox depth, tagged with the mailbox's `pid` so a stale
/// incarnation can be filtered against the slab. Covers only *published*
/// channels (`register` / `install` / `spawn_addr` / gen_server start); an
/// actor that holds only a private `channel()` receiver is invisible here and
/// reports depth 0.
pub(crate) struct MailboxInfo {
pub(crate) pid: Pid,
pub(crate) names: Vec<&'static str>,
pub(crate) depth: u32,
}
/// The directory. Invariant (held under the registry lock): every value in
/// `by_name` is the index of a [`Mailbox`] present in `by_index`, and that
/// mailbox's `pid.index()` equals the key. Stale entries (dead actors) violate
/// nothing — they are simply pruned on contact.
pub(crate) struct Registry {
/// `pid.index() -> the actor's mailbox`. The handle store.
by_index: HashMap<u32, Mailbox>,
/// `name -> pid.index()`. Several names may map to one actor.
by_name: HashMap<&'static str, u32>,
}
impl Registry {
pub(crate) fn new() -> Self {
Self { by_index: HashMap::new(), by_name: HashMap::new() }
}
/// Drop a dead actor's mailbox and every name that pointed at it.
fn prune(&mut self, index: u32) {
self.by_index.remove(&index);
self.by_name.retain(|_, idx| *idx != index);
}
/// RFC 016 snapshot input: per-slot-index registry view — the actor's
/// registered names (inverted from `by_name`) and its mailbox depth (queued
/// messages summed across every published typed channel). Built in one pass
/// under the registry Leaf; the per-channel `queued_len` takes a Channel
/// lock, legal under the Leaf (Leaf → Channel). Carries each mailbox's full
/// `pid` so the caller can discard a stale incarnation's entry against the
/// slab's live generation. Names that dangle (point at no mailbox) are
/// dropped — they violate no invariant and get pruned on next contact.
pub(crate) fn introspect_map(&self) -> HashMap<u32, MailboxInfo> {
let mut names: HashMap<u32, Vec<&'static str>> = HashMap::new();
for (&name, &idx) in &self.by_name {
names.entry(idx).or_default().push(name);
}
let mut out: HashMap<u32, MailboxInfo> = HashMap::with_capacity(self.by_index.len());
for (&idx, mb) in &self.by_index {
let depth: usize = mb.channels.values().map(|c| c.sender.queued_len()).sum();
out.insert(
idx,
MailboxInfo {
pid: mb.pid,
names: names.remove(&idx).unwrap_or_default(),
depth: depth.min(u32::MAX as usize) as u32,
},
);
}
out
}
/// Single-actor form of [`introspect_map`](Self::introspect_map): the
/// registry view for one slot index, or `None` if no mailbox is published
/// there. Used by `actor_info` so its cost stays proportional to the one
/// actor rather than locking every channel in the runtime.
pub(crate) fn introspect_one(&self, idx: u32) -> Option<MailboxInfo> {
let mb = self.by_index.get(&idx)?;
let depth: usize = mb.channels.values().map(|c| c.sender.queued_len()).sum();
let names = self
.by_name
.iter()
.filter_map(|(&n, &i)| (i == idx).then_some(n))
.collect();
Some(MailboxInfo { pid: mb.pid, names, depth: depth.min(u32::MAX as usize) as u32 })
}
}
/// Is `pid` a live actor right now? Atomic slot-word read; no lock.
fn live(inner: &crate::runtime::RuntimeInner, pid: Pid) -> bool {
inner.slot_at(pid).is_some_and(|s| s.is_live_for(pid))
}
/// Publish the current actor's `Sender<M>` under `name`, capturing the channel
/// so the name becomes messageable. Idempotent for the same `(name, type)`;
/// registering a *second* type under the same (or another) name on the same
/// actor just adds another channel to the actor's mailbox.
///
/// Fails with [`RegisterError::NameTaken`] if the name is held by a *different*
/// live actor (a binding to a dead actor is pruned and the name treated as
/// free). Panics if called outside `Runtime::run()`.
pub fn register<M: Send + 'static>(name: Name<M>, tx: Sender<M>) -> Result<(), RegisterError> {
register_with(self_pid(), name.as_str(), tx)
}
/// Bind `name` to `pid`'s mailbox and publish `tx` under `M`'s [`TypeId`], for
/// an explicit (already-live) actor rather than `self`. The shared core of
/// [`register`] (which passes `self_pid()`) and the parent-side server-name
/// bind in `gen_server` (which names a freshly spawned server before its body
/// has run, so the name resolves the instant `start()` returns). Same collision
/// rules and lock discipline as `register`.
pub(crate) fn register_with<M: Send + 'static>(
me: Pid,
key: &'static str,
tx: Sender<M>,
) -> Result<(), RegisterError> {
with_runtime(|inner| {
let mut reg = inner.registry.lock();
if !live(inner, me) {
return Err(RegisterError::NoProc);
}
if let Some(&holder_idx) = reg.by_name.get(key) {
match reg.by_index.get(&holder_idx).map(|m| m.pid) {
Some(holder) if holder == me => {} // same actor: just add the channel below
Some(holder) if live(inner, holder) => {
return Err(RegisterError::NameTaken { holder });
}
Some(_) => reg.prune(holder_idx), // dead holder: free the name
None => {
reg.by_name.remove(key); // dangling name: free it
}
}
}
// Publish (or extend) the mailbox with this channel, then bind the name.
publish_channel::<M>(&mut reg, me, tx);
reg.by_name.insert(key, me.index());
Ok(())
})
}
/// Insert or extend the current actor's mailbox with one typed channel, filed
/// under its message [`TypeId`]. Shared by [`register`] (which then binds a
/// name) and [`install`] (which does not). A leftover mailbox at this slot
/// index from a dead prior incarnation (pid mismatch) is replaced wholesale.
/// Caller holds the registry lock and has established that `me` is live.
fn publish_channel<M: Send + 'static>(reg: &mut Registry, me: Pid, tx: Sender<M>) {
let mb = reg.by_index.entry(me.index()).or_insert_with(|| Mailbox::new(me));
if mb.pid != me {
*mb = Mailbox::new(me);
}
mb.channels.insert(
TypeId::of::<M>(),
Channel { sender: Box::new(tx), msg_type: type_name::<M>() },
);
}
/// Publish the current actor's `Sender<A::Msg>` into its mailbox **without**
/// binding a name, and hand back the typed [`Pid<A>`] that addresses this
/// actor directly. This is the opt-in, lazy install of RFC 014 §5: an actor
/// that wants to be reachable by a direct, identity-bound [`Pid<A>`] (rather
/// than only via a re-resolving [`Name`]) calls this once with its inbox
/// sender, then hands the returned pid out.
///
/// Unlike [`register`] there is no name to collide on, and `self` is always a
/// live actor inside `run()`, so this is infallible. Panics if called outside
/// `Runtime::run()`.
pub fn install<A: Addressable>(tx: Sender<A::Msg>) -> Pid<A> {
let me = self_pid();
with_runtime(|inner| {
let mut reg = inner.registry.lock();
debug_assert!(live(inner, me), "self_pid() is a live actor inside run()");
publish_channel::<A::Msg>(&mut reg, me, tx);
});
// `me` is this actor; re-type the identity as `Pid<A>` (the channel for
// `A::Msg` was just published, so the typed address is now messageable).
Pid::from_raw(me.raw())
}
/// Publish `tx` into `pid`'s mailbox under `M`'s [`TypeId`], for an explicit
/// (freshly minted, already-live) actor rather than `self`. The parent-side
/// half of [`spawn_addr`](crate::spawn_addr): the spawner makes the inbox and
/// publishes the sender here *before* handing back the `Pid<A>`, so an immediate
/// `send_to` on the returned pid always resolves — the address is live the
/// instant the caller holds it, with no dependence on the body having run yet.
///
/// Caller guarantees `pid` is the just-installed actor (Queued, this exact
/// incarnation); `publish_channel` replaces any stale leftover at the slot.
pub(crate) fn install_for<M: Send + 'static>(pid: Pid, tx: Sender<M>) {
with_runtime(|inner| {
let mut reg = inner.registry.lock();
debug_assert!(live(inner, pid), "install_for: pid must be a freshly spawned, live actor");
publish_channel::<M>(&mut reg, pid, tx);
});
}
/// The single actor currently registered under `name`, or `None` if unbound or
/// no longer live (the stale binding is pruned on the way out).
pub fn whereis(name: &str) -> Option<Pid> {
with_runtime(|inner| {
let mut reg = inner.registry.lock();
let idx = *reg.by_name.get(name)?;
match reg.by_index.get(&idx).map(|m| m.pid) {
Some(pid) if live(inner, pid) => Some(pid),
Some(_) => {
reg.prune(idx);
None
}
None => {
reg.by_name.remove(name);
None
}
}
})
}
/// Resolve `name` to a *typed* [`Pid<A>`] — the identity-bound counterpart of
/// [`whereis`] (RFC 014 §4.4). Recovers the compile-checked
/// [`send_to`] path from a durable name: looks the name up,
/// then re-types the erased pid as `Pid<A>` via the unchecked
/// [`assert_type`](crate::pid::assert_type) primitive. A wrong `A` is not
/// unsound — it degrades to [`SendError::NoChannel`] on the next send (routing
/// is by message `TypeId`), never a misdelivery. `None` if unbound or dead.
///
/// Panics if called outside `Runtime::run()`.
pub fn lookup_as<A: Addressable>(name: &str) -> Option<Pid<A>> {
whereis(name).map(crate::pid::assert_type::<A>)
}
/// Resolve `name` to its actor's pid and a cloned `Sender<M>`, under the Leaf
/// lock (clone-under-lock, then release). The crate-internal building block for
/// `gen_server`'s by-name addressing: a named server publishes its inbox as a
/// `Sender<Envelope<G>>` (via [`register_with`]), and `whereis_server` / `call`
/// / `cast` recover that exact typed sender here to rebuild a `GenServerRef<G>`.
/// `None` if unbound, dead (pruned on the way out), or holding no `M` channel.
pub(crate) fn resolve_named_sender<M: Send + 'static>(name: &str) -> Option<(Pid, Sender<M>)> {
with_runtime(|inner| {
let mut reg = inner.registry.lock();
let idx = *reg.by_name.get(name)?;
let pid = match reg.by_index.get(&idx).map(|m| m.pid) {
Some(pid) if live(inner, pid) => pid,
Some(_) => {
reg.prune(idx);
return None;
}
None => {
reg.by_name.remove(name);
return None;
}
};
let tx = reg.by_index.get(&idx).and_then(Mailbox::clone_sender::<M>)?;
Some((pid, tx))
})
}
/// Remove the binding for `name`, returning the actor it pointed at if still
/// live. Only the *name* is freed; the actor's mailbox (and any other names for
/// it) remain. A binding to a dead actor is reported as `None`.
pub fn unregister(name: &str) -> Option<Pid> {
with_runtime(|inner| {
let mut reg = inner.registry.lock();
let idx = reg.by_name.remove(name)?;
match reg.by_index.get(&idx).map(|m| m.pid) {
Some(pid) if live(inner, pid) => Some(pid),
_ => None,
}
})
}
/// Resolve `name` to its actor's `Sender<M>` and deliver `msg`. The whole point
/// of the rework: a name you can *send* to.
///
/// Errors (message returned in every case): [`SendError::Unresolved`] if no
/// live actor holds the name, [`SendError::NoChannel`] if that actor has no
/// channel for `M`, [`SendError::Closed`] if its `M` channel's receiver is
/// gone. Panics if called outside `Runtime::run()`.
pub fn send<M: Send + 'static>(name: Name<M>, msg: M) -> Result<(), SendError<M>> {
let key = name.as_str();
with_runtime(|inner| {
// Resolve + clone the sender under the Leaf lock, then drop the lock
// before sending (a send can unpark a receiver).
let tx = {
let mut reg = inner.registry.lock();
let idx = match reg.by_name.get(key) {
Some(&i) => i,
None => return Err(SendError::Unresolved(msg)),
};
let pid = match reg.by_index.get(&idx).map(|m| m.pid) {
Some(pid) => pid,
None => {
reg.by_name.remove(key);
return Err(SendError::Unresolved(msg));
}
};
if !live(inner, pid) {
reg.prune(idx);
return Err(SendError::Unresolved(msg));
}
match reg.by_index.get(&idx).and_then(Mailbox::clone_sender::<M>) {
Some(tx) => tx,
None => return Err(SendError::NoChannel(msg)),
}
};
tx.send(msg).map_err(|crate::channel::SendError(m)| SendError::Closed(m))
})
}
/// Resolve a *raw* pid to its mailbox and deliver `msg` on the channel for `M`,
/// with **no redirect**. The stored mailbox must be this exact incarnation
/// (generation included) and still live; otherwise the actor this pid named is
/// gone and the result is [`SendError::Dead`] — even when the slot now holds a
/// different, live actor (which we leave untouched). Shared by [`send_to`]
/// (typed, `M = A::Msg`, channel guaranteed on an installed actor) and
/// [`send_dyn`] (explicit `M`, where `NoChannel` is a real outcome).
fn send_to_pid<M: Send + 'static>(
inner: &crate::runtime::RuntimeInner,
pid: Pid,
msg: M,
) -> Result<(), SendError<M>> {
// Resolve + clone the sender under the Leaf lock, then drop the lock before
// sending (a send can unpark a receiver) — Leaf -> Channel, as name `send`.
let tx = {
let mut reg = inner.registry.lock();
match reg.by_index.get(&pid.index()).map(|m| m.pid) {
// Exact incarnation, still alive: its `M` channel, or NoChannel.
Some(stored) if stored == pid && live(inner, pid) => {
match reg.by_index.get(&pid.index()).and_then(Mailbox::clone_sender::<M>) {
Some(tx) => tx,
None => return Err(SendError::NoChannel(msg)),
}
}
// Our incarnation's mailbox, but the actor has died: prune + Dead.
Some(stored) if stored == pid => {
reg.prune(pid.index());
return Err(SendError::Dead(msg));
}
// A different incarnation (or nothing) occupies the slot: the actor
// this pid named is gone. Do not disturb any newer occupant.
_ => return Err(SendError::Dead(msg)),
}
};
tx.send(msg).map_err(|crate::channel::SendError(m)| SendError::Closed(m))
}
/// Deliver `msg` to the exact actor named by `pid` — RFC 014 §4.2's direct,
/// identity-bound addressing mode. Unlike name-addressed [`send`] there is **no
/// redirect**: if that incarnation has died the message comes back as
/// [`SendError::Dead`], even if its slot now holds a different actor.
///
/// The message type is the actor's `A::Msg`, so on a live actor that has
/// installed its inbox (via [`install`] or [`register`]) the channel is always
/// present; [`SendError::NoChannel`] therefore means the actor is live but
/// never published a `Pid<A>`-reachable inbox. Panics if called outside
/// `Runtime::run()`.
pub fn send_to<A: Addressable>(pid: Pid<A>, msg: A::Msg) -> Result<(), SendError<A::Msg>> {
with_runtime(|inner| send_to_pid::<A::Msg>(inner, pid.erase(), msg))
}
/// The explicit bare-pid escape hatch (RFC 014 §4.6): deliver `msg` of type `M`
/// to `pid` when all you hold is an untyped [`Pid`] — a pid off a [`Down`], or
/// out of a future `members()` — so the typed [`send_to`] is unavailable.
///
/// This is the one send whose message type can genuinely be wrong: the actor
/// may be live yet expose no channel for `M`, returning [`SendError::NoChannel`]
/// (on the typed paths that downcast collapses to a `debug_assert`). It is
/// named and documented as the fallible fallback so the typed `Pid<A>` /
/// `Name<M>` paths stay the obvious default and an agentic caller reaches for a
/// present primitive instead of inventing a workaround. Liveness is identical
/// to [`send_to`]: identity-bound, no redirect, [`SendError::Dead`] once the
/// addressed incarnation is gone. Panics if called outside `Runtime::run()`.
///
/// [`Down`]: crate::Down
pub fn send_dyn<M: Send + 'static>(pid: Pid, msg: M) -> Result<(), SendError<M>> {
with_runtime(|inner| send_to_pid::<M>(inner, pid, msg))
}
src/run_queue.rs
-586
View File
@@ -1,586 +0,0 @@
//! The run queue, selected at COMPILE TIME by mutually-exclusive cargo
//! features (no runtime dispatch — the scheduler's pop loop is the hottest
//! code in the runtime):
//!
//! - `rq-mutex` (default) — `Mutex<VecDeque>`. The control/baseline:
//! strictly FIFO, trivially correct, one global lock.
//! - `rq-mpmc` — a single hand-rolled Vyukov bounded MPMC ring (per-cell
//! sequence numbers). Strict FIFO, lock-free, one hot
//! enqueue/dequeue cache-line pair.
//! - `rq-striped` — M Vyukov rings with fetch-add ticket distribution.
//! *Relaxed* FIFO: ordering across stripes is bounded-skewed
//! (≈ one ring's worth of reordering per stripe), in exchange
//! for spreading the hot line M ways. Predicted winner at
//! high core counts; phase 4's shootout decides.
//!
//! Select non-default variants with `--no-default-features --features rq-…`
//! (cargo features are additive, so the default must be switched off).
//!
//! All variants are compiled unconditionally (so every build runs every
//! variant's unit tests); the feature only picks which one the runtime uses
//! via the [`RunQueue`] alias.
//!
//! # Contract (shared by all variants)
//!
//! - **Occupancy is bounded by `max_actors`.** A pid is in the queue at most
//! once (pushes pair 1:1 with transitions into `Queued`; only the
//! scheduler transitions `Queued → Running` — see the state-machine docs
//! in `runtime.rs`), and at most `max_actors` actors exist. With the RFC
//! 005 wake slot enabled the invariant reads "in (slot ⊕ shared queue) at
//! most once" — a slot push *replaces* the queue push at the same
//! protocol point, and a displacement moves the occupant, never copies
//! it — so the bound holds verbatim. The bounded rings are sized ≥
//! `max_actors`, so **`push` is infallible**; a full
//! ring is an invariant violation and panics loudly rather than spinning.
//! - **Preemption must be disabled around every push/pop** (debug-asserted).
//! For the mutex variant this is the usual no-switch/no-unwind-under-lock
//! rule. For the rings it is *load-bearing in a sharper way*: a producer
//! suspended between claiming a cell and publishing its sequence number
//! stalls every consumer behind that cell — on a busy runtime that is a
//! livelock, since the suspended actor's own resume entry sits behind the
//! hole. Callers get this for free: every queue op happens inside
//! `with_runtime`/`try_with_runtime` (NoPreempt for their span since
//! phase 2) or on a scheduler thread between resumes (preemption off).
//! - **`pop() == None` is a snapshot, not a fence.** A push that is mid-
//! publish (or in a stripe the probe already passed) may be missed; the
//! caller's idle path sleeps ≤ 100µs and retries, so the cost is a bounded
//! latency blip, never a lost entry. Termination does not lean on this:
//! the all-clear is `live_actors == 0` (+ io quiescent), and `live == 0`
//! already implies the queue holds nothing actionable — see the argument
//! in `schedule_loop`.
//! - `len()` is approximate (stats only).
use crate::pid::Pid;
use crate::sync_shim::{AtomicUsize, Ordering, UnsafeCell};
use std::mem::MaybeUninit;
// ---------------------------------------------------------------------------
// Feature selection
// ---------------------------------------------------------------------------
#[cfg(not(any(feature = "rq-mutex", feature = "rq-mpmc", feature = "rq-striped")))]
compile_error!(
"smarm: no run queue selected. Enable exactly one of the features \
`rq-mutex` (default), `rq-mpmc`, `rq-striped`."
);
#[cfg(all(feature = "rq-mutex", feature = "rq-mpmc"))]
compile_error!(
"smarm: features `rq-mutex` and `rq-mpmc` are mutually exclusive \
(use --no-default-features to drop the default `rq-mutex`)."
);
#[cfg(all(feature = "rq-mutex", feature = "rq-striped"))]
compile_error!(
"smarm: features `rq-mutex` and `rq-striped` are mutually exclusive \
(use --no-default-features to drop the default `rq-mutex`)."
);
#[cfg(all(feature = "rq-mpmc", feature = "rq-striped"))]
compile_error!("smarm: features `rq-mpmc` and `rq-striped` are mutually exclusive.");
#[cfg(feature = "rq-mutex")]
pub(crate) type RunQueue = MutexQueue;
#[cfg(feature = "rq-mpmc")]
pub(crate) type RunQueue = MpmcRing;
#[cfg(feature = "rq-striped")]
pub(crate) type RunQueue = StripedRing;
#[inline]
fn assert_no_preempt() {
debug_assert!(
!crate::preempt::PREEMPTION_ENABLED.with(|c| c.get()),
"run-queue op with preemption enabled — a switch mid-op stalls or \
corrupts the queue; route through with_runtime or scheduler context"
);
}
// ---------------------------------------------------------------------------
// rq-mutex — the baseline
// ---------------------------------------------------------------------------
#[allow(dead_code)]
pub struct MutexQueue {
q: std::sync::Mutex<std::collections::VecDeque<Pid>>,
}
#[allow(dead_code)]
impl MutexQueue {
pub fn new(_threads: usize, max_actors: usize) -> Self {
Self {
// Pre-size: the queue can never outgrow the slab, and one
// allocation at init beats reallocating under the lock later.
q: std::sync::Mutex::new(std::collections::VecDeque::with_capacity(max_actors)),
}
}
pub fn push(&self, pid: Pid) {
assert_no_preempt();
match self.q.lock() {
Ok(mut g) => g.push_back(pid),
Err(e) => panic!("smarm: run-queue q lock poisoned (core corrupt): {e}"),
}
}
pub fn pop(&self) -> Option<Pid> {
assert_no_preempt();
match self.q.lock() {
Ok(mut g) => g.pop_front(),
Err(e) => panic!("smarm: run-queue q lock poisoned (core corrupt): {e}"),
}
}
pub fn len(&self) -> u64 {
match self.q.lock() {
Ok(g) => g.len() as u64,
Err(e) => panic!("smarm: run-queue q lock poisoned (core corrupt): {e}"),
}
}
pub fn is_empty(&self) -> bool {
match self.q.lock() {
Ok(g) => g.is_empty(),
Err(e) => panic!("smarm: run-queue q lock poisoned (core corrupt): {e}"),
}
}
}
// ---------------------------------------------------------------------------
// rq-mpmc — Vyukov bounded MPMC ring
// ---------------------------------------------------------------------------
//
// Dmitry Vyukov's bounded MPMC queue: each cell carries a sequence number.
// A producer may write cell `i` when `seq == pos` (its turn); it publishes
// with `seq = pos + 1`. A consumer may read when `seq == pos + 1`; it
// releases the cell to the next lap with `seq = pos + capacity`. Producers
// and consumers each contend on one counter; cell handoff is a per-cell
// Acquire/Release pair, so unrelated push/pop pairs don't serialize.
/// Pad to a cache-line pair so the producer and consumer counters (and the
/// cells) don't false-share.
#[repr(align(128))]
struct CachePadded<T>(T);
struct Cell {
seq: AtomicUsize,
pid: UnsafeCell<MaybeUninit<Pid>>,
}
#[allow(dead_code)]
pub struct MpmcRing {
buf: Box<[Cell]>,
mask: usize,
enqueue_pos: CachePadded<AtomicUsize>,
dequeue_pos: CachePadded<AtomicUsize>,
}
// SAFETY: cells are handed off between threads via the per-cell seq
// (Release on publish, Acquire on claim); Pid is Copy + Send.
unsafe impl Send for MpmcRing {}
unsafe impl Sync for MpmcRing {}
#[allow(dead_code)]
impl MpmcRing {
pub fn new(_threads: usize, max_actors: usize) -> Self {
Self::with_capacity(max_actors)
}
/// Pub for the raw-structure microbench (sized to the op count so the
/// occupancy contract is trivially met there). Runtime code uses `new`.
pub fn with_capacity(min_cap: usize) -> Self {
// Occupancy ≤ max_actors (queue contract), so capacity = the next
// power of two ≥ max_actors can never overflow. (≥ 2 so mask works.)
let cap = min_cap.next_power_of_two().max(2);
let buf: Box<[Cell]> = (0..cap)
.map(|i| Cell {
seq: AtomicUsize::new(i),
pid: UnsafeCell::new(MaybeUninit::uninit()),
})
.collect();
Self {
buf,
mask: cap - 1,
enqueue_pos: CachePadded(AtomicUsize::new(0)),
dequeue_pos: CachePadded(AtomicUsize::new(0)),
}
}
pub fn push(&self, pid: Pid) {
assert_no_preempt();
assert!(
self.try_push(pid),
"smarm: run queue overflow — occupancy exceeded the slab bound, \
which the at-most-once-enqueued invariant forbids. This is a \
runtime bug (double enqueue), not a capacity tuning problem."
);
}
/// One full claim attempt; `false` only if the ring is full.
fn try_push(&self, pid: Pid) -> bool {
let mut pos = self.enqueue_pos.0.load(Ordering::Relaxed);
loop {
let cell = &self.buf[pos & self.mask];
let seq = cell.seq.load(Ordering::Acquire);
let diff = seq as isize - pos as isize;
if diff == 0 {
// Our turn: claim the position.
match self.enqueue_pos.0.compare_exchange_weak(
pos, pos + 1, Ordering::Relaxed, Ordering::Relaxed,
) {
Ok(_) => {
// SAFETY: the claim gives us exclusive write access
// to this cell until we publish below.
cell.pid.with_mut(|p| unsafe { (*p).write(pid) });
cell.seq.store(pos + 1, Ordering::Release);
return true;
}
Err(actual) => pos = actual,
}
} else if diff < 0 {
return false; // full — a whole lap behind
} else {
pos = self.enqueue_pos.0.load(Ordering::Relaxed);
}
}
}
pub fn pop(&self) -> Option<Pid> {
assert_no_preempt();
let mut pos = self.dequeue_pos.0.load(Ordering::Relaxed);
loop {
let cell = &self.buf[pos & self.mask];
let seq = cell.seq.load(Ordering::Acquire);
let diff = seq as isize - (pos + 1) as isize;
if diff == 0 {
match self.dequeue_pos.0.compare_exchange_weak(
pos, pos + 1, Ordering::Relaxed, Ordering::Relaxed,
) {
Ok(_) => {
// SAFETY: the claim gives us exclusive read access;
// the producer's Release publish made `pid` visible
// to our Acquire load of `seq`.
let pid = cell.pid.with(|p| unsafe { (*p).assume_init_read() });
// Release the cell for the next lap.
cell.seq.store(pos + self.mask + 1, Ordering::Release);
return Some(pid);
}
Err(actual) => pos = actual,
}
} else if diff < 0 {
// Empty (or the producer at this cell hasn't published yet —
// a snapshot miss the caller's idle-retry loop absorbs).
return None;
} else {
pos = self.dequeue_pos.0.load(Ordering::Relaxed);
}
}
}
pub fn len(&self) -> u64 {
let e = self.enqueue_pos.0.load(Ordering::Relaxed);
let d = self.dequeue_pos.0.load(Ordering::Relaxed);
e.saturating_sub(d) as u64
}
pub fn is_empty(&self) -> bool {
self.len() == 0
}
}
// ---------------------------------------------------------------------------
// rq-striped — M Vyukov rings, ticket-distributed
// ---------------------------------------------------------------------------
//
// Producers fetch-add a ticket and start probing at stripe `ticket % M`;
// consumers do the same with their own ticket. Under symmetric load the
// tickets spread producers and consumers uniformly, so each stripe sees
// ~1/M of the traffic and the single hot cache-line pair becomes M cooler
// ones. FIFO is relaxed: two pushes that land in different stripes can be
// popped in either order, with skew bounded by stripe occupancy imbalance.
//
// Push probes forward from its home stripe until a `try_push` succeeds.
// Σ stripe capacity ≥ 2 × max_actors while occupancy ≤ max_actors, so at
// every instant at least half the total capacity is free and the probe
// terminates (in practice on the first stripe).
#[allow(dead_code)]
pub struct StripedRing {
stripes: Box<[MpmcRing]>,
/// Stripe count minus one (count is a power of two).
stripe_mask: usize,
push_ticket: CachePadded<AtomicUsize>,
pop_ticket: CachePadded<AtomicUsize>,
}
#[allow(dead_code)]
impl StripedRing {
pub fn new(threads: usize, max_actors: usize) -> Self {
// One stripe per scheduler thread, rounded up to a power of two —
// more stripes than threads buys nothing (at most `threads` ops are
// in flight) and costs pop-probe latency when mostly empty.
let n = threads.max(1).next_power_of_two();
// Per-stripe capacity: 2 × max_actors / n in total, and never below
// a floor that keeps degenerate configs (tiny slab, many threads)
// trivially correct.
let per = ((2 * max_actors) / n).next_power_of_two().max(8);
let stripes: Box<[MpmcRing]> = (0..n).map(|_| MpmcRing::with_capacity(per)).collect();
Self {
stripes,
stripe_mask: n - 1,
push_ticket: CachePadded(AtomicUsize::new(0)),
pop_ticket: CachePadded(AtomicUsize::new(0)),
}
}
pub fn push(&self, pid: Pid) {
assert_no_preempt();
let home = self.push_ticket.0.fetch_add(1, Ordering::Relaxed);
// Probe from the home stripe; capacity headroom (Σ ≥ 2×occupancy)
// guarantees a free stripe exists, so the outer loop terminates.
// The retry-from-home lap handles the racy case where every stripe
// momentarily refused us.
loop {
for i in 0..=self.stripe_mask {
let s = &self.stripes[(home + i) & self.stripe_mask];
if s.try_push(pid) {
return;
}
}
std::hint::spin_loop();
}
}
pub fn pop(&self) -> Option<Pid> {
assert_no_preempt();
let home = self.pop_ticket.0.fetch_add(1, Ordering::Relaxed);
for i in 0..=self.stripe_mask {
if let Some(pid) = self.stripes[(home + i) & self.stripe_mask].pop() {
return Some(pid);
}
}
None // snapshot miss possible across stripes; idle-retry absorbs it
}
pub fn len(&self) -> u64 {
self.stripes.iter().map(|s| s.len()).sum()
}
pub fn is_empty(&self) -> bool {
self.stripes.iter().all(|s| s.is_empty())
}
}
// ---------------------------------------------------------------------------
// Tests — all variants, in every build (the feature only picks the alias)
// ---------------------------------------------------------------------------
#[cfg(all(test, not(loom)))]
mod tests {
use super::*;
use std::collections::HashSet;
use std::sync::Arc;
fn pid(i: u32) -> Pid {
Pid::new(i, 0)
}
fn fifo_smoke<Q>(q: &Q, push: impl Fn(&Q, Pid), pop: impl Fn(&Q) -> Option<Pid>) {
for i in 0..100 {
push(q, pid(i));
}
for i in 0..100 {
assert_eq!(pop(q), Some(pid(i)));
}
assert_eq!(pop(q), None);
}
#[test]
fn mutex_fifo() {
let q = MutexQueue::new(1, 1024);
fifo_smoke(&q, |q, p| q.push(p), |q| q.pop());
}
#[test]
fn mpmc_fifo_single_thread() {
let q = MpmcRing::new(1, 1024);
fifo_smoke(&q, |q, p| q.push(p), |q| q.pop());
}
#[test]
fn mpmc_wraps_many_laps() {
let q = MpmcRing::with_capacity(8);
for lap in 0..1000u32 {
for i in 0..8 {
q.push(pid(lap * 8 + i));
}
for i in 0..8 {
assert_eq!(q.pop(), Some(pid(lap * 8 + i)));
}
}
assert_eq!(q.pop(), None);
}
/// N producers, M consumers, every element exactly once. Run on plain OS
/// threads (PREEMPTION_ENABLED defaults false, satisfying the contract).
fn exactly_once<Q: Send + Sync + 'static>(
q: Q,
push: fn(&Q, Pid),
pop: fn(&Q) -> Option<Pid>,
producers: u32,
consumers: u32,
per_producer: u32,
) {
let q = Arc::new(q);
let total = (producers * per_producer) as usize;
let popped = Arc::new(std::sync::Mutex::new(Vec::with_capacity(total)));
let remaining = Arc::new(AtomicUsize::new(total));
let mut hs = Vec::new();
for p in 0..producers {
let q = q.clone();
hs.push(std::thread::spawn(move || {
for i in 0..per_producer {
push(&q, pid(p * per_producer + i));
}
}));
}
for _ in 0..consumers {
let q = q.clone();
let popped = popped.clone();
let remaining = remaining.clone();
hs.push(std::thread::spawn(move || {
let mut local = Vec::new();
while remaining.load(Ordering::Relaxed) > 0 {
if let Some(pid) = pop(&q) {
remaining.fetch_sub(1, Ordering::Relaxed);
local.push(pid);
} else {
std::hint::spin_loop();
}
}
popped.lock().unwrap().extend(local);
}));
}
for h in hs {
h.join().unwrap();
}
let popped = popped.lock().unwrap();
assert_eq!(popped.len(), total, "count mismatch");
let set: HashSet<u64> = popped.iter().map(|p| ((p.index() as u64) << 32) | p.generation() as u64).collect();
assert_eq!(set.len(), total, "duplicate or lost element");
assert_eq!(pop(&q), None);
}
#[test]
fn mpmc_exactly_once_contended() {
exactly_once(MpmcRing::new(8, 4096), |q, p| q.push(p), |q| q.pop(), 4, 4, 1000);
}
#[test]
fn striped_exactly_once_contended() {
exactly_once(StripedRing::new(8, 4096), |q, p| q.push(p), |q| q.pop(), 4, 4, 1000);
}
#[test]
fn striped_drains_after_skewed_load() {
// Hammer pushes from one thread (all tickets walk the stripes in
// order) and verify a single consumer sees every element.
let q = StripedRing::new(4, 64);
let mut seen = HashSet::new();
for i in 0..64 {
q.push(pid(i));
}
while let Some(p) = q.pop() {
assert!(seen.insert(p.index()));
}
assert_eq!(seen.len(), 64);
}
}
// ---------------------------------------------------------------------------
// loom model tests — RUSTFLAGS="--cfg loom" cargo test --lib --release
// ---------------------------------------------------------------------------
#[cfg(all(test, loom))]
mod loom_tests {
use super::*;
use loom::sync::Arc;
use loom::thread;
fn pid(i: u32) -> Pid {
Pid::new(i, 0)
}
/// Two producers, main-thread consumer: both elements arrive exactly
/// once, across every interleaving — including through a lap wraparound
/// (capacity 2 forces cell reuse).
#[test]
fn mpmc_two_producers_exactly_once() {
loom::model(|| {
let q = Arc::new(MpmcRing::with_capacity(2));
let mut hs = Vec::new();
for i in 0..2u32 {
let q = q.clone();
hs.push(thread::spawn(move || q.push(pid(i))));
}
let mut got = Vec::new();
while got.len() < 2 {
match q.pop() {
Some(p) => got.push(p.index()),
None => thread::yield_now(),
}
}
for h in hs {
h.join().unwrap();
}
got.sort_unstable();
assert_eq!(got, vec![0, 1]);
assert!(q.pop().is_none());
});
}
/// Producer races a consumer on a single element: the consumer either
/// gets it or sees a clean None — never a torn/duplicated element.
#[test]
fn mpmc_push_pop_race() {
loom::model(|| {
let q = Arc::new(MpmcRing::with_capacity(2));
let q2 = q.clone();
let prod = thread::spawn(move || q2.push(pid(7)));
let seen = q.pop();
prod.join().unwrap();
match seen {
Some(p) => {
assert_eq!(p.index(), 7);
assert!(q.pop().is_none());
}
None => assert_eq!(q.pop().map(|p| p.index()), Some(7)),
}
});
}
/// Striped: two producers landing in (potentially) different stripes,
/// main-thread consumer drains both exactly once.
#[test]
fn striped_two_producers_exactly_once() {
loom::model(|| {
let q = Arc::new(StripedRing::new(2, 4));
let mut hs = Vec::new();
for i in 0..2u32 {
let q = q.clone();
hs.push(thread::spawn(move || q.push(pid(i))));
}
let mut got = Vec::new();
while got.len() < 2 {
match q.pop() {
Some(p) => got.push(p.index()),
None => thread::yield_now(),
}
}
for h in hs {
h.join().unwrap();
}
got.sort_unstable();
assert_eq!(got, vec![0, 1]);
assert!(q.pop().is_none());
});
}
}
src/runtime.rs
+385 -1078
View File
File diff suppressed because it is too large Load Diff
src/scheduler.rs
+141 -600
View File
@@ -9,7 +9,7 @@
use crate::actor::current_pid; use crate::actor::current_pid;
use crate::channel::Sender; use crate::channel::Sender;
use crate::pid::{Name, Pid}; use crate::pid::Pid;
use crate::runtime::{ use crate::runtime::{
self, RuntimeInner, YieldIntent, RUNTIME, self, RuntimeInner, YieldIntent, RUNTIME,
}; };
@@ -21,42 +21,18 @@ use std::sync::Arc;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
/// Borrow the current runtime. Panics if called outside `Runtime::run()`. /// Borrow the current runtime. Panics if called outside `Runtime::run()`.
///
/// The whole span runs with preemption disabled. Two reasons, both load-
/// bearing:
///
/// - The `RUNTIME` thread-local borrow is live across `f`. A preemption-
/// driven context switch inside `f` can resume the actor on a DIFFERENT OS
/// thread; the borrow guard would then increment this thread's RefCell but
/// decrement the other's — a count underflow that leaves that thread's
/// RefCell permanently "mutably borrowed". Holding a thread-local guard
/// across a potential switch point is the one unforgivable sin of green
/// threads; disabling preemption makes "no switch inside `f`" structural
/// instead of an accident of which bodies happen to allocate.
/// - `f` is runtime bookkeeping. Suspending an actor halfway through it (or
/// unwinding via the stop sentinel, which shares the gate) is never wanted.
pub(crate) fn with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> R { pub(crate) fn with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> R {
let prev = crate::preempt::PREEMPTION_ENABLED.with(|c| c.replace(false)); RUNTIME.with(|r| {
let result = RUNTIME.with(|r| {
let b = r.borrow(); let b = r.borrow();
let inner = match b.as_ref() { let inner = b.as_ref().expect("smarm: not inside Runtime::run()");
Some(inner) => inner,
None => panic!("smarm: not inside Runtime::run()"),
};
f(inner) f(inner)
}); })
crate::preempt::PREEMPTION_ENABLED.with(|c| c.set(prev));
result
} }
/// Borrow the runtime if present; returns `None` otherwise. /// Borrow the runtime if present; returns `None` otherwise.
/// Used on cleanup paths (channel Drop during teardown). /// Used on cleanup paths (channel Drop during teardown).
/// Same preemption gate as [`with_runtime`]; same reasons.
pub(crate) fn try_with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> Option<R> { pub(crate) fn try_with_runtime<R>(f: impl FnOnce(&Arc<RuntimeInner>) -> R) -> Option<R> {
let prev = crate::preempt::PREEMPTION_ENABLED.with(|c| c.replace(false)); RUNTIME.with(|r| r.borrow().as_ref().map(|inner| f(inner)))
let result = RUNTIME.with(|r| r.borrow().as_ref().map(f));
crate::preempt::PREEMPTION_ENABLED.with(|c| c.set(prev));
result
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -78,42 +54,22 @@ impl JoinHandle {
pub fn join(mut self) -> Result<(), JoinError> { pub fn join(mut self) -> Result<(), JoinError> {
use crate::actor::Outcome; use crate::actor::Outcome;
use crate::runtime::State; // need State visibility
let me = match current_pid() { let me = current_pid().expect("join() called outside an actor");
Some(pid) => pid,
None => panic!("join() called outside an actor"),
};
loop { loop {
// Check-Done-or-register-waiter is atomic under the target's cold
// lock; finalize publishes Done and takes the waiter list under
// the same lock, so we either see the outcome or are woken.
let outcome = with_runtime(|inner| { let outcome = with_runtime(|inner| {
let slot = match inner.slot_at(self.pid) { inner.with_shared(|s| {
Some(slot) => slot, let slot = s.slot_mut(self.pid)
None => panic!("join: pid index out of range: {:?}", self.pid), .expect("join: target slot has been reused");
}; if matches!(slot.state, State::Done) {
let mut cold = slot.cold.lock(); Some(slot.outcome.take().expect("Done slot must have outcome"))
match slot.status_for(self.pid) { } else {
// Our outstanding handle pins the slot: it cannot be slot.waiters.push(me);
// reclaimed (generation cannot change) while we hold it.
crate::slot_state::Status::Stale => {
panic!("join: target slot has been reused")
}
crate::slot_state::Status::Done => {
Some(match cold.outcome.take() {
Some(outcome) => outcome,
None => panic!("Done slot must have outcome"),
})
}
crate::slot_state::Status::Live => {
// begin_wait is lock-free, legal under the cold lock;
// registering under it makes the epoch atomic with
// the check-Done-or-register linearization point.
cold.waiters.push((me, begin_wait()));
None None
} }
} })
}); });
match outcome { match outcome {
@@ -139,25 +95,20 @@ impl JoinHandle {
fn decrement_handle_count(&mut self) { fn decrement_handle_count(&mut self) {
with_runtime(|inner| { with_runtime(|inner| {
let should_reclaim = match inner.slot_at(self.pid) { inner.with_shared(|s| {
let should_reclaim = match s.slot_mut(self.pid) {
Some(slot) => { Some(slot) => {
let mut cold = slot.cold.lock(); slot.outstanding_handles =
match slot.status_for(self.pid) { slot.outstanding_handles.saturating_sub(1);
crate::slot_state::Status::Stale => false, matches!(slot.state, crate::runtime::State::Done)
status => { && slot.outstanding_handles == 0
cold.outstanding_handles =
cold.outstanding_handles.saturating_sub(1);
cold.outstanding_handles == 0
&& status == crate::slot_state::Status::Done
}
}
} }
None => false, None => false,
}; };
if should_reclaim { if should_reclaim {
// Re-verified inside; benign if finalize's reclaim won a race. crate::runtime::reclaim_slot(s, self.pid);
crate::runtime::reclaim_slot(inner, self.pid);
} }
})
}); });
} }
} }
@@ -178,70 +129,65 @@ impl Drop for JoinHandle {
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
pub fn spawn(f: impl FnOnce() + Send + 'static) -> JoinHandle { pub fn spawn(f: impl FnOnce() + Send + 'static) -> JoinHandle {
let parent = current_pid().unwrap_or_else(|| { let parent = current_pid()
// Outside an actor but inside run(): the initial spawn. with_runtime .or_else(|| with_runtime(|inner| inner.with_shared(|s| s.root_pid)))
// panics with "not inside Runtime::run()" if there's no runtime at all. .expect("spawn() before run()");
with_runtime(|_| crate::runtime::ROOT_PID)
});
spawn_under(parent, f) spawn_under(parent, f)
} }
pub fn spawn_under<A>(supervisor: Pid<A>, f: impl FnOnce() + Send + 'static) -> JoinHandle { pub fn spawn_under(supervisor: Pid, f: impl FnOnce() + Send + 'static) -> JoinHandle {
let supervisor = supervisor.erase(); // Try to reuse a stack from the pool; fall back to a fresh mmap if empty.
// Stack + closure boxing happen before ANY runtime lock is taken: no // Allocation happens before taking the shared lock so any syscall doesn't
// syscall and no allocation ever stalls another scheduler thread. // stall other scheduler threads.
let stack = with_runtime(|inner| inner.stack_pool.lock().pop()) let stack = with_runtime(|inner| inner.stack_pool.lock().unwrap().pop())
.unwrap_or_else(|| { .unwrap_or_else(|| {
match crate::stack::Stack::new(crate::runtime::ACTOR_STACK_SIZE) { crate::stack::Stack::new(crate::runtime::ACTOR_STACK_SIZE)
Ok(stack) => stack, .expect("stack allocation failed")
Err(e) => panic!("stack allocation failed: {e}"),
}
}); });
let sp = init_actor_stack(stack.top(), crate::actor::trampoline); let sp = init_actor_stack(stack.top(), crate::actor::trampoline);
let closure: crate::runtime::Closure = Box::new(f);
let pid = with_runtime(|inner| { let pid = with_runtime(|inner| {
let idx = inner.allocate_slot(); // panics loudly on slab exhaustion inner.with_shared(|s| {
crate::runtime::install_actor(inner, idx, sp, stack, supervisor, closure) let (idx, gen) = s.allocate_slot();
let pid = Pid::new(idx, gen);
let slot = &mut s.slots[idx as usize];
slot.actor = Some(crate::actor::Actor {
pid,
stack,
sp,
supervisor,
stop: std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
trap: None,
});
slot.state = crate::runtime::State::Runnable;
slot.outstanding_handles = 1;
slot.outcome = None;
slot.waiters.clear();
slot.supervisor_channel = None;
slot.monitors.clear();
slot.links.clear();
slot.pending_unpark = false;
slot.pending_io_result = None;
s.run_queue.push_back(pid);
// Grow the closures vec to cover this slot index, then store.
let idx = idx as usize;
if s.pending_closures.len() <= idx {
s.pending_closures.resize_with(idx + 1, || None);
}
s.pending_closures[idx] = Some(Box::new(f) as crate::runtime::Closure);
crate::te!(crate::trace::Event::Spawn { parent: supervisor, child: pid });
crate::te!(crate::trace::Event::Enqueue(pid));
pid
})
}); });
JoinHandle { pid, consumed: false } JoinHandle { pid, consumed: false }
} }
/// Spawn a typed, single-message actor and hand back its identity-bound
/// [`Pid<A>`] (RFC 014's typed-path producer). The runtime makes the actor's
/// inbox, hands the body its [`Receiver<A::Msg>`], installs the sender, and
/// returns the parent a `Pid<A>`.
///
/// The inbox is published from the parent side **before** the pid is returned
/// (see [`registry::install_for`](crate::registry::install_for)), so the address
/// is live the instant the caller holds it: an immediate
/// [`send_to`](crate::send_to) always resolves, never racing the body's first
/// instruction. The actor is detached — its lifetime is governed by its own
/// logic (an explicit stop message, or returning), like
/// [`GenServerBuilder::start`](crate::GenServerBuilder::start) — so the backing join
/// handle is dropped. Spawns under the current actor (via [`spawn`]).
///
/// Panics if called outside `Runtime::run()`.
pub fn spawn_addr<A: crate::pid::Addressable>(
body: impl FnOnce(crate::channel::Receiver<A::Msg>) + Send + 'static,
) -> Pid<A> {
let (tx, rx) = crate::channel::channel::<A::Msg>();
let handle = spawn(move || body(rx));
let pid = handle.pid();
// Publish the sender for `pid` before returning the typed address. `handle`
// drops at end of scope (detached).
crate::registry::install_for::<A::Msg>(pid, tx);
crate::pid::assert_type::<A>(pid)
}
use crate::context::init_actor_stack; use crate::context::init_actor_stack;
pub fn self_pid() -> Pid { pub fn self_pid() -> Pid {
match current_pid() { current_pid().expect("self_pid() called outside an actor")
Some(pid) => pid,
None => panic!("self_pid() called outside an actor"),
}
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -256,18 +202,6 @@ pub fn yield_now() {
} }
pub fn park_current() { pub fn park_current() {
// Entry-side observation point: a stop flagged while we were QUEUED is
// otherwise lost — the stop's wildcard unpark no-ops on a Queued actor
// (the pending run "is" the wake), so if our first action on resume is
// this park, no wake is ever coming and the wake-side check below is
// unreachable. Checking here closes that hole; a flag that lands after
// this check is covered by the existing protocol (the stop's unpark
// finds Running / the prep-to-park window, sets Notified, and the
// park-return re-queues us into the wake-side check). Unwinding from
// here is the same unwind path as the wake side: leftover wait
// registrations are stale-epoch / dead-generation and self-clean at
// their wakers' failed CAS.
crate::preempt::check_cancelled();
runtime::set_yield_intent(YieldIntent::Park); runtime::set_yield_intent(YieldIntent::Park);
unsafe { crate::context::switch_to_scheduler() }; unsafe { crate::context::switch_to_scheduler() };
// Observation point on the wakeup side of every blocking primitive // Observation point on the wakeup side of every blocking primitive
@@ -278,89 +212,62 @@ pub fn park_current() {
} }
pub fn unpark(pid: Pid) { pub fn unpark(pid: Pid) {
// The whole protocol lives on the slot's packed word (gen + epoch + let result = try_with_runtime(|inner| {
// state in one CAS) — see slot_state.rs. No runtime lock unless we inner.with_shared(|s| {
// enqueue. WILDCARD form: reserved for terminal wakes (request_stop); if let Some(slot) = s.slot_mut(pid) {
// every registration-based waker must use `unpark_at`. match slot.state {
let _ = try_with_runtime(|inner| inner.unpark(pid)); crate::runtime::State::Parked => {
} // Actor is suspended — safe to re-queue immediately.
slot.state = crate::runtime::State::Runnable;
/// Epoch-matched unpark: wake `pid` only if its current wait is still the s.run_queue.push_back(pid);
/// one this waker registered for. The form every registration-based waker crate::te!(crate::trace::Event::UnparkDirect(pid));
/// (channel senders, mutex grants, wait-timers, io completions, joiner crate::te!(crate::trace::Event::Enqueue(pid));
/// wakes) must use — see slot_state.rs for the consuming-wake rules. }
pub(crate) fn unpark_at(pid: Pid, epoch: u32) { crate::runtime::State::Runnable => {
let _ = try_with_runtime(|inner| inner.unpark_at(pid, epoch)); // Actor is still running (between registering its
} // parked_receiver and calling park_current). Set the
// flag; the scheduler will re-queue after the Park
/// Open a new wait for the CURRENT actor: bump its park-epoch and return // yield instead of sleeping.
/// it. Call once per wait, before registering `(pid, epoch)` with any slot.pending_unpark = true;
/// waker. Lock-free (one CAS on the own slot word), so it is legal under crate::te!(crate::trace::Event::UnparkDeferred(pid));
/// any lock, including a Channel-class lock. }
pub(crate) fn begin_wait() -> u32 { crate::runtime::State::Done => {}
let me = match current_pid() { }
Some(pid) => pid, }
None => panic!("begin_wait() called outside an actor"), })
}; });
with_runtime(|inner| inner.begin_wait(me)) let _ = result;
}
/// Close the current actor's wait WITHOUT parking on it. For the no-park
/// exit of multi-registration waits (`select` finding an arm ready at
/// registration time): bumps the epoch so in-flight wakes die at their CAS,
/// eats a notification that already landed, then observes a pending stop —
/// in that order. After this, leftover registrations are stale-epoch and
/// self-clean at their wakers' failed CAS; nothing can fault the actor's
/// next one-shot park.
pub(crate) fn retire_wait() {
let me = match current_pid() {
Some(pid) => pid,
None => panic!("retire_wait() called outside an actor"),
};
with_runtime(|inner| inner.retire_wait(me));
// A request_stop that fired before the clear had its notification
// eaten, but it set the stop flag first — observe it here and unwind.
// One that fires after re-notifies a Running word as usual.
crate::preempt::check_cancelled();
} }
/// Request cooperative cancellation of `pid`. /// Request cooperative cancellation of `pid`.
/// ///
/// Sets the actor's stop flag and wakes it so it observes the flag promptly: /// Sets the actor's stop flag and, if it is parked, wakes it so it observes
/// a parked target is re-queued; a running target is marked notified, so its /// the flag promptly. The actor realises the stop as a controlled unwind at
/// next park returns immediately to an observation point. The actor realises /// its next observation point (`check!()`/allocation, or the wakeup side of a
/// the stop as a controlled unwind at its next observation point /// blocking park), terminating with `Outcome::Stopped`.
/// (`check!()`/allocation, or the wakeup side of a blocking park),
/// terminating with `Outcome::Stopped`.
/// ///
/// This is best-effort and cooperative: an actor that never reaches an /// This is best-effort and cooperative: an actor that never reaches an
/// observation point — a tight loop with no `check!()`, no allocation, and no /// observation point — a tight loop with no `check!()`, no allocation, and no
/// blocking op — cannot be stopped, exactly as it cannot be preempted. A no-op /// blocking op — cannot be stopped, exactly as it cannot be preempted. A no-op
/// if `pid` is already gone. /// if `pid` is already gone.
pub fn request_stop<A>(pid: Pid<A>) { pub fn request_stop(pid: Pid) {
let pid = pid.erase(); let _ = try_with_runtime(|inner| {
let _ = try_with_runtime(|inner| request_stop_inner(inner, pid)); inner.with_shared(|s| {
} if let Some(slot) = s.slot_mut(pid) {
if let Some(actor) = slot.actor.as_ref() {
/// The core of [`request_stop`], taking the runtime directly so it can be
/// driven from inside the runtime (e.g. the root-exit sweep in
/// `finalize_actor`) without re-borrowing the thread-local. Sets the stop flag
/// under the target's cold lock (generation re-verified there; a mismatch or a
/// slot with no live actor is a no-op) and wakes it.
pub(crate) fn request_stop_inner(inner: &RuntimeInner, pid: Pid) {
if let Some(slot) = inner.slot_at(pid) {
{
let cold = slot.cold.lock();
// Verify under the cold lock: generation can't change while
// we hold it (reclaim takes the same lock).
if slot.generation() == pid.generation() {
if let Some(actor) = cold.actor.as_ref() {
actor.stop.store(true, std::sync::atomic::Ordering::Relaxed); actor.stop.store(true, std::sync::atomic::Ordering::Relaxed);
} }
// Wake a parked target so it reaches its post-park observation
// point now. A Runnable target will observe on its next yield;
// a Done target has nothing to stop.
if matches!(slot.state, crate::runtime::State::Parked) {
slot.state = crate::runtime::State::Runnable;
s.run_queue.push_back(pid);
crate::te!(crate::trace::Event::Enqueue(pid));
} }
} }
inner.unpark(pid); })
} });
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -387,19 +294,10 @@ impl Drop for NoPreempt {
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
pub fn sleep(duration: std::time::Duration) { pub fn sleep(duration: std::time::Duration) {
let me = match current_pid() { let me = current_pid().expect("sleep() called outside an actor");
Some(pid) => pid,
None => panic!("sleep() called outside an actor"),
};
let _np = NoPreempt::enter(); let _np = NoPreempt::enter();
let epoch = begin_wait();
let deadline = crate::timer::deadline_from_now(duration); let deadline = crate::timer::deadline_from_now(duration);
with_runtime(|inner| { with_runtime(|inner| inner.with_shared(|s| s.timers.insert_sleep(deadline, me)));
match inner.timers.lock() {
Ok(mut timers) => timers.insert_sleep(deadline, me, epoch),
Err(e) => panic!("smarm: timers lock poisoned (core corrupt): {e}"),
}
});
park_current(); park_current();
} }
@@ -407,113 +305,17 @@ pub fn insert_wait_timer(
deadline: std::time::Instant, deadline: std::time::Instant,
pid: Pid, pid: Pid,
target: std::sync::Arc<dyn crate::timer::TimerTarget>, target: std::sync::Arc<dyn crate::timer::TimerTarget>,
epoch: u32, wait_seq: u64,
) { ) {
with_runtime(|inner| { with_runtime(|inner| {
match inner.timers.lock() { inner.with_shared(|s| {
Ok(mut timers) => timers.insert( s.timers.insert(
deadline, deadline,
pid, pid,
crate::timer::Reason::WaitTimeout { target, epoch }, crate::timer::Reason::WaitTimeout { target, wait_seq },
), );
Err(e) => panic!("smarm: timers lock poisoned (core corrupt): {e}"),
}
});
}
// ---------------------------------------------------------------------------
// send_after / cancel_timer — message-delivery timers (Erlang send_after).
//
// Arm a timer that delivers `msg` to an address after `after`, returning a
// `TimerId`. The destination is resolved *on fire*, not at arm time: a
// `Pid<A>` that has since died yields `SendError::Dead`, a `Name<M>` resolves
// to whoever currently holds it (so a restarted server is reached). Either way
// a failed resolve / closed inbox is dropped, matching `erlang:send_after`.
// `cancel_timer` prevents an as-yet-unfired delivery; it returns whether the
// timer was still armed.
// ---------------------------------------------------------------------------
/// Deliver `msg` to the exact actor named by `dest` (identity-bound, no
/// redirect — see [`send_to`](crate::registry::send_to)) after `after`.
/// Returns a [`TimerId`](crate::timer::TimerId) for [`cancel_timer`].
pub fn send_after<A: crate::pid::Addressable>(
after: std::time::Duration,
dest: Pid<A>,
msg: A::Msg,
) -> crate::timer::TimerId {
let deadline = crate::timer::deadline_from_now(after);
let fire = Box::new(move || {
let _ = crate::registry::send_to(dest, msg);
});
with_runtime(|inner| {
match inner.timers.lock() {
Ok(mut timers) => timers.insert_send(deadline, dest.erase(), fire),
Err(e) => panic!("smarm: timers lock poisoned (core corrupt): {e}"),
}
}) })
}
/// Deliver `msg` to whichever actor holds the name `dest` at fire time
/// (re-resolving [`send`](crate::registry::send) semantics) after `after`.
/// Returns a [`TimerId`](crate::timer::TimerId) for [`cancel_timer`].
pub fn send_after_named<M: Send + 'static>(
after: std::time::Duration,
dest: Name<M>,
msg: M,
) -> crate::timer::TimerId {
let deadline = crate::timer::deadline_from_now(after);
// Informational only (who armed it); not used for delivery.
let armed_by = current_pid().unwrap_or(Pid::new(0, 0));
let fire = Box::new(move || {
let _ = crate::registry::send(dest, msg);
}); });
with_runtime(|inner| {
match inner.timers.lock() {
Ok(mut timers) => timers.insert_send(deadline, armed_by, fire),
Err(e) => panic!("smarm: timers lock poisoned (core corrupt): {e}"),
}
})
}
/// Deliver `msg` onto a channel the caller owns after `after`, rather than to a
/// registry address. The sibling of [`send_after`] used by the gen_server timer
/// layer (RFC 015 §5): arming a server timer must land the fire on the loop's
/// own `Sys` channel — giving it the loop's arm position — not in the inbox.
///
/// Same substrate as [`send_after`]: a `Reason::Send` entry, the same `armed`
/// set, the same [`TimerId`](crate::timer::TimerId) for [`cancel_timer`]. Only
/// the fire thunk differs — `tx.send(msg)` instead of a registry resolve — so a
/// send onto a channel whose receiver is gone is dropped, exactly as a failed
/// address resolve is (Erlang `send_after` semantics). `pid` is informational
/// (who armed it); delivery lives entirely in the thunk.
pub(crate) fn send_after_to<T: Send + 'static>(
after: std::time::Duration,
tx: Sender<T>,
msg: T,
) -> crate::timer::TimerId {
let deadline = crate::timer::deadline_from_now(after);
let armed_by = current_pid().unwrap_or(Pid::new(0, 0));
let fire = Box::new(move || {
let _ = tx.send(msg);
});
with_runtime(|inner| {
match inner.timers.lock() {
Ok(mut timers) => timers.insert_send(deadline, armed_by, fire),
Err(e) => panic!("smarm: timers lock poisoned (core corrupt): {e}"),
}
})
}
/// Cancel a timer armed by [`send_after`] / [`send_after_named`]. Returns
/// `true` if it was still pending (delivery now prevented), `false` if it had
/// already fired or been cancelled.
pub fn cancel_timer(id: crate::timer::TimerId) -> bool {
with_runtime(|inner| {
match inner.timers.lock() {
Ok(mut timers) => timers.cancel(id),
Err(e) => panic!("smarm: timers lock poisoned (core corrupt): {e}"),
}
})
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -525,49 +327,28 @@ where
F: FnOnce() -> T + Send + 'static, F: FnOnce() -> T + Send + 'static,
T: Send + 'static, T: Send + 'static,
{ {
let me = match current_pid() { let me = current_pid().expect("block_on_io() called outside an actor");
Some(pid) => pid,
None => panic!("block_on_io() called outside an actor"),
};
let work: Box<dyn FnOnce() -> crate::io::IoResult + Send> = Box::new(move || { let work: Box<dyn FnOnce() -> crate::io::IoResult + Send> = Box::new(move || {
let v: T = f(); let v: T = f();
Ok(Box::new(v) as Box<dyn std::any::Any + Send>) Ok(Box::new(v) as Box<dyn std::any::Any + Send>)
}); });
{ {
let _np = NoPreempt::enter(); let _np = NoPreempt::enter();
let epoch = begin_wait(); with_runtime(|inner| inner.with_shared(|s| {
with_runtime(|inner| { let io = s.io.as_mut().expect("io thread not started");
let mut io = match inner.io.lock() { io.submit(me, work);
Ok(io) => io, }));
Err(e) => panic!("smarm: io lock poisoned (core corrupt): {e}"),
};
match io.as_mut() {
Some(io) => io.submit(me, epoch, work),
None => panic!("io thread not started"),
}
});
park_current(); park_current();
} }
let result = with_runtime(|inner| { let result = with_runtime(|inner| inner.with_shared(|s| {
let slot = match inner.slot_at(me) { s.slot_mut(me)
Some(slot) => slot, .expect("block_on_io: own slot vanished")
None => panic!("block_on_io: own slot vanished"), .pending_io_result
}; .take()
let mut cold = slot.cold.lock(); .expect("block_on_io: resumed without a result")
debug_assert_eq!( }));
slot.generation(), me.generation(),
"block_on_io: own slot reused mid-park"
);
match cold.pending_io_result.take() {
Some(result) => result,
None => panic!("block_on_io: resumed without a result"),
}
});
match result { match result {
Ok(any) => match any.downcast::<T>() { Ok(any) => *any.downcast::<T>().expect("block_on_io: type mismatch"),
Ok(typed) => *typed,
Err(_) => panic!("block_on_io: type mismatch"),
},
Err(payload) => std::panic::resume_unwind(payload), Err(payload) => std::panic::resume_unwind(payload),
} }
} }
@@ -581,202 +362,16 @@ pub fn wait_writable(fd: std::os::fd::RawFd) -> std::io::Result<()> {
} }
fn wait_fd(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::io::Result<()> { fn wait_fd(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::io::Result<()> {
let me = match current_pid() { let me = current_pid().expect("wait_*() called outside an actor");
Some(pid) => pid,
None => panic!("wait_*() called outside an actor"),
};
let _np = NoPreempt::enter(); let _np = NoPreempt::enter();
let epoch = begin_wait(); with_runtime(|inner| inner.with_shared(|s| {
with_runtime(|inner| { let io = s.io.as_mut().expect("io thread not started");
let mut io = match inner.io.lock() { io.epoll_register(fd, me, readable, writable)
Ok(io) => io, }))?;
Err(e) => panic!("smarm: io lock poisoned (core corrupt): {e}"),
};
match io.as_mut() {
Some(io) => io.epoll_register(fd, me, epoch, readable, writable),
None => panic!("io thread not started"),
}
})?;
// If a terminal stop unwinds us out of the park below, the registration
// must not outlive us: a stale `waiters` entry fails every future
// `wait_*` on this fd with AlreadyExists, and the kernel-side ADD leaks
// until the fd happens to be reused. Clean up iff the entry is still
// ours — a `FdReady` racing the stop may have consumed it already (it
// removes + DELs under the io lock), after which the fd may even carry
// ANOTHER actor's fresh registration; in that case touch nothing.
struct Dereg {
fd: std::os::fd::RawFd,
me: Pid,
epoch: u32,
}
impl Drop for Dereg {
fn drop(&mut self) {
with_runtime(|inner| {
let mut io = match inner.io.lock() {
Ok(io) => io,
Err(e) => panic!("smarm: io lock poisoned (core corrupt): {e}"),
};
if let Some(io) = io.as_mut() {
if io.waiters.get(&self.fd) == Some(&(self.me, self.epoch)) {
io.waiters.remove(&self.fd);
io.epoll_deregister(self.fd);
}
}
});
}
}
let guard = Dereg { fd, me, epoch };
park_current(); park_current();
// Normal wake: the FdReady path removed the entry and DEL'd the fd
// before the unpark, so the guard's check would be a guaranteed no-op —
// skip the io lock on the hot path. (Dereg owns nothing; forget leaks
// no resource.)
std::mem::forget(guard);
Ok(()) Ok(())
} }
// ---------------------------------------------------------------------------
// FdArm — fd readiness as a select arm (RFC 008)
// ---------------------------------------------------------------------------
/// An fd-readiness arm for [`crate::select`] / [`crate::select_timeout`]:
/// ready when the fd is readable (resp. writable), composable with channel
/// receivers on one wait epoch. Phase-1 rules apply: one waiter per fd at a
/// time, one direction per arm (duplex on a single fd needs `dup`; epoll
/// registrations key on the open file description, so dup'd fds register
/// independently).
pub struct FdArm {
fd: std::os::fd::RawFd,
readable: bool,
writable: bool,
}
impl FdArm {
pub fn readable(fd: std::os::fd::RawFd) -> Self {
FdArm { fd, readable: true, writable: false }
}
pub fn writable(fd: std::os::fd::RawFd) -> Self {
FdArm { fd, readable: false, writable: true }
}
}
impl crate::channel::sealed::Sealed for FdArm {}
impl crate::channel::Selectable for FdArm {
/// Ready-now check is a zero-timeout `poll(2)`; if the requested events
/// are pending the wait is retired without registering (`Ok(false)`,
/// the channel-arm contract). Otherwise register with the io thread —
/// every failure surfaces as `Err` (EBADF including a closed-fd
/// POLLNVAL, EMFILE on the epoll set, AlreadyExists for a second
/// waiter on the fd): the fallible-out, nothing-left-behind rule, in
/// deviation from RFC 008's permanently-ready lean, which would spin a
/// consumer whose fd is healthy but unregistrable (EMFILE).
fn sel_register(&self, pid: Pid, epoch: u32) -> std::io::Result<bool> {
if poll_events(self.fd, self.readable, self.writable)? {
return Ok(false);
}
with_runtime(|inner| {
let mut io = match inner.io.lock() {
Ok(io) => io,
Err(e) => panic!("smarm: io lock poisoned (core corrupt): {e}"),
};
match io.as_mut() {
Some(io) => {
io.epoll_register(self.fd, pid, epoch, self.readable, self.writable)
}
None => panic!("io thread not started"),
}
})?;
Ok(true)
}
/// Classification is the same zero-timeout poll: a pure function of fd
/// state, independent of the registration the cleanup pass removed. An
/// error here (EBADF: fd closed mid-wait) reports READY — the
/// consumer's read/write surfaces the errno; a dead arm is an event,
/// not a hang.
fn sel_ready(&self) -> bool {
poll_events(self.fd, self.readable, self.writable).unwrap_or(true)
}
/// `wait_fd`'s `Dereg` compare, verbatim: remove the waiters entry and
/// kernel-side registration iff the entry is still `(pid, epoch)`-ours.
/// A `FdReady` racing the wake may have consumed it (it removes + DELs
/// under the io lock), after which the fd may even carry ANOTHER
/// actor's fresh registration; in that case touch nothing.
fn sel_unregister(&self, pid: Pid, epoch: u32) {
with_runtime(|inner| {
let mut io = match inner.io.lock() {
Ok(io) => io,
Err(e) => panic!("smarm: io lock poisoned (core corrupt): {e}"),
};
if let Some(io) = io.as_mut() {
if io.waiters.get(&self.fd) == Some(&(pid, epoch)) {
io.waiters.remove(&self.fd);
io.epoll_deregister(self.fd);
}
}
});
}
fn sel_eager_cleanup(&self) -> bool {
true
}
}
/// Zero-timeout `poll(2)`: are any of the requested events (or ERR/HUP,
/// which make the consumer's read/write fail loudly rather than park
/// forever) pending on `fd`? POLLNVAL maps to `Err(EBADF)`.
fn poll_events(fd: std::os::fd::RawFd, readable: bool, writable: bool) -> std::io::Result<bool> {
let mut events: libc::c_short = 0;
if readable {
events |= libc::POLLIN;
}
if writable {
events |= libc::POLLOUT;
}
let mut pfd = libc::pollfd { fd, events, revents: 0 };
loop {
let r = unsafe { libc::poll(&mut pfd, 1, 0) };
if r < 0 {
let e = std::io::Error::last_os_error();
if e.kind() == std::io::ErrorKind::Interrupted {
continue;
}
return Err(e);
}
if r == 0 {
return Ok(false);
}
if pfd.revents & libc::POLLNVAL != 0 {
return Err(std::io::Error::from_raw_os_error(libc::EBADF));
}
return Ok(pfd.revents & (events | libc::POLLERR | libc::POLLHUP) != 0);
}
}
/// Wait until `fd` is readable or `timeout` elapses: `Ok(true)` = ready,
/// `Ok(false)` = timed out. A one-arm [`crate::try_select_timeout`].
pub fn wait_readable_timeout(
fd: std::os::fd::RawFd,
timeout: std::time::Duration,
) -> std::io::Result<bool> {
let arm = FdArm::readable(fd);
Ok(crate::channel::try_select_timeout(&[&arm], timeout)?.is_some())
}
/// Wait until `fd` is writable or `timeout` elapses: `Ok(true)` = ready,
/// `Ok(false)` = timed out.
pub fn wait_writable_timeout(
fd: std::os::fd::RawFd,
timeout: std::time::Duration,
) -> std::io::Result<bool> {
let arm = FdArm::writable(fd);
Ok(crate::channel::try_select_timeout(&[&arm], timeout)?.is_some())
}
pub fn read(fd: std::os::fd::RawFd, buf: &mut [u8]) -> std::io::Result<usize> { pub fn read(fd: std::os::fd::RawFd, buf: &mut [u8]) -> std::io::Result<usize> {
wait_readable(fd)?; wait_readable(fd)?;
let n = unsafe { libc::read(fd, buf.as_mut_ptr() as *mut _, buf.len()) }; let n = unsafe { libc::read(fd, buf.as_mut_ptr() as *mut _, buf.len()) };
@@ -794,16 +389,13 @@ pub fn write(fd: std::os::fd::RawFd, buf: &[u8]) -> std::io::Result<usize> {
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
pub fn register_supervisor_channel(pid: Pid, sender: Sender<Signal>) { pub fn register_supervisor_channel(pid: Pid, sender: Sender<Signal>) {
with_runtime(|inner| { with_runtime(|inner| inner.with_shared(|s| {
let slot = inner.slot_at(pid) if let Some(slot) = s.slot_mut(pid) {
.unwrap_or_else(|| panic!("register_supervisor_channel: pid {:?} not found", pid)); slot.supervisor_channel = Some(sender);
let mut cold = slot.cold.lock(); } else {
assert_eq!( panic!("register_supervisor_channel: pid {:?} not found", pid);
slot.generation(), pid.generation(), }
"register_supervisor_channel: pid {:?} not found", pid }));
);
cold.supervisor_channel = Some(sender);
});
} }
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -815,54 +407,3 @@ pub fn register_supervisor_channel(pid: Pid, sender: Sender<Signal>) {
pub fn run<F: FnOnce() + Send + 'static>(f: F) { pub fn run<F: FnOnce() + Send + 'static>(f: F) {
crate::runtime::init(crate::runtime::Config::exact(1)).run(f); crate::runtime::init(crate::runtime::Config::exact(1)).run(f);
} }
#[cfg(all(test, not(loom)))]
mod send_after_to_tests {
use super::*;
use crate::channel::channel;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::time::Duration;
// A fired send_after_to lands its message on the caller's own channel.
#[test]
fn delivers_onto_the_channel() {
run(|| {
let (tx, rx) = channel::<u32>();
send_after_to(Duration::from_millis(10), tx, 42);
// recv parks until the scheduler fires the timer thunk.
assert_eq!(rx.recv().unwrap(), 42);
});
}
// cancel_timer before the deadline prevents delivery and reports the race
// win; the channel then closes with no message once the lone sender (moved
// into the now-discarded thunk) is gone.
#[test]
fn cancel_prevents_delivery() {
run(|| {
let (tx, rx) = channel::<u32>();
let id = send_after_to(Duration::from_millis(50), tx, 7);
assert!(cancel_timer(id), "cancel before fire should win the race");
// No delivery: the discarded thunk drops the only sender, so recv
// sees a closed channel rather than the value.
assert!(rx.recv().is_err());
});
}
// The thunk runs on the scheduler thread; a closed receiver makes the send
// a harmless no-op (Erlang send_after semantics) rather than a panic.
#[test]
fn send_to_closed_channel_is_harmless() {
let reached = Arc::new(AtomicBool::new(false));
let r2 = reached.clone();
run(move || {
let (tx, rx) = channel::<u32>();
send_after_to(Duration::from_millis(10), tx, 1);
drop(rx); // receiver gone before the timer fires
crate::sleep(Duration::from_millis(30));
r2.store(true, Ordering::SeqCst);
});
assert!(reached.load(Ordering::SeqCst), "runtime survived the dead-channel fire");
}
}
src/slot_state.rs
-624
View File
@@ -1,624 +0,0 @@
//! The per-slot scheduling state machine, as a standalone unit.
//!
//! One atomic word packs `(generation << 32) | (epoch << 8) | state`; every
//! transition is a CAS on the packed word, so the generation check is atomic
//! with the transition — no ABA, no acting on a recycled slot. The diagram
//! and the full protocol rationale live in `runtime.rs`; this module is the
//! mechanism, factored out so that:
//!
//! - loom can model-check the production transitions directly (see the
//! `loom_tests` module; built with `RUSTFLAGS="--cfg loom"`), and
//! - every method asserts the precondition it relies on (`debug_assert!` —
//! these are hot paths), per the assert-the-invariants house rule.
//!
//! ## The park-epoch (wait identity)
//!
//! The middle 24 bits carry the slot's *park-epoch*: the identity of the
//! actor's current (or most recent) wait. The rules:
//!
//! - [`begin_wait`](StateWord::begin_wait) bumps the epoch and returns it;
//! the actor calls it once per wait, *before* registering itself with any
//! waker. Registrations carry `(pid, epoch)`.
//! - A wake may be **epoch-matched** (`unpark(gen, Some(epoch))`): it lands
//! only if the word still carries that epoch. Wakers whose registration
//! handle can outlive the wait it was created for (channel senders, mutex
//! grants, wait-timers) MUST use this form.
//! - Every successful wake **consumes** the epoch — `Parked(e) → Queued(e+1)`,
//! `Running(e) → RunningNotified(e+1)` — so at most one wake can ever land
//! per wait, by construction. A loser in a multi-waker race (e.g. the
//! non-winning arms of a `select`) fails the epoch check and no-ops; it can
//! neither steal a future wait's wake nor leave a pending notification that
//! would fault a later one-shot park (`Mutex::lock_timeout`, `sleep`,
//! `block_on_io`, `wait_fd` all rely on wakes being *meaningful*).
//! - The wildcard form (`unpark(gen, None)`) also consumes, and is reserved
//! for terminal wakes — `request_stop` — which never return control to the
//! code that parked.
//!
//! Epoch wrap (24 bits = 16.7M waits) is harmless: a collision would require
//! a taken registration to stay in flight across a full wrap of the *same
//! actor's* waits, and registrations are consumed at take-time under their
//! primitive's lock — the exposure is the taker's instruction window.
//!
//! Atomics come from `sync_shim` (std normally, `loom::sync` under
//! `cfg(loom)`).
use crate::sync_shim::{AtomicU64, Ordering};
pub(crate) const ST_VACANT: u64 = 0;
pub(crate) const ST_QUEUED: u64 = 1;
pub(crate) const ST_RUNNING: u64 = 2;
pub(crate) const ST_RUNNING_NOTIFIED: u64 = 3;
pub(crate) const ST_PARKED: u64 = 4;
pub(crate) const ST_DONE: u64 = 5;
/// Park-epoch width: 24 bits, packed at word bits 8..32.
pub(crate) const EPOCH_MASK: u32 = 0x00FF_FFFF;
#[inline]
pub(crate) const fn pack(gen: u32, epoch: u32, st: u64) -> u64 {
debug_assert!(epoch & !EPOCH_MASK == 0);
((gen as u64) << 32) | ((epoch as u64) << 8) | st
}
#[inline]
pub(crate) const fn word_gen(w: u64) -> u32 {
(w >> 32) as u32
}
#[inline]
pub(crate) const fn word_epoch(w: u64) -> u32 {
((w >> 8) as u32) & EPOCH_MASK
}
#[inline]
pub(crate) const fn word_state(w: u64) -> u64 {
w & 0xFF
}
/// What an unpark amounted to. The caller owns the side effects (enqueue,
/// trace events) — this module is pure state.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub(crate) enum Unpark {
/// Parked → Queued: the caller must enqueue the pid.
Enqueue,
/// Running → RunningNotified: the scheduler's park-return will re-queue.
Notified,
/// Stale generation, stale epoch, already queued/notified, done, or
/// vacant.
Noop,
}
/// A pid's-eye view of the slot, for cold paths that hold the slot lock.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub(crate) enum Status {
/// The generation no longer matches: the slot was reclaimed (and possibly
/// reused) — the pid is stale.
Stale,
/// The actor terminated; its outcome is (or was) in the slot.
Done,
/// Alive in some scheduling state (Queued / Running / Notified / Parked).
Live,
}
pub(crate) struct StateWord(AtomicU64);
impl StateWord {
pub(crate) fn new() -> Self {
Self(AtomicU64::new(pack(0, 0, ST_VACANT)))
}
#[inline]
pub(crate) fn load(&self) -> u64 {
self.0.load(Ordering::Acquire)
}
#[inline]
pub(crate) fn generation(&self) -> u32 {
word_gen(self.load())
}
#[inline]
pub(crate) fn status_for(&self, gen: u32) -> Status {
let w = self.load();
if word_gen(w) != gen {
return Status::Stale;
}
match word_state(w) {
ST_DONE => Status::Done,
// A matching generation on a Vacant slot is unreachable for any
// ISSUED pid — reclaim bumps the generation in the very store
// that vacates, and install publishes Queued before the pid
// escapes. But `Pid::new` is public, so a forged / never-issued
// pid (e.g. `Pid::new(5, 0)` against a fresh slab) can land
// here; for those, "no such actor" is the correct total answer.
ST_VACANT => Status::Stale,
_ => Status::Live,
}
}
/// Spawn-side publish: Vacant → Queued. The caller owns the vacant slot
/// exclusively (it popped the index from the free list), so this is a
/// plain Release store; it is the moment the actor becomes visible to
/// pops, unparks, and stops. The epoch starts at 0 for each occupancy
/// (`set_done` zeroes it; wait identity never crosses a lifetime).
pub(crate) fn publish_queued(&self, gen: u32) {
debug_assert_eq!(
self.load(),
pack(gen, 0, ST_VACANT),
"publish over a non-vacant slot"
);
self.0.store(pack(gen, 0, ST_QUEUED), Ordering::Release);
}
/// Scheduler pop-side claim: Queued → Running, epoch preserved. `false`
/// means the popped pid is stale — by the at-most-once-enqueued
/// invariant, a generation mismatch is the only possible failure
/// (asserted). Nothing can move a matching-gen word off Queued (wakes
/// no-op on Queued), so the CAS loop is single-shot in practice.
#[must_use]
pub(crate) fn try_claim(&self, gen: u32) -> bool {
loop {
let w = self.load();
if word_gen(w) != gen {
return false;
}
debug_assert_eq!(
word_state(w),
ST_QUEUED,
"queued pid found in unexpected state {} — double enqueue?",
word_state(w)
);
if self
.0
.compare_exchange(
w,
pack(gen, word_epoch(w), ST_RUNNING),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return true;
}
}
}
/// Yield return path: Running | RunningNotified → Queued, epoch
/// preserved. A notification that arrived mid-run coalesces into the
/// re-queue. Caller must enqueue. CAS loop because a notify can bump the
/// epoch between the read and the exchange.
pub(crate) fn yield_return(&self, gen: u32) {
loop {
let w = self.load();
debug_assert!(
matches!(word_state(w), ST_RUNNING | ST_RUNNING_NOTIFIED)
&& word_gen(w) == gen,
"yield return from invalid word {w:#x}"
);
if self
.0
.compare_exchange(
w,
pack(gen, word_epoch(w), ST_QUEUED),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return;
}
}
}
/// Park return path. `true` = actually parked. `false` = an unpark landed
/// in the prep-to-park window (RunningNotified); the word is already back
/// to Queued and the caller must enqueue — the lost-wakeup window,
/// closed. Epoch preserved on both paths (the notify already consumed
/// it).
#[must_use]
pub(crate) fn park_return(&self, gen: u32) -> bool {
loop {
let w = self.load();
debug_assert_eq!(word_gen(w), gen, "park return with stale gen");
let target = match word_state(w) {
ST_RUNNING => ST_PARKED,
ST_RUNNING_NOTIFIED => ST_QUEUED,
st => unreachable!("park return from invalid state {st}"),
};
if self
.0
.compare_exchange(
w,
pack(gen, word_epoch(w), target),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return target == ST_PARKED;
}
}
}
/// Open a new wait: bump the park-epoch and return it. Called by the
/// waiting actor itself (so the state is Running, or RunningNotified if
/// a terminal wake is already pending — the bump preserves the pending
/// notification), once per wait, BEFORE registering `(pid, epoch)` with
/// any waker.
#[must_use]
pub(crate) fn begin_wait(&self, gen: u32) -> u32 {
loop {
let w = self.load();
debug_assert!(
matches!(word_state(w), ST_RUNNING | ST_RUNNING_NOTIFIED)
&& word_gen(w) == gen,
"begin_wait from invalid word {w:#x}"
);
let next = word_epoch(w).wrapping_add(1) & EPOCH_MASK;
if self
.0
.compare_exchange(
w,
pack(gen, next, word_state(w)),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return next;
}
}
}
/// The unpark protocol — the one way anything outside the scheduler makes
/// an actor runnable. See [`Unpark`] for the caller's obligations.
///
/// `want = Some(epoch)` is the epoch-matched form: lands only if the word
/// still carries that epoch (i.e. the wait it was registered for is still
/// the current, un-woken wait). `want = None` is the wildcard, reserved
/// for terminal wakes. Both forms CONSUME the epoch on success.
#[must_use]
pub(crate) fn unpark(&self, gen: u32, want: Option<u32>) -> Unpark {
loop {
let w = self.load();
if word_gen(w) != gen {
return Unpark::Noop;
}
if let Some(e) = want {
if word_epoch(w) != e {
return Unpark::Noop;
}
}
let bumped = word_epoch(w).wrapping_add(1) & EPOCH_MASK;
match word_state(w) {
ST_PARKED => {
if self
.0
.compare_exchange(
w,
pack(gen, bumped, ST_QUEUED),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return Unpark::Enqueue;
}
}
ST_RUNNING => {
if self
.0
.compare_exchange(
w,
pack(gen, bumped, ST_RUNNING_NOTIFIED),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return Unpark::Notified;
}
}
_ => return Unpark::Noop, // Queued | Notified | Done | Vacant
}
}
}
/// Eat a pending notification: RunningNotified → Running, epoch
/// preserved; no-op on Running. Called by the RUNNING actor itself, on
/// the no-park exit of a wait it registered for but never parked on
/// (`select` returning a ready arm at registration time), AFTER bumping
/// the epoch and BEFORE re-checking its stop flag:
///
/// - post-bump, the only wakers that can have set RunningNotified are
/// ones stamped with the just-retired epoch (a select arm) or a
/// terminal wildcard (`request_stop`);
/// - the caller's stop-flag check AFTER the clear catches the terminal
/// case (the flag is set before the wake fires), so eating its
/// notification loses nothing — and a stop arriving later re-notifies
/// a Running word as usual;
/// - what remains eaten is exactly the stale arm wake that would
/// otherwise fault the actor's next one-shot park.
///
/// Returns whether a notification was eaten.
pub(crate) fn clear_notify(&self, gen: u32) -> bool {
loop {
let w = self.load();
debug_assert!(
matches!(word_state(w), ST_RUNNING | ST_RUNNING_NOTIFIED)
&& word_gen(w) == gen,
"clear_notify from invalid word {w:#x}"
);
if word_state(w) != ST_RUNNING_NOTIFIED {
return false;
}
if self
.0
.compare_exchange(
w,
pack(gen, word_epoch(w), ST_RUNNING),
Ordering::AcqRel,
Ordering::Acquire,
)
.is_ok()
{
return true;
}
}
}
/// Finalize: Running | RunningNotified → Done, epoch zeroed (wait
/// identity never crosses an occupancy). Called by the scheduler that
/// just ran the actor to completion (so those are the only legal prior
/// states), under the slot's cold lock so join's check-or-register is
/// linearized against it.
pub(crate) fn set_done(&self, gen: u32) {
let prev = self.0.swap(pack(gen, 0, ST_DONE), Ordering::AcqRel);
debug_assert!(
matches!(word_state(prev), ST_RUNNING | ST_RUNNING_NOTIFIED)
&& word_gen(prev) == gen,
"finalize from invalid word {prev:#x}"
);
}
/// Reclaim: Done → Vacant(gen + 1). The generation bump IS the reclaim:
/// every stale pid is dead from this store onwards. Caller holds the cold
/// lock and has verified eligibility (asserted).
pub(crate) fn reclaim(&self, gen: u32) {
debug_assert_eq!(
self.load(),
pack(gen, 0, ST_DONE),
"reclaim of a non-Done slot"
);
self.0
.store(pack(gen.wrapping_add(1), 0, ST_VACANT), Ordering::Release);
}
}
// ---------------------------------------------------------------------------
// loom model tests — RUSTFLAGS="--cfg loom" cargo test --lib --release
// ---------------------------------------------------------------------------
#[cfg(all(test, loom))]
mod loom_tests {
use super::*;
use loom::sync::atomic::{AtomicBool, AtomicUsize};
use loom::sync::Arc;
use loom::thread;
use std::sync::atomic::Ordering as O;
/// THE lost-wakeup theorem. A waiter registers a condition check then
/// parks (as every parking site does); a waker sets the condition then
/// unparks. In every interleaving the waiter must end up runnable —
/// parked-forever-with-condition-set must be unreachable.
#[test]
fn no_lost_wakeup_park_vs_unpark() {
loom::model(|| {
let word = Arc::new(StateWord::new());
word.publish_queued(0);
assert!(word.try_claim(0)); // scheduler claimed: actor Running
let epoch = word.begin_wait(0); // actor opens the wait
let ready = Arc::new(AtomicBool::new(false));
let enqueues = Arc::new(AtomicUsize::new(0));
// Waker: make the condition true, then wake the registered wait.
let w = word.clone();
let r = ready.clone();
let e = enqueues.clone();
let waker = thread::spawn(move || {
r.store(true, O::SeqCst);
if w.unpark(0, Some(epoch)) == Unpark::Enqueue {
e.fetch_add(1, O::SeqCst);
}
});
// Waiter (as the scheduler executes it): re-check the condition,
// park only if still false; a Notified park-return re-queues.
let parked = if ready.load(O::SeqCst) {
false // condition already visible: doesn't park at all
} else if word.park_return(0) {
true
} else {
enqueues.fetch_add(1, O::SeqCst); // notified → re-queued
false
};
waker.join().unwrap();
let w = word.load();
if parked {
// Parked is only a FINAL state if the waker's unpark moved it
// back to Queued (+ one enqueue). Parked-and-stays-parked
// would be the lost wakeup.
assert_eq!(word_state(w), ST_QUEUED, "lost wakeup: parked forever");
assert_eq!(enqueues.load(O::SeqCst), 1);
} else {
// Never more than one enqueue (at-most-once-enqueued).
assert!(enqueues.load(O::SeqCst) <= 1);
}
});
}
/// Two concurrent unparkers, one parked actor: exactly one wins the
/// enqueue (at-most-once), regardless of interleaving. Both stamped with
/// the live epoch — the consuming bump is what serializes them.
#[test]
fn two_unparkers_one_enqueue() {
loom::model(|| {
let word = Arc::new(StateWord::new());
word.publish_queued(0);
assert!(word.try_claim(0));
let epoch = word.begin_wait(0);
assert!(word.park_return(0)); // actor parked
let enqueues = Arc::new(AtomicUsize::new(0));
let mut hs = Vec::new();
for _ in 0..2 {
let w = word.clone();
let e = enqueues.clone();
hs.push(thread::spawn(move || {
if w.unpark(0, Some(epoch)) == Unpark::Enqueue {
e.fetch_add(1, O::SeqCst);
}
}));
}
for h in hs {
h.join().unwrap();
}
assert_eq!(enqueues.load(O::SeqCst), 1);
assert_eq!(word_state(word.load()), ST_QUEUED);
});
}
/// The stale-epoch theorem — what `select`'s loser arms lean on. An
/// actor opens a wait, two registered wakers race it (against the park
/// itself, covering the prep-to-park window); afterwards the actor is
/// runnable exactly once, and a LATE waker still stamped with the
/// consumed epoch can neither enqueue nor notify — in every
/// interleaving. (Under wildcard semantics the late waker would corrupt
/// the actor's NEXT one-shot park; this is the theorem that buys
/// `Mutex::lock_timeout`/`sleep`/`block_on_io` their unchanged code.)
#[test]
fn consumed_epoch_unpark_never_lands() {
loom::model(|| {
let word = Arc::new(StateWord::new());
word.publish_queued(0);
assert!(word.try_claim(0));
let epoch = word.begin_wait(0);
// Two arms race the wake, concurrent with the park itself.
let enqueues = Arc::new(AtomicUsize::new(0));
let mut hs = Vec::new();
for _ in 0..2 {
let w = word.clone();
let e = enqueues.clone();
hs.push(thread::spawn(move || {
if w.unpark(0, Some(epoch)) == Unpark::Enqueue {
e.fetch_add(1, O::SeqCst);
}
}));
}
let mut runnable_via_notify = false;
if !word.park_return(0) {
runnable_via_notify = true; // notified in prep-to-park
}
for h in hs {
h.join().unwrap();
}
// Exactly one path made the actor runnable.
let direct = enqueues.load(O::SeqCst);
if runnable_via_notify {
assert_eq!(direct, 0, "woken twice: notify AND enqueue");
} else {
assert_eq!(direct, 1, "parked forever, or woken twice");
}
assert_eq!(word_state(word.load()), ST_QUEUED);
// The actor runs again. A waker still holding the OLD epoch —
// a select loser arm firing later — must be a strict no-op,
// not a pending notification.
assert!(word.try_claim(0));
assert_eq!(word.unpark(0, Some(epoch)), Unpark::Noop);
assert_eq!(word_state(word.load()), ST_RUNNING, "stale epoch notified a live run");
});
}
/// The retire theorem — `select`'s no-park exit. An actor opens a wait
/// and registers, then finds an arm ready and returns WITHOUT parking;
/// a loser arm's waker fires concurrently, stamped with the live epoch.
/// The exit retires the wait (bump, then eat): in every interleaving
/// the run ends on a clean Running word — no pending notification
/// survives to fault the actor's next one-shot park — and the waker
/// never enqueues.
#[test]
fn retire_eats_late_arm_notification() {
loom::model(|| {
let word = Arc::new(StateWord::new());
word.publish_queued(0);
assert!(word.try_claim(0));
let epoch = word.begin_wait(0); // select opens + registers
let w = word.clone();
let waker = thread::spawn(move || w.unpark(0, Some(epoch)));
// No-park exit: bump (invalidates in-flight wakes), then eat
// (consumes one that already landed).
let _ = word.begin_wait(0);
word.clear_notify(0);
assert_ne!(waker.join().unwrap(), Unpark::Enqueue);
assert_eq!(
word_state(word.load()),
ST_RUNNING,
"stale arm wake survived the retire"
);
});
}
/// The ABA theorem: a stale-generation unpark racing reclaim + reuse can
/// never touch the slot's new occupant.
#[test]
fn stale_unpark_never_hits_reused_slot() {
loom::model(|| {
let word = Arc::new(StateWord::new());
// Gen-0 actor runs to completion.
word.publish_queued(0);
assert!(word.try_claim(0));
let w = word.clone();
let stale = thread::spawn(move || w.unpark(0, None));
// Scheduler: finalize, reclaim, and a new spawn reuses the slot.
word.set_done(0);
word.reclaim(0);
word.publish_queued(1);
// The stale unpark may have squeezed in only while gen 0 was
// still Running (→ Notified) — in which case set_done's swap
// absorbed it — or it observed Done/Vacant/gen-1 and no-op'd.
// Either way it must never claim an enqueue.
assert_ne!(stale.join().unwrap(), Unpark::Enqueue);
// And the new occupant is exactly where its spawn put it.
assert_eq!(word.load(), pack(1, 0, ST_QUEUED));
});
}
/// Unpark racing the claim itself: whatever the interleaving, the actor
/// is Running or RunningNotified afterwards and nobody enqueued (it was
/// never parked).
#[test]
fn unpark_vs_claim_coalesces() {
loom::model(|| {
let word = Arc::new(StateWord::new());
word.publish_queued(0);
let w = word.clone();
let unparker = thread::spawn(move || w.unpark(0, None));
assert!(word.try_claim(0)); // the entry is ours; claim must win
let r = unparker.join().unwrap();
assert_ne!(r, Unpark::Enqueue);
let st = word_state(word.load());
assert!(matches!(st, ST_RUNNING | ST_RUNNING_NOTIFIED));
});
}
}
src/supervisor.rs
+35 -111
View File
@@ -1,114 +1,16 @@
//! Supervision: keep a set of actors alive. //! Supervision signals.
//! //!
//! A *supervisor* is an actor whose only job is to start a fixed set of child //! Every actor has a supervisor, which is itself just an actor with a
//! actors and react when one of them terminates — restarting it (and, depending //! `Receiver<Signal>`. When a child actor terminates, the scheduler sends
//! on the strategy, some of its siblings) according to a policy, or giving up //! a `Signal` on the supervisor's channel. The supervisor decides what to
//! when failures arrive too fast. It is how you turn "an actor that might crash" //! do — restart, escalate, ignore.
//! into "a service that stays up": a crash becomes a restart instead of a hole
//! in the process tree.
//! //!
//! The supervisor type is [`OneForOne`]. The name is historical — the restart //! For v0.1 there is no built-in restart-intensity cap. That's policy and
//! *strategy* is selectable via [`OneForOne::strategy`], and //! lives in user code; library is mechanism only.
//! [`Strategy::OneForOne`] is merely the default. You declare the children up
//! front as [`ChildSpec`]s, each carrying a [`Restart`] policy, then hand the
//! supervision loop an actor of its own with [`OneForOne::run`].
//!
//! ## A child that crashes and recovers
//!
//! ```
//! use smarm::{run, spawn, ChildSpec, OneForOne, Restart};
//! use std::sync::Arc;
//! use std::sync::atomic::{AtomicUsize, Ordering};
//! use std::time::Duration;
//!
//! run(|| {
//! // A flaky child: it panics on its first two starts, then settles.
//! let starts = Arc::new(AtomicUsize::new(0));
//! let s = starts.clone();
//! let child = move || {
//! let n = s.fetch_add(1, Ordering::SeqCst) + 1;
//! if n < 3 {
//! panic!("boom {n}");
//! }
//! // The third start returns normally.
//! };
//!
//! // The supervisor runs on its own actor. `Transient` restarts a child
//! // that panics but treats a clean return as "done", so once the child
//! // finally succeeds the supervisor has nothing left to do and `run()`
//! // returns. smarm catches the child's panic and turns it into a restart;
//! // it never reaches the process as a real crash.
//! let sup = spawn(move || {
//! OneForOne::new()
//! .intensity(5, Duration::from_secs(60))
//! .child(ChildSpec::new(Restart::Transient, child))
//! .run();
//! });
//! sup.join().unwrap();
//!
//! assert_eq!(starts.load(Ordering::SeqCst), 3); // one start, two restarts
//! });
//! ```
//!
//! ## Restart policies
//!
//! Each child carries a [`Restart`] policy that decides whether *that child*
//! comes back when it terminates:
//!
//! - [`Restart::Permanent`] restarts on any termination, normal or panic —
//! for a service that should never be down.
//! - [`Restart::Transient`] restarts only on an abnormal exit (a panic or a
//! cooperative stop); a clean return means "done" — for work that runs to
//! completion but should be retried if it crashes.
//! - [`Restart::Temporary`] never restarts; the death is simply noted.
//!
//! ## Strategies: which siblings get cycled
//!
//! When a restart is due, the [`Strategy`] decides which *other* children are
//! cycled along with the one that died. The triggering child's own policy still
//! decides whether anything restarts at all.
//!
//! - [`Strategy::OneForOne`] restarts only the child that died — the default.
//! - [`Strategy::OneForAll`] restarts every child: the survivors are stopped,
//! then the whole set is restarted.
//! - [`Strategy::RestForOne`] restarts the dead child and every child started
//! after it, leaving earlier children untouched.
//!
//! ## Stopping a sibling is cooperative
//!
//! Cycling a sibling means stopping it first, and a supervisor never tears a
//! running actor down from outside: smarm actors share a heap and rely on
//! Drop/RAII, so unwinding a peer's stack from elsewhere would be unsound.
//! Instead the supervisor *requests* the stop and the child unwinds at its next
//! observation point — a `check!()`, an allocation, or a blocking call. A child
//! wedged in a tight loop with no observation point cannot be stopped, for the
//! same reason it cannot be preempted.
//!
//! ## Giving up: the restart-intensity cap
//!
//! A child that crashes the instant it starts would otherwise restart forever.
//! [`OneForOne::intensity`] bounds that: at most `max` restarts within any
//! `period`-long sliding window. One terminating child counts as a single
//! restart event even when the strategy cycles several siblings. When the cap
//! trips, the supervisor stops restarting, cooperatively stops any survivors in
//! reverse start order, and `run()` returns.
//!
//! ## Running context
//!
//! [`OneForOne::run`] takes over the calling actor as the supervision loop, so
//! a supervisor gets an actor of its own — typically
//! `spawn(|| OneForOne::new()/* … */.run())`, all from inside
//! [`run`](crate::run). Each child is spawned beneath the supervisor's pid, so
//! every child termination funnels back to it as a [`Signal`].
use crate::pid::Pid; use crate::pid::Pid;
use std::any::Any; use std::any::Any;
/// A child-termination notice delivered to its supervisor.
///
/// Every child a supervisor starts is spawned beneath the supervisor's pid, so
/// each child's termination funnels back to it as one of these. The variant
/// records *how* the child went — which is what its [`Restart`] policy keys off.
pub enum Signal { pub enum Signal {
/// The child exited normally. /// The child exited normally.
Exit(Pid), Exit(Pid),
@@ -140,6 +42,27 @@ impl Signal {
} }
} }
// ---------------------------------------------------------------------------
// One-for-one supervisor
//
// A supervisor is itself an actor. It spawns each child under its own pid so
// that every child death funnels into one mailbox (the `supervisor_channel`),
// then loops: receive a Signal, decide per the child's `Restart` policy
// whether to restart, and enforce a restart-intensity cap so a child that
// crashes in a tight loop eventually gives up instead of spinning forever.
//
// What this does NOT do: *forcibly* terminate a running child. smarm actors
// share a heap and rely on Drop/RAII, so tearing down a peer's stack from
// outside is unsound. Stopping a sibling — whether for `one_for_all` /
// `rest_for_one`, for a propagated link death, or for the ordered shutdown
// below — is therefore *cooperative*: `request_stop` flags the child and it
// unwinds at its next observation point. A child with no observation points
// (a tight loop with no `check!()`, allocation, or blocking op) cannot be
// stopped, exactly as it cannot be preempted. When the intensity cap trips,
// this supervisor stops restarting and tears the remaining children down in
// reverse start order before returning.
// ---------------------------------------------------------------------------
use crate::channel::channel; use crate::channel::channel;
use std::collections::{HashMap, VecDeque}; use std::collections::{HashMap, VecDeque};
use std::sync::Arc; use std::sync::Arc;
@@ -192,10 +115,11 @@ pub enum Strategy {
/// A supervisor over a fixed set of children. /// A supervisor over a fixed set of children.
/// ///
/// Build it with [`new`](Self::new), add children with [`child`](Self::child), /// Despite the name (kept for backwards compatibility), the restart strategy
/// pick a [`strategy`](Self::strategy) and an [`intensity`](Self::intensity) /// is selectable via [`OneForOne::strategy`]; the default is
/// cap, then drive the loop with [`run`](Self::run) on an actor of its own. See /// [`Strategy::OneForOne`]. Build with `new()`, add children with `child()`,
/// the [module docs](self) for the full picture. /// tune the cap with `intensity()`, then drive it with `run()` from inside an
/// actor (typically `spawn(|| OneForOne::new()....run())`).
pub struct OneForOne { pub struct OneForOne {
children: Vec<ChildSpec>, children: Vec<ChildSpec>,
strategy: Strategy, strategy: Strategy,
@@ -329,7 +253,7 @@ impl OneForOne {
.collect(), .collect(),
}; };
// Stop survivors in reverse start order (highest child index first). // Stop survivors in reverse start order (highest child index first).
to_stop.sort_unstable_by_key(|x| std::cmp::Reverse(x.1)); to_stop.sort_unstable_by(|a, b| b.1.cmp(&a.1));
// The set we will restart: the failed child plus every sibling we // The set we will restart: the failed child plus every sibling we
// are about to stop, restarted in start (ascending index) order. // are about to stop, restarted in start (ascending index) order.
@@ -375,7 +299,7 @@ impl OneForOne {
// and this is a no-op; on a cap-trip or mailbox-closed break it tears // and this is a no-op; on a cap-trip or mailbox-closed break it tears
// the remaining children down deterministically instead of leaking them. // the remaining children down deterministically instead of leaking them.
let mut survivors: Vec<(Pid, usize)> = by_pid.iter().map(|(p, i)| (*p, *i)).collect(); let mut survivors: Vec<(Pid, usize)> = by_pid.iter().map(|(p, i)| (*p, *i)).collect();
survivors.sort_unstable_by_key(|x| std::cmp::Reverse(x.1)); survivors.sort_unstable_by(|a, b| b.1.cmp(&a.1));
let mut awaiting: Vec<Pid> = Vec::with_capacity(survivors.len()); let mut awaiting: Vec<Pid> = Vec::with_capacity(survivors.len());
for (pid, _) in &survivors { for (pid, _) in &survivors {
crate::scheduler::request_stop(*pid); crate::scheduler::request_stop(*pid);
src/sync_shim.rs
-37
View File
@@ -1,37 +0,0 @@
//! std vs loom indirection for the modules that loom model-checks
//! (`slot_state`, `run_queue`). Everything else uses std paths directly —
//! the full runtime (context switches, futexes, real TLS) is not loom-able
//! and is never executed under `cfg(loom)`.
//!
//! Build the loom models with: `RUSTFLAGS="--cfg loom" cargo test --lib --release`
#[cfg(loom)]
pub(crate) use loom::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
#[cfg(not(loom))]
pub(crate) use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
/// `UnsafeCell` with loom's `with`/`with_mut` access API; pass-through cost
/// is zero in normal builds (`#[inline]`, newtype over std's cell).
#[cfg(loom)]
pub(crate) use loom::cell::UnsafeCell;
#[cfg(not(loom))]
pub(crate) struct UnsafeCell<T>(std::cell::UnsafeCell<T>);
#[cfg(not(loom))]
impl<T> UnsafeCell<T> {
pub(crate) fn new(v: T) -> Self {
Self(std::cell::UnsafeCell::new(v))
}
#[inline]
pub(crate) fn with<R>(&self, f: impl FnOnce(*const T) -> R) -> R {
f(self.0.get())
}
#[inline]
pub(crate) fn with_mut<R>(&self, f: impl FnOnce(*mut T) -> R) -> R {
f(self.0.get())
}
}
src/timer.rs
+22 -107
View File
@@ -15,14 +15,12 @@
//! `BinaryHeap` is a max-heap; entries are wrapped in `Reverse` to get //! `BinaryHeap` is a max-heap; entries are wrapped in `Reverse` to get
//! min-heap behaviour. //! min-heap behaviour.
//! //!
//! Cancellation is selective. A `Sleep` / `WaitTimeout` entry is left in the //! No cancellation. When a non-timer wakeup happens (e.g. lock granted
//! heap on a non-timer wakeup (lock granted before timeout): it is popped //! before timeout), the timer entry is left in the heap. It will be popped
//! eventually and no-ops because a stale unpark fails its epoch CAS — cheap //! eventually and the dispatch will observe "actor is no longer parked /
//! (~32 bytes per stale entry plus a few cycles on pop), bounded by one entry //! wait_seq is stale" and no-op. Cost is ~32 bytes per stale entry plus a
//! per parked actor. A `Send` entry is different: running its thunk delivers a //! few cycles on pop; acceptable given the upper bound is "one entry per
//! real message, so a stale one is *not* inert. `send_after` therefore carries //! parked actor".
//! true cancellation via the `armed` set keyed on the entry's `seq`; `pop_due`
//! fires a `Send` only while it is still armed, and `cancel` removes the arm.
//! //!
//! Stale pids (slot reused since the timer was inserted) are filtered on //! Stale pids (slot reused since the timer was inserted) are filtered on
//! pop by the scheduler — same convention as the run queue. //! pop by the scheduler — same convention as the run queue.
@@ -37,53 +35,19 @@ use std::time::{Duration, Instant};
/// ///
/// Held inside `Entry`, dispatched by the scheduler in `pop_due`. /// Held inside `Entry`, dispatched by the scheduler in `pop_due`.
pub enum Reason { pub enum Reason {
/// `sleep(d)`. Wake `pid` via the epoch-matched unpark: if anything /// `loom::sleep(d)`. Unpark `pid` unconditionally (modulo the usual
/// else (necessarily a terminal wake) already consumed the wait, the /// "still parked?" check the scheduler applies).
/// entry is stale and no-ops at the CAS. Sleep,
Sleep { epoch: u32 }, /// A bounded wait — currently only `Mutex::lock_timeout`. On expiry the
/// A bounded wait (`Mutex::lock_timeout`, `Receiver::recv_timeout`, /// scheduler calls `target.on_timeout(pid, wait_seq)`. The target then
/// `select_timeout`). On expiry the scheduler calls /// decides whether `pid` was actually still waiting, and if so unparks
/// `target.on_timeout(pid, epoch)`. The target then decides whether /// it with whatever error the wait was bounded for. `wait_seq` lets the
/// `pid` was actually still waiting (registration still present under /// target tell apart "this wait" from "a later wait by the same actor
/// its lock), and if so takes the registration and unparks via /// on the same target".
/// `unpark_at`. The epoch is the slot-word park-epoch — the runtime-wide
/// wait identity — so a stale entry is doubly inert: the registration
/// check misses, and even a racing unpark fails the word's epoch CAS.
WaitTimeout { WaitTimeout {
target: Arc<dyn TimerTarget>, target: Arc<dyn TimerTarget>,
epoch: u32, wait_seq: u64,
}, },
/// `send_after`: deliver a message to an address at the deadline,
/// cancellable. The destination (a `Pid<A>` / `Name<M>`) and the message
/// are captured inside `fire`, which resolves the address through the
/// registry and sends *when run* — so a target that died or, for a name,
/// was restarted is observed at fire time, not arm time. A failed resolve
/// or send is dropped (Erlang `erlang:send_after` semantics).
///
/// Unlike `Sleep` / `WaitTimeout`, a stale `Send` is **not** inert — running
/// the thunk delivers a real message — so these are the only timers that
/// carry true cancellation (the `armed` set on [`Timers`], keyed by the
/// entry's `seq`). `pop_due` fires the thunk only for an entry still armed.
Send { fire: Box<dyn FnOnce() + Send> },
}
/// Opaque handle to an armed `send_after` timer, returned by
/// [`Timers::insert_send`] and consumed by [`Timers::cancel`]. The inner value
/// is the entry's insertion `seq`; callers must treat it as opaque so the
/// backing structure can change (e.g. a future hierarchical timing wheel) with
/// no API churn.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TimerId(u64);
impl TimerId {
/// Wrap a raw value. Crate-internal: the gen_server timer layer mints its
/// own loop-local `TimerId`s (the public ids it hands out, decoupled from
/// the per-re-arm substrate `seq`) and maps them to live substrate ids.
/// These local ids are only ever resolved through that layer's registry —
/// never passed back to [`Timers::cancel`] — so the two id roles do not mix.
pub(crate) fn from_raw(v: u64) -> Self {
TimerId(v)
}
} }
/// Callback the scheduler invokes when a `WaitTimeout` entry pops. /// Callback the scheduler invokes when a `WaitTimeout` entry pops.
@@ -91,7 +55,7 @@ impl TimerId {
/// Implementors: do not touch `SchedulerState` other than via the public /// Implementors: do not touch `SchedulerState` other than via the public
/// `unpark` / channel APIs. The scheduler is mid-iteration when this fires. /// `unpark` / channel APIs. The scheduler is mid-iteration when this fires.
pub trait TimerTarget: Send + Sync { pub trait TimerTarget: Send + Sync {
fn on_timeout(&self, pid: Pid, epoch: u32); fn on_timeout(&self, pid: Pid, wait_seq: u64);
} }
pub struct Entry { pub struct Entry {
@@ -130,53 +94,18 @@ impl PartialOrd for Entry {
pub struct Timers { pub struct Timers {
/// Reverse-wrapped so the smallest deadline is at the top. /// Reverse-wrapped so the smallest deadline is at the top.
heap: BinaryHeap<Reverse<Entry>>, heap: BinaryHeap<Reverse<Entry>>,
/// Monotonic counter for the tiebreaker `seq` field (and the `TimerId` of a /// Monotonic counter for the tiebreaker `seq` field.
/// `Send` timer — the two are the same value).
next_seq: u64, next_seq: u64,
/// Presence set of *live* `Send` timers, keyed by `seq`. Populated on
/// `insert_send`, removed on fire (in `pop_due`) and on `cancel`. A `Send`
/// entry fires only while present, so a `cancel` that lands before the
/// entry pops prevents delivery; a `cancel` after it has fired finds
/// nothing (the race signal). Bounded by armed-but-not-yet-resolved timers
/// and self-collecting — no sweep. `Sleep` / `WaitTimeout` never touch it.
armed: std::collections::HashSet<u64>,
} }
impl Timers { impl Timers {
pub fn new() -> Self { pub fn new() -> Self {
Self { heap: BinaryHeap::new(), next_seq: 0, armed: std::collections::HashSet::new() } Self { heap: BinaryHeap::new(), next_seq: 0 }
} }
/// Insert a `Sleep` timer. Convenience for the common case. /// Insert a `Sleep` timer. Convenience for the common case.
pub fn insert_sleep(&mut self, deadline: Instant, pid: Pid, epoch: u32) { pub fn insert_sleep(&mut self, deadline: Instant, pid: Pid) {
self.insert(deadline, pid, Reason::Sleep { epoch }); self.insert(deadline, pid, Reason::Sleep);
}
/// Arm a cancellable `send_after` timer: run `fire` at `deadline` unless
/// [`cancel`](Self::cancel)led first. `pid` is informational only (the
/// destination, or who armed it — useful for introspection); it is *not*
/// used to wake anyone, the delivery lives entirely inside `fire`. Returns
/// a [`TimerId`] for cancellation.
pub fn insert_send(
&mut self,
deadline: Instant,
pid: Pid,
fire: Box<dyn FnOnce() + Send>,
) -> TimerId {
let seq = self.next_seq;
self.next_seq = self.next_seq.wrapping_add(1);
self.armed.insert(seq);
self.heap.push(Reverse(Entry { deadline, seq, pid, reason: Reason::Send { fire } }));
TimerId(seq)
}
/// Cancel an armed `send_after` timer. Returns `true` if the timer was
/// still armed (delivery is now prevented), `false` if it had already
/// fired or been cancelled. The heap entry, if still pending, is left to be
/// discarded when its deadline passes — `pop_due` drops any `Send` entry
/// whose `seq` is no longer armed.
pub fn cancel(&mut self, id: TimerId) -> bool {
self.armed.remove(&id.0)
} }
/// Insert an arbitrary timer entry. /// Insert an arbitrary timer entry.
@@ -195,7 +124,6 @@ impl Timers {
/// discarded so it can't keep the runtime alive. /// discarded so it can't keep the runtime alive.
pub fn clear(&mut self) { pub fn clear(&mut self) {
self.heap.clear(); self.heap.clear();
self.armed.clear();
} }
/// Soonest pending deadline, or `None` if the heap is empty. /// Soonest pending deadline, or `None` if the heap is empty.
@@ -205,24 +133,11 @@ impl Timers {
/// Pop every entry whose deadline is ≤ `now`, in deadline order. /// Pop every entry whose deadline is ≤ `now`, in deadline order.
/// The scheduler dispatches each entry by inspecting `entry.reason`. /// The scheduler dispatches each entry by inspecting `entry.reason`.
///
/// A due `Send` entry is returned only if it is still armed; a cancelled
/// one is silently dropped here (its `seq` was already removed from
/// `armed` by [`cancel`](Self::cancel)). Returning it removes it from
/// `armed`, so a later `cancel` of a fired timer reports `false`.
pub fn pop_due(&mut self, now: Instant) -> Vec<Entry> { pub fn pop_due(&mut self, now: Instant) -> Vec<Entry> {
let mut out = Vec::new(); let mut out = Vec::new();
while let Some(r) = self.heap.peek() { while let Some(r) = self.heap.peek() {
if r.0.deadline <= now { if r.0.deadline <= now {
let entry = match self.heap.pop() { out.push(self.heap.pop().unwrap().0);
Some(e) => e.0,
None => panic!("smarm: timer heap pop after peek returned None (core corrupt)"),
};
if matches!(entry.reason, Reason::Send { .. }) && !self.armed.remove(&entry.seq) {
// Cancelled before it came due: discard, do not deliver.
continue;
}
out.push(entry);
} else { } else {
break; break;
} }
src/trace.rs
+7 -25
View File
@@ -11,7 +11,7 @@
//! cargo test --test runtime <test_name> --features smarm-trace //! cargo test --test runtime <test_name> --features smarm-trace
//! //!
//! Output: smarm_trace.json in cwd, or $SMARM_TRACE_FILE. //! Output: smarm_trace.json in cwd, or $SMARM_TRACE_FILE.
//! View: <https://ui.perfetto.dev> or chrome://tracing //! View: https://ui.perfetto.dev or chrome://tracing
#[cfg(feature = "smarm-trace")] #[cfg(feature = "smarm-trace")]
#[macro_export] #[macro_export]
@@ -58,9 +58,6 @@ mod inner {
// Queue // Queue
Enqueue(Pid), Enqueue(Pid),
Dequeue(Pid), Dequeue(Pid),
// RFC 005 wake slot
SlotPush(Pid), // actor-context wake parked in the waking thread's slot
SlotPop(Pid), // scheduler resumed a pid from its own slot
} }
// ----------------------------------------------------------------------- // -----------------------------------------------------------------------
@@ -101,7 +98,7 @@ mod inner {
thread_local! { thread_local! {
static LOCAL_STATE: std::cell::RefCell<Option<LocalState>> = static LOCAL_STATE: std::cell::RefCell<Option<LocalState>> =
const { std::cell::RefCell::new(None) }; std::cell::RefCell::new(None);
} }
// ----------------------------------------------------------------------- // -----------------------------------------------------------------------
@@ -115,20 +112,14 @@ mod inner {
let (tx, rx) = mpsc::channel::<Msg>(); let (tx, rx) = mpsc::channel::<Msg>();
let start = Instant::now(); let start = Instant::now();
match GLOBAL.lock() { *GLOBAL.lock().unwrap() = Some(Global { sender: tx, start });
Ok(mut g) => *g = Some(Global { sender: tx, start }),
Err(e) => panic!("smarm: trace lock poisoned (core corrupt): {e}"),
}
// Drain thread: owns the Receiver, writes to disk. // Drain thread: owns the Receiver, writes to disk.
let path_for_thread = path.clone(); let path_for_thread = path.clone();
match std::thread::Builder::new() std::thread::Builder::new()
.name("smarm-trace-drain".into()) .name("smarm-trace-drain".into())
.spawn(move || drain_thread(rx, &path_for_thread)) .spawn(move || drain_thread(rx, &path_for_thread))
{ .expect("failed to spawn trace drain thread");
Ok(_) => {}
Err(e) => panic!("smarm: failed to spawn trace drain thread: {e}"),
}
eprintln!("[smarm-trace] writing to {}", path); eprintln!("[smarm-trace] writing to {}", path);
} }
@@ -139,10 +130,7 @@ mod inner {
// Drop the global sender so the drain thread's recv() returns Err // Drop the global sender so the drain thread's recv() returns Err
// after the Flush sentinel, signalling clean shutdown. // after the Flush sentinel, signalling clean shutdown.
let sender = { let sender = {
let mut g = match GLOBAL.lock() { let mut g = GLOBAL.lock().unwrap();
Ok(g) => g,
Err(e) => panic!("smarm: trace lock poisoned (core corrupt): {e}"),
};
g.take().map(|g| g.sender) g.take().map(|g| g.sender)
}; };
if let Some(tx) = sender { if let Some(tx) = sender {
@@ -171,11 +159,7 @@ mod inner {
let mut opt = cell.borrow_mut(); let mut opt = cell.borrow_mut();
// Lazily initialise: one mutex hit per thread, ever. // Lazily initialise: one mutex hit per thread, ever.
if opt.is_none() { if opt.is_none() {
let guard = match GLOBAL.lock() { if let Some(g) = GLOBAL.lock().unwrap().as_ref() {
Ok(g) => g,
Err(e) => panic!("smarm: trace lock poisoned (core corrupt): {e}"),
};
if let Some(g) = guard.as_ref() {
let tx = g.sender.clone(); let tx = g.sender.clone();
*opt = Some(LocalState { tx, start: g.start }); *opt = Some(LocalState { tx, start: g.start });
} }
@@ -253,8 +237,6 @@ mod inner {
Event::RecvWake(p) => ("recv_wake".into(), p.index()), Event::RecvWake(p) => ("recv_wake".into(), p.index()),
Event::Enqueue(p) => ("enqueue".into(), p.index()), Event::Enqueue(p) => ("enqueue".into(), p.index()),
Event::Dequeue(p) => ("dequeue".into(), p.index()), Event::Dequeue(p) => ("dequeue".into(), p.index()),
Event::SlotPush(p) => ("slot_push".into(), p.index()),
Event::SlotPop(p) => ("slot_pop".into(), p.index()),
} }
} }
task.md
+263
View File
@@ -0,0 +1,263 @@
# smarm — task.md (next steps)
Handoff for a future session reusing this sandbox. Read top to bottom once
before starting; the gotchas section is hard-won and will save you a faceplant.
## Resume the environment
- Repo: `smarm`. Two branches (the old single `arm-port` stack was split):
- `master` — the mainline, and HEAD. Carries roadmap #1–#5: cooperative
cancellation, supervisor strategies (one_for_one/all, rest_for_one) + the
orphaned-timer shutdown fix, links/trap_exit, selective receive, gen_server,
and demonitor/`MonitorId`. Tagged `v0.4.0`. x86-64 Linux only.
- `arm-port` — `master` plus a single commit: `feat(arch): aarch64 context
switch + cycle counter`. Extracts the x86-64 context-switch / stack-init /
cycle-counter out of `context.rs` into a `target_arch`-gated `src/arch/`
(x86_64 + aarch64 backends) and adds an AAPCS64 backend. ⚠️ UNTESTED: never
built or run on real ARM hardware. The x86-64 path is unchanged
(`arch/x86_64.rs` is the old `context.rs` body verbatim), so the x86 suite
passing says nothing about the aarch64 backend. Build + test on-device
before trusting it.
- Toolchain is installed but NOT on PATH in a fresh shell. First line of every
session: `. "$HOME/.cargo/env"` (rustc/cargo 1.96).
- Build `cargo build` · all tests `cargo test` · one suite `cargo test --test monitor`.
- Bench probe `cargo bench --bench general` (custom print-only harness; compiles
tokio in release the first time — slow — but `target/` persists across git
checkouts so it's paid once).
- Perf regression check: `git checkout <pre-change-sha>` →
`cargo bench --bench general | tee before.txt` → `git checkout arm-port` →
run again → diff the `smarm 1-thread` medians for `chained_spawn` and
`yield_many` (those exercise spawn/finalize/scheduler). Numbers are noisy on
this shared CPU; treat as "regression beyond noise?" not a precise delta.
## Roadmap (dependency order)
### 1. Cooperative cancellation — the keystone ✅ DONE (`a8ddb4a`)
Everything below (one_for_all/rest_for_one, links) needs a *safe* way to stop a
running peer. Forcible teardown of another green thread's stack is unsound here
(shared heap + Drop). So: cooperative stop the actor observes and unwinds itself.
Shipped as designed (sentinel unwind, not Result-threading). Notes for what
came next / future readers:
- Stop flag lives on `Actor` behind `Arc<AtomicBool>` (fresh per spawn), NOT a
`Slot` field — sidesteps the three-place reset, at the cost of one small
alloc per spawn. The scheduler hands the resume path a raw `*const AtomicBool`
(no per-resume refcount traffic); `yield_many` bench stayed at baseline,
`chained_spawn` ~+6% from that alloc (left as-is; move to a `Slot` field if it
ever matters).
- Observation points: amortised `maybe_preempt`/`check!()` path + the wakeup
side of `park_current`/`yield_now`. Sentinel = `StopSentinel` (zero-size),
recognised in the trampoline → `Outcome::Stopped`. `join()` on a stopped actor
returns `Ok(())` (no payload to propagate; reason is on the monitor channel).
- Documented gaps confirmed by tests: no-observation-point loop can't be stopped
(same as preemption); a user `catch_unwind` can swallow the sentinel but the
flag stays set so the next yield re-raises.
Original plan, for reference:
- Add a per-actor stop flag (Slot field + atomic, or check via shared state).
- `request_stop(pid)`: set the flag, unpark if parked.
- Realize the stop as a **controlled unwind**: when the scheduler resumes a
stop-requested actor, inject a sentinel panic (dedicated payload type) so the
existing `trampoline` `catch_unwind` tears the stack down and runs Drop. The
trampoline recognizes the sentinel and reports a new `Outcome::Stopped`
(distinct from a user `Panic`). This avoids changing every blocking-op
signature.
- Alternative considered: thread `Result<_, Cancelled>` through recv/sleep/
lock/io. Rejected — large API churn. Go with the sentinel unwind.
- Caveat to document: user code with its own `catch_unwind` can swallow the
sentinel (cf. Erlang `catch`); re-check the flag at the next yield and/or
re-raise. And a tight no-alloc loop without `check!()` can't be stopped —
same inherent limitation as preemption.
- Observation points: `maybe_preempt()`/`check!()` (cheap flag check) and the
blocking parks (recv/sleep/mutex/io) on the stop-driven unpark.
- Tests: looping actor on `check!()` gets stopped → `Outcome::Stopped`, Drop
guards ran; parked-on-recv actor gets stopped; no-check loop documents the gap.
### 2. one_for_all / rest_for_one + ordered shutdown ✅ DONE (`351dc9c`)
Shipped. What landed vs the plan:
- `Strategy::{OneForOne,OneForAll,RestForOne}` selected via `.strategy()`,
default `OneForOne`. The struct keeps the `OneForOne` name (compat; existing
tests untouched) — a rename to `Supervisor` is a deferred refactor.
- The *triggering* child's `Restart` policy decides whether anything restarts;
the strategy decides which live siblings are cycled (all / index-> after the
failed one). Survivors are `request_stop`'d in reverse start order, awaited on
the existing `supervisor_channel` funnel (no new channel, no `select`),
restarted in start order. One failure = one intensity tick regardless of group
size. Out-of-band signals during an await are stashed and replayed.
- `Signal::Stopped(pid)` + `DownReason::Stopped` added (kept distinct from Exit,
as planned). A `Stopped` signal counts as abnormal for the restart decision.
- Ordered shutdown: on cap-trip / mailbox-close-with-survivors, stop remaining
children in reverse start order and await them (no-op on the normal exit).
- ⚠️ Surfaced + fixed a latent keystone bug (`e80334b`): a cancelled
sleeping/timeout actor orphans its timer entry, and the scheduler's shutdown
check counted pending timers → `run()` hung until the dead actor's deadline
fired (a `sleep(30s)` sleeper hung shutdown 30s). Fix: timers no longer gate
shutdown (`live == 0` already implies nothing a timer could wake); heap is
cleared on exit. Independent of the supervisor work.
- Tests: all-restart (sibling cycled despite clean exit), suffix-restart
(prefix child left alone), reverse-order teardown.
Original plan, for reference:
- one_for_all: on any child failure, `request_stop` all siblings, await their
termination signals, restart all per spec.
- rest_for_one: stop+restart the failed child and those started after it.
- Supervisor shutdown: stop children in reverse start order.
- Decide signal surface: add `Signal::Stopped(pid)` + `DownReason::Stopped`
rather than folding into Exit (clearer for the supervisor's await logic).
- Tests: all-restart, suffix-restart, reverse-order shutdown.
### 3. Links + trap_exit ✅ DONE (`6581484`)
- `Slot.links: Vec<Pid>` (bidirectional); `link`/`unlink`; `trap_exit()` flag
lives on `Actor` (fresh per spawn → a restarted child starts un-trapped, and
no fourth slot-reset site).
- On finalize, reverse links are cleared under the lock (always — keeps the
cascade acyclic), then for each linked peer: abnormal death (`Panic`/
`Stopped`) → `request_stop(peer)` unless peer traps, in which case deliver an
`ExitSignal` *message* instead. Normal exit does NOT propagate. Linking an
already-dead pid delivers an immediate `NoProc` signal (message if trapping,
else `request_stop(self)` — not a silent no-op).
- Resolved: the trap inbox is a **dedicated** channel (`trap_exit() ->
Receiver<ExitSignal>`), distinct from the monitor `Down` channel; `ExitSignal`
reuses `DownReason` and carries no panic payload (joiner-only, as with
monitors). `spawn_link` deferred to #5.
- Tests (`tests/link.rs`): linked pair one panics → other stopped (+Drop ran);
trap_exit → other gets a message and survives; normal exit doesn't propagate;
dead-pid link stops a non-trapper / messages a trapper; `unlink` prevents
propagation.
### 4. Selective receive (independent track) ✅ DONE (`03f3875`)
Shipped. What landed vs the plan:
- `Receiver::recv_match(pred) -> Result<T, RecvError>` scans the queued
`VecDeque` front-to-back, removes+returns the first match, leaves the rest in
arrival order; parks and re-scans when nothing matches. `try_recv_match` (the
non-blocking variant, mirroring `try_recv`) rolled in same commit.
- Wakeup turned out cheaper than feared: `Sender::send` *already* took
`parked_receiver` on every push, so "wake on ANY send" needed no send-side
change. The one real edit was relaxing `Sender::drop` to unpark the parked
receiver on the last-sender drop regardless of queue emptiness — a selective
receiver can park on a non-empty no-match queue and must wake to observe
closure. No-op for plain `recv` (only ever parks on an empty queue); stress
suite stays green.
- `pred` is `Fn(&T) -> bool` (not `FnMut`) on purpose: it's re-run from scratch
on every scan, so a stateful predicate would re-count surprisingly. It runs
under the channel lock — keep it cheap/pure, don't re-enter the channel.
- Close semantics: `recv_match` returns `Err(RecvError)` only when closed AND no
queued message matches; a match is still returned on a closed channel.
Non-matches are left for a later `recv`.
- Tests (`tests/selective_recv.rs`): out-of-order match pulled first; non-matches
remain in order; park-on-non-empty then wake on a match; closed-with-only-
non-matches → Err; closed-but-match-present → match; `try_recv_match` states.
Original plan, for reference:
- Add `Receiver::recv_match(pred) -> T`: scan the queued `VecDeque`, remove+return
first match, leave the rest in order; park and re-scan on new arrivals.
- This changes channel wakeup: a parked selective receiver must wake on ANY send
(not just empty→nonempty) and re-scan. Touches `channel.rs` carefully — the
stress tests guard lost-wakeup invariants; keep them green.
- Tests: messages arrive out of interest-order; match pulled first; non-matches
remain for a later `recv`.
### 5. Grab-bag (each its own small commit)
- `spawn_link`: spawn-and-link atomically (deferred from #3); thin wrapper over
`spawn_under` + `link`, but do it under one lock so there's no window where
the child dies before the link is recorded.
- `demonitor`: needs a per-monitor id to remove a specific sender. Decide the
monitor API NOW before more code depends on it — likely return a
`Monitor { id, rx }` instead of a bare `Receiver<Down>`.
✅ DONE (this commit). What landed vs the plan:
- `monitor()` now returns `Monitor { id, target, rx }` (added `target` over
the sketched `{id, rx}` so `demonitor` jumps straight to the slot instead of
scanning every slot for the id). `MonitorId(u64)` is opaque, from a
monotonic `next_monitor_id` counter on `SharedState`, bumped under the
shared lock in `monitor()` — no atomics, deterministic, never reused.
- `Slot.monitors: Vec<(MonitorId, Sender<Down>)>`. The three slot-reset sites
were untouched — they `.clear()`/`Vec::new()`, which is element-type-
agnostic, so no new reset obligation. `finalize_actor` just destructures
`(_, m)` and sends as before.
- `demonitor(&Monitor) -> Option<MonitorId>`: `Some(id)` when a live
registration was found+removed, `None` when it had already fired (drained on
finalize), was `NoProc`, or the slot was reclaimed. Chose `Option<MonitorId>`
over a bare bool — names which registration went. Generation half of the pid
makes a stale demonitor a clean no-op: a recycled slot index fails
`slot_mut`'s generation check, so it can never strip a different actor's
monitor.
- ⚠️ Reentrancy: the removed `Sender` is `remove`d out of the Vec under the
lock but **dropped after the lock is released** — `Sender::drop` can unpark a
parked receiver → `with_shared`, and the shared mutex is non-reentrant. Same
discipline as `finalize_actor`.
- "Flush" (discard a `Down` the target already queued) falls out of dropping
the `Monitor`: `demonitor(&m); drop(m)`. That's the cleanup the still-to-come
gen_server **call timeout** wants — monitor the server, wait reply-or-Down-
or-deadline, then demonitor+drop so a timed-out call leaks no registration
and no stale `Down`.
- Perf: touches `Slot` + `finalize_actor`, but `chained_spawn`/`yield_many`
register no monitors, so the Vec stays empty (take-empty is identical cost,
finalize loop runs zero times). before/after `general` probe medians within
noise. Tests (`tests/monitor.rs`): demonitor-stops-delivery, one-of-many
(siblings untouched), after-fire-is-None.
- Named registry: `register(name,pid)`/`whereis`/`send_by_name`; a
`HashMap<String,Pid>` in `SharedState`.
- gen_server-style call/cast: request-reply correlation as a thin layer over
channels (`call` sends `{req, reply_tx}`, awaits `reply_rx`); no runtime change.
✅ DONE (`a4fcf6c`). What landed vs the plan:
- `GenServer` trait on the state value: assoc `Call`/`Reply`/`Cast` types,
required `handle_call`/`handle_cast`, optional `init`/`terminate` hooks.
`ServerRef<G>` is a clonable inbox sender + `pid()`; `start` / `start_under`.
- One inbox, not two: a single `Envelope { Call(req, reply_tx) | Cast }`
channel, dispatched by variant. Forced by no-`select`/no-unified-mailbox —
a server can't wait on a call channel and a cast channel at once.
- Server-down falls out of channel closure (no monitor needed): `send` fails
if the inbox is gone; the reply sender drops on the server's unwind so a
parked caller wakes to `Err`. Both → `Call/CastError::ServerDown`.
- `terminate` runs via a drop guard → fires on *every* exit path (clean inbox
close, handler panic, `request_stop`), not just the clean one. Caveat: it
may run mid-unwind, so keep it non-blocking (a panic inside it during an
unwind double-panics → abort).
- No `handle_info`, no call timeout — both deferred to land with timeouts
(`handle_info` needs the still-unmade cross-channel mailbox merge; a call
timeout needs a per-`recv` deadline / `Signal::Timeout`).
- Pure additive layer (no Slot/scheduler/spawn/finalize change) → no perf
check run. Tests (`tests/gen_server.rs`): cast→call roundtrip, init/terminate
ordering, both server-down paths.
- Docs: README now points at the experimental, untested aarch64 port on the
`arm-port` branch. The module table still calls `context` x86-64-only — true
for `master`, since the `src/arch/` split rides on `arm-port`. Fold the arch/
split and ARM64-supported wording into the README module table + build section
once `arm-port` is validated on hardware and merged.
## Gotchas / invariants (respect these)
- **Shared mutex is non-reentrant.** `Sender::send` can call `unpark` →
`with_shared`. NEVER send on a channel while holding the shared lock. Pattern:
`mem::take` the senders/data under the lock, send after releasing. See
`finalize_actor` (supervisor signal + monitor Downs both sent post-lock).
- **`finalize_actor` order:** take stack/waiters/monitors under lock + set
Done/outcome → recycle stack (post-lock) → deliver supervisor Signal + monitor
Downs (post-lock) → unpark joiners → reclaim slot iff `outstanding_handles==0`.
Death notifications always precede reclamation, so a pid carried in a
Signal/Down is still matchable even as its slot is about to be reused.
- **Slot lifecycle is reset in THREE places** — `Slot::vacant()`,
`reclaim_slot()` (runtime.rs), and the slot-init block in `spawn_under`
(scheduler.rs). Any new Slot field must be reset in all three (monitors was).
- **Pid = (index, generation);** stale handles caught by generation mismatch in
`slot()/slot_mut()`. The monitor `NoProc` path relies on this.
- **No `select`, no unified per-process mailbox.** Why the supervisor uses the
single `supervisor_channel` funnel rather than N monitor channels. trap_exit
resolved this by giving each trapping actor a dedicated `Receiver<ExitSignal>`
inbox (see #3); selective receive (#4) stayed *per-channel* (`recv_match`
scans one channel's queue) rather than introducing a cross-channel mailbox —
if selective receive ever needs to span the monitor/trap inboxes too, that
cross-channel merge is the still-unmade decision.
- **Cooperative-only**: preemption and (future) cancellation both depend on the
actor reaching `check!()`/yield/alloc/blocking points.
- `run()` is single-thread (`Config::exact(1)`); tests rely on deterministic
single-thread ordering (parent runs until it parks). Multi-thread via
`runtime::init(Config…)`.
## Workflow expectations (from the human)
- TDD: write the failing test first, then implement.
- Commit incrementally with conventional-commit messages; keep each commit a
reviewable unit (they diff in their IDE and are the filter to the codebase).
- Run the full suite before each commit; check perf when a change touches
Slot/scheduler/spawn/finalize hot paths.
tests/README.md
-120
View File
@@ -1,120 +0,0 @@
# Tests
Integration tests for the runtime. Each file owns one feature area or one
class of bug. Everything here runs under plain `cargo test`; the loom model
tests are the exception — they live **in the library** (`src/slot_state.rs`,
`src/run_queue.rs`), not in this directory, because loom must compile the
production code with shimmed atomics (see "Loom" below).
## Running
```
cargo test # debug build — RUN THIS ONE: all invariant asserts live
cargo test --release # what users actually execute (LTO, no debug_asserts)
```
Debug builds are not just "slower tests": the runtime self-checks its
invariants only there — every `StateWord` transition asserts its
precondition, `enqueue` asserts the exact `(gen, Queued)` word, `RawMutex`
enforces the never-two-cold-locks leaf rule with a per-thread held-count,
`live_actors` checks for double-finalize underflow. A green release run with
a red debug run means an invariant broke without (yet) corrupting behavior —
treat it as a real failure.
### The queue-variant matrix
The run queue is compile-time selected; the suite must pass under all three
(features are additive, so drop the default first):
```
cargo test # rq-mutex (default)
cargo test --no-default-features --features rq-mpmc
cargo test --no-default-features --features rq-striped
```
### Loom (model checking)
```
RUSTFLAGS="--cfg loom" cargo test --lib --release
```
Exhaustively explores interleavings of the slot state machine
(`src/slot_state.rs`: lost-wakeup, at-most-once-enqueue, the stale-pid ABA
theorem, unpark-vs-claim) and the ring queues (`src/run_queue.rs`:
exactly-once through lap wraparound, push/pop races). Models run the
production transitions through `src/sync_shim.rs` — std atomics normally,
`loom::sync` under `--cfg loom`. `RawMutex` is deliberately not modeled:
futexes can't be, and it's the textbook Drepper mutex3 with stress and
unwind-safety tests of its own.
### Trace feature
`cargo test --features smarm-trace` exists mainly to catch bit-rot in the
`te!()` call sites; run it after touching scheduler paths.
### Before a runtime-core PR
The full matrix, in rough order of bug-finding power per minute:
1. `cargo test` (debug, default variant)
2. debug under `rq-mpmc` and `rq-striped`
3. `cargo test --release`
4. loom
5. `cargo build --features smarm-trace`
## Catalog
**Low-level units (no scheduler)**
| file | covers |
|---|---|
| `context.rs` | `init_actor_stack` + the naked-asm context-switch shims, poked directly |
| `stack.rs` | the mmap'd stack allocator |
| `pid.rs` | pid packing/equality |
**Feature areas (run under a real runtime)**
| file | covers |
|---|---|
| `runtime.rs` | `Config`, `Runtime::run`, re-running a runtime, correctness under genuine parallelism |
| `scheduler.rs` | spawn / join / panic delivery / `yield_now` / `self_pid` |
| `channel.rs` | send/recv (recv parks, so these need the runtime) |
| `selective_recv.rs` | `recv_match` / `try_recv_match` |
| `mutex.rs` | the actor-blocking `Mutex<T>` (lock parks) |
| `timer.rs` | `sleep` ordering — time-sensitive, generous tolerances by design |
| `io.rs` | `block_on_io`: blocking closures on the pool while the actor parks |
| `io_epoll.rs` | `wait_readable` / `wait_writable` + the `read`/`write` sugar |
| `preempt.rs` | explicit preemption via `smarm::check!()` |
| `cancel.rs` | cooperative cancellation (`request_stop`) — the keystone semantics |
| `monitor.rs` | `monitor` delivers exactly one `Down`; `demonitor` |
| `link.rs` | bidirectional links + `trap_exit` |
| `supervisor.rs` | one-for-one supervision |
| `gen_server.rs` | call/cast round-trips, lifecycle callbacks, server-down detection |
**Regression & stress**
| file | covers |
|---|---|
| `stress.rs` | lost wakeups, pid-table pressure, thundering herds, panic isolation under concurrency. Where the phase-2 RefCell-migration bug was caught. |
| `poison_stop.rs` | `request_stop` racing an alloc-under-lock must not poison/abort. See its header for the full story. |
| `many_timers_multi_thread.rs` | multi-thread sleep-timer lost-wakeup regression |
## Conventions
- **Each test owns its runtime.** `init(Config::exact(N))` + `rt.run(...)`;
never share a `Runtime` between tests. Oversubscription (`exact(4)` on one
core) is deliberate — forced interleaving at yield points is how
single-core CI finds races at all.
- **Regression tests must be validated against the bug.** A regression test
that passes with the bug reintroduced is documentation, not a test.
Reintroduce the fix's inverse locally and watch it fail before trusting it
(`poison_stop.rs` went through exactly this: its first version never fired
the sentinel under a lock, and was rewritten until it SIGABRT'd pre-fix).
- **Stochastic tests get the odds stacked.** Use `Config::alloc_interval(1)`
to make every allocation an observation point, many actors, and both
phases of any every-other-allocation cadence (see
`poison_stop::self_stop_during_spawn...`).
- **Time-based assertions use ordering, not durations.** Assert
"didn't return instantly" / "A woke before B", with generous tolerances;
CI machines are slow and noisy.
- New invariants added to the runtime should come with the assert at the
point of reliance (debug_assert on hot paths) *and*, where the invariant is
a protocol, a loom model in the owning module — that combination is what
made phases 2–5 land without a single post-merge race so far.
tests/cancel.rs
-58
View File
@@ -130,61 +130,3 @@ fn join_on_stopped_actor_returns_ok() {
assert!(h.join().is_ok(), "join on a stopped actor returns Ok(())"); assert!(h.join().is_ok(), "join on a stopped actor returns Ok(())");
}); });
} }
/// Regression: `request_stop` against a QUEUED actor must not be lossy.
///
/// The stop flag is set, but the wildcard unpark no-ops on a Queued actor
/// (the pending run "is" the wake). If the actor's first action on resume
/// is a blocking park — no allocation, no `check!()` on the way — a
/// wake-side-only check in `park_current` never runs: the actor parks with
/// the stop flag already set, and nothing will ever wake it. The runtime
/// then idles forever (the root is parked on the monitor channel).
///
/// Fix: an entry-side `check_cancelled` in `park_current`. The remaining
/// window (flag set after the entry check, before the park lands) is closed
/// by the existing protocol: the stop's unpark then finds Running /
/// the prep-to-park window, sets Notified, and the park-return re-queues
/// into the wake-side check.
///
/// Watchdog harness: without the fix this deadlocks, so the runtime runs on
/// a side thread and the test fails on a timeout instead of hanging cargo.
#[test]
fn stop_flagged_while_queued_lands_at_first_park() {
use std::sync::mpsc;
use std::time::Duration;
let dropped = Arc::new(AtomicBool::new(false));
let saw_stopped = Arc::new(AtomicBool::new(false));
let (d, s) = (dropped.clone(), saw_stopped.clone());
let (done_tx, done_rx) = mpsc::channel::<()>();
std::thread::spawn(move || {
let rt = smarm::init(smarm::Config::exact(1));
rt.run(move || {
let h = spawn(move || {
let _g = DropFlag(d);
let (tx, rx) = channel::<u8>();
let _keep = tx; // keep the channel open: recv() parks
let _ = rx.recv(); // first observation point is this park
});
let pid = h.pid();
let down = monitor(pid);
// Stop while the child is still QUEUED — before it ever runs.
// The unpark no-ops; only the flag is left behind.
request_stop(pid);
let dn = down.rx.recv().expect("monitor channel closed before Down");
assert_eq!(dn.pid, pid);
if matches!(dn.reason, DownReason::Stopped) {
s.store(true, Ordering::SeqCst);
}
let _ = h.join();
});
let _ = done_tx.send(());
});
done_rx
.recv_timeout(Duration::from_secs(10))
.expect("runtime deadlocked: stop against a QUEUED actor was lost at its first park");
assert!(saw_stopped.load(Ordering::SeqCst), "expected DownReason::Stopped");
assert!(dropped.load(Ordering::SeqCst), "Drop guard must run during the cancellation unwind");
}
tests/channel.rs
-186
View File
@@ -108,189 +108,3 @@ fn recv_returns_err_when_all_senders_dropped() {
assert!(saw_err.load(std::sync::atomic::Ordering::SeqCst)); assert!(saw_err.load(std::sync::atomic::Ordering::SeqCst));
} }
#[test]
fn channel_ops_interleaved_with_monitor_churn_multi_thread() {
// Regression for the RawMutex migration: monitor registration clones the
// Down sender under the target's cold (Leaf) lock, which now nests a
// Channel-class lock under it. Debug builds enforce the Leaf -> Channel
// ordering on every acquisition, so driving channels, monitors, and actor
// death concurrently across schedulers makes any ordering regression
// panic here rather than deadlock in the field.
use std::sync::atomic::{AtomicI64, Ordering};
use std::sync::Arc;
let total = Arc::new(AtomicI64::new(0));
let total2 = total.clone();
smarm::init(smarm::Config::exact(4)).run(move || {
let (tx, rx) = channel::<i64>();
let consumer = spawn(move || {
let mut sum = 0;
while let Ok(v) = rx.recv() {
sum += v;
}
OUT.with(|c| c.set(sum)); // not asserted cross-thread; see total
total2.fetch_add(sum, Ordering::Relaxed);
});
let mut handles = Vec::new();
for i in 0..32i64 {
let tx = tx.clone();
handles.push(spawn(move || {
// Short-lived target whose death fires the monitor below.
let t = spawn(move || {
tx.send(i).unwrap();
});
let m = smarm::monitor(t.pid());
t.join().unwrap();
// Down delivery exercises send-from-finalize.
let d = m.rx.recv().unwrap();
assert_eq!(d.reason, smarm::DownReason::Exit);
}));
}
drop(tx);
for h in handles {
h.join().unwrap();
}
consumer.join().unwrap();
});
assert_eq!(total.load(std::sync::atomic::Ordering::Relaxed), (0..32).sum::<i64>());
}
// ---------------------------------------------------------------------------
// recv_timeout
// ---------------------------------------------------------------------------
use smarm::RecvTimeoutError;
use std::time::{Duration, Instant};
#[test]
fn recv_timeout_returns_queued_message_immediately() {
run(|| {
let (tx, rx) = channel::<i64>();
tx.send(5).unwrap();
assert_eq!(rx.recv_timeout(Duration::from_secs(10)), Ok(5));
});
}
#[test]
fn recv_timeout_times_out_on_silent_channel() {
run(|| {
let (_tx, rx) = channel::<i64>();
let start = Instant::now();
let r = rx.recv_timeout(Duration::from_millis(50));
assert_eq!(r, Err(RecvTimeoutError::Timeout));
assert!(start.elapsed() >= Duration::from_millis(50));
});
}
#[test]
fn recv_timeout_wakes_promptly_on_send() {
run(|| {
let (tx, rx) = channel::<i64>();
let h = spawn(move || {
let start = Instant::now();
assert_eq!(rx.recv_timeout(Duration::from_secs(10)), Ok(9));
// Far below the timeout: the send woke us, not the deadline.
assert!(start.elapsed() < Duration::from_secs(1));
});
smarm::yield_now();
tx.send(9).unwrap();
h.join().unwrap();
});
}
#[test]
fn recv_timeout_reports_disconnected_on_close() {
run(|| {
let (tx, rx) = channel::<i64>();
let h = spawn(move || {
assert_eq!(
rx.recv_timeout(Duration::from_secs(10)),
Err(RecvTimeoutError::Disconnected)
);
});
smarm::yield_now();
drop(tx);
h.join().unwrap();
});
}
#[test]
fn recv_timeout_zero_duration_is_a_bounded_poll() {
run(|| {
let (_tx, rx) = channel::<i64>();
assert_eq!(rx.recv_timeout(Duration::ZERO), Err(RecvTimeoutError::Timeout));
});
}
#[test]
fn channel_remains_usable_after_a_timeout() {
// The stale timer entry from the first (timed-out) wait must not cancel
// or corrupt later waits — seq isolation.
run(|| {
let (tx, rx) = channel::<i64>();
assert_eq!(
rx.recv_timeout(Duration::from_millis(10)),
Err(RecvTimeoutError::Timeout)
);
// Plain recv still works...
tx.send(1).unwrap();
assert_eq!(rx.recv(), Ok(1));
// ...and so does a second bounded wait, woken by a send.
let h = spawn(move || {
tx.send(2).unwrap();
});
assert_eq!(rx.recv_timeout(Duration::from_secs(10)), Ok(2));
h.join().unwrap();
});
}
#[test]
fn recv_timeout_many_waiters_multi_thread() {
// Mixed outcomes under real parallelism: half the channels get fed,
// half time out; every actor must resolve correctly.
use std::sync::atomic::{AtomicU32, Ordering};
use std::sync::Arc;
let got = Arc::new(AtomicU32::new(0));
let timed_out = Arc::new(AtomicU32::new(0));
let (got2, timed_out2) = (got.clone(), timed_out.clone());
smarm::init(smarm::Config::exact(4)).run(move || {
let mut handles = Vec::new();
for i in 0..24i64 {
let (tx, rx) = channel::<i64>();
let got = got2.clone();
let timed_out = timed_out2.clone();
handles.push(spawn(move || match rx.recv_timeout(Duration::from_millis(100)) {
Ok(v) => {
assert_eq!(v, i);
got.fetch_add(1, Ordering::Relaxed);
}
Err(RecvTimeoutError::Timeout) => {
timed_out.fetch_add(1, Ordering::Relaxed);
}
Err(e) => panic!("unexpected: {e}"),
}));
if i % 2 == 0 {
handles.push(spawn(move || {
tx.send(i).unwrap();
}));
}
// odd i: tx drops here -> Disconnected, not Timeout! Keep it alive
// instead by leaking the sender into a holder actor that outlives
// the deadline.
else {
handles.push(spawn(move || {
smarm::sleep(Duration::from_millis(200));
drop(tx);
}));
}
}
for h in handles {
h.join().unwrap();
}
});
assert_eq!(got.load(std::sync::atomic::Ordering::Relaxed), 12);
assert_eq!(timed_out.load(std::sync::atomic::Ordering::Relaxed), 12);
}
tests/context.rs
+34
View File
@@ -58,6 +58,7 @@ use std::sync::OnceLock;
static REG_BEFORE: OnceLock<[u64; 4]> = OnceLock::new(); static REG_BEFORE: OnceLock<[u64; 4]> = OnceLock::new();
static REG_AFTER: OnceLock<[u64; 4]> = OnceLock::new(); static REG_AFTER: OnceLock<[u64; 4]> = OnceLock::new();
#[cfg(target_arch = "x86_64")]
extern "C-unwind" fn actor_reg_check() { extern "C-unwind" fn actor_reg_check() {
unsafe { unsafe {
let s0: u64 = 0xAAAA_BBBB_0000_0001; let s0: u64 = 0xAAAA_BBBB_0000_0001;
@@ -83,6 +84,39 @@ extern "C-unwind" fn actor_reg_check() {
} }
} }
// aarch64 sibling: same intent, AAPCS64 callee-saved integer registers.
// LLVM reserves x19 (and uses x29/x30 as fp/lr), so those can't be named as
// asm operands. We use x23–x26 instead — callee-saved and bindable — moving
// known values into them, yielding, then reading them back, exactly mirroring
// the x86 test's move-into-r12..r15 pattern. The shim saves x23–x26 in its
// `stp x23,x24` / `stp x25,x26` pairs, so a clean round-trip proves they
// survive the switch.
#[cfg(target_arch = "aarch64")]
extern "C-unwind" fn actor_reg_check() {
unsafe {
let s0: u64 = 0xAAAA_BBBB_0000_0001;
let s1: u64 = 0xCCCC_DDDD_0000_0002;
let s2: u64 = 0xEEEE_FFFF_0000_0003;
let s3: u64 = 0x1111_2222_0000_0004;
core::arch::asm!(
"mov x23, {s0}", "mov x24, {s1}", "mov x25, {s2}", "mov x26, {s3}",
s0 = in(reg) s0, s1 = in(reg) s1, s2 = in(reg) s2, s3 = in(reg) s3,
out("x23") _, out("x24") _, out("x25") _, out("x26") _,
);
REG_BEFORE.set([s0, s1, s2, s3]).ok();
switch_to_scheduler();
let a0: u64; let a1: u64; let a2: u64; let a3: u64;
core::arch::asm!(
"mov {a0}, x23", "mov {a1}, x24", "mov {a2}, x25", "mov {a3}, x26",
a0 = out(reg) a0, a1 = out(reg) a1, a2 = out(reg) a2, a3 = out(reg) a3,
);
REG_AFTER.set([a0, a1, a2, a3]).ok();
switch_to_scheduler();
}
}
#[test] #[test]
fn callee_saved_registers_survive_yield() { fn callee_saved_registers_survive_yield() {
let stack = Stack::new(64 * 1024).unwrap(); let stack = Stack::new(64 * 1024).unwrap();
tests/fd_select.rs
-403
View File
@@ -1,403 +0,0 @@
//! RFC 008 — fd arms in select. Beyond the functional cases, the
//! *_stays_usable tests are the soundness probes for the one asymmetry the
//! RFC must close: a losing CHANNEL arm's stale registration is inert, but
//! a losing FD arm's registration (waiters entry + kernel ONESHOT) poisons
//! the fd with AlreadyExists until the eager cleanup pass removes it. Every
//! "loser" scenario therefore re-waits on the same fd afterwards and must
//! succeed — pre-cleanup, each of those re-waits errors or hangs.
//!
//! House pattern: actor panics are trampoline-caught and `run` returns
//! normally, so every test funnels its result into an outcome flag asserted
//! OUTSIDE `run` — an in-actor assertion alone passes vacuously.
use smarm::{
channel, run, select, select_timeout, spawn, try_select, wait_readable,
wait_readable_timeout, wait_writable_timeout, yield_now, FdArm,
};
use std::os::fd::RawFd;
use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
// ---------------------------------------------------------------------------
// Pipe helper (as in io_epoll.rs)
// ---------------------------------------------------------------------------
struct Pipe {
read: RawFd,
write: RawFd,
}
impl Pipe {
fn new() -> Self {
let mut fds: [libc::c_int; 2] = [0; 2];
let r = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_CLOEXEC | libc::O_NONBLOCK) };
assert_eq!(r, 0, "pipe2 failed");
Pipe { read: fds[0], write: fds[1] }
}
}
impl Drop for Pipe {
fn drop(&mut self) {
unsafe {
libc::close(self.read);
libc::close(self.write);
}
}
}
fn raw_write(fd: RawFd, buf: &[u8]) -> isize {
unsafe { libc::write(fd, buf.as_ptr() as *const _, buf.len()) }
}
fn raw_read(fd: RawFd, buf: &mut [u8]) -> isize {
unsafe { libc::read(fd, buf.as_mut_ptr() as *mut _, buf.len()) }
}
fn flag() -> (Arc<AtomicBool>, Arc<AtomicBool>) {
let f = Arc::new(AtomicBool::new(false));
(f.clone(), f)
}
// ---------------------------------------------------------------------------
// Ready-now: data already pending retires the wait without parking.
// ---------------------------------------------------------------------------
#[test]
fn fd_arm_ready_now_returns_without_parking() {
let (ok, ok2) = flag();
run(move || {
let p = Pipe::new();
assert_eq!(raw_write(p.write, b"x"), 1);
let (_tx, rx) = channel::<i64>();
let fd_arm = FdArm::readable(p.read);
// fd arm at index 1: the ready-now path must also work for a
// non-first arm (and clean nothing — channel arms are inert).
let i = select(&[&rx, &fd_arm]);
assert_eq!(i, 1);
let mut buf = [0u8; 1];
assert_eq!(raw_read(p.read, &mut buf), 1);
ok2.store(true, Ordering::SeqCst);
});
assert!(ok.load(Ordering::SeqCst));
}
// ---------------------------------------------------------------------------
// Park-then-wake: fd arm wins against an idle channel arm.
// ---------------------------------------------------------------------------
#[test]
fn fd_arm_parks_until_data_then_wins() {
let got = Arc::new(AtomicU32::new(0));
let got2 = got.clone();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let (_tx_keepalive, rx) = channel::<i64>();
let h = spawn(move || {
let fd_arm = FdArm::readable(rfd);
let i = select(&[&fd_arm, &rx]);
assert_eq!(i, 0);
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
got2.store(buf[0] as u32, Ordering::SeqCst);
});
yield_now(); // let it park
assert_eq!(raw_write(wfd, b"y"), 1);
let _ = h.join();
});
assert_eq!(got.load(Ordering::SeqCst), b'y' as u32);
}
// ---------------------------------------------------------------------------
// THE asymmetry probe: channel arm wins, losing fd arm must be cleaned —
// the same actor (and the io thread) must be able to wait that fd again.
// ---------------------------------------------------------------------------
#[test]
fn losing_fd_arm_is_cleaned_up_and_fd_stays_usable() {
let got = Arc::new(AtomicU32::new(0));
let got2 = got.clone();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let (tx, rx) = channel::<i64>();
let h = spawn(move || {
let fd_arm = FdArm::readable(rfd);
// Channel wins; the fd arm registered and lost.
let i = select(&[&fd_arm, &rx]);
assert_eq!(i, 1);
assert_eq!(rx.try_recv().unwrap(), Some(7));
// Pre-cleanup this wait_readable fails AlreadyExists (the
// waiters entry is stale-ours) — the cleanup pass must have
// removed it.
wait_readable(rfd).unwrap();
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
got2.store(buf[0] as u32, Ordering::SeqCst);
});
yield_now(); // let it park in the select
tx.send(7).unwrap();
yield_now(); // let it reach the second wait
assert_eq!(raw_write(wfd, b"z"), 1);
let _ = h.join();
});
assert_eq!(got.load(Ordering::SeqCst), b'z' as u32);
}
// ---------------------------------------------------------------------------
// Ready-now on a LATER arm must unregister an earlier fd arm (the
// register_arms prefix-cleanup path: no park ever happens).
// ---------------------------------------------------------------------------
#[test]
fn ready_now_later_arm_cleans_earlier_fd_arm() {
let (ok, ok2) = flag();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let (tx, rx) = channel::<i64>();
tx.send(1).unwrap(); // arm 1 ready before the select
let fd_arm = FdArm::readable(rfd);
let i = select(&[&fd_arm, &rx]);
assert_eq!(i, 1);
assert_eq!(rx.try_recv().unwrap(), Some(1));
// The fd arm registered (idle pipe), then arm 1 retired the wait.
// Its registration must have been removed in the same pass.
assert_eq!(raw_write(wfd, b"a"), 1);
wait_readable(rfd).unwrap();
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
ok2.store(true, Ordering::SeqCst);
});
assert!(ok.load(Ordering::SeqCst));
}
// ---------------------------------------------------------------------------
// Two fd arms in one select (phase-1: distinct fds, nothing special).
// ---------------------------------------------------------------------------
#[test]
fn two_fd_arms_second_fires_first_stays_usable() {
let (ok, ok2) = flag();
run(move || {
let pa = Pipe::new();
let pb = Pipe::new();
let (rfd_a, wfd_a) = (pa.read, pa.write);
let (rfd_b, wfd_b) = (pb.read, pb.write);
let h = spawn(move || {
let a = FdArm::readable(rfd_a);
let b = FdArm::readable(rfd_b);
let i = select(&[&a, &b]);
assert_eq!(i, 1);
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd_b, &mut buf), 1);
// Arm a lost; its fd must be immediately re-waitable.
assert_eq!(raw_write(wfd_a, b"q"), 1);
wait_readable(rfd_a).unwrap();
assert_eq!(raw_read(rfd_a, &mut buf), 1);
assert_eq!(buf[0], b'q');
ok2.store(true, Ordering::SeqCst);
});
yield_now();
assert_eq!(raw_write(wfd_b, b"b"), 1);
let _ = h.join();
});
assert!(ok.load(Ordering::SeqCst));
}
// ---------------------------------------------------------------------------
// select_timeout: timer wins over an idle fd arm; the fd is left clean.
// ---------------------------------------------------------------------------
#[test]
fn select_timeout_timer_beats_idle_fd_arm_and_fd_stays_usable() {
let (ok, ok2) = flag();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let fd_arm = FdArm::readable(rfd);
let start = Instant::now();
let r = select_timeout(&[&fd_arm], Duration::from_millis(30));
assert!(r.is_none(), "idle fd must time out");
assert!(start.elapsed() >= Duration::from_millis(30));
// Timer win is exactly the case where the fd arm's registration is
// left behind without an eager pass.
assert_eq!(raw_write(wfd, b"c"), 1);
wait_readable(rfd).unwrap();
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
ok2.store(true, Ordering::SeqCst);
});
assert!(ok.load(Ordering::SeqCst));
}
// ---------------------------------------------------------------------------
// Derived wrappers.
// ---------------------------------------------------------------------------
#[test]
fn wait_readable_timeout_times_out_then_succeeds_with_data() {
let (ok, ok2) = flag();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let start = Instant::now();
assert_eq!(wait_readable_timeout(rfd, Duration::from_millis(30)).unwrap(), false);
assert!(start.elapsed() >= Duration::from_millis(30));
// Timed-out wait must leave the fd clean; ready path returns true.
assert_eq!(raw_write(wfd, b"d"), 1);
assert_eq!(wait_readable_timeout(rfd, Duration::from_secs(5)).unwrap(), true);
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
ok2.store(true, Ordering::SeqCst);
});
assert!(ok.load(Ordering::SeqCst));
}
#[test]
fn wait_readable_timeout_wakes_on_late_data() {
let got = Arc::new(AtomicU32::new(0));
let got2 = got.clone();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let h = spawn(move || {
assert_eq!(wait_readable_timeout(rfd, Duration::from_secs(5)).unwrap(), true);
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
got2.store(buf[0] as u32, Ordering::SeqCst);
});
yield_now();
assert_eq!(raw_write(wfd, b"e"), 1);
let _ = h.join();
});
assert_eq!(got.load(Ordering::SeqCst), b'e' as u32);
}
#[test]
fn wait_writable_timeout_ready_now_on_empty_pipe() {
let (ok, ok2) = flag();
run(move || {
let p = Pipe::new();
// An empty pipe's write end is writable: ready-now path, no park.
assert_eq!(wait_writable_timeout(p.write, Duration::from_secs(5)).unwrap(), true);
ok2.store(true, Ordering::SeqCst);
});
assert!(ok.load(Ordering::SeqCst));
}
// ---------------------------------------------------------------------------
// Error surface: registration failure is an Err from try_select, with the
// wait retired (the actor can immediately wait on something else).
// ---------------------------------------------------------------------------
#[test]
fn try_select_surfaces_registration_error_and_retires_the_wait() {
let (ok, ok2) = flag();
run(move || {
let bad: RawFd = {
let p = Pipe::new();
p.read
}; // both ends closed by Drop: EBADF on registration
let fd_arm = FdArm::readable(bad);
let err = try_select(&[&fd_arm]).unwrap_err();
// EBADF, whether the pre-poll or epoll_ctl ADD reports it.
assert_eq!(err.raw_os_error(), Some(libc::EBADF));
// The wait was retired: a normal select right after works.
let (tx, rx) = channel::<i64>();
tx.send(9).unwrap();
let i = select(&[&rx]);
assert_eq!(i, 0);
assert_eq!(rx.try_recv().unwrap(), Some(9));
ok2.store(true, Ordering::SeqCst);
});
assert!(ok.load(Ordering::SeqCst));
}
// ---------------------------------------------------------------------------
// Stop-unwind: an actor stopped while parked in an fd-arm select must not
// poison the fd (the UnregisterGuard generalization of wait_fd's Dereg).
// Mirrors io_epoll.rs::stopped_waiter_does_not_poison_the_fd.
// ---------------------------------------------------------------------------
#[test]
fn stopped_selector_does_not_poison_the_fd() {
let seen = Arc::new(AtomicU32::new(0));
let seen_outer = seen.clone();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let (_tx_keepalive, rx) = channel::<i64>();
let h = spawn(move || {
let fd_arm = FdArm::readable(rfd);
select(&[&fd_arm, &rx]);
unreachable!("neither arm ever fires while this actor lives");
});
yield_now(); // let it reach the park
smarm::request_stop(h.pid());
let _ = h.join(); // Ok(()): stopped, not panicked
// Second waiter on the SAME fd must register and be woken.
let seen2 = seen.clone();
let h2 = spawn(move || {
wait_readable(rfd).unwrap();
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
seen2.store(buf[0] as u32, Ordering::SeqCst);
});
yield_now();
assert_eq!(raw_write(wfd, b"x"), 1);
let _ = h2.join();
});
assert_eq!(seen_outer.load(Ordering::SeqCst), b'x' as u32);
}
// ---------------------------------------------------------------------------
// Phase-1 misuse: a second waiter on an fd that already has one is an Err
// (AlreadyExists), not a hang — and does not disturb the first waiter.
// ---------------------------------------------------------------------------
#[test]
fn second_waiter_on_same_fd_errs_without_disturbing_the_first() {
let got = Arc::new(AtomicU32::new(0));
let got2 = got.clone();
let (ok, ok2) = flag();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
let h = spawn(move || {
wait_readable(rfd).unwrap();
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
got2.store(buf[0] as u32, Ordering::SeqCst);
});
yield_now(); // first waiter parked
let fd_arm = FdArm::readable(rfd);
let err = try_select(&[&fd_arm]).unwrap_err();
assert_eq!(err.kind(), std::io::ErrorKind::AlreadyExists);
// First waiter still wakes normally.
assert_eq!(raw_write(wfd, b"w"), 1);
let _ = h.join();
ok2.store(true, Ordering::SeqCst);
});
assert_eq!(got.load(Ordering::SeqCst), b'w' as u32);
assert!(ok.load(Ordering::SeqCst));
}
tests/gen_server.rs
+2 -537
View File
@@ -1,7 +1,7 @@
//! gen_server tests: call round-trip, cast, lifecycle callbacks, and the two //! gen_server tests: call round-trip, cast, lifecycle callbacks, and the two
//! server-down detection paths (reply-channel close vs. inbox-send failure). //! server-down detection paths (reply-channel close vs. inbox-send failure).
use smarm::gen_server::{start, CallError, GenServer, GenServerBuilder}; use smarm::gen_server::{start, CallError, GenServer};
use smarm::run; use smarm::run;
use std::sync::{Arc, Mutex}; use std::sync::{Arc, Mutex};
@@ -26,8 +26,6 @@ impl GenServer for Counter {
type Call = Req; type Call = Req;
type Reply = i64; type Reply = i64;
type Cast = Op; type Cast = Op;
type Info = ();
type Timer = ();
fn handle_call(&mut self, req: Req) -> i64 { fn handle_call(&mut self, req: Req) -> i64 {
match req { match req {
@@ -70,10 +68,8 @@ impl GenServer for Lifecycle {
type Call = (); type Call = ();
type Reply = (); type Reply = ();
type Cast = (); type Cast = ();
type Info = ();
type Timer = ();
fn init(&mut self, _ctx: &smarm::gen_server::GenServerCtx<Self>) { fn init(&mut self) {
self.log.lock().unwrap().push("init"); self.log.lock().unwrap().push("init");
} }
@@ -139,534 +135,3 @@ fn call_after_server_gone_is_server_down() {
}); });
assert_eq!(*got.lock().unwrap(), Some(Err(CallError::ServerDown))); assert_eq!(*got.lock().unwrap(), Some(Err(CallError::ServerDown)));
} }
// ---------------------------------------------------------------------------
// call_timeout
// ---------------------------------------------------------------------------
use smarm::gen_server::CallTimeoutError;
use std::time::{Duration, Instant};
/// Replies after sleeping `delay_ms` (parking the server actor, not the OS
/// thread), so callers can race a deadline against the reply.
struct Slow;
impl GenServer for Slow {
type Call = u64; // delay in ms
type Reply = u64;
type Cast = ();
type Info = ();
type Timer = ();
fn handle_call(&mut self, delay_ms: u64) -> u64 {
if delay_ms > 0 {
smarm::sleep(Duration::from_millis(delay_ms));
}
delay_ms
}
fn handle_cast(&mut self, _: ()) {}
}
#[test]
fn call_timeout_returns_reply_within_deadline() {
run(|| {
let srv = start(Slow);
assert_eq!(srv.call_timeout(0, Duration::from_secs(10)), Ok(0));
});
}
#[test]
fn call_timeout_times_out_on_slow_handler() {
run(|| {
let srv = start(Slow);
let start_t = Instant::now();
let r = srv.call_timeout(500, Duration::from_millis(50));
assert_eq!(r, Err(CallTimeoutError::Timeout));
let elapsed = start_t.elapsed();
// Gave up at the deadline, not at the reply.
assert!(elapsed >= Duration::from_millis(50));
assert!(elapsed < Duration::from_millis(500));
});
}
#[test]
fn server_survives_an_abandoned_call_and_late_reply_is_discarded() {
run(|| {
let srv = start(Slow);
assert_eq!(
srv.call_timeout(100, Duration::from_millis(20)),
Err(CallTimeoutError::Timeout)
);
// The timed-out request is still handled; its reply send fails
// harmlessly (receiver dropped). The server must keep serving, and
// the late reply must not leak into THIS call's reply channel.
assert_eq!(srv.call_timeout(0, Duration::from_secs(10)), Ok(0));
// Plain unbounded call still fine too.
assert_eq!(srv.call(0), Ok(0));
});
}
#[test]
fn call_timeout_to_dead_server_is_server_down_not_timeout() {
struct Bomb;
impl GenServer for Bomb {
type Call = ();
type Info = ();
type Timer = ();
type Reply = ();
type Cast = ();
fn handle_call(&mut self, _: ()) {
panic!("kaboom");
}
fn handle_cast(&mut self, _: ()) {}
}
run(|| {
let srv = start(Bomb);
// Dies mid-call: reply channel closes -> ServerDown (even though the
// generous deadline never fires).
assert_eq!(
srv.call_timeout((), Duration::from_secs(10)),
Err(CallTimeoutError::ServerDown)
);
// Already gone: inbox send fails -> ServerDown.
assert_eq!(
srv.call_timeout((), Duration::from_secs(10)),
Err(CallTimeoutError::ServerDown)
);
});
}
// ---------------------------------------------------------------------------
// handle_info: out-of-band channels selected alongside the inbox (v0.8)
// ---------------------------------------------------------------------------
/// Logs every message it handles, in order; a call reads the log back.
struct Logger {
log: Vec<&'static str>,
}
impl GenServer for Logger {
type Call = ();
type Reply = Vec<&'static str>;
type Cast = ();
type Info = &'static str;
type Timer = ();
fn handle_call(&mut self, _: ()) -> Vec<&'static str> {
self.log.clone()
}
fn handle_cast(&mut self, _: ()) {
self.log.push("cast");
}
fn handle_info(&mut self, info: &'static str) {
self.log.push(info);
}
}
// An info message is dispatched to handle_info, interleaved with normal
// service.
#[test]
fn info_is_dispatched() {
let got = Arc::new(Mutex::new(Vec::new()));
let got2 = got.clone();
run(move || {
let (info_tx, info_rx) = smarm::channel::<&'static str>();
let server = GenServerBuilder::new(Logger { log: Vec::new() })
.with_info(info_rx)
.start();
info_tx.send("info").unwrap();
*got2.lock().unwrap() = server.call(()).unwrap();
});
assert_eq!(*got.lock().unwrap(), vec!["info"]);
}
// Arm priority: with a cast AND an info both queued before the server first
// runs, the info is handled first — info arms outrank the inbox. Relies on
// run()'s deterministic single-thread ordering.
#[test]
fn info_outranks_inbox() {
let got = Arc::new(Mutex::new(Vec::new()));
let got2 = got.clone();
run(move || {
let (info_tx, info_rx) = smarm::channel::<&'static str>();
let server = GenServerBuilder::new(Logger { log: Vec::new() })
.with_info(info_rx)
.start();
// The server actor hasn't run yet: both messages are queued before
// its first select. Inbox first in *send* order, info first in *arm*
// order — arm order must win.
server.cast(()).unwrap();
info_tx.send("info").unwrap();
*got2.lock().unwrap() = server.call(()).unwrap();
});
assert_eq!(*got.lock().unwrap(), vec!["info", "cast"]);
}
// Two info channels: declaration order is priority order.
#[test]
fn info_arms_keep_declaration_priority() {
let got = Arc::new(Mutex::new(Vec::new()));
let got2 = got.clone();
run(move || {
let (hi_tx, hi_rx) = smarm::channel::<&'static str>();
let (lo_tx, lo_rx) = smarm::channel::<&'static str>();
let server = GenServerBuilder::new(Logger { log: Vec::new() })
.with_info(hi_rx)
.with_info(lo_rx)
.start();
// Sent low-priority first; handled high-priority first.
lo_tx.send("lo").unwrap();
hi_tx.send("hi").unwrap();
*got2.lock().unwrap() = server.call(()).unwrap();
});
assert_eq!(*got.lock().unwrap(), vec!["hi", "lo"]);
}
// A closed info arm is silently dropped and the server keeps serving; the
// closure does NOT reach handle_info and does NOT starve the inbox (the
// closed-arm-is-ready-forever gotcha).
#[test]
fn closed_info_arm_is_dropped_silently() {
let got = Arc::new(Mutex::new(Vec::new()));
let got2 = got.clone();
run(move || {
let (info_tx, info_rx) = smarm::channel::<&'static str>();
let server = GenServerBuilder::new(Logger { log: Vec::new() })
.with_info(info_rx)
.start();
drop(info_tx); // closed before the server's first select
server.cast(()).unwrap();
*got2.lock().unwrap() = server.call(()).unwrap();
});
assert_eq!(*got.lock().unwrap(), vec!["cast"]);
}
// ---------------------------------------------------------------------------
// handle_down: monitors handed to the loop via Watcher (v0.8)
// ---------------------------------------------------------------------------
use smarm::gen_server::Watcher;
use smarm::{monitor, spawn, DownReason, Pid};
/// The motivating pattern: a server that spawns workers from a handler,
/// watches them, and logs their deaths.
struct Pool {
watcher: Option<Watcher<Self>>,
log: Vec<DownReason>,
}
enum PoolCast {
SpawnDoomedWorker,
Watch(Pid),
}
impl GenServer for Pool {
type Call = ();
type Reply = Vec<DownReason>;
type Cast = PoolCast;
type Info = ();
type Timer = ();
fn init(&mut self, ctx: &smarm::gen_server::GenServerCtx<Self>) {
self.watcher = Some(ctx.watcher());
}
fn handle_call(&mut self, _: ()) -> Vec<DownReason> {
self.log.clone()
}
fn handle_cast(&mut self, cast: PoolCast) {
let watcher = self.watcher.as_ref().expect("init ran first");
match cast {
PoolCast::SpawnDoomedWorker => {
let h = spawn(|| panic!("worker died"));
watcher.watch(monitor(h.pid()));
}
PoolCast::Watch(pid) => watcher.watch(monitor(pid)),
}
}
fn handle_down(&mut self, down: smarm::Down) {
self.log.push(down.reason);
}
}
// A worker spawned and watched from inside a handler delivers its Down to
// handle_down. Down arms outrank the inbox, so the death is in the log by
// the time the follow-up call is answered.
#[test]
fn worker_pool_down_reaches_handle_down() {
let got = Arc::new(Mutex::new(Vec::new()));
let got2 = got.clone();
run(move || {
let server = start(Pool { watcher: None, log: Vec::new() });
server.cast(PoolCast::SpawnDoomedWorker).unwrap();
let _ = server.call(()).unwrap(); // sync point: cast handled, worker live
*got2.lock().unwrap() = server.call(()).unwrap();
});
assert_eq!(*got.lock().unwrap(), vec![DownReason::Panic]);
}
// Watching an already-dead pid yields an immediate NoProc Down, and the down
// arm outranks the inbox: the call cast *after* the watch still observes it.
#[test]
fn watch_dead_pid_is_noproc_down() {
let got = Arc::new(Mutex::new(Vec::new()));
let got2 = got.clone();
run(move || {
let h = spawn(|| {});
let dead = h.pid();
h.join().unwrap();
let server = start(Pool { watcher: None, log: Vec::new() });
server.cast(PoolCast::Watch(dead)).unwrap();
*got2.lock().unwrap() = server.call(()).unwrap();
});
assert_eq!(*got.lock().unwrap(), vec![DownReason::NoProc]);
}
// A state that never clones the Watcher closes the control arm; the loop
// falls back to the plain-inbox park and keeps serving. (Every pre-v0.8 test
// in this file also exercises this path.)
#[test]
fn unused_ctx_closes_control_arm_silently() {
let got = Arc::new(Mutex::new(0i64));
let got2 = got.clone();
run(move || {
let server = start(Counter { n: 0 });
server.cast(Op::Add(2)).unwrap();
server.cast(Op::Add(40)).unwrap();
*got2.lock().unwrap() = server.call(Req::Get).unwrap();
});
assert_eq!(*got.lock().unwrap(), 42);
}
// ---------------------------------------------------------------------------
// RFC 015 — gen_server timers. A server that arms one-shot timers from a cast
// and records each fire's payload, plus the cancel race signal.
// ---------------------------------------------------------------------------
use smarm::gen_server::{GenServerCtx, TimerHandle};
use smarm::TimerId;
enum TkCast {
Arm(Duration),
Tick(Duration),
CancelLast,
}
struct Timed {
timer: Option<TimerHandle<Self>>,
fired: Arc<Mutex<Vec<u32>>>,
cancel_won: Arc<Mutex<Option<bool>>>,
last: Option<TimerId>,
}
impl GenServer for Timed {
type Call = ();
type Reply = usize; // count of fires so far (a sync read point)
type Cast = TkCast;
type Info = ();
type Timer = u32;
fn init(&mut self, ctx: &GenServerCtx<Self>) {
self.timer = Some(ctx.timer());
}
fn handle_call(&mut self, _: ()) -> usize {
self.fired.lock().unwrap().len()
}
fn handle_cast(&mut self, c: TkCast) {
let t = self.timer.as_ref().expect("init ran first");
match c {
TkCast::Arm(d) => self.last = Some(t.arm_after(d, 7)),
TkCast::Tick(d) => self.last = Some(t.tick_every(d, 9)),
TkCast::CancelLast => {
let id = self.last.take().expect("a timer was armed");
*self.cancel_won.lock().unwrap() = Some(t.cancel(id));
}
}
}
fn handle_timer(&mut self, msg: u32) {
self.fired.lock().unwrap().push(msg);
}
}
fn timed(fired: Arc<Mutex<Vec<u32>>>, cancel_won: Arc<Mutex<Option<bool>>>) -> Timed {
Timed { timer: None, fired, cancel_won, last: None }
}
// A one-shot armed from a handler fires into handle_timer with its payload.
#[test]
fn arm_after_fires_into_handle_timer() {
let fired = Arc::new(Mutex::new(Vec::new()));
let f2 = fired.clone();
run(move || {
let cw = Arc::new(Mutex::new(None));
let server = start(timed(f2, cw));
server.cast(TkCast::Arm(Duration::from_millis(10))).unwrap();
let _ = server.call(()).unwrap(); // sync: arm done
smarm::sleep(Duration::from_millis(40)); // let the timer fire
let count = server.call(()).unwrap(); // timer arm outranks this inbox call
assert_eq!(count, 1, "the one-shot should have fired exactly once");
});
assert_eq!(*fired.lock().unwrap(), vec![7]);
}
// cancel before the deadline wins the race (returns true) and suppresses the
// fire entirely.
#[test]
fn cancel_before_fire_suppresses_it() {
let fired = Arc::new(Mutex::new(Vec::new()));
let cancel_won = Arc::new(Mutex::new(None));
let f2 = fired.clone();
let c2 = cancel_won.clone();
run(move || {
let server = start(timed(f2, c2));
server.cast(TkCast::Arm(Duration::from_millis(50))).unwrap();
server.cast(TkCast::CancelLast).unwrap();
let _ = server.call(()).unwrap(); // sync: arm + cancel both handled
smarm::sleep(Duration::from_millis(80)); // past the original deadline
let count = server.call(()).unwrap();
assert_eq!(count, 0, "cancelled timer must not fire");
});
assert_eq!(*cancel_won.lock().unwrap(), Some(true), "cancel beat the fire");
assert!(fired.lock().unwrap().is_empty());
}
// tick_every re-arms: a periodic fires repeatedly off one arm, each tick
// carrying a fresh payload. (Timer fires outrank the inbox by arm position, so
// a periodic cannot be starved by userspace traffic — the same property the
// info_outranks_inbox test pins for infos.)
#[test]
fn tick_every_rearms_repeatedly() {
let fired = Arc::new(Mutex::new(Vec::new()));
let f2 = fired.clone();
run(move || {
let cw = Arc::new(Mutex::new(None));
let server = start(timed(f2, cw));
server.cast(TkCast::Tick(Duration::from_millis(20))).unwrap();
let _ = server.call(()).unwrap(); // sync: periodic armed
smarm::sleep(Duration::from_millis(130)); // ~6 periods
let count = server.call(()).unwrap();
assert!(count >= 3, "periodic should have re-armed several times, got {count}");
});
// Every tick delivered the same payload.
assert!(fired.lock().unwrap().iter().all(|&v| v == 9));
}
// Cancelling a periodic stops the re-arm: no further ticks land after cancel.
#[test]
fn cancel_stops_a_periodic() {
let fired = Arc::new(Mutex::new(Vec::new()));
let cancel_won = Arc::new(Mutex::new(None));
let f2 = fired.clone();
let c2 = cancel_won.clone();
run(move || {
let server = start(timed(f2, c2));
server.cast(TkCast::Tick(Duration::from_millis(20))).unwrap();
let _ = server.call(()).unwrap();
smarm::sleep(Duration::from_millis(70)); // a few ticks
server.cast(TkCast::CancelLast).unwrap();
let after_cancel = server.call(()).unwrap(); // sync: cancel handled
smarm::sleep(Duration::from_millis(80)); // would be several more ticks
let later = server.call(()).unwrap();
assert_eq!(later, after_cancel, "no ticks may land after cancel");
});
// The periodic had fired at least once before being cancelled.
assert!(!fired.lock().unwrap().is_empty());
}
// ---------------------------------------------------------------------------
// RFC 015 §4.4 — idle / receive timeout. A server that sets an idle window in
// init and counts handle_idle fires; casts are traffic that resets the window.
// ---------------------------------------------------------------------------
struct Idler {
window: Duration,
idles: Arc<Mutex<u32>>,
}
impl GenServer for Idler {
type Call = ();
type Reply = u32; // idle fire count
type Cast = (); // a poke: traffic that resets the idle window
type Info = ();
type Timer = ();
fn init(&mut self, ctx: &GenServerCtx<Self>) {
ctx.idle_after(self.window);
}
fn handle_call(&mut self, _: ()) -> u32 {
*self.idles.lock().unwrap()
}
fn handle_cast(&mut self, _: ()) {}
fn handle_idle(&mut self) {
*self.idles.lock().unwrap() += 1;
}
}
// A quiet inbox fires handle_idle, and the window re-arms (steady detector):
// several fires across a quiet span.
#[test]
fn idle_fires_repeatedly_on_quiet() {
let idles = Arc::new(Mutex::new(0));
let i2 = idles.clone();
run(move || {
let server = start(Idler { window: Duration::from_millis(25), idles: i2 });
smarm::sleep(Duration::from_millis(130)); // quiet ⇒ ~5 windows
drop(server); // keep the server alive across the quiet span
});
assert!(*idles.lock().unwrap() >= 2, "idle should re-arm and fire several times");
}
// Traffic within the window keeps idle from firing; only once the inbox goes
// quiet does handle_idle fire.
#[test]
fn traffic_resets_the_idle_window() {
let idles = Arc::new(Mutex::new(0));
let i2 = idles.clone();
let before_quiet = Arc::new(Mutex::new(u32::MAX));
let bq = before_quiet.clone();
run(move || {
let server = start(Idler { window: Duration::from_millis(60), idles: i2 });
// Poke every 25ms (< 60ms window) for ~100ms: each cast resets the
// window before it can elapse.
for _ in 0..4 {
server.cast(()).unwrap();
smarm::sleep(Duration::from_millis(25));
}
*bq.lock().unwrap() = server.call(()).unwrap(); // count while traffic kept it quiet-free
smarm::sleep(Duration::from_millis(140)); // now genuinely quiet
drop(server);
});
assert_eq!(*before_quiet.lock().unwrap(), 0, "steady traffic must suppress idle");
assert!(*idles.lock().unwrap() >= 1, "idle fires once the inbox falls quiet");
}
// RFC 015 §4.7 — no armed timer survives loop exit. A server with a live
// periodic is dropped; the loop's drop guard drains and cancels it (a surviving
// re-arming timer would trip the in-Drop debug_assert), runs terminate, and no
// further tick lands after exit.
#[test]
fn no_timer_survives_exit() {
let fired = Arc::new(Mutex::new(Vec::new()));
let f_server = fired.clone();
let f_read = fired.clone();
run(move || {
let server = start(timed(f_server, Arc::new(Mutex::new(None))));
server.cast(TkCast::Tick(Duration::from_millis(15))).unwrap();
let _ = server.call(()).unwrap(); // sync: periodic armed
smarm::sleep(Duration::from_millis(45)); // a couple of ticks
let mon = smarm::monitor(server.pid());
drop(server); // inbox closes → loop exits → guard drains timers
// Clean Down ⇒ the loop returned without the no-leak assert aborting.
assert!(mon.rx.recv().is_ok());
let at_exit = f_read.lock().unwrap().len();
smarm::sleep(Duration::from_millis(90)); // would be several more ticks
assert_eq!(f_read.lock().unwrap().len(), at_exit, "no tick may fire after exit");
});
}
tests/gen_statem.rs
-380
View File
@@ -1,380 +0,0 @@
//! gen_statem behaviour tests, driven through the `gen_statem!` macro: cast/call
//! round-trip, `enter` firing on start and on every real transition (but not on
//! a stay), the machine-down path when a handler panics, and the timeout
//! surface (state-timeout firing + auto-reset across transitions; named
//! timeouts surviving transitions; cancellation).
use smarm::gen_statem;
use smarm::gen_statem::{CallError, Reply};
use smarm::run;
use std::sync::{Arc, Mutex};
use std::time::Duration;
// ===========================================================================
// Timeouts
// ===========================================================================
//
// A small timer machine. `Idle` is quiet; `Armed` arms a state-timeout on entry
// that — when it fires — bumps `st_fires` and returns to `Idle`. A named
// timeout ("ping") is armed independently, survives the Idle/Armed transition,
// and bumps `named_fires` when it fires. Counters are read back over calls.
//
// Durations are tiny and waits use `smarm::sleep` (parks the actor, leaves the
// timer wheel turning). These tests run against real time, so they are a touch
// slow; a controllable clock would tighten them.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum T {
Idle,
Armed,
}
struct TData {
enters: u32, // total state entries (incl. initial)
st_fires: u32, // state-timeout fires
named_fires: u32, // named-timeout fires
st_window: u64, // ms for the Armed state-timeout (set per test intent)
}
enum TCast {
Arm, // Idle -> Armed
Disarm, // Armed -> Idle (a transition that should auto-reset the state-timeout)
Ping(u64), // arm a named "ping" timeout after the given ms
CancelPing, // cancel the named "ping"
}
enum TCall {
Enters(Reply<u32>),
StFires(Reply<u32>),
NamedFires(Reply<u32>),
Boom(Reply<u32>), // panics, to exercise the call-to-dead-machine path
}
gen_statem! {
machine: TimerSm { state: T, data: TData };
event: Ev2 { cast: TCast, call: TCall, info: () };
context(data, prev, cx);
enter {
// On entering Armed, arm the state-timeout. On Idle, nothing — and the
// loop has already auto-reset any pending state-timeout on the way in.
T::Armed => { data.enters += 1; cx.state_timeout(Duration::from_millis(data.st_window)); },
T::Idle => data.enters += 1,
}
on T::Idle => {
cast TCast::Arm => T::Armed,
cast TCast::Disarm => unhandled,
state_timeout => unhandled,
}
on T::Armed => {
// The state-timeout elapsed while still Armed: count it and go Idle.
state_timeout => { data.st_fires += 1; T::Idle },
cast TCast::Disarm => T::Idle,
cast TCast::Arm => unhandled,
}
// State-independent rows: the named-timeout (survives transitions), the
// arm/cancel casts, the counter reads, and the panicking call.
on _ => {
cast TCast::Ping(ms) => { cx.timeout("ping", Duration::from_millis(ms)); prev },
cast TCast::CancelPing => { cx.cancel_timeout("ping"); prev },
timeout "ping" => { data.named_fires += 1; prev },
timeout _ => unhandled,
call TCall::Enters(r) => { r.reply(data.enters); prev },
call TCall::StFires(r) => { r.reply(data.st_fires); prev },
call TCall::NamedFires(r) => { r.reply(data.named_fires); prev },
call TCall::Boom(_r) => boom(),
}
}
fn boom() -> T {
panic!("boom")
}
// A state-timeout armed on entry to Armed fires after its window, bumping the
// counter and returning the machine to Idle on its own.
#[test]
fn state_timeout_fires() {
let got = Arc::new(Mutex::new(0u32));
let got2 = got.clone();
run(move || {
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 5 });
m.send(Ev2::Cast(TCast::Arm)).unwrap(); // -> Armed, arms 5ms state-timeout
smarm::sleep(Duration::from_millis(40)); // let it fire
*got2.lock().unwrap() = m.call(|r| Ev2::Call(TCall::StFires(r))).unwrap();
});
assert_eq!(*got.lock().unwrap(), 1, "state-timeout fired exactly once");
}
// Leaving Armed before the window elapses auto-resets the state-timeout: it
// must not fire afterward, even though we wait well past its original window.
#[test]
fn state_timeout_auto_resets_on_transition() {
let got = Arc::new(Mutex::new(99u32));
let got2 = got.clone();
run(move || {
// Long window so the explicit Disarm beats it comfortably.
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 50 });
m.send(Ev2::Cast(TCast::Arm)).unwrap(); // -> Armed, arms 50ms state-timeout
m.send(Ev2::Cast(TCast::Disarm)).unwrap(); // -> Idle, auto-resets it
smarm::sleep(Duration::from_millis(80)); // past the original window
*got2.lock().unwrap() = m.call(|r| Ev2::Call(TCall::StFires(r))).unwrap();
});
assert_eq!(*got.lock().unwrap(), 0, "auto-reset cancelled the pending state-timeout");
}
// A named timeout survives a state change: armed in Idle, it still fires after
// the machine has moved to Armed and back.
#[test]
fn named_timeout_survives_transition() {
let got = Arc::new(Mutex::new(0u32));
let got2 = got.clone();
run(move || {
// Armed's own state-timeout is long so it doesn't interfere.
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 200 });
m.send(Ev2::Cast(TCast::Ping(20))).unwrap(); // arm "ping" for 20ms (in Idle)
m.send(Ev2::Cast(TCast::Arm)).unwrap(); // -> Armed (ping must survive this)
m.send(Ev2::Cast(TCast::Disarm)).unwrap(); // -> Idle (and this)
smarm::sleep(Duration::from_millis(60)); // let "ping" fire
*got2.lock().unwrap() = m.call(|r| Ev2::Call(TCall::NamedFires(r))).unwrap();
});
assert_eq!(*got.lock().unwrap(), 1, "named timeout fired across the transitions");
}
// Cancelling a named timeout before its window prevents the fire.
#[test]
fn named_timeout_cancel() {
let got = Arc::new(Mutex::new(99u32));
let got2 = got.clone();
run(move || {
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 200 });
m.send(Ev2::Cast(TCast::Ping(30))).unwrap(); // arm "ping" for 30ms
m.send(Ev2::Cast(TCast::CancelPing)).unwrap(); // cancel before it fires
smarm::sleep(Duration::from_millis(60)); // past the original window
*got2.lock().unwrap() = m.call(|r| Ev2::Call(TCall::NamedFires(r))).unwrap();
});
assert_eq!(*got.lock().unwrap(), 0, "cancel prevented the named-timeout fire");
}
// ===========================================================================
// Core behaviour (cast/call round-trip, enter semantics, panic -> Down)
// ===========================================================================
// Casts are applied in order and a later call observes the resulting state via
// its counters: two Arm/Disarm round-trips leave the machine back in Idle.
#[test]
fn cast_then_call_roundtrip() {
let got = Arc::new(Mutex::new(0u32));
let got2 = got.clone();
run(move || {
// Long state-timeout window so it never fires during the test.
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 10_000 });
m.send(Ev2::Cast(TCast::Arm)).unwrap(); // Idle -> Armed (enter)
m.send(Ev2::Cast(TCast::Disarm)).unwrap(); // Armed -> Idle (enter)
m.send(Ev2::Cast(TCast::Arm)).unwrap(); // Idle -> Armed (enter)
m.send(Ev2::Cast(TCast::Disarm)).unwrap(); // Armed -> Idle (enter)
// enters = 1 (start) + 4 transitions = 5.
*got2.lock().unwrap() = m.call(|r| Ev2::Call(TCall::Enters(r))).unwrap();
});
assert_eq!(*got.lock().unwrap(), 5, "one enter on start, one per real transition");
}
// `enter` fires once on start and once per *real* transition; a stay (a call
// that returns the current tag) does not re-enter.
#[test]
fn enter_on_start_and_each_transition_but_not_stay() {
let got = Arc::new(Mutex::new((0u32, 0u32, 0u32)));
let got2 = got.clone();
run(move || {
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 10_000 }); // enter -> 1
let after_start = m.call(|r| Ev2::Call(TCall::Enters(r))).unwrap();
// A stay (a counter read returns `prev`) must not bump enters.
let _ = m.call(|r| Ev2::Call(TCall::StFires(r))).unwrap();
let still = m.call(|r| Ev2::Call(TCall::Enters(r))).unwrap();
m.send(Ev2::Cast(TCast::Arm)).unwrap(); // Idle -> Armed -> enter -> 2
let after_arm = m.call(|r| Ev2::Call(TCall::Enters(r))).unwrap();
*got2.lock().unwrap() = (after_start, still, after_arm);
});
assert_eq!(*got.lock().unwrap(), (1, 1, 2));
}
// A handler that panics tears the loop down; the in-flight call's reply channel
// closes as the stack unwinds, so the parked caller wakes with Down (mirrors
// gen_server's panicking-handler path).
#[test]
fn call_to_panicking_handler_is_down() {
let got = Arc::new(Mutex::new(None::<Result<u32, CallError>>));
let got2 = got.clone();
run(move || {
let m = TimerSm::start(T::Idle, TData { enters: 0, st_fires: 0, named_fires: 0, st_window: 10_000 });
let r = m.call(|rep| Ev2::Call(TCall::Boom(rep)));
*got2.lock().unwrap() = Some(r);
});
assert_eq!(*got.lock().unwrap(), Some(Err(CallError::Down)));
}
// ===========================================================================
// Postpone
// ===========================================================================
//
// Two machines. `LatchSm` defers a `Take` *call* while `Empty` and answers it
// from `Filled` — the Reply rides inside the postponed event onto the queue and
// is honoured by whichever later state handles the replay. `RelaySm` defers a
// `Mark` cast through two states so a replayed event can postpone *again*,
// landing only once the handling state is reached.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum L {
Empty,
Filled,
}
struct LData {
value: u32, // the value a Fill stored, handed back by a Take
takes: u32, // completed takes
}
enum LCast {
Fill(u32), // Empty -> Filled, storing the value
}
enum LCall {
Take(Reply<u32>), // Filled: reply value & empty; Empty: postpone until filled
Takes(Reply<u32>), // completed-take count (stay)
Status(Reply<L>), // current state tag (stay)
}
gen_statem! {
machine: LatchSm { state: L, data: LData };
event: LEv { cast: LCast, call: LCall, info: () };
context(data, prev, cx);
enter { _ => {} }
on L::Empty => {
cast LCast::Fill(v) => { data.value = v; L::Filled },
// No value yet: defer the take (with its Reply) until a Fill arrives.
call LCall::Take(r) => postpone,
}
on L::Filled => {
cast LCast::Fill(_) => unhandled, // already full
call LCall::Take(r) => { r.reply(data.value); data.takes += 1; L::Empty },
}
on _ => {
call LCall::Takes(r) => { r.reply(data.takes); prev },
call LCall::Status(r) => { r.reply(prev); prev },
state_timeout => unhandled,
timeout _ => unhandled,
}
}
// A `Take` issued while the latch is Empty parks the caller and is postponed
// (Reply included). A later Fill transitions Empty -> Filled, whose replay
// answers the deferred call — the parked caller wakes with the filled value.
#[test]
fn postponed_call_answered_after_transition() {
let got = Arc::new(Mutex::new(None::<u32>));
let g2 = got.clone();
run(move || {
let m = LatchSm::start(L::Empty, LData { value: 0, takes: 0 });
// Child actor issues the Take while Empty; its call parks on the reply.
let m2 = m.clone();
let taken = Arc::new(Mutex::new(None::<u32>));
let t2 = taken.clone();
smarm::scheduler::spawn(move || {
let v = m2.call(|r| LEv::Call(LCall::Take(r))).unwrap();
*t2.lock().unwrap() = Some(v);
});
smarm::sleep(Duration::from_millis(20)); // let the Take land and be deferred
// While deferred, the latch is untouched: still Empty, no take completed.
// (These reads are stays — they don't disturb the postponed event.)
assert_eq!(m.call(|r| LEv::Call(LCall::Status(r))).unwrap(), L::Empty);
assert_eq!(m.call(|r| LEv::Call(LCall::Takes(r))).unwrap(), 0);
m.send(LEv::Cast(LCast::Fill(42))).unwrap(); // Empty -> Filled: replays the Take
smarm::sleep(Duration::from_millis(20)); // let the child wake with its reply
*g2.lock().unwrap() = *taken.lock().unwrap();
});
assert_eq!(*got.lock().unwrap(), Some(42), "postponed call answered by the Filled state");
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum R {
S0,
S1,
S2,
}
struct RData {
marks: u32, // Marks handled (only S2 handles one)
}
enum RCast {
Go, // S0 -> S1 -> S2 -> S0
Mark, // postponed in S0/S1, handled in S2
}
enum RCall {
Marks(Reply<u32>),
State(Reply<R>),
}
gen_statem! {
machine: RelaySm { state: R, data: RData };
event: REv { cast: RCast, call: RCall, info: () };
context(data, prev, cx);
enter { _ => {} }
on R::S0 => {
cast RCast::Go => R::S1,
cast RCast::Mark => postpone,
}
on R::S1 => {
cast RCast::Go => R::S2,
cast RCast::Mark => postpone, // a replay here defers again
}
on R::S2 => {
cast RCast::Go => R::S0,
cast RCast::Mark => { data.marks += 1; prev }, // finally handled
}
on _ => {
call RCall::Marks(r) => { r.reply(data.marks); prev },
call RCall::State(r) => { r.reply(prev); prev },
state_timeout => unhandled,
timeout _ => unhandled,
}
}
// A postponed event that is replayed into a state which *also* postpones it
// re-queues, and is handled only once a state that accepts it is reached. Each
// `Marks` call is a stay that acts as a sync barrier after the preceding casts.
#[test]
fn replayed_event_can_postpone_again() {
let got = Arc::new(Mutex::new((9u32, 9u32, 9u32, R::S0)));
let g2 = got.clone();
run(move || {
let m = RelaySm::start(R::S0, RData { marks: 0 });
m.send(REv::Cast(RCast::Mark)).unwrap(); // S0: postponed
let a = m.call(|r| REv::Call(RCall::Marks(r))).unwrap(); // deferred -> 0
m.send(REv::Cast(RCast::Go)).unwrap(); // S0 -> S1: replay Mark -> postponed again
let b = m.call(|r| REv::Call(RCall::Marks(r))).unwrap(); // re-deferred -> 0
m.send(REv::Cast(RCast::Go)).unwrap(); // S1 -> S2: replay Mark -> handled
let c = m.call(|r| REv::Call(RCall::Marks(r))).unwrap(); // -> 1
let s = m.call(|r| REv::Call(RCall::State(r))).unwrap(); // Mark was a stay in S2
*g2.lock().unwrap() = (a, b, c, s);
});
let (a, b, c, s) = *got.lock().unwrap();
assert_eq!(a, 0, "deferred while S0");
assert_eq!(b, 0, "re-deferred while S1");
assert_eq!(c, 1, "handled once S2 is reached");
assert_eq!(s, R::S2, "Mark handled as a stay in S2");
}
tests/introspect.rs
-354
View File
@@ -1,354 +0,0 @@
//! RFC 016 Chunk 1 — the read primitive. These exercise exactly what the RFC
//! promised: tests that assert an actor's state, parentage, names, mailbox
//! depth, and lifecycle counts directly off `snapshot()` / `actor_info()`
//! instead of sleeping-and-hoping.
use smarm::{
actor_info, channel, monitor, register, run, self_pid, send, snapshot, spawn, tree, tree_from,
ActorInfo, ActorState, Name, Pid, RuntimeSnapshot, SNAPSHOT_FORMAT_VERSION,
};
const SVC: Name<u64> = Name::new("svc");
/// Bounded poll on the introspection result itself (not a wall-clock sleep):
/// yield until `pred` holds for the given pid, panicking if it never does.
fn spin_until(pid: Pid, mut pred: impl FnMut(&smarm::ActorInfo) -> bool) -> smarm::ActorInfo {
for _ in 0..100_000 {
if let Some(info) = actor_info(pid) {
if pred(&info) {
return info;
}
}
smarm::yield_now();
}
panic!("actor {pid:?} never reached the expected state");
}
#[test]
fn snapshot_lists_actors_with_parent_edge() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let (_cmd_tx, cmd_rx) = channel::<u64>();
let h = spawn(move || {
register(Name::<u64>::new("w"), _cmd_tx).unwrap();
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap(); // park here until released
drop(cmd_rx);
});
ready_rx.recv().unwrap();
let me = self_pid();
let snap = snapshot();
assert_eq!(snap.format_version, SNAPSHOT_FORMAT_VERSION);
let worker = snap
.actors
.iter()
.find(|a| a.pid == h.pid())
.expect("worker present in snapshot");
assert_eq!(worker.names, vec!["w"]);
// `spawn` records the spawning actor as the parent (D9).
assert_eq!(worker.supervisor, me);
assert!(!worker.trap_exit);
assert_eq!((worker.monitors, worker.links, worker.joiners), (0, 0, 0));
// The root itself is on-CPU (it's running this code) and rooted under
// the forest sentinel.
let root = snap.actors.iter().find(|a| a.pid == me).expect("root present");
assert_eq!(root.state, ActorState::Running);
assert_eq!(root.supervisor, smarm::Pid::new(u32::MAX, u32::MAX));
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn parked_state_is_observable() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let h = spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap();
// The worker has nothing to do but block on the empty gate channel, so
// it must reach Parked.
let info = spin_until(h.pid(), |a| a.state == ActorState::Parked);
assert_eq!(info.state, ActorState::Parked);
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn mailbox_depth_counts_queued_messages() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let (cmd_tx, _cmd_rx) = channel::<u64>();
let h = spawn(move || {
// Publish the command inbox, then block on an unrelated gate so the
// queued commands are never drained while we observe them.
register(SVC, cmd_tx).unwrap();
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
drop(_cmd_rx);
});
ready_rx.recv().unwrap();
for i in 0..3 {
send(SVC, i).unwrap();
}
// Depth is a property of the queue, set synchronously by `send`, so it
// reads 3 regardless of the worker's scheduling state.
let via_snapshot = snapshot()
.actors
.into_iter()
.find(|a| a.pid == h.pid())
.expect("worker present");
assert_eq!(via_snapshot.mailbox_depth, 3);
assert_eq!(actor_info(h.pid()).unwrap().mailbox_depth, 3);
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn monitor_count_is_visible() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let h = spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap();
let _m = monitor(h.pid());
let info = actor_info(h.pid()).expect("worker present");
assert_eq!(info.monitors, 1);
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn stale_and_forged_pids_return_none() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let h = spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap();
let live = h.pid();
// Same slot index, wrong generation → stale, no such incarnation.
let stale = Pid::new(live.index(), live.generation().wrapping_add(7));
assert!(actor_info(stale).is_none());
// Out-of-range index → not in the slab at all.
let forged = Pid::new(u32::MAX - 1, 0);
assert!(actor_info(forged).is_none());
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn done_actor_is_a_tombstone() {
run(|| {
// Hold the join handle so the slot is NOT reclaimed when the actor
// exits: outstanding_handles stays > 0, leaving a Done tombstone to
// observe.
let h = spawn(|| {});
let pid = h.pid();
let info = spin_until(pid, |a| a.state == ActorState::Done);
assert_eq!(info.state, ActorState::Done);
// The Actor record is gone at finalize, so a tombstone reports root-less
// with empty lifecycle counts.
assert_eq!(info.supervisor, Pid::new(u32::MAX, u32::MAX));
assert_eq!((info.monitors, info.links, info.joiners), (0, 0, 0));
h.join().unwrap();
});
}
#[test]
fn tree_places_child_under_its_spawner() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let h = spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap();
let me = self_pid();
let t = tree();
assert_eq!(t.format_version, SNAPSHOT_FORMAT_VERSION);
// The root is parented at the forest sentinel, so it's a genuine root,
// and the worker it spawned hangs beneath it.
let root = t.roots.iter().find(|n| n.info.pid == me).expect("root in forest");
assert!(!root.orphaned);
assert!(
root.children.iter().any(|c| c.info.pid == h.pid()),
"spawned worker should be a child of its spawner"
);
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
/// D8 re-rooting and nesting, exercised on a synthetic snapshot via the public
/// `tree_from` — the live lifecycle race (parent reclaimed while child lives)
/// is exactly what's awkward to stage deterministically, which is why the fold
/// is testable in isolation.
#[test]
fn tree_from_nests_children_and_reroots_orphans() {
let root_sentinel = Pid::new(u32::MAX, u32::MAX);
let root_pid = Pid::new(0, 1);
let child = Pid::new(1, 1);
let orphan = Pid::new(2, 1);
let absent_parent = Pid::new(99, 1);
let mk = |pid: Pid, supervisor: Pid| ActorInfo {
pid,
names: Vec::new(),
state: ActorState::Running,
supervisor,
trap_exit: false,
monitors: 0,
links: 0,
joiners: 0,
mailbox_depth: 0,
overruns: 0,
messages_received: 0,
budget_cycles: 0,
};
let snap = RuntimeSnapshot {
format_version: SNAPSHOT_FORMAT_VERSION,
actors: vec![
mk(root_pid, root_sentinel),
mk(child, root_pid),
mk(orphan, absent_parent),
],
};
let t = tree_from(snap);
assert_eq!(t.roots.len(), 2);
let root = t.roots.iter().find(|n| n.info.pid == root_pid).expect("root present");
assert!(!root.orphaned);
assert_eq!(root.children.len(), 1);
assert_eq!(root.children[0].info.pid, child);
assert!(!root.children[0].orphaned);
let o = t.roots.iter().find(|n| n.info.pid == orphan).expect("orphan re-rooted");
assert!(o.orphaned, "an actor whose parent is absent must be flagged orphaned");
assert!(o.children.is_empty());
}
#[test]
fn overrun_count_increments_on_forced_preemption() {
run(|| {
// A worker that forces its slice to expire, then hits an observation
// point so the slice-expiry site fires and tallies one overrun.
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let h = spawn(move || {
smarm::preempt::expire_timeslice_for_test();
smarm::check!(); // preempt-yield here → one overrun tallied
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap(); // worker is past the forced preemption
let info = actor_info(h.pid()).expect("worker present");
assert!(
info.overruns >= 1,
"forced timeslice expiry should tally at least one overrun, got {}",
info.overruns
);
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn messages_received_counts_dequeues() {
const MQ: Name<u64> = Name::new("mq");
const N: u64 = 5;
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (done_tx, done_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let (cmd_tx, cmd_rx) = channel::<u64>();
let h = spawn(move || {
register(MQ, cmd_tx).unwrap();
ready_tx.send(()).unwrap(); // sends don't count toward received
for _ in 0..N {
cmd_rx.recv().unwrap(); // each dequeue tallies one
}
done_tx.send(()).unwrap();
gate_rx.recv().unwrap(); // happens only after we've checked
});
ready_rx.recv().unwrap();
for i in 0..N {
send(MQ, i).unwrap();
}
done_rx.recv().unwrap(); // worker has drained all N
let info = actor_info(h.pid()).expect("worker present");
assert_eq!(info.messages_received, N, "one tally per dequeued message");
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[cfg(feature = "budget-accounting")]
#[test]
fn budget_cycles_accumulate_when_enabled() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let h = spawn(move || {
// A little work so the consumed slice is non-trivial, then park.
let mut acc = 0u64;
for i in 0..10_000u64 {
acc = acc.wrapping_add(i);
smarm::check!();
}
std::hint::black_box(acc);
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap();
// Once the worker has run and yielded (here, parked), its slice is
// charged.
let info = spin_until(h.pid(), |a| a.state == ActorState::Parked);
assert!(
info.budget_cycles > 0,
"budget should accrue after the actor runs and yields"
);
gate_tx.send(()).unwrap();
h.join().unwrap();
});
}
tests/io_epoll.rs
-43
View File
@@ -322,46 +322,3 @@ fn wait_writable_on_empty_pipe_returns_quickly() {
elapsed elapsed
); );
} }
// ---------------------------------------------------------------------------
// Fd hygiene on actor death (v0.8)
// ---------------------------------------------------------------------------
// An actor stopped while parked on an fd must not leak its `waiters` entry:
// before the unwind-path guard in wait_fd, the stale entry made every
// future wait_*() on that fd fail with AlreadyExists, forever.
#[test]
fn stopped_waiter_does_not_poison_the_fd() {
let outcome = Arc::new(StdMutex::new(None::<u8>));
let outcome2 = outcome.clone();
run(move || {
let p = Pipe::new();
let (rfd, wfd) = (p.read, p.write);
// First waiter parks on the (empty) pipe and is stopped in place.
let h = smarm::spawn(move || {
wait_readable(rfd).unwrap();
unreachable!("the pipe is never written while this actor lives");
});
yield_now(); // let it reach the park
smarm::request_stop(h.pid());
h.join().unwrap(); // Ok(()): stopped, not panicked
// Second waiter on the SAME fd must be able to register...
let seen = Arc::new(AtomicU32::new(0));
let seen2 = seen.clone();
let h2 = smarm::spawn(move || {
wait_readable(rfd).unwrap();
let mut buf = [0u8; 1];
assert_eq!(raw_read(rfd, &mut buf), 1);
seen2.store(buf[0] as u32, Ordering::SeqCst);
});
yield_now(); // ...and park (a failed register would panic the unwrap)
// ...and actually be woken by readiness.
assert_eq!(raw_write(wfd, b"x"), 1);
h2.join().unwrap();
*outcome2.lock().unwrap() = Some(seen.load(Ordering::SeqCst) as u8);
});
assert_eq!(*outcome.lock().unwrap(), Some(b'x'));
}
tests/mutex.rs
+1 -2
View File
@@ -1,5 +1,4 @@
//! `smarm::Mutex<T>` (the actor-blocking mutex) tests. All run under the //! `loom::Mutex<T>` tests. All run under the scheduler because `lock()`
//! scheduler because `lock()`
//! needs to be able to park. //! needs to be able to park.
use smarm::{run, spawn, yield_now, LockTimeout, Mutex}; use smarm::{run, spawn, yield_now, LockTimeout, Mutex};
tests/observer.rs
-121
View File
@@ -1,121 +0,0 @@
//! RFC 016 Chunk 4 — the observer gen_server. The whole file is gated on the
//! `observer` feature (run with `cargo test --features observer`); without it
//! the module does not exist and there is nothing to compile.
//!
//! The point these prove: the observer is *transport over the same reads*. Each
//! verb returns exactly what the corresponding Chunk-1 primitive would, just
//! marshalled over the gen_server call channel — so a known spawned actor that
//! `snapshot()` / `actor_info()` would see is equally visible through the
//! observer.
#![cfg(feature = "observer")]
use smarm::observer::{self, ObserverReply, ObserverRequest};
use smarm::{channel, run, ActorState, SNAPSHOT_FORMAT_VERSION};
#[test]
fn observer_relays_snapshot_tree_and_actor_info() {
run(|| {
// A worker parked on an empty gate: a known, stable actor for the
// observer to find across all three verbs.
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let worker = smarm::spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap();
});
ready_rx.recv().unwrap();
let obs = observer::start();
// Snapshot: the worker is present, and so is the observer itself — it
// is a scheduled actor like any other.
let ObserverReply::Snapshot(snap) = obs.call(ObserverRequest::Snapshot).unwrap() else {
panic!("Snapshot verb must reply Snapshot");
};
assert_eq!(snap.format_version, SNAPSHOT_FORMAT_VERSION);
assert!(
snap.actors.iter().any(|a| a.pid == worker.pid()),
"observer's snapshot should contain the spawned worker"
);
assert!(
snap.actors.iter().any(|a| a.pid == obs.pid()),
"observer should appear in the snapshot it produced"
);
// Tree: same data folded into the parentage forest, same version.
let ObserverReply::Tree(t) = obs.call(ObserverRequest::Tree).unwrap() else {
panic!("Tree verb must reply Tree");
};
assert_eq!(t.format_version, SNAPSHOT_FORMAT_VERSION);
fn contains(nodes: &[smarm::TreeNode], pid: smarm::Pid) -> bool {
nodes
.iter()
.any(|n| n.info.pid == pid || contains(&n.children, pid))
}
assert!(
contains(&t.roots, worker.pid()),
"worker should appear somewhere in the observer's tree"
);
// ActorInfo: coherent single-actor view, matching a direct read.
let ObserverReply::ActorInfo(Some(info)) =
obs.call(ObserverRequest::ActorInfo(worker.pid())).unwrap()
else {
panic!("ActorInfo verb must reply ActorInfo(Some) for a live worker");
};
assert_eq!(info.pid, worker.pid());
gate_tx.send(()).unwrap();
worker.join().unwrap();
});
}
#[test]
fn observer_reports_none_for_a_forged_pid() {
run(|| {
let obs = observer::start();
// An index that is not in the slab at all — the verb relays the
// primitive's `None` faithfully.
let forged = smarm::Pid::new(u32::MAX - 1, 0);
let ObserverReply::ActorInfo(none) =
obs.call(ObserverRequest::ActorInfo(forged)).unwrap()
else {
panic!("ActorInfo verb must reply ActorInfo");
};
assert!(none.is_none(), "a forged pid should relay as None");
});
}
#[test]
fn observer_sees_a_parked_actor_as_parked() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (gate_tx, gate_rx) = channel::<()>();
let worker = smarm::spawn(move || {
ready_tx.send(()).unwrap();
gate_rx.recv().unwrap(); // nothing to do but park on the gate
});
ready_rx.recv().unwrap();
let obs = observer::start();
// Bounded poll through the observer until the worker reaches Parked —
// proving the live state classification rides the call channel intact.
let mut parked = false;
for _ in 0..100_000 {
let ObserverReply::ActorInfo(info) =
obs.call(ObserverRequest::ActorInfo(worker.pid())).unwrap()
else {
panic!("ActorInfo verb must reply ActorInfo");
};
if matches!(info, Some(i) if i.state == ActorState::Parked) {
parked = true;
break;
}
smarm::yield_now();
}
assert!(parked, "observer should eventually report the worker as Parked");
gate_tx.send(()).unwrap();
worker.join().unwrap();
});
}
tests/pg.rs
-131
View File
@@ -1,131 +0,0 @@
//! Process-group tests that run under the scheduler: `join` installs a real
//! monitor on a live actor, and a real death drives eviction on next contact.
//! (Pure structural invariants live in the `pg` unit tests.)
use smarm::{channel, members, pick, run, spawn};
use smarm::{join, leave};
#[test]
fn join_then_members_lists_a_live_member() {
run(|| {
let (tx, rx) = channel::<()>();
let h = spawn(move || {
rx.recv().unwrap();
});
let pid = h.pid();
assert!(join("workers", pid), "first join is new");
assert!(!join("workers", pid), "second join is idempotent");
assert_eq!(members("workers"), vec![pid]);
assert_eq!(pick("workers"), Some(pid));
tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn a_dead_actor_vanishes_from_every_group_it_joined() {
run(|| {
let (tx, rx) = channel::<()>();
let h = spawn(move || {
rx.recv().unwrap();
});
let pid = h.pid();
join("g1", pid);
join("g2", pid);
assert_eq!(members("g1"), vec![pid]);
assert_eq!(members("g2"), vec![pid]);
// Release and reap the actor. finalize_actor queues the Down to our
// monitors before unparking joiners, so by the time join() returns the
// Down is already waiting in the membership channel.
tx.send(()).unwrap();
h.join().unwrap();
// Drain-on-contact: touching g1 detects the death and sweeps the pid
// out of every group (g2 included), not just g1.
assert!(members("g1").is_empty(), "evicted from the touched group");
assert!(members("g2").is_empty(), "and swept from the untouched group");
assert_eq!(pick("g1"), None);
});
}
#[test]
fn pick_returns_none_when_the_only_member_is_dead() {
run(|| {
let (tx, rx) = channel::<()>();
let h = spawn(move || {
rx.recv().unwrap();
});
let pid = h.pid();
join("pool", pid);
tx.send(()).unwrap();
h.join().unwrap();
assert_eq!(pick("pool"), None);
assert!(members("pool").is_empty());
});
}
#[test]
fn live_members_survive_a_peers_death() {
run(|| {
let (tx_a, rx_a) = channel::<()>();
let (tx_b, rx_b) = channel::<()>();
let a = spawn(move || {
rx_a.recv().unwrap();
});
let b = spawn(move || {
rx_b.recv().unwrap();
});
join("svc", a.pid());
join("svc", b.pid());
// Kill a; b is still parked on its channel.
tx_a.send(()).unwrap();
a.join().unwrap();
assert_eq!(members("svc"), vec![b.pid()], "only the dead peer is reaped");
assert_eq!(pick("svc"), Some(b.pid()));
tx_b.send(()).unwrap();
b.join().unwrap();
});
}
#[test]
fn leave_drops_a_membership_without_affecting_others() {
run(|| {
let (tx_a, rx_a) = channel::<()>();
let (tx_b, rx_b) = channel::<()>();
let a = spawn(move || {
rx_a.recv().unwrap();
});
let b = spawn(move || {
rx_b.recv().unwrap();
});
join("g", a.pid());
join("g", b.pid());
assert!(leave("g", a.pid()), "a was a member");
assert!(!leave("g", a.pid()), "leaving twice finds nothing");
assert_eq!(members("g"), vec![b.pid()]);
tx_a.send(()).unwrap();
tx_b.send(()).unwrap();
a.join().unwrap();
b.join().unwrap();
});
}
#[test]
fn joining_an_already_dead_pid_is_evicted_on_next_contact() {
run(|| {
let h = spawn(|| {});
let pid = h.pid();
h.join().unwrap(); // actor is finalized before we join it to anything
// monitor() on a gone pid queues a NoProc Down immediately, so the
// membership is reaped the next time the group is touched.
join("late", pid);
assert!(members("late").is_empty(), "dead-at-join member is reaped on read");
assert_eq!(pick("late"), None);
});
}
tests/poison_stop.rs
-89
View File
@@ -1,89 +0,0 @@
//! Regression: request_stop racing an alloc-under-lock must not poison any
//! runtime mutex. Before the fix, check_cancelled() fired regardless of
//! PREEMPTION_ENABLED, so a sentinel unwind could trigger inside with_shared
//! (which allocates: run_queue.push_back, waiters.push, etc), poisoning the
//! shared mutex and cascading lock().unwrap() panics.
use smarm::runtime::{init, Config};
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
#[test]
fn stop_storm_does_not_poison_runtime() {
// alloc_interval(1): every allocation is an observation point, so pre-fix
// the sentinel fires inside with_shared's alloc sites (run_queue.push_back,
// waiters.push, ...) with near-certainty rather than 1-in-128.
let rt = init(Config::exact(4).alloc_interval(1));
let completed = Arc::new(AtomicUsize::new(0));
let c = completed.clone();
rt.run(move || {
// Spawn many short actors that allocate + yield heavily (hammering
// with_shared), and request_stop each one mid-flight from siblings.
let mut handles = Vec::new();
for _ in 0..200 {
let h = smarm::spawn(|| {
for _ in 0..50 {
let _v: Vec<u8> = Vec::with_capacity(64); // alloc → maybe_preempt
smarm::yield_now();
}
});
handles.push(h);
}
// Cancel half of them; the others run to completion. If any lock got
// poisoned the runtime would panic on a subsequent lock().unwrap().
for (i, h) in handles.iter().enumerate() {
if i % 2 == 0 {
smarm::request_stop(h.pid());
}
}
for h in handles {
let _ = h.join();
}
c.fetch_add(1, Ordering::SeqCst);
});
assert_eq!(completed.load(Ordering::SeqCst), 1, "root completed cleanly");
}
/// The sharper repro: a stop-flagged actor whose *next allocation* is the
/// `Box::new(closure)` inside `spawn`'s `with_shared` critical section.
/// Pre-fix, the ungated `check_cancelled` in `maybe_preempt` raises the
/// sentinel right there, unwinding while the global shared mutex is held →
/// poisoned → every later `with_shared` panics on every scheduler thread and
/// the whole runtime collapses. Post-fix, observation is deferred to the next
/// lock-free point and each actor dies a clean `Outcome::Stopped`.
///
/// `request_stop(self_pid())` sets the flag without parking (we're running),
/// and the capturing closure makes `Box::new(f)` a real allocation. With
/// `alloc_interval(1)` the check fires every other allocation, so each actor
/// has ~50% odds of the check landing on the under-lock alloc; 64 actors make
/// a pre-fix escape astronomically unlikely.
#[test]
fn self_stop_during_spawn_does_not_poison_shared_mutex() {
let rt = init(Config::exact(4).alloc_interval(1));
let completed = Arc::new(AtomicUsize::new(0));
let c = completed.clone();
rt.run(move || {
let mut handles = Vec::new();
for i in 0..64usize {
let h = smarm::spawn(move || {
// Vary pre-stop allocation count to cover both phases of the
// every-other-allocation check cadence.
for _ in 0..(i % 2) {
let _phase: Vec<u8> = Vec::with_capacity(8);
}
let payload = vec![0u8; 64]; // captured → Box::new(f) allocates
smarm::request_stop(smarm::self_pid());
let grandchild = smarm::spawn(move || drop(payload));
let _ = grandchild.join();
});
handles.push(h);
}
for h in handles {
// Stopped reports Ok from join; the point is that join itself
// (with_shared) doesn't panic on a poisoned mutex.
let _ = h.join();
}
c.fetch_add(1, Ordering::SeqCst);
});
assert_eq!(completed.load(Ordering::SeqCst), 1, "root completed cleanly");
}
tests/registry.rs
-251
View File
@@ -1,251 +0,0 @@
//! Mailbox-registry tests (RFC 014). Run under the scheduler: registration
//! captures a live actor's channel, resolution checks liveness.
//!
//! Workers register their *own* inbox (`register` claims the current actor);
//! the root closure resolves and sends by name. A `ready` handshake closes the
//! register-then-send race without busy-waiting on `whereis`.
use smarm::{
channel, install, register, run, send, send_dyn, send_to, spawn, unregister, whereis,
Addressable, Name, Pid, RegisterError, SendError,
};
const SVC: Name<u64> = Name::new("svc");
#[test]
fn register_then_send_by_name_delivers() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (tx, rx) = channel::<u64>();
let h = spawn(move || {
register(SVC, tx).unwrap();
ready_tx.send(()).unwrap();
assert_eq!(rx.recv().unwrap(), 42);
});
ready_rx.recv().unwrap(); // worker has registered
assert_eq!(whereis("svc"), Some(h.pid()));
send(SVC, 42).unwrap();
h.join().unwrap();
});
}
#[test]
fn one_actor_many_typed_channels_route_by_type() {
// Same name, two message types: capability separation falls out of the
// type parameter — `Name<u64>` and `Name<&str>` hit different channels of
// the one actor (RFC 014 §4.7).
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (cmd_tx, cmd_rx) = channel::<u64>();
let (adm_tx, adm_rx) = channel::<&'static str>();
let h = spawn(move || {
register(Name::<u64>::new("port"), cmd_tx).unwrap();
register(Name::<&'static str>::new("port"), adm_tx).unwrap();
ready_tx.send(()).unwrap();
assert_eq!(cmd_rx.recv().unwrap(), 7);
assert_eq!(adm_rx.recv().unwrap(), "halt");
});
ready_rx.recv().unwrap();
send(Name::<u64>::new("port"), 7u64).unwrap();
send(Name::<&'static str>::new("port"), "halt").unwrap();
h.join().unwrap();
});
}
#[test]
fn name_held_by_live_actor_is_taken() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (tx_a, rx_a) = channel::<u64>();
let a = spawn(move || {
register(SVC, tx_a).unwrap();
ready_tx.send(()).unwrap();
assert_eq!(rx_a.recv().unwrap(), 0); // wait to be released
});
ready_rx.recv().unwrap();
// Root tries to claim a live actor's name for itself -> NameTaken.
let (tx_b, _rx_b) = channel::<u64>();
assert_eq!(register(SVC, tx_b), Err(RegisterError::NameTaken { holder: a.pid() }));
send(SVC, 0).unwrap(); // release a (delivers to the holder, a)
a.join().unwrap();
});
}
#[test]
fn dead_holder_is_pruned_and_name_taken_over() {
// a registers, signals, then dies. Its slot index is typically reused by b;
// b's registration must prune the stale binding and take the name over.
run(|| {
let (rt1, rr1) = channel::<()>();
let (tx1, _rx1) = channel::<u64>();
let a = spawn(move || {
register(SVC, tx1).unwrap();
rt1.send(()).unwrap(); // then return -> die, _rx1 dropped
});
rr1.recv().unwrap();
let a_pid = a.pid();
a.join().unwrap(); // a is dead; "svc" now points at a stale pid
let (rt2, rr2) = channel::<()>();
let (tx2, rx2) = channel::<u64>();
let b = spawn(move || {
register(SVC, tx2).unwrap(); // takes over the freed name
rt2.send(()).unwrap();
assert_eq!(rx2.recv().unwrap(), 9);
});
rr2.recv().unwrap();
assert_ne!(b.pid(), a_pid); // distinct incarnation even if slot reused
assert_eq!(whereis("svc"), Some(b.pid()));
send(SVC, 9).unwrap();
b.join().unwrap();
});
}
#[test]
fn send_errors_unresolved_and_no_channel() {
run(|| {
// No actor at all.
assert!(matches!(send(Name::<u64>::new("ghost"), 1u64), Err(SendError::Unresolved(_))));
let (ready_tx, ready_rx) = channel::<()>();
let (tx, rx) = channel::<u64>();
let h = spawn(move || {
register(Name::<u64>::new("svc2"), tx).unwrap();
ready_tx.send(()).unwrap();
assert_eq!(rx.recv().unwrap(), 0);
});
ready_rx.recv().unwrap();
// Right actor, wrong message type: it has a u64 channel, not a String.
let e = send(Name::<String>::new("svc2"), "x".to_string());
assert!(matches!(e, Err(SendError::NoChannel(_))));
assert_eq!(e.unwrap_err().into_inner(), "x"); // message handed back
send(Name::<u64>::new("svc2"), 0u64).unwrap();
h.join().unwrap();
});
}
#[test]
fn unregister_frees_the_name_only() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (done_tx, done_rx) = channel::<()>();
let (tx, _rx) = channel::<u64>(); // _rx moves into the actor, kept open
let h = spawn(move || {
register(SVC, tx).unwrap();
let _keep_open = _rx;
ready_tx.send(()).unwrap();
done_rx.recv().unwrap(); // released over a separate channel
});
ready_rx.recv().unwrap();
assert_eq!(whereis("svc"), Some(h.pid()));
assert_eq!(unregister("svc"), Some(h.pid()));
assert_eq!(whereis("svc"), None);
assert!(matches!(send(SVC, 1u64), Err(SendError::Unresolved(_))));
done_tx.send(()).unwrap();
h.join().unwrap();
});
}
// --- RFC 014 §4.2: direct, identity-bound addressing via `Pid<A>` ----------
// A stand-in single-message actor. `install::<Worker>` publishes its inbox and
// returns a `Pid<Worker>` that delivers `u64` to exactly that incarnation.
struct Worker;
impl Addressable for Worker {
type Msg = u64;
}
#[test]
fn install_then_send_to_pid_delivers() {
run(|| {
let (addr_tx, addr_rx) = channel::<Pid<Worker>>();
let h = spawn(move || {
let (tx, rx) = channel::<u64>();
let me = install::<Worker>(tx); // nameless publish, typed pid back
addr_tx.send(me).unwrap();
assert_eq!(rx.recv().unwrap(), 42);
});
let addr = addr_rx.recv().unwrap(); // worker installed, handed its Pid<Worker>
assert_eq!(addr.erase(), h.pid()); // same identity, just re-typed
send_to(addr, 42u64).unwrap();
h.join().unwrap();
});
}
#[test]
fn send_to_does_not_redirect_after_takeover() {
// The load-bearing §4.2 property: a `Pid<A>` is identity-bound. When the
// actor dies and a new incarnation reuses the slot, sending to the *old*
// address fails `Dead` — it must never silently reach the new occupant
// (that redirect is the re-resolving `Name`'s job, not a pid's).
run(|| {
let (addr_a_tx, addr_a_rx) = channel::<Pid<Worker>>();
let (rt1, rr1) = channel::<()>();
let a = spawn(move || {
let (tx, _rx) = channel::<u64>();
let me = install::<Worker>(tx);
addr_a_tx.send(me).unwrap();
rt1.send(()).unwrap(); // then return -> die
});
let a_addr = addr_a_rx.recv().unwrap();
rr1.recv().unwrap();
a.join().unwrap(); // a dead; a_addr names a dead incarnation
let (addr_b_tx, addr_b_rx) = channel::<Pid<Worker>>();
let (rt2, rr2) = channel::<()>();
let b = spawn(move || {
let (tx, rx) = channel::<u64>();
let me = install::<Worker>(tx); // reuses a's slot index, new generation
addr_b_tx.send(me).unwrap();
rt2.send(()).unwrap();
// Only b's own message ever arrives; the stale send never redirects.
assert_eq!(rx.recv().unwrap(), 7);
});
let b_addr = addr_b_rx.recv().unwrap();
rr2.recv().unwrap();
assert_ne!(b_addr.erase(), a_addr.erase()); // distinct incarnation
assert!(matches!(send_to(a_addr, 99u64), Err(SendError::Dead(_)))); // no redirect
send_to(b_addr, 7u64).unwrap(); // b's real message
b.join().unwrap();
});
}
// --- RFC 014 §4.6: explicit bare-pid escape hatch ---------------------------
#[test]
fn send_dyn_delivers_and_reports_wrong_type() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (done_tx, done_rx) = channel::<()>();
let (tx, rx) = channel::<u64>();
let h = spawn(move || {
register(Name::<u64>::new("dyn"), tx).unwrap(); // publishes a u64 channel
ready_tx.send(()).unwrap();
assert_eq!(rx.recv().unwrap(), 3);
done_rx.recv().unwrap(); // stay alive for the wrong-type probe
});
ready_rx.recv().unwrap();
let p = h.pid(); // a bare Pid<Erased>, as if recovered off a Down
send_dyn::<u64>(p, 3u64).unwrap(); // right type: delivered
// Live actor, but it has no channel for &str — the genuinely-fallible case.
assert!(matches!(send_dyn::<&'static str>(p, "nope"), Err(SendError::NoChannel(_))));
done_tx.send(()).unwrap();
h.join().unwrap();
});
}
#[test]
fn send_dyn_to_dead_pid_is_dead() {
run(|| {
let (ready_tx, ready_rx) = channel::<()>();
let (tx, _rx) = channel::<u64>();
let h = spawn(move || {
register(Name::<u64>::new("dyn2"), tx).unwrap();
ready_tx.send(()).unwrap(); // then return -> die
});
ready_rx.recv().unwrap();
let p = h.pid();
h.join().unwrap(); // dead; the bare pid now names a dead incarnation
assert!(matches!(send_dyn::<u64>(p, 1u64), Err(SendError::Dead(_))));
});
}
tests/select.rs
-342
View File
@@ -1,342 +0,0 @@
//! select tests. Beyond the functional cases, the *_stays_precise tests are
//! soundness probes for the consuming-wake protocol: they fire stale loser-
//! arm wakes at an actor and then run a one-shot park (`sleep`, whose early
//! return would be observable as a short elapsed time) to prove the stale
//! wake died at its epoch CAS instead of corrupting the next wait.
use smarm::{channel, run, select, spawn};
use std::sync::atomic::{AtomicI64, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
#[test]
fn ready_arm_returns_immediately_without_parking() {
let out = Arc::new(AtomicI64::new(0));
let out2 = out.clone();
run(move || {
let (txa, rxa) = channel::<i64>();
let (_txb, rxb) = channel::<i64>();
txa.send(42).unwrap();
let i = select(&[&rxb, &rxa]);
assert_eq!(i, 1);
out2.store(rxa.try_recv().unwrap().expect("ready arm must hold a message"), Ordering::SeqCst);
});
assert_eq!(out.load(Ordering::SeqCst), 42);
}
#[test]
fn lower_index_wins_when_several_arms_are_ready() {
run(|| {
let (txa, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
txa.send(1).unwrap();
txb.send(2).unwrap();
// Documented priority order: index 0 first, regardless of send order.
assert_eq!(select(&[&rxa, &rxb]), 0);
assert_eq!(select(&[&rxb, &rxa]), 0);
});
}
#[test]
fn parks_until_any_arm_fires() {
let out = Arc::new(AtomicI64::new(0));
let out2 = out.clone();
run(move || {
let (txa, _rxa_keepalive) = (channel::<i64>().0, ());
let _hold = txa; // arm a: sender alive, never sends
let (txa, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
let _keep_a_open = txa;
let h = spawn(move || {
smarm::sleep(Duration::from_millis(10));
txb.send(7).unwrap();
});
let i = select(&[&rxa, &rxb]);
assert_eq!(i, 1);
out2.store(rxb.try_recv().unwrap().unwrap(), Ordering::SeqCst);
h.join().unwrap();
});
assert_eq!(out.load(Ordering::SeqCst), 7);
}
#[test]
fn closed_arm_counts_as_ready() {
run(|| {
let (_keep, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
drop(txb);
let i = select(&[&rxa, &rxb]);
assert_eq!(i, 1);
// The caller observes the closure on the arm itself.
assert!(rxb.try_recv().is_err());
});
}
#[test]
fn closure_while_parked_wakes_the_select() {
run(|| {
let (_keep, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
let h = spawn(move || {
smarm::sleep(Duration::from_millis(10));
drop(txb);
});
assert_eq!(select(&[&rxa, &rxb]), 1);
assert!(rxb.try_recv().is_err());
h.join().unwrap();
});
}
#[test]
fn loser_arm_wake_after_parked_select_stays_precise() {
// Both arms registered; arm 0 wins the wake; arm 1's sender then fires
// a wake stamped with the consumed epoch. The subsequent sleep is a
// one-shot park: an early return would mean the stale wake landed.
run(|| {
let (txa, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
let h = spawn(move || {
smarm::sleep(Duration::from_millis(10));
txa.send(1).unwrap(); // wins
txb.send(2).unwrap(); // loser arm: stale-epoch wake
});
assert_eq!(select(&[&rxa, &rxb]), 0);
assert_eq!(rxa.try_recv().unwrap(), Some(1));
let t0 = Instant::now();
smarm::sleep(Duration::from_millis(40));
assert!(
t0.elapsed() >= Duration::from_millis(40),
"one-shot park returned early: a stale loser-arm wake landed"
);
// The loser's message was never lost.
assert_eq!(select(&[&rxa, &rxb]), 1);
assert_eq!(rxb.try_recv().unwrap(), Some(2));
h.join().unwrap();
});
}
#[test]
fn no_park_exit_retires_the_wait() {
// Arm 1 is ready at registration time, so select returns WITHOUT
// parking while arm 0 holds a live-epoch registration. Arm 0's sender
// then fires. retire_wait must have invalidated/eaten that wake;
// the sleep proves it.
run(|| {
let (txa, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
txb.send(2).unwrap();
assert_eq!(select(&[&rxa, &rxb]), 1);
assert_eq!(rxb.try_recv().unwrap(), Some(2));
let h = spawn(move || {
txa.send(1).unwrap(); // fires at the (retired) select epoch
});
h.join().unwrap();
let t0 = Instant::now();
smarm::sleep(Duration::from_millis(40));
assert!(
t0.elapsed() >= Duration::from_millis(40),
"one-shot park returned early: the no-park exit leaked a wake"
);
assert_eq!(rxa.try_recv().unwrap(), Some(1));
});
}
#[test]
fn select_then_plain_recv_on_a_loser_arm() {
// A leftover own-registration from a select must not trip the next
// direct wait on that channel (it is overwritten, not asserted away).
run(|| {
let (txa, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
txa.send(1).unwrap();
assert_eq!(select(&[&rxa, &rxb]), 0); // rxb may keep a registration
assert_eq!(rxa.try_recv().unwrap(), Some(1));
let h = spawn(move || {
smarm::sleep(Duration::from_millis(5));
txb.send(9).unwrap();
});
assert_eq!(rxb.recv().unwrap(), 9);
h.join().unwrap();
});
}
#[test]
fn select_loop_drains_two_producers_completely() {
const N: i64 = 200;
let out = Arc::new(AtomicI64::new(0));
let out2 = out.clone();
run(move || {
let (txa, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
let ha = spawn(move || {
for v in 0..N {
txa.send(v).unwrap();
if v % 7 == 0 {
smarm::yield_now();
}
}
});
let hb = spawn(move || {
for v in 0..N {
txb.send(v).unwrap();
if v % 5 == 0 {
smarm::yield_now();
}
}
});
// A closed arm stays permanently ready, so it must leave the arm
// set once observed (keeping it would starve the other arm at
// priority order) — select until the FIRST closure, then drain the
// survivor with plain recv.
let mut sum = 0i64;
let survivor: &smarm::Receiver<i64> = loop {
let i = select(&[&rxa, &rxb]);
let arm: &smarm::Receiver<i64> = if i == 0 { &rxa } else { &rxb };
match arm.try_recv() {
Ok(Some(v)) => sum += v,
Ok(None) => {} // defensive: ready arm already drained
Err(_) => break if i == 0 { &rxb } else { &rxa },
}
};
loop {
match survivor.recv() {
Ok(v) => sum += v,
Err(_) => break,
}
}
out2.store(sum, Ordering::SeqCst);
ha.join().unwrap();
hb.join().unwrap();
});
assert_eq!(out.load(Ordering::SeqCst), 2 * (0..200i64).sum::<i64>());
}
#[test]
fn motivating_pattern_inbox_plus_monitor_down() {
// The gen_server/handle_info shape select unlocks: a server waiting on
// its request inbox AND a monitor Down channel in one park.
use smarm::monitor;
run(|| {
let (req_tx, req_rx) = channel::<i64>();
let worker = spawn(|| {
smarm::sleep(Duration::from_millis(10));
// worker exits -> Down fires
});
let m = monitor(worker.pid());
let _keep_inbox_open = req_tx;
let mut served = 0;
loop {
match select(&[&m.rx, &req_rx]) {
0 => {
let _down = m.rx.try_recv().unwrap().expect("Down message");
break;
}
_ => {
if let Ok(Some(_)) = req_rx.try_recv() {
served += 1;
}
}
}
}
assert_eq!(served, 0);
worker.join().unwrap();
});
}
// ---------------------------------------------------------------------------
// select_timeout
// ---------------------------------------------------------------------------
use smarm::select_timeout;
#[test]
fn select_timeout_returns_none_after_the_deadline() {
run(|| {
let (_keep_a, rxa) = channel::<i64>();
let (_keep_b, rxb) = channel::<i64>();
let t0 = Instant::now();
let r = select_timeout(&[&rxa, &rxb], Duration::from_millis(30));
assert_eq!(r, None);
assert!(t0.elapsed() >= Duration::from_millis(30));
});
}
#[test]
fn select_timeout_ready_arm_wins_without_arming_a_timer() {
run(|| {
let (txa, rxa) = channel::<i64>();
let (_keep_b, rxb) = channel::<i64>();
txa.send(5).unwrap();
assert_eq!(select_timeout(&[&rxb, &rxa], Duration::from_millis(500)), Some(1));
assert_eq!(rxa.try_recv().unwrap(), Some(5));
});
}
#[test]
fn select_timeout_arm_beats_timer_and_stale_entry_stays_inert() {
run(|| {
let (txa, rxa) = channel::<i64>();
let (_keep_b, rxb) = channel::<i64>();
let h = spawn(move || {
smarm::sleep(Duration::from_millis(5));
txa.send(1).unwrap();
});
let t0 = Instant::now();
let r = select_timeout(&[&rxa, &rxb], Duration::from_millis(200));
assert_eq!(r, Some(0));
assert!(t0.elapsed() < Duration::from_millis(200));
assert_eq!(rxa.try_recv().unwrap(), Some(1));
h.join().unwrap();
// The abandoned timer entry expires mid-sleep; a stale-epoch wake
// landing would return this one-shot park early.
let t1 = Instant::now();
smarm::sleep(Duration::from_millis(250));
assert!(
t1.elapsed() >= Duration::from_millis(250),
"one-shot park returned early: the stale select timer landed"
);
});
}
#[test]
fn select_timeout_timer_first_message_still_delivered_later() {
run(|| {
let (txa, rxa) = channel::<i64>();
let h = spawn(move || {
smarm::sleep(Duration::from_millis(60));
txa.send(9).unwrap();
});
assert_eq!(select_timeout(&[&rxa], Duration::from_millis(10)), None);
// The wait is over but the channel is intact: the late message
// arrives and a fresh select sees it.
assert_eq!(select(&[&rxa]), 0);
assert_eq!(rxa.try_recv().unwrap(), Some(9));
h.join().unwrap();
});
}
#[test]
fn select_timeout_zero_duration_polls() {
run(|| {
let (txa, rxa) = channel::<i64>();
let (_keep_b, rxb) = channel::<i64>();
assert_eq!(select_timeout(&[&rxa, &rxb], Duration::ZERO), None);
txa.send(3).unwrap();
assert_eq!(select_timeout(&[&rxa, &rxb], Duration::ZERO), Some(0));
assert_eq!(rxa.try_recv().unwrap(), Some(3));
});
}
#[test]
fn select_timeout_closed_arm_is_ready_not_a_timeout() {
run(|| {
let (_keep_a, rxa) = channel::<i64>();
let (txb, rxb) = channel::<i64>();
drop(txb);
assert_eq!(select_timeout(&[&rxa, &rxb], Duration::from_millis(200)), Some(1));
assert!(rxb.try_recv().is_err());
});
}
tests/terminal_wake.rs
-115
View File
@@ -1,115 +0,0 @@
//! Terminal wake: a scheduler thread blocked in the idle wait must be woken
//! when a sibling reaches the all-done verdict, or `rt.run` stalls in its
//! worker join.
//!
//! Mechanism (runtime.rs, `Pop::Idle`): an idle scheduler snapshots
//! `peek_deadline()` / `io_outstanding` and blocks in `poll_wake` (or
//! `thread::sleep`) on that snapshot. `enqueue` does not write the wake
//! pipe — only IO completions do — so the snapshot can go terminally stale:
//!
//! - An actor parked in `wait_readable` that is `request_stop`ped produces
//! NO completion (cancellation deregisters the waiter); a sibling that
//! blocked on `io_outstanding > 0` with no timers is in `poll(-1)` forever.
//! - An actor cancelled out of a long `sleep` leaves its timer entry
//! orphaned; a sibling that blocked on that deadline sleeps it out in full.
//!
//! In both cases the remaining work completes on the *other* scheduler
//! thread, which hits AllDone and returns — and nothing wakes the blocked
//! one. `Runtime::run` joins it: a permanent hang in the first case, a
//! full-deadline stall in the second.
//!
//! Both tests force the window deterministically: the root busy-spins
//! (creating no timer entries and occupying one scheduler thread) so the
//! other thread settles into the stale idle wait before the stop is issued.
use std::sync::mpsc;
use std::time::{Duration, Instant};
struct PipePair {
read: libc::c_int,
write: libc::c_int,
}
impl PipePair {
fn new() -> Self {
let mut fds: [libc::c_int; 2] = [0; 2];
let r = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_CLOEXEC | libc::O_NONBLOCK) };
assert_eq!(r, 0, "pipe2 failed");
PipePair { read: fds[0], write: fds[1] }
}
}
impl Drop for PipePair {
fn drop(&mut self) {
unsafe {
libc::close(self.read);
libc::close(self.write);
}
}
}
/// Occupy the current scheduler thread without creating timer entries or
/// parking. A plain spin has no observation points, so the root stays
/// on-CPU and the sibling scheduler is left alone with the idle branch.
fn spin_for(d: Duration) {
let t0 = Instant::now();
while t0.elapsed() < d {
std::hint::spin_loop();
}
}
/// Run `body` under a 2-scheduler runtime on a watchdog thread; fail if
/// `Runtime::run` has not returned within `limit`.
fn run_with_watchdog(limit: Duration, body: impl FnOnce() + Send + 'static) {
let (done_tx, done_rx) = mpsc::channel::<()>();
std::thread::spawn(move || {
let rt = smarm::init(smarm::Config::exact(2));
rt.run(body);
let _ = done_tx.send(());
});
done_rx
.recv_timeout(limit)
.expect("Runtime::run did not return: idle scheduler thread was never woken at termination");
}
/// Permanent-hang variant: sibling blocked in `poll_wake(wake_fd, None)`
/// because `io_outstanding > 0` (one actor parked in `wait_readable`) and no
/// timers are pending. The waiter is then stop-cancelled — no IO completion
/// ever writes the wake pipe — and everything else finishes on the root's
/// thread. Without a terminal wake, `rt.run` never returns.
#[test]
fn run_returns_after_io_waiter_is_stop_cancelled() {
run_with_watchdog(Duration::from_secs(10), || {
let pipe = PipePair::new();
let rfd = pipe.read;
let h = smarm::spawn(move || {
// Never-readable fd (write end open, nothing written).
let _ = smarm::wait_readable(rfd);
});
// Let the waiter park and the sibling scheduler settle into the
// io_outstanding>0 / no-timers idle wait: poll(wake_fd, -1).
spin_for(Duration::from_millis(200));
smarm::request_stop(h.pid());
let _ = h.join();
drop(pipe);
});
}
/// Finite-stall variant: sibling blocked on an orphaned long timer
/// deadline. An actor cancelled out of `sleep(60s)` leaves its timer entry
/// behind (documented as harmless at AllDone — but a sibling that already
/// blocked on that deadline sleeps it out in full, stalling `rt.run` for
/// the better part of a minute).
#[test]
fn run_returns_after_long_sleeper_is_stop_cancelled() {
run_with_watchdog(Duration::from_secs(10), || {
let h = smarm::spawn(|| {
smarm::sleep(Duration::from_secs(60));
});
// Let the sleeper park and the sibling scheduler block on the 60s
// deadline: poll(wake_fd, ~60_000ms).
spin_for(Duration::from_millis(200));
smarm::request_stop(h.pid());
let _ = h.join();
});
}
tests/timer.rs
+15 -215
View File
@@ -124,11 +124,11 @@ use smarm::pid::Pid;
use smarm::timer::{Reason, TimerTarget, Timers}; use smarm::timer::{Reason, TimerTarget, Timers};
struct RecordingTarget { struct RecordingTarget {
calls: Mutex<Vec<(Pid, u32)>>, calls: Mutex<Vec<(Pid, u64)>>,
} }
impl TimerTarget for RecordingTarget { impl TimerTarget for RecordingTarget {
fn on_timeout(&self, pid: Pid, epoch: u32) { fn on_timeout(&self, pid: Pid, seq: u64) {
self.calls.lock().unwrap().push((pid, epoch)); self.calls.lock().unwrap().push((pid, seq));
} }
} }
@@ -137,9 +137,9 @@ fn timers_pop_due_returns_entries_in_deadline_order() {
let mut t = Timers::new(); let mut t = Timers::new();
let now = Instant::now(); let now = Instant::now();
// Insert out of order; pop_due should hand them back sorted by deadline. // Insert out of order; pop_due should hand them back sorted by deadline.
t.insert_sleep(now + Duration::from_millis(30), Pid::new(0, 0), 1); t.insert_sleep(now + Duration::from_millis(30), Pid::new(0, 0));
t.insert_sleep(now + Duration::from_millis(10), Pid::new(1, 0), 1); t.insert_sleep(now + Duration::from_millis(10), Pid::new(1, 0));
t.insert_sleep(now + Duration::from_millis(20), Pid::new(2, 0), 1); t.insert_sleep(now + Duration::from_millis(20), Pid::new(2, 0));
// Advance past all of them. // Advance past all of them.
let due = t.pop_due(now + Duration::from_millis(50)); let due = t.pop_due(now + Duration::from_millis(50));
@@ -152,8 +152,8 @@ fn timers_pop_due_returns_entries_in_deadline_order() {
fn timers_only_pop_entries_whose_deadline_has_passed() { fn timers_only_pop_entries_whose_deadline_has_passed() {
let mut t = Timers::new(); let mut t = Timers::new();
let now = Instant::now(); let now = Instant::now();
t.insert_sleep(now + Duration::from_millis(5), Pid::new(0, 0), 1); t.insert_sleep(now + Duration::from_millis(5), Pid::new(0, 0));
t.insert_sleep(now + Duration::from_millis(100), Pid::new(1, 0), 1); t.insert_sleep(now + Duration::from_millis(100), Pid::new(1, 0));
let due = t.pop_due(now + Duration::from_millis(20)); let due = t.pop_due(now + Duration::from_millis(20));
assert_eq!(due.len(), 1); assert_eq!(due.len(), 1);
@@ -169,11 +169,11 @@ fn timers_mix_sleep_and_wait_timeout_reasons() {
let target = Arc::new(RecordingTarget { calls: Mutex::new(Vec::new()) }); let target = Arc::new(RecordingTarget { calls: Mutex::new(Vec::new()) });
let now = Instant::now(); let now = Instant::now();
t.insert_sleep(now + Duration::from_millis(5), Pid::new(0, 0), 1); t.insert_sleep(now + Duration::from_millis(5), Pid::new(0, 0));
t.insert( t.insert(
now + Duration::from_millis(10), now + Duration::from_millis(10),
Pid::new(1, 0), Pid::new(1, 0),
Reason::WaitTimeout { target: target.clone(), epoch: 42 }, Reason::WaitTimeout { target: target.clone(), wait_seq: 42 },
); );
let due = t.pop_due(now + Duration::from_millis(20)); let due = t.pop_due(now + Duration::from_millis(20));
@@ -181,11 +181,11 @@ fn timers_mix_sleep_and_wait_timeout_reasons() {
// Order: Sleep (5ms) first, WaitTimeout (10ms) second. // Order: Sleep (5ms) first, WaitTimeout (10ms) second.
match &due[0].reason { match &due[0].reason {
Reason::Sleep { .. } => {} Reason::Sleep => {}
_ => panic!("first entry should be a Sleep"), _ => panic!("first entry should be a Sleep"),
} }
match &due[1].reason { match &due[1].reason {
Reason::WaitTimeout { epoch, .. } => assert_eq!(*epoch, 42), Reason::WaitTimeout { wait_seq, .. } => assert_eq!(*wait_seq, 42),
_ => panic!("second entry should be a WaitTimeout"), _ => panic!("second entry should be a WaitTimeout"),
} }
} }
@@ -197,211 +197,11 @@ fn same_deadline_entries_pop_in_insertion_order() {
let mut t = Timers::new(); let mut t = Timers::new();
let now = Instant::now(); let now = Instant::now();
let d = now + Duration::from_millis(10); let d = now + Duration::from_millis(10);
t.insert_sleep(d, Pid::new(0, 0), 1); t.insert_sleep(d, Pid::new(0, 0));
t.insert_sleep(d, Pid::new(1, 0), 1); t.insert_sleep(d, Pid::new(1, 0));
t.insert_sleep(d, Pid::new(2, 0), 1); t.insert_sleep(d, Pid::new(2, 0));
let due = t.pop_due(now + Duration::from_millis(20)); let due = t.pop_due(now + Duration::from_millis(20));
let pids: Vec<u32> = due.iter().map(|e| e.pid.index()).collect(); let pids: Vec<u32> = due.iter().map(|e| e.pid.index()).collect();
assert_eq!(pids, vec![0, 1, 2]); assert_eq!(pids, vec![0, 1, 2]);
} }
// ---------------------------------------------------------------------------
// send_after / cancel_timer — the message-delivery timer substrate.
//
// Unit tests drive `Timers` directly with a flag-flipping fire thunk (no
// runtime needed, mirroring RecordingTarget above). Integration tests drive
// the public scheduler API and assert real registry-resolved delivery.
// ---------------------------------------------------------------------------
use std::sync::atomic::{AtomicBool, Ordering};
// Pull the Send fire thunk out of a popped entry and run it.
fn run_fire(entry: smarm::timer::Entry) {
match entry.reason {
Reason::Send { fire } => fire(),
_ => panic!("expected a Send entry"),
}
}
#[test]
fn armed_send_timer_is_returned_and_fires() {
let mut t = Timers::new();
let now = Instant::now();
let fired = Arc::new(AtomicBool::new(false));
let f = fired.clone();
let _id = t.insert_send(
now + Duration::from_millis(10),
Pid::new(0, 0),
Box::new(move || f.store(true, Ordering::SeqCst)),
);
let mut due = t.pop_due(now + Duration::from_millis(20));
assert_eq!(due.len(), 1, "an armed send timer should pop when due");
assert!(!fired.load(Ordering::SeqCst), "pop must not fire on its own");
run_fire(due.pop().unwrap());
assert!(fired.load(Ordering::SeqCst), "running the thunk delivers");
assert!(t.is_empty());
}
#[test]
fn cancelled_send_timer_is_discarded_not_returned() {
let mut t = Timers::new();
let now = Instant::now();
let fired = Arc::new(AtomicBool::new(false));
let f = fired.clone();
let id = t.insert_send(
now + Duration::from_millis(10),
Pid::new(0, 0),
Box::new(move || f.store(true, Ordering::SeqCst)),
);
assert!(t.cancel(id), "cancel before fire returns true");
let due = t.pop_due(now + Duration::from_millis(20));
assert!(due.is_empty(), "a cancelled send timer must not pop");
assert!(!fired.load(Ordering::SeqCst));
}
#[test]
fn cancel_after_fire_returns_false() {
// The race signal Mark wanted: cancelling a timer that already fired tells
// you it was too late.
let mut t = Timers::new();
let now = Instant::now();
let id = t.insert_send(
now + Duration::from_millis(5),
Pid::new(0, 0),
Box::new(|| {}),
);
let due = t.pop_due(now + Duration::from_millis(10));
assert_eq!(due.len(), 1);
assert!(!t.cancel(id), "cancel after the timer fired returns false");
}
#[test]
fn cancel_unknown_id_returns_false() {
let mut t = Timers::new();
let now = Instant::now();
let id = t.insert_send(now + Duration::from_millis(5), Pid::new(0, 0), Box::new(|| {}));
assert!(t.cancel(id));
// Second cancel of the same id: already gone.
assert!(!t.cancel(id));
}
#[test]
fn send_timers_interleave_with_sleep_in_deadline_order() {
let mut t = Timers::new();
let now = Instant::now();
t.insert_sleep(now + Duration::from_millis(30), Pid::new(0, 0), 1);
let _id = t.insert_send(now + Duration::from_millis(10), Pid::new(1, 0), Box::new(|| {}));
t.insert_sleep(now + Duration::from_millis(20), Pid::new(2, 0), 1);
let due = t.pop_due(now + Duration::from_millis(50));
assert_eq!(due.len(), 3);
// 10ms Send, then 20ms Sleep, then 30ms Sleep.
assert!(matches!(due[0].reason, Reason::Send { .. }));
assert_eq!(due[1].pid.index(), 2);
assert_eq!(due[2].pid.index(), 0);
}
#[test]
fn clear_drops_armed_send_timers() {
let mut t = Timers::new();
let now = Instant::now();
let id = t.insert_send(now + Duration::from_millis(10), Pid::new(0, 0), Box::new(|| {}));
t.clear();
assert!(t.is_empty());
// The arm record is gone too: cancelling reports nothing to cancel.
assert!(!t.cancel(id));
}
// --- Integration: real delivery through the scheduler + registry. ---
use smarm::{cancel_timer, channel, register, send_after_named, Name};
#[test]
fn send_after_named_delivers_after_the_delay() {
const PING: Name<u64> = Name::new("send_after_ping");
run(|| {
let (tx, rx) = channel::<u64>();
register(PING, tx).unwrap();
let t0 = Instant::now();
let _id = send_after_named(Duration::from_millis(30), PING, 99);
assert_eq!(rx.recv().unwrap(), 99);
assert!(
t0.elapsed() >= Duration::from_millis(25),
"delivered too early: {:?}",
t0.elapsed()
);
});
}
#[test]
fn cancel_timer_prevents_delivery() {
const C: Name<u64> = Name::new("send_after_cancel");
run(|| {
let (tx, rx) = channel::<u64>();
register(C, tx).unwrap();
let id = send_after_named(Duration::from_millis(50), C, 7);
assert!(cancel_timer(id), "cancel before fire returns true");
sleep(Duration::from_millis(90));
assert_eq!(rx.try_recv(), Ok(None), "cancelled timer delivered anyway");
});
}
#[test]
fn send_after_to_unresolved_name_is_silent() {
const NOPE: Name<u64> = Name::new("send_after_nobody_home");
run(|| {
// Nobody registered NOPE; firing resolves to nothing and is dropped.
let _id = send_after_named(Duration::from_millis(10), NOPE, 1);
sleep(Duration::from_millis(40)); // let it fire and no-op
// Reaching here without a panic is the assertion.
});
}
// --- Integration: typed Pid<A> delivery (exercises send_to on fire). ---
use smarm::{send_after, send_to, spawn_addr, Addressable, Receiver};
struct Sink;
impl Addressable for Sink {
type Msg = u64;
}
#[test]
fn send_after_delivers_to_typed_pid() {
run(|| {
// A reply channel so the test actor learns what Sink received.
let (report_tx, report_rx) = channel::<u64>();
let sink: Pid<Sink> = spawn_addr::<Sink>(move |rx: Receiver<u64>| {
if let Ok(v) = rx.recv() {
let _ = report_tx.send(v);
}
});
let _id = send_after(Duration::from_millis(25), sink, 1234);
assert_eq!(report_rx.recv().unwrap(), 1234);
});
}
#[test]
fn send_after_to_dead_typed_pid_is_silent() {
run(|| {
// Sink exits immediately after handling one message; arm a second
// delivery for after it's gone. The fire-time send_to returns Dead and
// is dropped — no panic.
let (report_tx, report_rx) = channel::<u64>();
let sink: Pid<Sink> = spawn_addr::<Sink>(move |rx: Receiver<u64>| {
if let Ok(v) = rx.recv() {
let _ = report_tx.send(v);
}
// body returns -> actor exits
});
send_to(sink, 1).unwrap();
assert_eq!(report_rx.recv().unwrap(), 1); // sink has now exited
let _id = send_after(Duration::from_millis(15), sink, 2);
sleep(Duration::from_millis(45)); // let it fire against the dead pid
// No panic, and nothing further delivered.
assert_eq!(report_rx.try_recv(), Ok(None));
});
}
tests/wake_slot.rs
-176
View File
@@ -1,176 +0,0 @@
//! RFC 005 wake-slot tests: correctness with the slot on, push-policy
//! discrimination (actor vs scheduler context, spawns), displacement, the
//! default-off contract, and per-run counter reset.
//!
//! The slot is same-thread plain ops behind the existing queue-op contract,
//! so there is nothing new to model-check (RFC 005 §Summary); these tests
//! pin the *policy* — who lands in the slot, who never does — which is
//! observable through the `slot_hits` / `slot_displacements` counters.
use smarm::channel::channel;
use smarm::runtime::{init, Config};
use smarm::spawn;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
/// Ping-pong over channels: the slot's home pattern. Returns total roundtrips.
fn ping_pong(pairs: usize, roundtrips: u64) -> impl FnOnce() + Send + 'static {
move || {
let handles: Vec<_> = (0..pairs)
.map(|_| {
spawn(move || {
let (tx_ab, rx_ab) = channel::<u64>();
let (tx_ba, rx_ba) = channel::<u64>();
let echo = spawn(move || {
for _ in 0..roundtrips {
let v = rx_ab.recv().expect("echo recv");
tx_ba.send(v + 1).expect("echo send");
}
});
for i in 0..roundtrips {
tx_ab.send(i).expect("ping send");
assert_eq!(rx_ba.recv().expect("ping recv"), i + 1);
}
let _ = echo.join();
})
})
.collect();
for h in handles {
h.join().expect("pair");
}
}
}
// ---------------------------------------------------------------------------
// Correctness: messaging workloads complete with the slot on, 1 and N threads
// ---------------------------------------------------------------------------
#[test]
fn ping_pong_correct_with_slot_on_single_thread() {
let rt = init(Config::exact(1).wake_slot(true));
rt.run(ping_pong(4, 200));
}
#[test]
fn ping_pong_correct_with_slot_on_multi_thread() {
let rt = init(Config::exact(4).wake_slot(true));
rt.run(ping_pong(8, 200));
}
// ---------------------------------------------------------------------------
// Push policy: actor-context wakes hit the slot; the default is off
// ---------------------------------------------------------------------------
#[test]
fn messaging_workload_exercises_the_slot() {
let rt = init(Config::exact(1).wake_slot(true));
rt.run(ping_pong(2, 100));
let stats = rt.stats();
assert!(
stats.slot_hits() > 0,
"send-wakes are actor-context unparks — the slot must see hits, got 0"
);
}
#[test]
fn slot_off_means_zero_slot_traffic() {
// Off explicitly…
let rt = init(Config::exact(1).wake_slot(false));
rt.run(ping_pong(2, 100));
assert_eq!(rt.stats().slot_hits(), 0);
assert_eq!(rt.stats().slot_displacements(), 0);
// …and off by default (RFC 005: default off until the shootout accepts).
let rt = init(Config::exact(1));
rt.run(ping_pong(2, 100));
assert_eq!(rt.stats().slot_hits(), 0, "wake_slot must default to OFF");
}
// ---------------------------------------------------------------------------
// Push policy: spawns and join-wakes (finalize = scheduler context) bypass
// ---------------------------------------------------------------------------
#[test]
fn spawn_join_workload_bypasses_the_slot() {
let rt = init(Config::exact(1).wake_slot(true));
rt.run(|| {
for _ in 0..20 {
let handles: Vec<_> = (0..50).map(|_| spawn(|| {})).collect();
for h in handles {
h.join().expect("trivial actor");
}
}
});
let stats = rt.stats();
assert_eq!(
stats.slot_hits(),
0,
"spawns go shared by policy and joiner wakes fire from finalize \
(scheduler context) — a pure spawn/join workload must never touch \
the slot"
);
assert_eq!(stats.slot_displacements(), 0);
}
// ---------------------------------------------------------------------------
// Displacement: newest wake takes the slot, occupant goes shared — and runs
// ---------------------------------------------------------------------------
#[test]
fn displaced_occupant_reaches_the_shared_queue_and_runs() {
// Single thread, strict FIFO (rq-mutex default): rx1 and rx2 park on
// their recvs before the sender runs; the sender's back-to-back sends
// then produce two actor-context wakes — the second displaces the first.
let rt = init(Config::exact(1).wake_slot(true));
let ran = Arc::new(AtomicU64::new(0));
let (r1, r2) = (ran.clone(), ran.clone());
rt.run(move || {
let (tx1, rx1) = channel::<u32>();
let (tx2, rx2) = channel::<u32>();
let h1 = spawn(move || {
assert_eq!(rx1.recv().expect("rx1"), 1);
r1.fetch_add(1, Ordering::Relaxed);
});
let h2 = spawn(move || {
assert_eq!(rx2.recv().expect("rx2"), 2);
r2.fetch_add(1, Ordering::Relaxed);
});
let sender = spawn(move || {
tx1.send(1).expect("send 1"); // rx1 → slot
tx2.send(2).expect("send 2"); // rx2 → slot, rx1 displaced → shared
});
sender.join().expect("sender");
h1.join().expect("h1");
h2.join().expect("h2");
});
assert_eq!(ran.load(Ordering::Relaxed), 2, "both receivers must run");
let stats = rt.stats();
assert!(
stats.slot_displacements() >= 1,
"back-to-back wakes of parked receivers must displace at least once"
);
assert!(stats.slot_hits() >= 1, "the displacing wake is slot-popped");
}
// ---------------------------------------------------------------------------
// Counters reset at the start of each run() on a reused Runtime
// ---------------------------------------------------------------------------
#[test]
fn slot_counters_reset_per_run() {
let rt = init(Config::exact(1).wake_slot(true));
rt.run(ping_pong(2, 100));
let first = rt.stats().slot_hits();
assert!(first > 0);
// A slot-bypassing run on the same handle must read 0, not `first`.
rt.run(|| {
let h = spawn(|| {});
h.join().expect("trivial");
});
assert_eq!(
rt.stats().slot_hits(),
0,
"counters are reset at run() start; the second run had no slot traffic"
);
}