Skip to content

perf(pty): writer thread per PTY, wake on output, frame floor - #77

Merged
bsommers merged 8 commits into
mainfrom
perf/pty-writer-and-wake-on-output
Nov 11, 2026
Merged

bsommers merged 8 commits into
mainfrom
perf/pty-writer-and-wake-on-output

Conversation

@bsommers

Copy link
Copy Markdown
Owner

What

Step 3a of the responsiveness work: stop PTY I/O from waiting on the UI thread or the 16 ms tick.

  • Writer thread per PTY (src/pty/writer.rs, src/pty/mod.rs): write_all enqueues and returns; one FIFO per PTY, whole chunks in order. Backlog limit 4 MiB per PTY; over it the write is refused with an error shown in the status line, and the caller is never blocked.
  • Wake on output (src/pty/wake.rs, src/app.rs, src/app/pacing.rs, src/wm/pty_drain.rs): reader threads wake the event loop, which drains PTYs immediately. The 16 ms tick stays for timers, STT, tmux link and reaping.
  • Frame floor: 8 ms between draw starts (125 fps cap under flood). A redraw caused by input that wrote to a PTY waits up to 2 ms so the echo shares its frame; it always draws.
  • App::handle_crossterm_event now reports errors in the status line and returns Ok; previously one pane's write error could end the GUI loops, which propagate with ?.
  • Review follow-ups (a5f031f): a tmux link command refused under backpressure is held and retried in order; Exited is reported at most once per PTY; the writer's finish notification is sent under the lock; unsent query replies are logged.

Measurements

Key to echo, release, n=300 (tests/echo_latency.rs, #[ignore]):

median p95
Before (16 ms tick poll) 9.07 ms 16.07 ms
After, output wake 0.058 ms 0.070 ms
After, real run_loop, key event → frame drawn (no-op draw) 0.098 ms 0.142 ms

Verification

  • tests/pty_writer_thread.rs, src/pty/writer_tests.rs: write to a non-reading child returns; ordering across small/large/small writes through cat; thread ends on drop, idle and blocked; refused tmux command is delivered later, in order.
  • tests/app_loop_wake.rs: under a yes flood, 100 key events are each consumed within 2 loop turns and draws stay within the frame floor.
  • Mutation checks: removing the floor fails the flood test; removing the reader wake fails the echo test.
  • Local gate after merging main: 180 of 182 pass; the two failures are phase68_69_surface_parity and swarm_wiring, which fail on main and are fixed by ci: six-cell OS/arch matrix, coverage gate, VT fuzz test, fix two stale swarm tests #71. GOLDENS OK 11.
  • Independent read-only review found no deadlock, lost wakeup or ordering bug.

Open decision

A failed write marks the pane exited, which drops its PTY and kills the child. On Linux a master write should fail only once every slave descriptor is closed (not tested). Elsewhere, or on an unexpected errno, the child could still be alive; the alternative is to keep the pane open as output-only.

Known gaps

  • GUI loops (src/ui/gui_window.rs, gui_macos.rs, gui_font/linux_x11.rs) still sleep 16 ms between polls, so the latency gain applies to the TUI loop only.
  • The tmux link driver's PTY, the web pump and the RPC wait tick are unchanged.
  • A writer blocked in the kernel ends only when the tty slave closes; a grandchild holding the tty keeps the thread alive. Tested on Linux only.
  • Two existing tests were edited: phase64_traffic_hooks now waits for the tx count (counted on the writer thread); phase64_layer_dag hook anchors moved with the code.

🤖 Generated with Claude Code

bsommers and others added 8 commits November 10, 2026 06:42
PtySession::write_all wrote to the PTY master on the caller (the UI thread).
A child that does not read fills the ~4 KiB kernel tty buffer, so a large
paste stalled the whole multiplexer.

write_all now appends to a FIFO queue drained by one writer thread per PTY:
- order preserved (single queue, single consumer, whole chunks)
- backlog bounded at 4 MiB; a write over the limit is refused whole with an
  error the caller shows, never blocked on, never dropped silently
- a write error is recorded, fails later writes fast and is reported as a
  PtyEvent::Exited so the pane is held/closed
- traffic tx is counted when the bytes are really written
- the thread ends when the session is dropped; the reaper gives accepted
  input up to 250 ms to reach a reading child first

Also adds pty::wake (process-wide output wake used by the next commit); the
reader thread signals it after each chunk.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…me floor

PTY output was drained only on the 16 ms tick, so every echo waited 0-16 ms
(measured median 9.1 ms, p95 16.1 ms), and each keypress drew a frame before
its echo existed.

- PTY reader threads signal pty::wake; App::run_loop has a select arm that
  drains PTYs at once (WindowManager::drain_pty_output, same 32 x 8 KiB
  per-pane bound). The 16 ms tick stays for timers, RPC waiters, STT, the
  tmux link and reaping.
- FramePacer: draws start at least 8 ms apart (FRAME_FLOOR), so a flooding
  pane is capped at 125 fps; an idle terminal draws immediately.
- Echo hold: a redraw caused by input that sent bytes to a PTY is deferred up
  to 2 ms so the echo shares its frame. Deferred, never skipped, so input that
  also changed WM state is still drawn.
- select! is biased (tick, signals, input, RPC, frame deadline, PTY output) so
  flooding output cannot starve input: an event is consumed within two turns.
- App::run is now a thin host adapter over the generic, headlessly testable
  App::run_loop.
- App::handle_crossterm_event reports handler errors in the status line and
  returns Ok: the GUI loops propagate its result with ?, so one pane's refused
  or failed write could end the whole GUI.

tests/app_loop_wake.rs drives the real loop headlessly (flood + input, echo
before the next tick, exit). tests/echo_latency.rs is the ignored harness.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- tmux link: a command the PTY refuses (input backlog full) or fails to take
  is held and retried ahead of newer commands instead of being popped and
  dropped; the refusal is logged once per episode.
- pane: terminal query replies that are not sent are logged instead of
  discarded with 'let _ ='.
- PtySession::drain_events reports Exited at most once per PTY, whether it
  came from the reader or was synthesised for a write failure, in the same
  poll or a later one (pty::exit_report).
- writer: the finished flag is published under the state lock so
  wait_finished/wait_drained cannot miss the notification.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
On a loaded runner the 16 ms tick drains most output and input events also
cause redraws, so draws can exceed wake-driven drains (CI: 618 vs 450).
The frame-floor bound already asserts coalescing.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@bsommers
bsommers merged commit 9a2e2d6 into main Nov 11, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant