pty: park the Linux PTY reader in poll(2) without spinning #421

Merged

natsukium merged 3 commits from pty/linux-reader-no-spin into main 2026-09-25 08:46:58 +09:00

Conversation 0 Commits 3 Files changed 4 +33 -5

natsukium commented 2026-09-25 07:07:11 +09:00

Owner

Copy link

On Linux the PTY reader stops spinning on EAGAIN and parks in poll(2) right away. macOS keeps the 50 µs spin, which was sized for its ~1 KiB PTY lockstep. Linux queues ~68 KiB, so there the spin cost reader CPU and did not change the frame rate.

Closes #399. The two parser costs from its profile are split out to #416 (SGR pen re-interning, 21% of the parse thread under DOOM-fire) and #417 (Params::push_run, 10.7%).

Refs #400. That issue proposed coalescing the ~13-byte reads on vtebench's scrolling rows. It is rejected, and docs/explanation/implementation.md records why: when output sits unread in the kernel, the producer's own write path gets slower. A bare drain pausing 20-50 µs between reads took scrolling at 82x212 from ~160 to ~255 ms per sample (five interleaved pairs). A felis build that waited up to 50 µs while the parser was busy cut reader CPU by 93% but ran the harness's scrolling rows up to twice as slow.

Measurements

Linux, i5-12400F, niri 60 Hz, NVIDIA through the pinned ICD (checked in the client's mapped libraries). Release builds of main 6f3931a1 and of this change, run interleaved. The host is also the CI runner, so the 1-min load average is given with each figure.

workload	load	main	this branch
DOOM-fire fps, 12 s at 93x212, 5 undisturbed pairs	2.5-7.6	897 / 914 / 902 / 945 / 981 (mean 928)	910 / 896 / 938 / 959 / 947 (mean 930)
DOOM-fire reader thread, user + sys per 12 s	same	1.7-2.5 + 3.2-3.6 s	0.3-0.4 + 3.6-3.7 s
DOOM-fire suite, 20 s at 212x82, fps (daemon CPU)	3.7-10.8	1029 / 947 / 951 (28.8-29.1 s)	991 / 940 / 917 (26.7-26.9 s)
vtebench scrolling median, 93x212, 3 pairs	2.7-3.5	130.5 / 123 / 133 ms	126 / 113 / 108.5 ms
vtebench scrolling_top_region median, 3 pairs	3.5-4.0	124.5 / 125 / 121 ms	134.5 / 112 / 121.5 ms
cat suite ascii / unicode / csi, 150 MB	6.3-10.1	1.56 / 0.85 / 1.05 s	1.53 / 0.77 / 0.90 s
profile_echo_latency p50 / p99, 3 pairs	2.1-4.1	5.41 / 6.44-6.48 ms	5.38-5.41 / 6.44-6.58 ms

The spin never touched the scrolling rows' reader cost: those ~13-byte reads always find data waiting.

Review

pi (sol) round 1: PASS, with one non-blocking finding. It suggested dropping the doc comment on the Linux READ_SPIN_WINDOW because the explanation doc already carries the rationale. I kept the comment: it is the why-not for someone who would otherwise bring the macOS spin back to Linux.

On Linux the PTY reader stops spinning on `EAGAIN` and parks in `poll(2)` right away. macOS keeps the 50 µs spin, which was sized for its ~1 KiB PTY lockstep. Linux queues ~68 KiB, so there the spin cost reader CPU and did not change the frame rate. Closes #399. The two parser costs from its profile are split out to #416 (SGR pen re-interning, 21% of the parse thread under DOOM-fire) and #417 (`Params::push_run`, 10.7%). Refs #400. That issue proposed coalescing the ~13-byte reads on vtebench's scrolling rows. It is rejected, and `docs/explanation/implementation.md` records why: when output sits unread in the kernel, the producer's own write path gets slower. A bare drain pausing 20-50 µs between reads took `scrolling` at 82x212 from ~160 to ~255 ms per sample (five interleaved pairs). A felis build that waited up to 50 µs while the parser was busy cut reader CPU by 93% but ran the harness's scrolling rows up to twice as slow. ## Measurements Linux, i5-12400F, niri 60 Hz, NVIDIA through the pinned ICD (checked in the client's mapped libraries). Release builds of main `6f3931a1` and of this change, run interleaved. The host is also the CI runner, so the 1-min load average is given with each figure. | workload | load | main | this branch | |---|---|---|---| | DOOM-fire fps, 12 s at 93x212, 5 undisturbed pairs | 2.5-7.6 | 897 / 914 / 902 / 945 / 981 (mean 928) | 910 / 896 / 938 / 959 / 947 (mean 930) | | DOOM-fire reader thread, user + sys per 12 s | same | 1.7-2.5 + 3.2-3.6 s | 0.3-0.4 + 3.6-3.7 s | | DOOM-fire suite, 20 s at 212x82, fps (daemon CPU) | 3.7-10.8 | 1029 / 947 / 951 (28.8-29.1 s) | 991 / 940 / 917 (26.7-26.9 s) | | vtebench `scrolling` median, 93x212, 3 pairs | 2.7-3.5 | 130.5 / 123 / 133 ms | 126 / 113 / 108.5 ms | | vtebench `scrolling_top_region` median, 3 pairs | 3.5-4.0 | 124.5 / 125 / 121 ms | 134.5 / 112 / 121.5 ms | | `cat` suite ascii / unicode / csi, 150 MB | 6.3-10.1 | 1.56 / 0.85 / 1.05 s | 1.53 / 0.77 / 0.90 s | | `profile_echo_latency` p50 / p99, 3 pairs | 2.1-4.1 | 5.41 / 6.44-6.48 ms | 5.38-5.41 / 6.44-6.58 ms | The spin never touched the scrolling rows' reader cost: those ~13-byte reads always find data waiting. ## Review pi (sol) round 1: PASS, with one non-blocking finding. It suggested dropping the doc comment on the Linux `READ_SPIN_WINDOW` because the explanation doc already carries the rationale. I kept the comment: it is the why-not for someone who would otherwise bring the macOS spin back to Linux.

natsukium added 2 commits 2026-09-25 07:07:12 +09:00

pty: park the Linux PTY reader in poll(2) without spinning ... dae797e795

The 50 µs non-blocking retry window in MasterReader::read was sized
against the macOS PTY, which drains a bulk write in a ~1 KiB lockstep:
there each read is what lets the writer refill, and spinning through the
2-4 µs gaps took DOOM-fire from 628 to 666 fps. Linux queues ~68 KiB
(64 KiB of flip buffers plus the 4 KiB line-discipline read buffer), so
its writer is not paced by the reader chunk by chunk, and the spin only
bought reader CPU. Linux now parks in poll(2) at the first EAGAIN; macOS
keeps the spin.

Measured on Linux (i5-12400F, niri 60 Hz, NVIDIA; this host is also the
CI runner, load average given per figure), release builds of main
6f3931a1 and of this change, interleaved:

- DOOM-fire, 12 s at 93x212, five undisturbed pairs (load 2.5-7.6):
  fps 897/914/902/945/981 before, 910/896/938/959/947 after (means 928
  and 930). Reader user time 1.7-2.5 s -> 0.3-0.4 s per 12 s, sys
  +0.3-0.5 s for the extra poll(2) parks; net reader CPU 5.3-5.9 s ->
  4.0-4.1 s.
- DOOM-fire suite (tools/bench, 20 s at 212x82), three pairs at load
  3.7-10.8: fps 1029/947/951 before, 991/940/917 after; daemon CPU
  28.8-29.1 s -> 26.7-26.9 s.
- vtebench scrolling / scrolling_top_region, 10 s at 93x212, three
  pairs each (load 2.7-4.0): medians 130.5/123/133 vs 126/113/108.5 ms
  and 124.5/125/121 vs 134.5/112/121.5 ms. The reader's cost there is
  ~13-byte reads, which the spin never touched.
- cat suite (ascii/unicode/csi, 150 MB): 1.56/0.85/1.05 s before,
  1.53/0.77/0.90 s after in the undisturbed pair.
- profile_echo_latency (keystroke to shadow grid), three pairs: p50
  5.41/5.41/5.41 ms vs 5.41/5.41/5.38 ms, p99 6.44-6.48 vs 6.44-6.58 ms.

The explanation doc also records why the ~13-byte reads stay: a reader
that lets a trickling producer's output pile up in the kernel slows that
producer's own write path. A bare consumer pausing 20-50 µs between
reads (sleep or busy-wait) took vtebench scrolling at 82x212 from ~160
to ~255 ms per sample, and a felis reader that waited up to 50 µs while
the parser was busy cut its CPU by 93% but ran the bench harness's
scrolling rows up to twice as slow.

Assisted-by: Claude Code

skills: map where the Linux PTY reader's CPU goes ... 1e745e90fd

The perf-trace cost map described the reader's 50 µs spin as the
topology everywhere and its rejected alternatives without saying they
were measured on macOS. With the spin now macOS-only, a Linux pass
starting from the map would otherwise re-derive two things: that the
reader, not the parser, dominates daemon CPU on vtebench's scrolling
rows (~13-byte reads, ~1.2 M/s), and that batching those reads is a
known loss, because output left unread slows the producer's own kernel
write path. The figures are the ones behind the Linux reader change.

Assisted-by: Claude Code

natsukium referenced this pull request 2026-09-25 07:07:34 +09:00

daemon: Linux vtebench scrolling rows trail the peers and vary 25-50% between rounds #400

natsukium added 1 commit 2026-09-25 07:52:48 +09:00

Merge remote-tracking branch 'origin/main' into pty/linux-reader-no-spin 57a4c12bf7

natsukium referenced this pull request 2026-09-25 07:53:26 +09:00

bench: follow up the 9d1d842f cross-terminal run #405

natsukium merged commit 4eca27b347 into main 2026-09-25 08:46:58 +09:00

natsukium deleted branch pty/linux-reader-no-spin 2026-09-25 08:46:58 +09:00

natsukium referenced this pull request from a commit 2026-09-25 08:46:59 +09:00

pty: park the Linux PTY reader in poll(2) without spinning (#421)

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!421

No description provided.