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

gen_server: type Timer + handle_timer/handle_idle; fold control into Sys channel (RFC 015 §4.5, §6)

Browse Source
This commit is contained in:
smarm-agent
2026-06-18 18:54:24 +00:00
parent 47d75d1ead
commit 57eadb5c6c
3 changed files with 94 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/gen_server.rs
+84 -29
View File
@@ -73,12 +73,25 @@ pub trait GenServer: Send + 'static {
/// ([`ServerBuilder::with_info`]). Servers with several out-of-band
/// sources enum them up into one `Info`. Use `()` if unused.
type Info: Send + 'static;
/// The server's own scheduled-timer payload, delivered to
/// [`handle_timer`](Self::handle_timer) when a timer armed via the loop's
/// [`TimerHandle`] fires (RFC 015). Kept distinct from
/// [`Info`](Self::Info) — `Info` is *external* out-of-band traffic, `Timer`
/// is the server's *own* fires — so the system/userspace split stays
/// legible and a tagged timer round-trips
/// (`arm_after(d, Tk::Retry(n))` → `handle_timer(Tk::Retry(n))`). Use `()`
/// if unused, exactly as `Info` does.
type Timer: Send + 'static;
/// Runs once inside the server actor before any message is handled. The
/// [`ServerCtx`] is the loop's one runtime hook: clone its [`Watcher`]
/// into the state here to be able to [`watch`](Watcher::watch) monitors
/// from any later handler.
fn init(&mut self, _ctx: &ServerCtx) {}
fn init(&mut self, _ctx: &ServerCtx<Self>)
where
Self: Sized,
{
}
/// Handle a synchronous call and produce the reply sent back to the caller.
fn handle_call(&mut self, request: Self::Call) -> Self::Reply;
@@ -94,6 +107,21 @@ pub trait GenServer: Send + 'static {
/// [`Watcher::watch`]. Default: drop it.
fn handle_down(&mut self, _down: Down) {}
/// Handle a fired timer armed through the loop's [`TimerHandle`]
/// ([`arm_after`](TimerHandle::arm_after) /
/// [`tick_every`](TimerHandle::tick_every)). Timer fires re-enter at system
/// priority — above infos and the inbox — so a heartbeat cannot be starved
/// by userspace traffic. Default: drop it (RFC 015 §6).
fn handle_timer(&mut self, _msg: Self::Timer) {}
/// Handle a receive/idle timeout: fired when the loop has waited a full
/// idle window (set once via [`ServerCtx::idle_after`]) with no message of
/// any kind dispatched. The window resets on every dispatched message and
/// re-arms after this fires (a steady idle detector); a server wanting
/// one-shot idle-shutdown simply requests its own stop here. Default: no-op
/// (RFC 015 §4.4, §6).
fn handle_idle(&mut self) {}
/// Runs as the server actor exits, on any exit path (see module docs).
fn terminate(&mut self) {}
}
@@ -221,16 +249,34 @@ impl<G: GenServer> ServerRef<G> {
}
}
/// The server loop's runtime hook, passed to [`GenServer::init`]. Currently
/// carries only the [`Watcher`]; opaque so fields can grow without breaking.
pub struct ServerCtx {
watcher: Watcher,
/// The server loop's internal *system intake* channel (RFC 015 §4.5). Control
/// (monitor handoff) and armed-timer fires are structurally the same — both are
/// loop-internal sources selected above the inbox — so they fold into one
/// channel, dispatched by variant. The arm stays open while any [`Watcher`] or
/// [`TimerHandle`] clone (or an in-flight fire thunk) still holds a sender.
enum Sys<G: GenServer> {
/// A monitor handed in via [`Watcher::watch`]; pushed onto the loop's
/// monitor set.
Watch(Monitor),
/// A fired one-shot timer carrying its loop-local id (so the loop can retire
/// it from the live set) and the server's payload, dispatched to
/// [`GenServer::handle_timer`].
// Constructed by `TimerHandle::arm_after` in the next RFC 015 chunk; until
// then only the `Watch` variant is produced.
#[allow(dead_code)]
Timer(crate::timer::TimerId, G::Timer),
}
impl ServerCtx {
/// The server loop's runtime hook, passed to [`GenServer::init`]. Currently
/// carries only the [`Watcher`]; opaque so fields can grow without breaking.
pub struct ServerCtx<G: GenServer> {
watcher: Watcher<G>,
}
impl<G: GenServer> ServerCtx<G> {
/// A clonable handle to the loop's monitor intake. Store it in the state
/// during `init` to watch monitors from later handlers.
pub fn watcher(&self) -> Watcher {
pub fn watcher(&self) -> Watcher<G> {
self.watcher.clone()
}
@@ -244,17 +290,24 @@ impl ServerCtx {
/// [`GenServer::handle_down`]. Down arms outrank every other arm (a death
/// notice cannot be starved), and a delivered `Down` retires its arm —
/// monitors are one-shot.
#[derive(Clone)]
pub struct Watcher {
tx: Sender<Monitor>,
pub struct Watcher<G: GenServer> {
tx: Sender<Sys<G>>,
}
impl Watcher {
// Manual Clone: deriving would demand `G: Clone`, but the handle is clonable
// regardless of the server type (it clones only the inner sender).
impl<G: GenServer> Clone for Watcher<G> {
fn clone(&self) -> Self {
Watcher { tx: self.tx.clone() }
}
}
impl<G: GenServer> Watcher<G> {
/// Transfer `m` to the server loop. If the server is already gone the
/// monitor is silently dropped (its queued `Down`, if any, with it) —
/// there is no loop left to care.
pub fn watch(&self, m: Monitor) {
let _ = self.tx.send(m);
let _ = self.tx.send(Sys::Watch(m));
}
}
@@ -490,18 +543,19 @@ fn server_loop<G: GenServer>(
let mut guard = Terminate(state);
// The control arm: Watchers feed Monitors to the loop through it. The
// ctx (and with it the loop's own sender) drops right after init — a
// state that didn't clone the Watcher closes the arm, the first select
// observes the closure, and the loop falls back to the plain-inbox park.
let (watch_tx, watch_rx) = channel::<Monitor>();
guard.0.init(&ServerCtx { watcher: Watcher { tx: watch_tx } });
// The system intake arm: Watchers feed Monitors and (next chunk) armed
// timers feed fires to the loop through it. The ctx (and with it the loop's
// own sender) drops right after init — a state that didn't clone the
// Watcher closes the arm, the first select observes the closure, and the
// loop falls back to the plain-inbox park.
let (sys_tx, sys_rx) = channel::<Sys<G>>();
guard.0.init(&ServerCtx { watcher: Watcher { tx: sys_tx } });
let mut monitors: Vec<Monitor> = Vec::new();
let mut watch_open = true;
let mut sys_open = true;
loop {
if monitors.is_empty() && !watch_open && infos.is_empty() {
if monitors.is_empty() && !sys_open && infos.is_empty() {
// Nothing to select over: park on the inbox alone, exactly the
// pre-v0.8 loop.
match rx.recv() {
@@ -510,19 +564,19 @@ fn server_loop<G: GenServer>(
Err(_) => break,
}
} else {
// Arm priority: downs, then the control arm, then infos (each in
// Arm priority: downs, then the system arm, then infos (each in
// declaration order), then the inbox. The arm slice is rebuilt
// per iteration because every set but the inbox shrinks or grows.
let nd = monitors.len();
let nw = watch_open as usize;
let nw = sys_open as usize;
let i = {
let mut arms: Vec<&dyn Selectable> =
Vec::with_capacity(nd + nw + infos.len() + 1);
for m in &monitors {
arms.push(&m.rx);
}
if watch_open {
arms.push(&watch_rx);
if sys_open {
arms.push(&sys_rx);
}
for r in &infos {
arms.push(r);
@@ -538,13 +592,14 @@ fn server_loop<G: GenServer>(
guard.0.handle_down(down);
}
} else if i < nd + nw {
match watch_rx.try_recv() {
Ok(Some(m)) => monitors.push(m),
match sys_rx.try_recv() {
Ok(Some(Sys::Watch(m))) => monitors.push(m),
Ok(Some(Sys::Timer(_id, msg))) => guard.0.handle_timer(msg),
// Single-receiver: nothing can drain the arm between
// select's ready and our try_recv.
Ok(None) => debug_assert!(false, "ready control arm was empty"),
// Every Watcher gone: stop selecting on the arm.
Err(_) => watch_open = false,
Ok(None) => debug_assert!(false, "ready system arm was empty"),
// Every Watcher/TimerHandle gone: stop selecting on the arm.
Err(_) => sys_open = false,
}
} else if i < nd + nw + infos.len() {
let j = i - nd - nw;