diff --git a/src/app.rs b/src/app.rs index c57b2ace..12c537c6 100644 --- a/src/app.rs +++ b/src/app.rs @@ -1,8 +1,10 @@ +pub mod pacing; + use std::io::{self, Write}; -use std::time::Duration; +use std::time::{Duration, Instant}; use crossterm::event::{Event, EventStream, KeyEventKind}; -use futures::StreamExt; +use futures::{Stream, StreamExt}; use ratatui::backend::CrosstermBackend; use ratatui::layout::Rect; use ratatui::Terminal; @@ -13,6 +15,30 @@ use crate::pane::CompositePane; use crate::ui::WorkspaceWidget; use crate::wm::WindowManager; +pub use pacing::{FramePacer, LoopStats, ECHO_GRACE, FRAME_FLOOR}; + +/// Cadence of timers, RPC waiters and STT draining (PTY output no longer waits for it). +pub const TICK: Duration = Duration::from_millis(16); + +/// The always-on foreground RPC socket: request stream plus its handler. +pub type LiveRpcPair = (crate::api::live::LiveRpcRx, crate::api::live::LiveRpcHandler); + +/// Resolves on SIGINT (Ctrl+C), SIGTERM or SIGHUP. +async fn host_shutdown_signal() { + #[cfg(unix)] + let (mut sigterm, mut sighup) = { + use tokio::signal::unix::{signal, SignalKind}; + (signal(SignalKind::terminate()).ok(), signal(SignalKind::hangup()).ok()) + }; + #[cfg(not(unix))] + let (mut sigterm, mut sighup) = ((), ()); + tokio::select! { + _ = tokio::signal::ctrl_c() => {} + _ = next_unix_signal(&mut sigterm) => {} + _ = next_unix_signal(&mut sighup) => {} + } +} + static HOST_OUT_TAP: std::sync::OnceLock = std::sync::OnceLock::new(); /// `io::Stdout` wrapper that counts every byte written to the host terminal (hook H29, @@ -120,46 +146,84 @@ impl App { ) -> Result<()> { self.wm.set_tui_cell_grid_mode(true); let _ = terminal.hide_cursor(); - let mut reader = EventStream::new(); + let reader = EventStream::new(); let input_tap = self.wm.traffic_meter().open_channel( crate::traffic::Origin::HostTty, "host-input", None, crate::traffic::Role::Wire, ); - let (mut live_rx, mut live) = match crate::api::live::LiveRpc::start(self.wm.traffic_meter()) { - Some((rx, handler)) => (Some(rx), Some(handler)), - None => { - crate::pty::set_live_socket(None); - (None, None) + let live = crate::api::live::LiveRpc::start(self.wm.traffic_meter()); + if live.is_none() { + crate::pty::set_live_socket(None); + } + let draw = |app: &mut App| -> Result<()> { + terminal.draw(|frame| { + let area = frame.area(); + app.last_viewport = area; + let _ = app.wm.resize_all(area); + frame.render_widget(WorkspaceWidget::new(&app.wm), area); + crate::ui::gui_font::geometric::sanitize_tui_pua_buffer( + frame.buffer_mut(), + app.wm.config().glyphs, + ); + })?; + Ok(()) + }; + let events = reader.inspect(|item| { + if item.is_ok() { + input_tap.event(1); } + }); + self.run_loop(events, draw, live, host_shutdown_signal(), &LoopStats::default()).await + } + + /// The event loop proper, generic over the host so it can be driven headlessly: `events` is + /// the host input stream, `draw` paints one frame, `shutdown` resolves when the process is + /// asked to stop. + /// + /// PTY output wakes the loop through [`crate::pty::wake`] and is drained at once; redraws + /// are paced by a [`FramePacer`]. The `select!` is `biased`, in an order chosen so that no + /// arm can starve another: + /// 1. the 16 ms tick (rate-limited by its timer, so it cannot starve anything); + /// 2. shutdown signals; + /// 3. host input, ahead of everything a flooding pane can keep ready; + /// 4. RPC requests; + /// 5. the frame deadline; + /// 6. PTY output, last: it may be ready on every turn during a flood, and each drain is + /// bounded (32 x 8 KiB per pane), so input is consumed at most two turns after it arrives. + pub async fn run_loop( + &mut self, + mut events: S, + mut draw: D, + live: Option, + shutdown: Q, + stats: &LoopStats, + ) -> Result<()> + where + S: Stream> + Unpin, + D: FnMut(&mut App) -> Result<()>, + Q: std::future::Future, + { + let (mut live_rx, mut live) = match live { + Some((rx, handler)) => (Some(rx), Some(handler)), + None => (None, None), }; - let mut tick = tokio::time::interval(Duration::from_millis(16)); + let mut tick = tokio::time::interval(TICK); tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip); let mut input_errors: u8 = 0; - let ctrl_c = tokio::signal::ctrl_c(); - tokio::pin!(ctrl_c); - #[cfg(unix)] - let (mut sigterm, mut sighup) = { - use tokio::signal::unix::{signal, SignalKind}; - (signal(SignalKind::terminate()).ok(), signal(SignalKind::hangup()).ok()) - }; - #[cfg(not(unix))] - let (mut sigterm, mut sighup) = ((), ()); + let mut pacer = FramePacer::default(); + let mut output_seen = crate::pty::wake::output_seq(); + tokio::pin!(shutdown); loop { - if self.needs_redraw { - terminal.draw(|frame| { - let area = frame.area(); - self.last_viewport = area; - let _ = self.wm.resize_all(area); - frame.render_widget(WorkspaceWidget::new(&self.wm), area); - crate::ui::gui_font::geometric::sanitize_tui_pua_buffer( - frame.buffer_mut(), - self.wm.config().glyphs, - ); - })?; + LoopStats::bump(&stats.turns); + let now = Instant::now(); + if self.needs_redraw && pacer.can_draw(now) { + draw(self)?; self.needs_redraw = false; + pacer.drew(now); + LoopStats::bump(&stats.draws); } self.flush_osc52_to_host()?; @@ -168,12 +232,31 @@ impl App { break; } + let frame_due = tokio::time::Instant::from_std(pacer.due(now)); tokio::select! { - maybe_event = reader.next() => { - if matches!(maybe_event, Some(Ok(_))) { - input_tap.event(1); + biased; + _ = tick.tick() => { + LoopStats::bump(&stats.ticks); + if let Some(handler) = live.as_mut() { + handler.poll_waiters(&mut self.wm); + } + self.wm.drain_stt_events(); + if self.poll_all_ptys() { + pacer.output_arrived(); } + } + _ = &mut shutdown => { + self.should_quit = true; + } + maybe_event = events.next() => { + let redraw_was_pending = self.needs_redraw; + let sent_before = crate::pty::wake::input_seq(); self.on_input_stream_item(maybe_event, &mut input_errors); + if crate::pty::wake::input_seq() != sent_before { + pacer.input_sent_to_pty(Instant::now(), redraw_was_pending); + } + LoopStats::bump(&stats.inputs); + stats.last_input_turn.set(stats.turns.get()); } Some((line, reply)) = next_live_request(&mut live_rx) => { if let Some(handler) = live.as_mut() { @@ -181,23 +264,21 @@ impl App { } self.needs_redraw = true; } - _ = tick.tick() => { - if let Some(handler) = live.as_mut() { - handler.poll_waiters(&mut self.wm); + _ = tokio::time::sleep_until(frame_due), if self.needs_redraw => {} + _ = crate::pty::wake::output_ready(&mut output_seen) => { + LoopStats::bump(&stats.pty_wakes); + let drained = self.wm.drain_pty_output(); + if drained.exited { + // Reap or hold the pane now, exactly as the tick would. + self.poll_all_ptys(); } - self.wm.drain_stt_events(); - if self.poll_all_ptys() { + if drained.changed || drained.exited { self.needs_redraw = true; + pacer.output_arrived(); } - } - _ = &mut ctrl_c => { - self.should_quit = true; - } - _ = next_unix_signal(&mut sigterm) => { - self.should_quit = true; - } - _ = next_unix_signal(&mut sighup) => { - self.should_quit = true; + // Let the runtime turn its timer and I/O drivers even if output keeps this + // arm ready on every turn (matters on a current-thread runtime). + tokio::task::yield_now().await; } } } @@ -246,9 +327,7 @@ impl App { match item { Some(Ok(event)) => { *consecutive_errors = 0; - if let Err(err) = self.handle_crossterm_event(event) { - self.report_event_error(&err); - } + let _ = self.handle_crossterm_event(event); self.needs_redraw = true; } Some(Err(_)) => { @@ -267,7 +346,17 @@ impl App { self.needs_redraw = true; } + /// Handles one host event. Always `Ok`: an error from handling it (a refused or failed PTY + /// write on one pane, a rejected command) is shown in the status line and must never end + /// the event loop of any front end (the GUI loops propagate this result with `?`). pub fn handle_crossterm_event(&mut self, event: Event) -> Result<()> { + if let Err(err) = self.dispatch_crossterm_event(event) { + self.report_event_error(&err); + } + Ok(()) + } + + fn dispatch_crossterm_event(&mut self, event: Event) -> Result<()> { match event { Event::Key(key) if matches!(key.kind, KeyEventKind::Press | KeyEventKind::Repeat) => { if handle_wm_key_event(&mut self.wm, key)? == AppAction::Quit { diff --git a/src/app/pacing.rs b/src/app/pacing.rs new file mode 100644 index 00000000..f6a24d93 --- /dev/null +++ b/src/app/pacing.rs @@ -0,0 +1,147 @@ +//! Frame pacing for the wake-driven event loop (`RESP-01`). +//! +//! PTY output now wakes the loop at once, so something must stop a flooding pane from causing +//! one redraw per 8 KiB chunk. [`FramePacer`] decides *when* a pending redraw may be drawn: +//! +//! * **Frame floor** ([`FRAME_FLOOR`]): two draws are never started closer together than this. +//! An idle terminal is not affected (the first draw after a pause is immediate); a flood is +//! capped at `1 / FRAME_FLOOR` frames per second. +//! * **Echo hold** ([`ECHO_GRACE`]): a redraw caused by input that sent bytes to a PTY is held +//! back briefly so the echo lands in the *same* frame. Without it the keypress draws a frame +//! in which nothing visible changed, and that draw starts the frame floor, delaying the echo +//! that arrives a fraction of a millisecond later. The redraw is only deferred, never skipped, +//! so input that also changed window-manager state is still drawn, at most `ECHO_GRACE` late. + +use std::cell::Cell; +use std::time::{Duration, Instant}; + +/// Minimum time between the starts of two draws. +/// +/// 8 ms caps a flooding pane at 125 frames/s: no slower than a 120 Hz display can show and +/// twice the old fixed 16 ms cadence, while bounding redraw work however fast output arrives. +pub const FRAME_FLOOR: Duration = Duration::from_millis(8); + +/// How long a redraw caused by PTY-bound input waits for the echo before drawing anyway. +/// +/// A local echo takes well under a millisecond (measured median 0.06 ms for `cat`, `tests/echo_latency.rs`); 2 ms covers +/// it with margin and is far below what is perceptible when no echo comes (password prompts). +pub const ECHO_GRACE: Duration = Duration::from_millis(2); + +/// Decides when a pending redraw may be drawn. Pure: every method takes the current instant. +#[derive(Debug, Default, Clone, Copy)] +pub struct FramePacer { + last_draw: Option, + hold_until: Option, +} + +impl FramePacer { + /// Earliest instant at which a pending redraw may be drawn. + pub fn due(&self, now: Instant) -> Instant { + let floor = self.last_draw.map_or(now, |t| t + FRAME_FLOOR); + let hold = self.hold_until.unwrap_or(now); + floor.max(hold).max(now) + } + + pub fn can_draw(&self, now: Instant) -> bool { + self.due(now) <= now + } + + /// A draw started at `now`. + pub fn drew(&mut self, now: Instant) { + self.last_draw = Some(now); + self.hold_until = None; + } + + /// Input just sent bytes to a PTY. Starts the echo hold unless a redraw was already pending + /// (`redraw_was_pending`), so repeated input can never push a frame back indefinitely. + pub fn input_sent_to_pty(&mut self, now: Instant, redraw_was_pending: bool) { + if !redraw_was_pending && self.hold_until.is_none() { + self.hold_until = Some(now + ECHO_GRACE); + } + } + + /// PTY output was ingested: whatever the hold was waiting for is here. + pub fn output_arrived(&mut self) { + self.hold_until = None; + } +} + +/// Counters of one event loop run, readable while it runs (tests, diagnostics). +#[derive(Debug, Default)] +pub struct LoopStats { + /// Passes through the loop (one `select!` each). + pub turns: Cell, + /// Frames drawn. + pub draws: Cell, + /// Host input stream items consumed. + pub inputs: Cell, + /// `turns` value at which the latest input item was consumed. + pub last_input_turn: Cell, + /// Wake-driven PTY drains (not counting the 16 ms tick). + pub pty_wakes: Cell, + /// 16 ms timer ticks serviced. + pub ticks: Cell, +} + +impl LoopStats { + pub(super) fn bump(c: &Cell) { + c.set(c.get() + 1); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn ms(n: u64) -> Duration { + Duration::from_millis(n) + } + + #[test] + fn first_draw_is_immediate_and_floor_spaces_the_next() { + let t0 = Instant::now(); + let mut p = FramePacer::default(); + assert!(p.can_draw(t0)); + p.drew(t0); + assert!(!p.can_draw(t0 + ms(1))); + assert_eq!(p.due(t0 + ms(1)), t0 + FRAME_FLOOR); + assert!(p.can_draw(t0 + FRAME_FLOOR)); + // After a pause the floor is long past: no added latency for an idle terminal. + assert!(p.can_draw(t0 + ms(500))); + } + + #[test] + fn echo_hold_defers_but_never_skips_and_is_cleared_by_output() { + let t0 = Instant::now(); + let mut p = FramePacer::default(); + p.input_sent_to_pty(t0, false); + assert!(!p.can_draw(t0), "the keypress frame waits for the echo"); + assert_eq!(p.due(t0), t0 + ECHO_GRACE); + assert!(p.can_draw(t0 + ECHO_GRACE), "no echo: drawn anyway after the grace"); + p.output_arrived(); + assert!(p.can_draw(t0 + Duration::from_micros(100)), "echo arrived: draw now"); + } + + #[test] + fn repeated_input_cannot_postpone_a_pending_frame() { + let t0 = Instant::now(); + let mut p = FramePacer::default(); + p.input_sent_to_pty(t0, false); + for i in 1..50 { + p.input_sent_to_pty(t0 + Duration::from_micros(i * 30), true); + p.input_sent_to_pty(t0 + Duration::from_micros(i * 30), false); + } + assert_eq!(p.due(t0), t0 + ECHO_GRACE, "the deadline is fixed by the first input"); + } + + #[test] + fn hold_never_shortens_the_frame_floor() { + let t0 = Instant::now(); + let mut p = FramePacer::default(); + p.drew(t0); + p.input_sent_to_pty(t0 + ms(1), false); + assert_eq!(p.due(t0 + ms(1)), t0 + FRAME_FLOOR); + p.output_arrived(); + assert_eq!(p.due(t0 + ms(1)), t0 + FRAME_FLOOR); + } +} diff --git a/src/pane/mod.rs b/src/pane/mod.rs index 27e20354..0358f922 100644 --- a/src/pane/mod.rs +++ b/src/pane/mod.rs @@ -830,7 +830,7 @@ impl CompositePane { } if let Some(pty) = self.transport.local_pty() { for resp in self.vt.take_query_responses() { - let _ = pty.write_all(&resp); + crate::pane::transport::send_query_reply(pty, &resp); } } self.sync_page_hold_after_output(); @@ -885,7 +885,7 @@ impl CompositePane { } if let Some(pty) = self.transport.local_pty() { for resp in self.vt.take_query_responses() { - let _ = pty.write_all(&resp); + crate::pane::transport::send_query_reply(pty, &resp); } } self.sync_page_hold_after_output(); diff --git a/src/pane/scroll.rs b/src/pane/scroll.rs index afb91af1..ec81b73e 100644 --- a/src/pane/scroll.rs +++ b/src/pane/scroll.rs @@ -790,7 +790,7 @@ impl CompositePane { pub fn flush_query_responses(&mut self) { if let Some(pty) = self.transport.local_pty() { for resp in self.vt.take_query_responses() { - let _ = pty.write_all(&resp); + crate::pane::transport::send_query_reply(pty, &resp); } } } diff --git a/src/pane/transport.rs b/src/pane/transport.rs index 75a966f4..76eb3cf9 100644 --- a/src/pane/transport.rs +++ b/src/pane/transport.rs @@ -36,6 +36,15 @@ impl RemotePaneBridge { } } +/// Sends one terminal query reply (DA, DSR, ...) and logs it when the PTY does not take it +/// (input backlog full or the write side failed); replies are answers to the child, so there is +/// nobody to show the error to. +pub(crate) fn send_query_reply(pty: &PtySession, reply: &[u8]) { + if let Err(err) = pty.write_all(reply) { + tracing::warn!(error = %err, bytes = reply.len(), "terminal query reply not sent"); + } +} + /// How a pane's input bytes leave the process. #[derive(Default)] pub enum PaneTransport { diff --git a/src/pty/exit_report.rs b/src/pty/exit_report.rs new file mode 100644 index 00000000..72fe1aa7 --- /dev/null +++ b/src/pty/exit_report.rs @@ -0,0 +1,86 @@ +//! "Exited" is reported at most once per PTY (`RESP-01`). +//! +//! Two things can end a PTY for the pane: the reader thread seeing EOF/EIO, and the writer +//! thread failing a write. Whichever is drained first is the exit; the other is not repeated, +//! in the same poll or any later one. + +use super::PtyEvent; + +/// Finishes one `drain_events` batch. `write_failure` is the writer's error, passed only once +/// the output queue was drained empty (so the exit never overtakes output queued before it). +/// Returns `true` when an `Exited` was synthesised for the write failure. +pub(super) fn settle(events: &mut Vec, exit_reported: &mut bool, write_failure: Option<&str>) -> bool { + let mut kept_exit = *exit_reported; + events.retain(|e| { + if !matches!(e, PtyEvent::Exited(_)) { + return true; + } + let first = !kept_exit; + kept_exit = true; + first + }); + let synthesise = !kept_exit && write_failure.is_some(); + if synthesise { + events.push(PtyEvent::Exited(None)); + kept_exit = true; + } + *exit_reported = kept_exit; + synthesise +} + +#[cfg(test)] +mod tests { + use super::*; + + fn out(b: &[u8]) -> PtyEvent { + PtyEvent::Output(b.to_vec()) + } + + #[test] + fn write_failure_is_reported_once_after_queued_output() { + let mut reported = false; + let mut ev = vec![out(b"a")]; + assert!(settle(&mut ev, &mut reported, Some("EIO"))); + assert_eq!(ev, vec![out(b"a"), PtyEvent::Exited(None)]); + let mut later = Vec::new(); + assert!(!settle(&mut later, &mut reported, Some("EIO"))); + assert!(later.is_empty(), "no second exit on later polls"); + } + + #[test] + fn reader_exit_drained_in_an_earlier_poll_suppresses_the_synthesised_one() { + let mut reported = false; + let mut first = vec![out(b"a"), PtyEvent::Exited(Some(3))]; + assert!(!settle(&mut first, &mut reported, None)); + assert_eq!(first.len(), 2); + assert!(reported); + // The writer fails afterwards (the review's case): nothing more is reported. + let mut second = Vec::new(); + assert!(!settle(&mut second, &mut reported, Some("EIO"))); + assert!(second.is_empty()); + } + + #[test] + fn reader_exit_in_the_same_poll_wins_and_a_late_reader_exit_is_dropped() { + let mut reported = false; + let mut ev = vec![PtyEvent::Exited(Some(0))]; + assert!(!settle(&mut ev, &mut reported, Some("EIO"))); + assert_eq!(ev, vec![PtyEvent::Exited(Some(0))]); + // Synthesised first, reader's EOF arrives in a later poll: dropped, output kept. + let mut reported = false; + let mut a = Vec::new(); + assert!(settle(&mut a, &mut reported, Some("EIO"))); + let mut b = vec![out(b"tail"), PtyEvent::Exited(None)]; + assert!(!settle(&mut b, &mut reported, Some("EIO"))); + assert_eq!(b, vec![out(b"tail")]); + } + + #[test] + fn no_failure_and_no_exit_reports_nothing() { + let mut reported = false; + let mut ev = vec![out(b"x")]; + assert!(!settle(&mut ev, &mut reported, None)); + assert_eq!(ev, vec![out(b"x")]); + assert!(!reported); + } +} diff --git a/src/pty/mod.rs b/src/pty/mod.rs index 66c2c10b..6e69be3e 100644 --- a/src/pty/mod.rs +++ b/src/pty/mod.rs @@ -1,10 +1,13 @@ +mod exit_report; pub mod line_discipline; pub mod shell_integration; +pub mod wake; +pub mod writer; pub use line_discipline::LineDisciplineState; use std::collections::BTreeMap; -use std::io::{Read, Write}; +use std::io::Read; use std::sync::atomic::{AtomicUsize, Ordering}; use std::sync::{Arc, Mutex}; use std::thread; @@ -136,7 +139,10 @@ pub enum PtyEvent { /// Live cross-platform PTY session wrapping `portable-pty` with deduplicated `SIGWINCH` resizing. pub struct PtySession { - writer: Mutex>>, + /// Input queue drained by this PTY's writer thread; writes never block the caller. + writer: Arc, + /// `drain_events` has handed out a `PtyEvent::Exited` (the reader's or a synthesised one). + exit_reported: bool, master: Mutex>>, child: Mutex>>, output_rx: mpsc::Receiver, @@ -220,6 +226,8 @@ impl PtySession { { break; } + // Wake the UI loop now; it must not wait for its next timer tick. + wake::notify_output(); } Err(_) => { let _ = tx.blocking_send(PtyEvent::Exited(None)); @@ -227,12 +235,16 @@ impl PtySession { } } } + wake::notify_output(); }) .map_err(BiltermError::Io)?; + let writer = writer::PtyWriter::spawn(writer, traffic.clone()).map_err(BiltermError::Io)?; + Ok(Self { master: Mutex::new(Some(pair.master)), - writer: Mutex::new(Some(writer)), + writer: Arc::new(writer), + exit_reported: false, child: Mutex::new(Some(child)), output_rx: rx, current_size: Mutex::new((initial_rows, initial_cols)), @@ -249,20 +261,33 @@ impl PtySession { &self.traffic } - /// Writes raw bytes to the PTY master input stream and flushes immediately. + /// Queues raw bytes for the PTY master and returns at once: the blocking write happens on + /// this PTY's writer thread, in call order (see [`writer`]). + /// + /// `Err` when the PTY write side has failed, or when the bytes would push the unwritten + /// backlog past [`writer::MAX_QUEUED_INPUT_BYTES`] (the child is not reading); the write is + /// then refused whole and the caller is expected to show the error. pub fn write_all(&self, bytes: &[u8]) -> Result<()> { - let mut guard = self - .writer - .lock() - .map_err(|_| BiltermError::Pty("PTY writer mutex poisoned".to_string()))?; - if let Some(writer) = guard.as_mut() { - writer.write_all(bytes)?; - self.traffic.tx(bytes.len()); - writer.flush()?; - } + self.writer.enqueue(bytes)?; + wake::note_input(); Ok(()) } + /// Bytes accepted by `write_all` that the child has not been given yet. + pub fn pending_input_bytes(&self) -> usize { + self.writer.pending_bytes() + } + + /// Total bytes `write_all` refused because the backlog was full. + pub fn rejected_input_bytes(&self) -> u64 { + self.writer.rejected_bytes() + } + + /// Observer for the writer thread's lifetime (it must end when the session is dropped). + pub fn writer_probe(&self) -> writer::WriterProbe { + self.writer.probe() + } + /// Resizes the PTY only if `(rows, cols)` changed, preventing `SIGWINCH` storms when /// moving or hiding the overlaid floating command prompt (`PANE-01`). /// @@ -358,21 +383,32 @@ impl PtySession { Err(_) => break, } } + let drained_all = events.len() < MAX_EVENTS_PER_POLL; + let failure = if drained_all && !self.exit_reported { self.writer.failure() } else { None }; + if exit_report::settle(&mut events, &mut self.exit_reported, failure.as_deref()) { + tracing::warn!(error = ?failure, pid = ?self.child_pid, "PTY write failed; reporting the pane as exited"); + } events } } +/// How long the reaper lets already-accepted input reach the child before killing it. +const CLOSE_FLUSH_PATIENCE: std::time::Duration = std::time::Duration::from_millis(250); + impl Drop for PtySession { fn drop(&mut self) { self.output_rx.close(); while self.output_rx.try_recv().is_ok() {} - let writer = self.writer.lock().ok().and_then(|mut g| g.take()); + let writer = self.writer.clone(); let child = self.child.lock().ok().and_then(|mut g| g.take()); let master = self.master.lock().ok().and_then(|mut g| g.take()); let _ = thread::Builder::new() .name("bilterm-pty-reaper".to_string()) .spawn(move || { - drop(writer); + // Input written just before the drop (a final command) still reaches a child + // that is reading; a child that is not reading costs at most this wait. + writer.wait_drained(CLOSE_FLUSH_PATIENCE); + writer.close(); if let Some(mut c) = child { let _ = c.kill(); let _ = c.wait(); diff --git a/src/pty/wake.rs b/src/pty/wake.rs new file mode 100644 index 00000000..8c57b292 --- /dev/null +++ b/src/pty/wake.rs @@ -0,0 +1,77 @@ +//! Process-wide "a PTY has something for the UI loop" wake (`RESP-01`). +//! +//! PTY reader threads (and writer threads, on failure) call [`notify_output`]; an event loop +//! awaits [`output_ready`] in its `select!` and drains PTYs at once instead of waiting for its +//! next timer tick. The signal is level-triggered through a sequence number, so a notification +//! that lands while the loop is busy (drawing, handling input) is never lost, and any number of +//! loops in one process (tests) can wait without stealing each other's wakeups. + +use std::sync::atomic::{AtomicU64, Ordering}; + +use tokio::sync::Notify; + +static OUTPUT_WAKE: Notify = Notify::const_new(); +static OUTPUT_SEQ: AtomicU64 = AtomicU64::new(0); +static INPUT_SEQ: AtomicU64 = AtomicU64::new(0); + +/// Signals that some PTY queued output (or changed state) for the UI loop. Callable from any +/// thread; never blocks. +pub fn notify_output() { + OUTPUT_SEQ.fetch_add(1, Ordering::SeqCst); + OUTPUT_WAKE.notify_waiters(); +} + +/// Current output sequence number; pass a copy of it to [`output_ready`]. +pub fn output_seq() -> u64 { + OUTPUT_SEQ.load(Ordering::SeqCst) +} + +/// Resolves once [`notify_output`] has been called since `*seen` was taken, then advances +/// `*seen`. Cancel-safe: dropping the future loses nothing because `*seen` only moves on return. +pub async fn output_ready(seen: &mut u64) { + loop { + let notified = OUTPUT_WAKE.notified(); + tokio::pin!(notified); + // Register before reading the sequence so a notify between the two is not missed. + notified.as_mut().enable(); + let now = OUTPUT_SEQ.load(Ordering::SeqCst); + if now != *seen { + *seen = now; + return; + } + notified.await; + } +} + +/// Records that bytes were queued for some PTY (keyboard input, paste, query reply). +pub(super) fn note_input() { + INPUT_SEQ.fetch_add(1, Ordering::Relaxed); +} + +/// Count of PTY writes accepted so far in this process. An event loop compares it around an +/// input event to learn whether that event sent bytes to a PTY (and so may be echoed). +pub fn input_seq() -> u64 { + INPUT_SEQ.load(Ordering::Relaxed) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn notify_before_wait_is_not_lost_and_seen_advances() { + let mut seen = output_seq(); + notify_output(); + output_ready(&mut seen).await; + assert!(seen >= 1); + // Nothing new since `seen` (other tests may notify concurrently, so only check that a + // fresh notify resolves a fresh wait). + let mut again = output_seq(); + let waiter = tokio::spawn(async move { + output_ready(&mut again).await; + }); + tokio::task::yield_now().await; + notify_output(); + waiter.await.unwrap(); + } +} diff --git a/src/pty/writer.rs b/src/pty/writer.rs new file mode 100644 index 00000000..12868a99 --- /dev/null +++ b/src/pty/writer.rs @@ -0,0 +1,254 @@ +//! Per-PTY input writer thread (`RESP-01`). +//! +//! `PtySession::write_all` used to write to the PTY master on the caller, which is the UI +//! thread: a child that stops reading (or is itself blocked writing output nobody drains) fills +//! the kernel tty buffer (about 4 KiB on Linux) and the next write stalls the whole multiplexer. +//! Here the caller only appends to a FIFO queue; one thread per PTY owns the master writer and +//! performs the blocking writes. +//! +//! Guarantees: +//! * **Order**: one queue, one consumer, chunks written whole and in arrival order. +//! * **Bounded memory**: at most [`MAX_QUEUED_INPUT_BYTES`] accepted-but-unwritten bytes. +//! * **At the limit**: the *whole* write is refused with an error (never a fragment, so no torn +//! escape or UTF-8 sequence), the caller is never blocked, and the refusal is returned to the +//! caller, counted in [`PtyWriter::rejected_bytes`] and logged. Nothing is dropped silently. +//! * **Write error**: recorded once; later writes fail fast, and the session reports the PTY as +//! exited. The error never leaves this module as a panic. +//! * **Shutdown**: `close()` ends the thread as soon as it is not inside a kernel write; a +//! thread blocked in a write ends when the PTY is torn down (the write fails with `EIO`). + +use std::collections::VecDeque; +use std::io::Write; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::{Arc, Condvar, Mutex, MutexGuard}; +use std::thread; +use std::time::{Duration, Instant}; + +use crate::error::{BiltermError, Result}; +use crate::traffic::TrafficTap; + +/// Upper bound on bytes accepted for one PTY but not yet written to it. +/// +/// Sized from the largest legitimate burst, a paste delivered as one event: the remote link +/// already caps that at 1 MiB (`REMOTE_INPUT_CAP`); 4 MiB leaves room for bracketed-paste +/// framing and several pastes in flight, while a pane whose child never reads costs at most +/// 4 MiB (50 such panes: 200 MiB) instead of growing without bound. +pub const MAX_QUEUED_INPUT_BYTES: usize = 4 * 1024 * 1024; + +#[derive(Default)] +struct State { + queue: VecDeque>, + /// Bytes in `queue` plus the chunk currently being written. + pending: usize, + closed: bool, + failed: Option, + rejected: u64, + overflow_logged: bool, +} + +struct Shared { + state: Mutex, + work: Condvar, + drained: Condvar, + finished: AtomicBool, + limit: usize, +} + +impl Shared { + fn lock(&self) -> MutexGuard<'_, State> { + // The state is plain data; a panic elsewhere must not wedge the UI thread. + self.state.lock().unwrap_or_else(|p| p.into_inner()) + } +} + +/// Sets `finished` when the writer thread ends, however it ends. +struct FinishGuard(Arc); + +impl Drop for FinishGuard { + fn drop(&mut self) { + // Under the state lock: a waiter checks `finished` and then waits while holding it, so + // a store + notify outside the lock could land in between and be missed. + let _st = self.0.lock(); + self.0.finished.store(true, Ordering::SeqCst); + self.0.drained.notify_all(); + } +} + +/// Observer for "has this PTY's writer thread ended" that outlives the session. +#[derive(Clone)] +pub struct WriterProbe(Arc); + +impl WriterProbe { + pub fn finished(&self) -> bool { + self.0.finished.load(Ordering::SeqCst) + } + + /// Blocks until the thread has ended or `patience` passed; returns whether it ended. + pub fn wait_finished(&self, patience: Duration) -> bool { + let deadline = Instant::now() + patience; + let mut st = self.0.lock(); + while !self.finished() { + let now = Instant::now(); + if now >= deadline { + return false; + } + st = self.0.drained.wait_timeout(st, deadline - now).unwrap_or_else(|p| p.into_inner()).0; + } + true + } +} + +/// Queue handle for one PTY's writer thread. +pub struct PtyWriter { + shared: Arc, +} + +impl PtyWriter { + /// Starts the writer thread over `sink` with the default byte limit. + pub fn spawn(sink: Box, traffic: TrafficTap) -> std::io::Result { + Self::spawn_with_limit(sink, traffic, MAX_QUEUED_INPUT_BYTES) + } + + /// Starts the writer thread with an explicit pending-byte limit. + pub fn spawn_with_limit( + mut sink: Box, + traffic: TrafficTap, + limit: usize, + ) -> std::io::Result { + let shared = Arc::new(Shared { + state: Mutex::new(State::default()), + work: Condvar::new(), + drained: Condvar::new(), + finished: AtomicBool::new(false), + limit, + }); + let th = shared.clone(); + thread::Builder::new().name("bilterm-pty-writer".to_string()).spawn(move || { + let _guard = FinishGuard(th.clone()); + loop { + let chunk = { + let mut st = th.lock(); + loop { + if st.closed { + return; + } + if let Some(c) = st.queue.pop_front() { + break c; + } + st = th.work.wait(st).unwrap_or_else(|p| p.into_inner()); + } + }; + let written = sink.write_all(&chunk).and_then(|()| sink.flush()); + let mut st = th.lock(); + match written { + Ok(()) => { + // Counted when the bytes are really on the wire (`TMON-01`). + traffic.tx(chunk.len()); + st.pending -= chunk.len(); + if st.pending == 0 { + th.drained.notify_all(); + } + } + Err(e) => { + st.failed = Some(e.to_string()); + st.queue.clear(); + st.pending = 0; + drop(st); + th.drained.notify_all(); + // Let the UI loop notice the dead PTY now rather than on its next tick. + super::wake::notify_output(); + return; + } + } + } + })?; + Ok(Self { shared }) + } + + /// Queues `bytes` for the PTY and returns at once. `Err` when the writer has failed or the + /// write would exceed the pending-byte limit (the write is then refused whole). + pub fn enqueue(&self, bytes: &[u8]) -> Result<()> { + if bytes.is_empty() { + return Ok(()); + } + let mut st = self.shared.lock(); + if let Some(e) = st.failed.as_ref() { + return Err(BiltermError::Pty(format!("PTY write failed: {e}"))); + } + if st.closed { + return Ok(()); + } + if st.pending.saturating_add(bytes.len()) > self.shared.limit { + st.rejected = st.rejected.saturating_add(bytes.len() as u64); + if !st.overflow_logged { + st.overflow_logged = true; + tracing::warn!(pending = st.pending, refused = bytes.len(), "PTY input queue full; write refused"); + } + return Err(BiltermError::Pty(format!( + "input not sent: {} bytes are still waiting for a program that is not reading (limit {} bytes)", + st.pending, self.shared.limit + ))); + } + st.overflow_logged = false; + st.pending += bytes.len(); + st.queue.push_back(bytes.to_vec()); + drop(st); + self.shared.work.notify_one(); + Ok(()) + } + + /// Bytes accepted and not yet written. + pub fn pending_bytes(&self) -> usize { + self.shared.lock().pending + } + + /// Total bytes refused because the queue was full. + pub fn rejected_bytes(&self) -> u64 { + self.shared.lock().rejected + } + + /// The write error that stopped the thread, if any. + pub fn failure(&self) -> Option { + self.shared.lock().failed.clone() + } + + pub fn probe(&self) -> WriterProbe { + WriterProbe(self.shared.clone()) + } + + /// Waits (off the UI thread only) until everything accepted has been written, the writer + /// failed or ended, or `patience` passed. Returns whether the queue is empty. + pub fn wait_drained(&self, patience: Duration) -> bool { + let deadline = Instant::now() + patience; + let mut st = self.shared.lock(); + while st.pending > 0 && st.failed.is_none() && !self.shared.finished.load(Ordering::SeqCst) { + let now = Instant::now(); + if now >= deadline { + return false; + } + st = self.shared.drained.wait_timeout(st, deadline - now).unwrap_or_else(|p| p.into_inner()).0; + } + st.pending == 0 + } + + /// Stops accepting writes and ends the thread once it is not inside a kernel write. + /// Unwritten bytes are discarded. + pub fn close(&self) { + let mut st = self.shared.lock(); + st.closed = true; + let discarded: usize = st.queue.drain(..).map(|c| c.len()).sum(); + st.pending -= discarded; + drop(st); + self.shared.work.notify_all(); + } +} + +impl Drop for PtyWriter { + fn drop(&mut self) { + self.close(); + } +} + +#[cfg(test)] +#[path = "writer_tests.rs"] +mod tests; diff --git a/src/pty/writer_tests.rs b/src/pty/writer_tests.rs new file mode 100644 index 00000000..79eafbbf --- /dev/null +++ b/src/pty/writer_tests.rs @@ -0,0 +1,184 @@ +//! Deterministic tests for the PTY writer thread: fake sinks, no real PTY, no sleeps. + +use std::io::{self, Write}; +use std::sync::mpsc::{channel, Receiver, Sender}; +use std::sync::{Arc, Mutex}; +use std::time::Duration; + +use super::*; +use crate::traffic::ChannelCounters; + +const LONG: Duration = Duration::from_secs(30); + +type Captured = Arc>>; + +/// Sink that stores what it is given; each `write` first waits for a permit when gated. +struct Sink { + out: Arc>>, + gate: Option>, + entered: Option>, + fail: bool, +} + +impl Write for Sink { + fn write(&mut self, buf: &[u8]) -> io::Result { + if let Some(tx) = self.entered.as_ref() { + let _ = tx.send(()); + } + if let Some(gate) = self.gate.as_ref() { + // A closed gate means "the PTY was torn down": the blocked write fails. + gate.recv().map_err(|_| io::Error::other("torn down"))?; + } + if self.fail { + return Err(io::Error::other("EIO")); + } + self.out.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + fn flush(&mut self) -> io::Result<()> { + Ok(()) + } +} + +fn open_sink() -> (Box, Captured) { + let out = Arc::new(Mutex::new(Vec::new())); + (Box::new(Sink { out: out.clone(), gate: None, entered: None, fail: false }), out) +} + +/// A sink whose every `write` blocks until a permit is sent (like a child that is not reading). +fn gated_sink() -> (Box, Captured, Sender<()>, Receiver<()>) { + let out = Arc::new(Mutex::new(Vec::new())); + let (permit_tx, permit_rx) = channel(); + let (entered_tx, entered_rx) = channel(); + let sink = Sink { out: out.clone(), gate: Some(permit_rx), entered: Some(entered_tx), fail: false }; + (Box::new(sink), out, permit_tx, entered_rx) +} + +fn counters() -> crate::traffic::TrafficTap { + let c = ChannelCounters::new(); + c.set_flags(crate::traffic::cell::F_ENABLED); + c +} + +#[test] +fn enqueue_returns_while_the_sink_is_blocked() { + let (sink, out, permit, entered) = gated_sink(); + let w = PtyWriter::spawn(sink, counters()).unwrap(); + // If enqueue wrote on the caller this would deadlock: nobody sends a permit yet. + w.enqueue(&vec![b'a'; 1024 * 1024]).unwrap(); + w.enqueue(b"tail").unwrap(); + entered.recv_timeout(LONG).expect("writer thread reached the blocking write"); + assert_eq!(w.pending_bytes(), 1024 * 1024 + 4, "in-flight bytes still count as pending"); + assert!(out.lock().unwrap().is_empty()); + // Release the two chunks' writes (one `write` call each: the sink takes the whole buffer). + permit.send(()).unwrap(); + permit.send(()).unwrap(); + assert!(w.wait_drained(LONG)); + assert_eq!(out.lock().unwrap().len(), 1024 * 1024 + 4); +} + +#[test] +fn order_is_preserved_across_many_small_and_one_large_write() { + let (sink, out) = open_sink(); + let traffic = counters(); + let w = PtyWriter::spawn(sink, traffic.clone()).unwrap(); + let mut expect = Vec::new(); + let mut push = |bytes: Vec| { + w.enqueue(&bytes).unwrap(); + expect.extend_from_slice(&bytes); + }; + for i in 0..2000u32 { + push(format!("[{i}]").into_bytes()); + } + push((0..1_500_000u32).map(|i| (i % 251) as u8).collect()); + for i in 2000..4000u32 { + push(format!("[{i}]").into_bytes()); + } + assert!(w.wait_drained(LONG)); + assert!(*out.lock().unwrap() == expect, "byte stream differs from the write order"); + let r = traffic.read(); + assert_eq!((r.tx_bytes, r.tx_msgs), (expect.len() as u64, 4001), "tx counted once per write"); +} + +#[test] +fn full_queue_refuses_the_whole_write_without_blocking_or_dropping_silently() { + let (sink, out, permit, entered) = gated_sink(); + let w = PtyWriter::spawn_with_limit(sink, counters(), 100).unwrap(); + w.enqueue(&[b'a'; 60]).unwrap(); + entered.recv_timeout(LONG).unwrap(); + w.enqueue(&[b'b'; 40]).unwrap(); + let err = w.enqueue(b"c").expect_err("over the limit"); + assert!(err.to_string().contains("not reading"), "{err}"); + assert_eq!(w.rejected_bytes(), 1); + assert_eq!(w.pending_bytes(), 100, "a refused write leaves no fragment behind"); + permit.send(()).unwrap(); + permit.send(()).unwrap(); + assert!(w.wait_drained(LONG)); + // Room again: accepted, and the stream is exactly the accepted writes in order. + w.enqueue(b"d").unwrap(); + permit.send(()).unwrap(); + assert!(w.wait_drained(LONG)); + let mut expect = vec![b'a'; 60]; + expect.extend_from_slice(&[b'b'; 40]); + expect.push(b'd'); + assert_eq!(*out.lock().unwrap(), expect); +} + +#[test] +fn write_error_is_recorded_fails_later_writes_and_ends_the_thread() { + let out = Arc::new(Mutex::new(Vec::new())); + let traffic = counters(); + let sink = Sink { out: out.clone(), gate: None, entered: None, fail: true }; + let w = PtyWriter::spawn(Box::new(sink), traffic.clone()).unwrap(); + let probe = w.probe(); + let seq = super::super::wake::output_seq(); + w.enqueue(b"x").unwrap(); + assert!(probe.wait_finished(LONG)); + assert_eq!(w.failure().as_deref(), Some("EIO")); + assert!(w.enqueue(b"y").is_err(), "writes after a failure are refused, not queued"); + assert_eq!(w.pending_bytes(), 0); + assert_eq!(traffic.read().tx_bytes, 0, "bytes that never reached the PTY are not counted"); + assert_ne!(super::super::wake::output_seq(), seq, "the UI loop is woken to notice the dead PTY"); +} + +#[test] +fn drop_ends_an_idle_thread() { + let (sink, _out) = open_sink(); + let w = PtyWriter::spawn(sink, counters()).unwrap(); + let probe = w.probe(); + assert!(!probe.finished()); + drop(w); + assert!(probe.wait_finished(LONG)); +} + +#[test] +fn drop_ends_a_thread_blocked_in_write_once_the_pty_is_torn_down() { + let (sink, out, permit, entered) = gated_sink(); + let w = PtyWriter::spawn(sink, counters()).unwrap(); + let probe = w.probe(); + w.enqueue(b"stuck").unwrap(); + w.enqueue(b"never written").unwrap(); + entered.recv_timeout(LONG).unwrap(); + drop(w); + assert!(!probe.finished(), "still inside the blocked write"); + drop(permit); // the PTY goes away: the blocked write fails + assert!(probe.wait_finished(LONG)); + assert!(out.lock().unwrap().is_empty(), "queued bytes are discarded on close"); +} + +/// Review fix: the thread's "finished" flag is published under the state lock, so a waiter can +/// never check the flag, miss the notify, and sleep out its whole patience. With the race a +/// missed notify costs `LONG` (30 s) per iteration; the bound below is 1000x the normal total. +#[test] +fn wait_finished_never_misses_the_exit_notification() { + let started = std::time::Instant::now(); + for _ in 0..2000 { + let (sink, _out) = open_sink(); + let w = PtyWriter::spawn(sink, counters()).unwrap(); + let probe = w.probe(); + let waiter = std::thread::spawn(move || probe.wait_finished(LONG)); + drop(w); + assert!(waiter.join().unwrap()); + } + assert!(started.elapsed() < LONG, "a waiter slept through the exit notification"); +} diff --git a/src/tmux/transport.rs b/src/tmux/transport.rs index 17f7e99f..c2bc1656 100644 --- a/src/tmux/transport.rs +++ b/src/tmux/transport.rs @@ -33,6 +33,11 @@ pub struct PtyLinkDriver { exit_reported: bool, /// The PTY stream ended at this instant; the exit code is still being collected. exit_seen: Option, + /// A command taken off `cmd_rx` that the PTY refused (input backlog full) or failed to + /// take; it is offered again, ahead of newer commands, on the next pump. + held_cmd: Option, + /// The current refusal has been logged (one line per episode, not one per pump). + refusal_logged: bool, } impl Default for PtyLinkDriver { @@ -45,6 +50,8 @@ impl Default for PtyLinkDriver { cmd_rx: None, exit_reported: false, exit_seen: None, + held_cmd: None, + refusal_logged: false, } } } @@ -82,6 +89,8 @@ impl PtyLinkDriver { cmd_rx: Some(cmd_rx), exit_reported: false, exit_seen: None, + held_cmd: None, + refusal_logged: false, }; Ok((control, driver)) } @@ -119,15 +128,37 @@ impl PtyLinkDriver { let (Some(rx), Some(pty)) = (self.cmd_rx.as_mut(), self.pty.as_ref()) else { return; }; - while let Ok(mut cmd) = rx.try_recv() { - if !cmd.ends_with('\n') { - cmd.push('\n'); - } - if pty.write_all(cmd.as_bytes()).is_err() { - break; + // Order is kept: the held command first, then the channel. A refused command is never + // dropped; it stays held until the PTY takes it or the driver is killed. + loop { + let cmd = match self.held_cmd.take() { + Some(c) => c, + None => match rx.try_recv() { + Ok(mut c) => { + if !c.ends_with('\n') { + c.push('\n'); + } + c + } + Err(_) => break, + }, + }; + if let Err(err) = pty.write_all(cmd.as_bytes()) { + if !self.refusal_logged { + self.refusal_logged = true; + tracing::warn!(target: "bilterm::link", error = %err, bytes = cmd.len(), "link command not written; held for retry"); + } + self.held_cmd = Some(cmd); + return; } + self.refusal_logged = false; } } + + /// Bytes of the command held back by PTY backpressure (0 when none). + pub fn held_command_len(&self) -> usize { + self.held_cmd.as_ref().map_or(0, String::len) + } } impl LinkDriver for PtyLinkDriver { diff --git a/src/wm/mod.rs b/src/wm/mod.rs index 277ca6f9..38e2eb8a 100644 --- a/src/wm/mod.rs +++ b/src/wm/mod.rs @@ -40,6 +40,7 @@ pub mod layout_profile; pub mod link_cmd; pub mod pane_hold; pub mod panel_dock; +pub mod pty_drain; pub mod quick_terminal; pub mod registry; pub mod rename_dialog; diff --git a/src/wm/pty_drain.rs b/src/wm/pty_drain.rs new file mode 100644 index 00000000..e826b058 --- /dev/null +++ b/src/wm/pty_drain.rs @@ -0,0 +1,32 @@ +//! Wake-driven PTY drain (`RESP-01`): the part of `poll_all_ptys` that must not wait for the +//! 16 ms tick. Timers, the tmux link, traffic sampling and pane reaping stay on the tick. + +use crate::wm::WindowManager; + +/// Outcome of [`WindowManager::drain_pty_output`]. +#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] +pub struct PtyDrain { + /// Some pane ingested output (a redraw is needed). + pub changed: bool, + /// Some pane's child exited during this drain; the caller must run `poll_all_ptys` so the + /// pane is reaped or held before anything asks `all_panes_exited`. + pub exited: bool, +} + +impl WindowManager { + /// Feeds queued PTY output into every pane (and the quick terminal), with the same bounded + /// per-pane budget as the tick (`PtySession::drain_events`: 32 chunks of 8 KiB). + pub fn drain_pty_output(&mut self) -> PtyDrain { + let mut out = PtyDrain::default(); + for pane in self.panes.values_mut().chain(std::iter::once(&mut self.quick_terminal.pane)) { + let was_exited = pane.has_exited(); + if pane.poll_pty_events() { + out.changed = true; + } + if !was_exited && pane.has_exited() { + out.exited = true; + } + } + out + } +} diff --git a/tests/app_loop_wake.rs b/tests/app_loop_wake.rs new file mode 100644 index 00000000..4447b926 --- /dev/null +++ b/tests/app_loop_wake.rs @@ -0,0 +1,159 @@ +//! RESP-01: the event loop is woken by PTY output, paces its redraws, and keeps servicing input +//! while a pane floods. Drives the real `App::run_loop` headlessly (no host terminal). + +#![cfg(unix)] + +use std::cell::Cell; +use std::io; +use std::time::{Duration, Instant}; + +use bilterm::app::{App, LoopStats, FRAME_FLOOR}; +use bilterm::pane::CompositePane; +use bilterm::pty::PtyConfig; +use crossterm::event::{Event, KeyCode, KeyEvent, KeyModifiers}; +use tokio::sync::mpsc::{unbounded_channel, UnboundedSender}; + +/// Generous bound for "this must eventually happen"; passing never depends on it being short. +const LONG: Duration = Duration::from_secs(60); + +fn sh(script: &str) -> PtyConfig { + PtyConfig { program: "sh".into(), args: vec!["-c".into(), script.into()], rows: 24, cols: 80, ..PtyConfig::default() } +} + +fn key(c: char) -> io::Result { + Ok(Event::Key(KeyEvent::new(KeyCode::Char(c), KeyModifiers::NONE))) +} + +/// Yields to the loop until `cond` holds; panics after `LONG`. +async fn until(what: &str, cond: impl Fn() -> bool) { + let end = Instant::now() + LONG; + while !cond() { + assert!(Instant::now() < end, "timed out waiting for: {what}"); + tokio::task::yield_now().await; + } +} + +type Events = UnboundedSender>; + +/// Runs `App::run_loop` over `pane` next to `driver`; the loop ends when the driver drops the +/// event sender. `on_draw` is called for every frame the loop decides to draw. +async fn run_with(pane: CompositePane, stats: &LoopStats, on_draw: impl Fn(&App), driver: F) +where + F: FnOnce(Events) -> Fut, + Fut: std::future::Future, +{ + let mut app = App::new(pane); + let (tx, mut rx) = unbounded_channel(); + let events = futures::stream::poll_fn(move |cx| rx.poll_recv(cx)); + let draw = |app: &mut App| { + on_draw(app); + Ok(()) + }; + let looped = app.run_loop(events, draw, None, std::future::pending(), stats); + let (res, ()) = tokio::join!(looped, driver(tx)); + res.unwrap(); +} + +/// `yes`-style flood in the pane while input events are delivered: every event is consumed +/// within two loop turns of being sent, and redraws are coalesced by the frame floor. +#[tokio::test] +async fn input_is_serviced_within_two_turns_during_a_flood_and_draws_are_coalesced() { + const EVENTS: u64 = 100; + let pane = CompositePane::spawn(1, sh("exec yes bilterm-flood-line-0123456789")).unwrap(); + let stats = LoopStats::default(); + let started = Instant::now(); + let worst = Cell::new(0u64); + let wakes_during_input = Cell::new(0u64); + run_with(pane, &stats, |_| {}, |tx| async { + until("the flood to wake the loop", || stats.pty_wakes.get() >= 50).await; + let wakes_at_start = stats.pty_wakes.get(); + for i in 0..EVENTS { + // Only send while the flood is demonstrably keeping the loop busy. + let wakes = stats.pty_wakes.get(); + until("more flood output", || stats.pty_wakes.get() > wakes).await; + let sent_at_turn = stats.turns.get(); + tx.send(key('a')).unwrap(); + until("the input event to be consumed", || stats.inputs.get() > i).await; + worst.set(worst.get().max(stats.last_input_turn.get() - sent_at_turn)); + } + wakes_during_input.set(stats.pty_wakes.get() - wakes_at_start); + drop(tx); + }) + .await; + let elapsed = started.elapsed(); + + assert_eq!(stats.inputs.get(), EVENTS + 1, "every event plus the end of the stream"); + assert!(wakes_during_input.get() >= EVENTS, "the pane flooded throughout: {wakes_during_input:?}"); + // A sent event is taken on the next turn, or the one after if the 16 ms tick was due. + assert!(worst.get() <= 2, "input waited {} loop turns behind PTY output", worst.get()); + // The pacer never starts two draws closer than FRAME_FLOOR, so N draws need (N-1) floors. + // Slowness can only reduce the draw count, so this cannot flake. + let max_draws = (elapsed.as_micros() / FRAME_FLOOR.as_micros()) as u64 + 1; + assert!(stats.draws.get() >= 2, "the flood was drawn"); + assert!(stats.draws.get() <= max_draws, "{} draws in {elapsed:?}", stats.draws.get()); + // Not asserted: `pty_wakes > draws`. On a loaded machine the 16 ms tick (first in the biased + // select) drains most of the output and input events cause redraws too, so draws can exceed + // wake-driven drains (CI saw 618 draws against 450 wakes). The floor bound above is the + // coalescing guarantee. +} + +const RAW_ECHO_CHILD: &str = "stty raw -echo; printf '\\033[?1049hREADY'; exec cat"; + +fn marks(app: &App) -> usize { + app.wm.active_pane().vt().contents().matches('#').count() +} + +/// A key forwarded to the PTY is echoed and drawn without waiting for the 16 ms tick. The old +/// loop drained PTY output only inside the tick, so every echo needed at least one tick between +/// the keypress and the frame showing it. +#[tokio::test] +async fn echo_is_drawn_by_the_output_wake_not_the_tick() { + const KEYS: usize = 60; + // Alternate screen: the pane routes keys straight to the PTY (like vim/htop). Raw and no + // tty echo: `cat` writes each byte back as soon as it reads it. + let pane = CompositePane::spawn(1, sh(RAW_ECHO_CHILD)).unwrap(); + let stats = LoopStats::default(); + let drawn_marks = Cell::new(0usize); + let ready = Cell::new(false); + let zero_tick_echoes = Cell::new(0usize); + let on_draw = |app: &App| { + drawn_marks.set(marks(app)); + ready.set(ready.get() || app.wm.active_pane().vt().contents().contains("READY")); + }; + run_with(pane, &stats, on_draw, |tx| async { + until("the child to configure its tty", || ready.get()).await; + for i in 0..KEYS { + // Start each sample just after a tick so the next one is a full period away. + let t = stats.ticks.get(); + until("a tick boundary", || stats.ticks.get() > t).await; + let ticks_before = stats.ticks.get(); + tx.send(key('#')).unwrap(); + until("the echo to be drawn", || drawn_marks.get() > i).await; + if stats.ticks.get() == ticks_before { + zero_tick_echoes.set(zero_tick_echoes.get() + 1); + } + } + drop(tx); + }) + .await; + assert_eq!(drawn_marks.get(), KEYS, "every key was echoed and drawn exactly once"); + assert!(stats.pty_wakes.get() >= 1); + assert!( + zero_tick_echoes.get() >= 1, + "no echo was drawn between ticks: output is still waiting for the 16 ms tick" + ); + println!("echoes drawn before the next tick: {}/{KEYS}", zero_tick_echoes.get()); +} + +/// A pane whose child exits is reaped/held by the wake path just as by the tick, and the loop +/// ends when the last pane is gone (no hang waiting for input). +#[tokio::test] +async fn loop_ends_when_the_only_pane_exits() { + let pane = CompositePane::spawn(1, sh("printf bye")).unwrap(); + let stats = LoopStats::default(); + let mut app = App::new(pane); + let events = futures::stream::pending::>(); + let looped = app.run_loop(events, |_| Ok(()), None, std::future::pending(), &stats); + tokio::time::timeout(LONG, looped).await.expect("loop did not end").unwrap(); + assert!(app.all_panes_exited()); +} diff --git a/tests/echo_latency.rs b/tests/echo_latency.rs new file mode 100644 index 00000000..19d8f9f6 --- /dev/null +++ b/tests/echo_latency.rs @@ -0,0 +1,157 @@ +//! Echo-latency harness (`#[ignore]`: wall-clock measurements, never part of the CI gate). +//! +//! Run: `cargo test --release --test echo_latency -- --ignored --nocapture --test-threads=1` +//! +//! Each sample writes one byte to a `cat` PTY (the tty echoes it) and times how long it takes +//! until the pane has ingested the echo, i.e. until it is visible to the pane's VT state. + +#![cfg(unix)] + +use std::time::{Duration, Instant}; + +use bilterm::pane::CompositePane; +use bilterm::pty::PtyConfig; + +const SAMPLES: usize = 300; + +fn cat() -> PtyConfig { + PtyConfig { program: "cat".into(), args: Vec::new(), rows: 24, cols: 80, ..PtyConfig::default() } +} + +/// Idle gap before sample `i`: spreads writes over every phase of a 16 ms tick. +fn phase(i: usize) -> Duration { + Duration::from_micros(20_000 + ((i * 3_700) % 16_000) as u64) +} + +fn report(label: &str, mut v: Vec) { + v.sort(); + let us = |d: Duration| d.as_secs_f64() * 1e3; + let pct = |p: f64| us(v[((v.len() as f64 * p) as usize).min(v.len() - 1)]); + println!( + "ECHO {label}: n={} median={:.3}ms p95={:.3}ms min={:.3}ms max={:.3}ms", + v.len(), + pct(0.50), + pct(0.95), + us(v[0]), + us(v[v.len() - 1]) + ); +} + +/// The pre-change loop policy: PTY output is drained only on the 16 ms tick. +#[tokio::test] +#[ignore = "wall-clock measurement"] +async fn echo_latency_tick_polled_16ms() { + let mut pane = CompositePane::spawn(1, cat()).unwrap(); + let mut tick = tokio::time::interval(Duration::from_millis(16)); + tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip); + let mut out = Vec::with_capacity(SAMPLES); + for i in 0..SAMPLES { + tokio::time::sleep(phase(i)).await; + while pane.poll_pty_events() {} + let t0 = Instant::now(); + pane.write_to_pty(b"x").unwrap(); + loop { + tick.tick().await; + if pane.poll_pty_events() { + break; + } + assert!(t0.elapsed() < Duration::from_secs(5), "no echo"); + } + out.push(t0.elapsed()); + } + report("before (16 ms tick poll)", out); +} + +/// The new policy, same measurement: the reader thread's wake drains the PTY at once; the 16 ms +/// tick stays as the fallback. Same `select!` shape as `App::run_loop`. +#[tokio::test] +#[ignore = "wall-clock measurement"] +async fn echo_latency_wake_driven() { + let mut pane = CompositePane::spawn(1, cat()).unwrap(); + let mut tick = tokio::time::interval(Duration::from_millis(16)); + tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip); + let mut seen = bilterm::pty::wake::output_seq(); + let mut out = Vec::with_capacity(SAMPLES); + for i in 0..SAMPLES { + tokio::time::sleep(phase(i)).await; + while pane.poll_pty_events() {} + let t0 = Instant::now(); + pane.write_to_pty(b"x").unwrap(); + loop { + tokio::select! { + biased; + _ = tick.tick() => {} + _ = bilterm::pty::wake::output_ready(&mut seen) => {} + } + if pane.poll_pty_events() { + break; + } + assert!(t0.elapsed() < Duration::from_secs(5), "no echo"); + } + out.push(t0.elapsed()); + } + report("after (output wake)", out); +} + +/// End to end through the real `App::run_loop`: a key event enters the loop, is forwarded to the +/// PTY, `cat` writes it back, and the time is taken when the loop draws the frame that shows it +/// (so it includes the writer thread, the wake, the echo hold and the frame floor). +#[tokio::test] +#[ignore = "wall-clock measurement"] +async fn echo_latency_run_loop_key_to_frame() { + use bilterm::app::{App, LoopStats}; + use crossterm::event::{Event, KeyCode, KeyEvent, KeyModifiers}; + use std::cell::{Cell, RefCell}; + + let cfg = PtyConfig { + program: "sh".into(), + args: vec!["-c".into(), "stty raw -echo; printf '\\033[?1049hREADY'; exec cat".into()], + rows: 24, + cols: 80, + ..PtyConfig::default() + }; + let mut app = App::new(CompositePane::spawn(1, cfg).unwrap()); + let stats = LoopStats::default(); + let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::>(); + let events = futures::stream::poll_fn(move |cx| rx.poll_recv(cx)); + let ready = Cell::new(false); + let drawn = Cell::new(0usize); + let sent_at: Cell> = Cell::new(None); + let samples = RefCell::new(Vec::with_capacity(SAMPLES)); + let draw = |app: &mut App| { + let text = app.wm.active_pane().vt().contents(); + ready.set(ready.get() || text.contains("READY")); + let marks = text.matches('#').count(); + if marks > drawn.get() { + drawn.set(marks); + if let Some(t0) = sent_at.take() { + samples.borrow_mut().push(t0.elapsed()); + } + } + Ok(()) + }; + let driver = async { + while !ready.get() { + tokio::task::yield_now().await; + } + for i in 0..SAMPLES { + tokio::time::sleep(phase(i)).await; + sent_at.set(Some(Instant::now())); + tx.send(Ok(Event::Key(KeyEvent::new(KeyCode::Char('#'), KeyModifiers::NONE)))).unwrap(); + while drawn.get() <= i { + tokio::task::yield_now().await; + } + } + drop(tx); + }; + let (res, ()) = tokio::join!(app.run_loop(events, draw, None, std::future::pending(), &stats), driver); + res.unwrap(); + println!( + "run_loop: draws={} pty_wakes={} ticks={} inputs={}", + stats.draws.get(), + stats.pty_wakes.get(), + stats.ticks.get(), + stats.inputs.get() + ); + report("after (run_loop, key event -> frame drawn)", samples.into_inner()); +} diff --git a/tests/phase64_layer_dag.rs b/tests/phase64_layer_dag.rs index 554fd3fa..bc76ab2f 100644 --- a/tests/phase64_layer_dag.rs +++ b/tests/phase64_layer_dag.rs @@ -85,7 +85,7 @@ use HookStatus::Done; /// Plan 64-02 flipped entries to `Done`; MCP stdio (H26/H27) is `Deferred` to 64-03. pub const HOOK_MANIFEST: &[(&str, &str, &str, HookStatus)] = &[ ("src/pty/mod.rs", "match reader.read(&mut buf) {", ".rx(", Done), - ("src/pty/mod.rs", "writer.write_all(bytes)?;", ".tx(", Done), + ("src/pty/writer.rs", "let written = sink.write_all(&chunk).and_then(|()| sink.flush());", ".tx(", Done), ("src/vt/worker.rs", "match pty_reader.read(&mut buf) {", ".rx(", Done), ("src/vt/worker.rs", "let _ = writer.write_all(&data);", ".tx(", Done), ("src/vt/worker.rs", "let _ = writer.write_all(&resp);", ".tx(", Done), @@ -113,7 +113,7 @@ pub const HOOK_MANIFEST: &[(&str, &str, &str, HookStatus)] = &[ ("src/api/mcp.rs", "stdout.write_all(format!(\"{resp}\\n\").as_bytes()).await?;", ".tx(", Done), ("src/app.rs", "out.write_all(wire.as_bytes())?;", ".tx(", Done), ("src/main.rs", "let backend = CrosstermBackend::new(bilterm::app::CountingStdout::new(", "Counting", Done), - ("src/app.rs", "let mut reader = EventStream::new();", "input_tap", Done), + ("src/app.rs", "let reader = EventStream::new();", "input_tap", Done), ("src/clipboard.rs", "let _ = stdin.write_all(text.as_bytes());", "traffic_tap()", Done), ("src/clipboard.rs", "let _ = out.read_to_end(&mut buf);", "traffic_tap()", Done), ("src/stt/provider.rs", ".write_all(&request)", ".tx(", Done), diff --git a/tests/phase64_traffic_hooks.rs b/tests/phase64_traffic_hooks.rs index c801b5c3..de05931d 100644 --- a/tests/phase64_traffic_hooks.rs +++ b/tests/phase64_traffic_hooks.rs @@ -68,6 +68,8 @@ fn pty_read_and_write_are_counted_once() { })); assert!(cell.read().rx_msgs >= 1); s.write_all(b"x").unwrap(); + // Counted by the PTY writer thread once the byte is really written (RESP-01). + assert!(wait_for(|| cell.read().tx_bytes == 1)); assert_eq!(cell.read().tx_bytes, 1); assert_eq!(cell.read().tx_msgs, 1); } @@ -142,6 +144,7 @@ fn pty_less_pane_counts_tx_once_and_events() { fn live_pty_pane_input_is_counted_at_the_pty_only() { let mut pane = CompositePane::spawn(2, sh("sleep 2")).unwrap(); pane.write_to_pty(b"abc").unwrap(); + assert!(wait_for(|| pane.traffic_cell().unwrap().read().tx_bytes == 3)); assert_eq!(pane.traffic_cell().unwrap().read().tx_bytes, 3); assert!(pane.existing_payload_cell().is_none(), "no double count on a live PTY pane"); } diff --git a/tests/pty_writer_thread.rs b/tests/pty_writer_thread.rs new file mode 100644 index 00000000..8aa331d7 --- /dev/null +++ b/tests/pty_writer_thread.rs @@ -0,0 +1,200 @@ +//! RESP-01: PTY writes never block the caller; real-PTY evidence for the writer thread. +//! +//! The pure queue semantics (order, limit, error, shutdown) are unit-tested with fake sinks in +//! `src/pty/writer_tests.rs`; these tests prove the same properties against a real kernel PTY. + +#![cfg(unix)] + +use std::sync::mpsc::channel; +use std::time::{Duration, Instant}; + +use bilterm::pane::CompositePane; +use bilterm::pty::writer::MAX_QUEUED_INPUT_BYTES; +use bilterm::pty::{PtyConfig, PtyEvent, PtySession}; + +/// Generous bound for "this must eventually happen"; passing never depends on it being short. +const LONG: Duration = Duration::from_secs(30); + +fn sh(script: &str) -> PtyConfig { + PtyConfig { program: "sh".into(), args: vec!["-c".into(), script.into()], rows: 24, cols: 80, ..PtyConfig::default() } +} + +fn wait_for(mut f: impl FnMut() -> bool) -> bool { + let end = Instant::now() + LONG; + while Instant::now() < end { + if f() { + return true; + } + std::thread::sleep(Duration::from_millis(5)); + } + false +} + +/// A child that never reads its tty. The kernel tty buffer holds a few KiB, so a synchronous +/// 1 MiB write could never complete: before the writer thread this call hung the caller forever. +#[test] +fn write_to_a_child_that_does_not_read_returns_to_the_caller() { + let session = PtySession::spawn(sh("exec sleep 600")).unwrap(); + let (done_tx, done_rx) = channel(); + let worker = std::thread::spawn(move || { + let big = vec![b'x'; 1024 * 1024]; + let r = session.write_all(&big); + let pending = session.pending_input_bytes(); + let _ = done_tx.send((r.is_ok(), pending)); + session + }); + let (ok, pending) = done_rx.recv_timeout(LONG).expect("write_all blocked on a non-reading child"); + assert!(ok); + assert!(pending > 512 * 1024, "the bytes are queued, not written: pending={pending}"); + drop(worker.join().unwrap()); +} + +/// The backlog for a non-reading child is bounded, and overflow is reported to the caller. +#[test] +fn backlog_for_a_non_reading_child_is_bounded_and_overflow_is_an_error() { + let session = PtySession::spawn(sh("exec sleep 600")).unwrap(); + let chunk = vec![b'y'; 1024 * 1024]; + let mut accepted = 0usize; + let mut refused = None; + for _ in 0..16 { + match session.write_all(&chunk) { + Ok(()) => accepted += chunk.len(), + Err(e) => { + refused = Some(e.to_string()); + break; + } + } + } + let msg = refused.expect("a 16 MiB backlog must be refused"); + assert!(msg.contains("not reading"), "{msg}"); + assert!(accepted <= MAX_QUEUED_INPUT_BYTES + 64 * 1024, "accepted {accepted}"); + assert!(session.pending_input_bytes() <= MAX_QUEUED_INPUT_BYTES); + assert_eq!(session.rejected_input_bytes(), chunk.len() as u64); +} + +/// Dropping a session whose writer thread is stuck in a kernel write ends that thread. +#[test] +fn writer_thread_ends_when_the_pty_is_dropped_even_while_blocked() { + let session = PtySession::spawn(sh("exec sleep 600")).unwrap(); + session.write_all(&vec![b'z'; 1024 * 1024]).unwrap(); + let probe = session.writer_probe(); + assert!(!probe.finished()); + drop(session); + assert!(probe.wait_finished(LONG), "writer thread leaked after the PTY was dropped"); +} + +#[test] +fn writer_thread_ends_when_an_idle_pty_is_dropped() { + let session = PtySession::spawn(sh("exec sleep 600")).unwrap(); + let probe = session.writer_probe(); + drop(session); + assert!(probe.wait_finished(LONG)); +} + +/// Many small writes, one large write, many small writes: the child sees exactly that stream. +#[test] +fn byte_order_through_a_real_pty_is_exact() { + // Raw, no echo: `cat` copies its input verbatim. The marker says the tty is configured. + let mut session = PtySession::spawn(sh("stty raw -echo; printf READY; exec cat")).unwrap(); + let mut seen = Vec::new(); + assert!(wait_for(|| { + for ev in session.drain_events() { + if let PtyEvent::Output(b) = ev { + seen.extend_from_slice(&b); + } + } + seen.ends_with(b"READY") + })); + let mut expect = Vec::new(); + let mut put = |bytes: Vec| { + session.write_all(&bytes).unwrap(); + expect.extend_from_slice(&bytes); + }; + for i in 0..500u32 { + put(format!("<{i}>").into_bytes()); + } + // Printable, so no tty special characters are involved even in raw mode. + put((0..300_000u32).map(|i| b'a' + (i % 26) as u8).collect()); + for i in 500..1000u32 { + put(format!("<{i}>").into_bytes()); + } + let mut got = Vec::new(); + assert!( + wait_for(|| { + for ev in session.drain_events() { + if let PtyEvent::Output(b) = ev { + got.extend_from_slice(&b); + } + } + got.len() >= expect.len() + }), + "got {} of {} bytes", + got.len(), + expect.len() + ); + assert!(got == expect, "the child saw a different byte stream than was written"); + assert_eq!(session.pending_input_bytes(), 0); +} + +/// A write that fails (the child is gone) marks the pane exited; it is not an error that can +/// escape and take the application down. +#[test] +fn write_after_the_child_died_marks_the_pane_exited() { + let mut pane = CompositePane::spawn(7, sh("exit 0")).unwrap(); + assert!(wait_for(|| { + // Keep writing: once the slave side is closed a write fails, or the reader sees EOF. + let _ = pane.write_to_pty(b"x"); + pane.poll_pty_events(); + pane.has_exited() + })); + assert!(pane.has_exited()); +} + +/// Review fix: a link command refused under PTY backpressure is held and delivered, in order, +/// once the child reads again (it used to be popped and silently dropped). +#[test] +fn link_command_refused_under_backpressure_is_held_and_delivered_in_order() { + use bilterm::tmux::link::LinkDriver; + use bilterm::tmux::transport::PtyLinkDriver; + + let dir = std::env::temp_dir().join(format!("btfifo-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let fifo = dir.join("gate"); + let _ = std::fs::remove_file(&fifo); + assert!(std::process::Command::new("mkfifo").arg(&fifo).status().unwrap().success()); + // The child does not read its tty until the gate fifo is opened and closed by the test. + let script = format!("stty raw -echo; printf READY; cat '{}' >/dev/null; exec cat", fifo.display()); + let (control, mut driver) = PtyLinkDriver::spawn(sh(&script)).unwrap(); + let mut seen = Vec::new(); + assert!(wait_for(|| { + seen.extend_from_slice(&driver.pump().raw_output); + seen.ends_with(b"READY") + })); + + // Fill the input backlog to its limit, then queue two commands. + let block = vec![b'k'; 1024 * 1024]; + for _ in 0..MAX_QUEUED_INPUT_BYTES / block.len() { + driver.write_raw(&block).unwrap(); + } + control.cmd_tx.send("first-command".to_string()).unwrap(); + control.cmd_tx.send("second-command".to_string()).unwrap(); + let mut got = driver.pump().raw_output; + assert_eq!(driver.held_command_len(), "first-command\n".len(), "refused command is held, not dropped"); + let _ = driver.pump(); + assert_eq!(driver.held_command_len(), "first-command\n".len(), "still held while the backlog is full"); + + // Open the gate: the child starts reading and echoes everything back. + drop(std::fs::OpenOptions::new().write(true).open(&fifo).unwrap()); + let tail = b"first-command\nsecond-command\n"; + assert!( + wait_for(|| { + got.extend_from_slice(&driver.pump().raw_output); + got.ends_with(tail) + }), + "commands were lost or reordered; got {} bytes", + got.len() + ); + assert_eq!(got.len(), MAX_QUEUED_INPUT_BYTES + tail.len(), "nothing dropped, nothing duplicated"); + assert_eq!(driver.held_command_len(), 0); + let _ = std::fs::remove_dir_all(&dir); +}