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

gen_server: docs — disambiguate client call deadline from server idle timeout (RFC 015 §7)

Browse Source
This commit is contained in:
smarm-agent
2026-06-18 19:20:12 +00:00
parent 1df85e2384
commit f454a9195a
1 changed files with 25 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/gen_server.rs
+25
View File
@@ -43,11 +43,29 @@
//! one. Keep it cheap and non-blocking: it may run mid-unwind, and a panic //! one. Keep it cheap and non-blocking: it may run mid-unwind, and a panic
//! inside it during an unwind aborts the process (a double panic). //! inside it during an unwind aborts the process (a double panic).
//! //!
//! ## Time (timers and idle)
//!
//! A server arms timers through a [`TimerHandle`] cloned from the [`ServerCtx`]
//! in `init` and stored on the state — the same shape as [`Watcher`] for
//! monitors. [`arm_after`](TimerHandle::arm_after) is a one-shot,
//! [`tick_every`](TimerHandle::tick_every) a periodic; both fire into
//! [`handle_timer`](GenServer::handle_timer) at *system priority* (above infos
//! and the inbox, by arm position), and [`cancel`](TimerHandle::cancel) carries
//! the substrate's race signal. Separately, [`ServerCtx::idle_after`] sets a
//! receive-timeout window: quiet for the whole window fires
//! [`handle_idle`](GenServer::handle_idle).
//!
//! Two unrelated things share the word *timeout*: the server-side **idle /
//! receive timeout** above, and the client-side **call deadline**
//! ([`ServerRef::call_timeout`]) — how long a caller waits for a reply. They sit
//! on different axes and never interact (RFC 015 §7).
//!
//! ## Not here (yet) //! ## Not here (yet)
//! //!
//! No dynamic info subscription: the info-channel set is fixed at start. //! No dynamic info subscription: the info-channel set is fixed at start.
//! Revisit against a real consumer. (Monitor `Down` forwarding is dynamic — //! Revisit against a real consumer. (Monitor `Down` forwarding is dynamic —
//! see `handle_down` — because monitors are inherently created at runtime.) //! see `handle_down` — because monitors are inherently created at runtime.)
//! The idle window is likewise set once, in `init` (RFC 015 §4.4).
use crate::channel::{channel, select, select_timeout, Receiver, RecvTimeoutError, Selectable, Sender}; use crate::channel::{channel, select, select_timeout, Receiver, RecvTimeoutError, Selectable, Sender};
use crate::monitor::{demonitor, monitor, Down, Monitor}; use crate::monitor::{demonitor, monitor, Down, Monitor};
@@ -199,6 +217,13 @@ impl<G: GenServer> ServerRef<G> {
/// Bounded synchronous request-reply: like [`call`](Self::call), but /// Bounded synchronous request-reply: like [`call`](Self::call), but
/// gives up after `timeout`, returning [`CallTimeoutError::Timeout`]. /// gives up after `timeout`, returning [`CallTimeoutError::Timeout`].
/// ///
/// This `timeout` is a **client-side call deadline** — how long *this caller*
/// waits for a reply — and is wholly separate from the server-side idle /
/// receive timeout ([`ServerCtx::idle_after`] →
/// [`GenServer::handle_idle`]), which measures quiet on the *server's* inbox.
/// Same word ("timeout"), two different axes (RFC 015 §7); neither touches
/// the other.
///
/// The roadmap sketched this as monitor + wait-reply-or-Down + demonitor; /// The roadmap sketched this as monitor + wait-reply-or-Down + demonitor;
/// that machinery is unnecessary here because server death is already /// that machinery is unnecessary here because server death is already
/// observable on the reply channel itself — the reply sender is dropped /// observable on the reply channel itself — the reply sender is dropped