Panics in terminate()
-
gen_server's terminate() runs from a drop guard, possibly mid-unwind. A panic inside it during an unwind is a double panic → process abort, no supervision tree to save you. Keep it cheap, non-blocking, non-panicking.
+
gen_server's terminate() runs from a drop guard, possibly mid-unwind. A panic inside it during an unwind is a double panic → process abort, no supervision tree to save you. On the panic and hard-stop paths keep it cheap, non-blocking, non-panicking. Only the graceful path (handle_shutdown → Exit, StopHandle::stop, inbox close) runs it outside an unwind, where it may do real work.
Cold locks are leaf locks
diff --git a/examples/graceful_shutdown.rs b/examples/graceful_shutdown.rs
new file mode 100644
index 0000000..9a9031d
--- /dev/null
+++ b/examples/graceful_shutdown.rs
@@ -0,0 +1,142 @@
+//! Graceful shutdown, end to end: a supervised app tree, a server that
+//! drains before it exits, and the two ways the whole thing winds down.
+//!
+//! Stopping an actor comes in two strengths, as in OTP:
+//! - `request_stop(pid)` = `exit(Pid, kill)`: cooperative hard stop,
+//! unwinds at the next observation point.
+//! - `request_shutdown(pid)` = `exit(Pid, shutdown)`: a trapping target gets
+//! an `ExitSignal { reason: Shutdown }` and winds
+//! down on its own terms; a non-trapping one is
+//! stopped outright.
+//!
+//! A supervisor traps exits. `request_shutdown(sup)` runs its ordered
+//! shutdown — children in reverse start order, each per its `ChildSpec`
+//! `Shutdown` policy (`Timeout(d)` default 5s, `Infinity`, `BrutalKill`) —
+//! and the supervisor then returns normally.
+//!
+//! Two triggers are shown:
+//! 1. **Root exit.** The run's root actor returning means "the program is
+//! done": the runtime delivers `request_shutdown` to every top-level actor
+//! (here: the supervisor). Trapping actors may keep running to drain and
+//! end the run when they stop themselves; non-trapping ones are stopped.
+//! 2. **An outside thread** (e.g. a signal handler) driving it via
+//! `RuntimeHandle::request_shutdown` on the supervisor — the root then
+//! just waits for the tree to come down.
+
+use smarm::gen_server::{
+ GenServer, GenServerBuilder, GenServerCtx, ShutdownAction, StopHandle, TimerHandle,
+};
+use smarm::supervisor::{ChildSpec, OneForOne, Restart, Shutdown};
+use smarm::{monitor, request_shutdown, self_pid, sleep, spawn, trap_exit, DownReason};
+use std::thread;
+use std::time::Duration;
+
+/// A server with in-flight work: on shutdown it stops accepting, finishes what
+/// it has (simulated with a ticking timer), then ends itself.
+struct Drainer {
+ pending: u32,
+ stop: Option
>,
+ timer: Option>,
+}
+
+impl GenServer for Drainer {
+ type Call = ();
+ type Reply = ();
+ type Cast = ();
+ type Info = ();
+ type Timer = ();
+
+ fn init(&mut self, ctx: &GenServerCtx) {
+ ctx.trap_exit(); // opt in: shutdown arrives as handle_shutdown
+ self.stop = Some(ctx.stop_handle());
+ self.timer = Some(ctx.timer());
+ }
+ fn handle_call(&mut self, _: ()) {}
+ fn handle_cast(&mut self, _: ()) {}
+ fn handle_shutdown(&mut self) -> ShutdownAction {
+ println!(
+ "drainer: shutdown requested, {} items pending",
+ self.pending
+ );
+ self.timer
+ .as_ref()
+ .unwrap()
+ .tick_every(Duration::from_millis(20), ());
+ ShutdownAction::Continue // keep serving until drained
+ }
+ fn handle_timer(&mut self, _: ()) {
+ self.pending -= 1;
+ if self.pending == 0 {
+ println!("drainer: drained, stopping");
+ self.stop.as_ref().unwrap().stop(); // normal exit
+ }
+ }
+ fn terminate(&mut self) {
+ // Graceful path: this runs on the normal path and may block.
+ println!("drainer: terminate");
+ }
+}
+
+/// A supervised child wrapping the server. (A gen_server is not yet directly
+/// usable as a `ChildSpec` start fn; the wrapper traps, forwards the shutdown,
+/// and waits for the server to finish. See ROADMAP "open items".)
+fn drainer_child() {
+ let inbox = trap_exit();
+ let srv = GenServerBuilder::new(Drainer {
+ pending: 3,
+ stop: None,
+ timer: None,
+ })
+ .under(self_pid())
+ .start();
+ let mon = monitor(srv.pid());
+ // Wait for our shutdown, forward it, wait for the server.
+ while let Ok(sig) = inbox.recv() {
+ if sig.reason == DownReason::Shutdown {
+ request_shutdown(srv.pid());
+ let _ = mon.rx.recv();
+ return;
+ }
+ }
+}
+
+fn app_tree() -> OneForOne {
+ OneForOne::new()
+ .child(
+ ChildSpec::new(Restart::Permanent, || {
+ // A plain worker that does not trap: stopped outright on shutdown.
+ loop {
+ sleep(Duration::from_millis(10));
+ }
+ })
+ .shutdown(Shutdown::Timeout(Duration::from_millis(100))),
+ )
+ .child(ChildSpec::new(Restart::Permanent, drainer_child).shutdown(Shutdown::Infinity))
+}
+
+fn main() {
+ println!("--- 1. root exit drives the shutdown ---");
+ smarm::run(|| {
+ spawn(|| app_tree().run());
+ sleep(Duration::from_millis(50)); // the app "runs" for a while
+ // Returning here asks the supervisor to shut down; the run ends when
+ // the tree — drainer included — is gone.
+ });
+
+ println!("--- 2. an outside thread drives the shutdown ---");
+ let rt = smarm::init(smarm::Config::default());
+ let handle = rt.handle(); // Send + Sync; grab it before run
+ rt.run(move || {
+ let sup = spawn(|| app_tree().run());
+ let sup_pid = sup.pid();
+ // Stand-in for a SIGTERM handler thread.
+ thread::spawn(move || {
+ thread::sleep(Duration::from_millis(50));
+ println!("signal thread: requesting shutdown");
+ handle.request_shutdown(sup_pid);
+ });
+ sup.join()
+ .expect("supervisor returns normally after ordered shutdown");
+ println!("supervisor down; root returns");
+ });
+}
diff --git a/examples/named_genserver.rs b/examples/named_genserver.rs
index 27f17ca..468ffd3 100644
--- a/examples/named_genserver.rs
+++ b/examples/named_genserver.rs
@@ -66,6 +66,12 @@ fn main() {
let svc: Option> = whereis_server(COUNTER);
if let Some(svc) = svc {
let _ = svc.call(Query::Get);
+ // A named server is pinned alive by the registry, so dropping refs
+ // does not end it. Stop it explicitly: `shutdown()` asks politely
+ // (a trapping server drains first; this one is stopped outright)
+ // and waits until it is gone. Left running, the root's return
+ // would shut it down the same way — see examples/graceful_shutdown.rs.
+ svc.shutdown();
}
});
}