From 9ca661ee8e684d720724673b69c8f8a110fb72b2 Mon Sep 17 00:00:00 2001 From: npub1cc3ha7z055mu0rwwu7806t2wt8mj3pvu0uv5mfp2c50dahaqhczshdalg6 Date: Sun, 2 Aug 2026 01:52:08 -0400 Subject: [PATCH] docs(terminal): say that the tail-depth signals have no consumer yet `tail_full` and `tail_drained` are the queue bound, and nothing outside the tests calls them: the runtime reader pumps `drain` to completion after every read, so the tail cannot reach the cap and nobody needs to ask. That is fine and it is the design -- the signal was built for the reader that stops pumping -- but an exported, documented predicate with an empty call graph reads as wired to anyone who doesn't go looking. Stated in the doc comment instead, because an unused signal that looks connected is worse than one that says it isn't. Co-authored-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com> Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com> --- desktop/src-tauri/crates/buzz-terminal/src/lib.rs | 1 + desktop/src-tauri/crates/buzz-terminal/src/reader.rs | 9 +++++++++ 2 files changed, 10 insertions(+) diff --git a/desktop/src-tauri/crates/buzz-terminal/src/lib.rs b/desktop/src-tauri/crates/buzz-terminal/src/lib.rs index 5959d79d9..9665ed07d 100644 --- a/desktop/src-tauri/crates/buzz-terminal/src/lib.rs +++ b/desktop/src-tauri/crates/buzz-terminal/src/lib.rs @@ -158,6 +158,7 @@ impl Terminal { } /// Whether the tail is at its cap and the reader must stop reading. + /// Not yet consumed in production -- see [`reader::Feeder::tail_full`]. pub fn tail_full(&self) -> bool { self.feeder.tail_full() } diff --git a/desktop/src-tauri/crates/buzz-terminal/src/reader.rs b/desktop/src-tauri/crates/buzz-terminal/src/reader.rs index 18ce98d41..4dc4aa46c 100644 --- a/desktop/src-tauri/crates/buzz-terminal/src/reader.rs +++ b/desktop/src-tauri/crates/buzz-terminal/src/reader.rs @@ -111,6 +111,15 @@ impl Feeder { /// latch is a state the fence owns and could fail to clear, which is /// exactly how a paused reader strands a child mid-teardown; a reader that /// simply stops asking resumes by default. + /// + /// **Not yet consumed in production.** The runtime reader pumps + /// [`Feeder::drain`] to completion after every read, so the tail cannot + /// currently grow to the cap and nothing needs to ask. This signal exists + /// for the reader that stops pumping -- it is the queue bound, and the + /// pump loop is the only reason the queue bound is not load-bearing + /// today. Stated rather than left to be inferred from an empty + /// call-graph: an unused signal that looks wired is worse than one that + /// says it isn't. pub fn tail_full(&self) -> bool { self.pending_bytes() >= TAIL_CAP }