Skip to content

Measure the PTY receive queue under slow, absent and burst consumers #184

Open

Description

@Blind-Striker

What

Measure the terminal receive queue when the consumer reads slowly, stops reading, or receives a
burst: queue length, and retained and peak memory over time, for PtySession and
PersistentPtySession. Use a macro harness (a long-running scenario whose socket produces output
faster than it is read), not only BenchmarkDotNet's MemoryDiagnoser. Record the numbers with their
environment.

Why in 1.0

The receive queue is unbounded by contract, and ADR-0023 says a memory limit and an overflow policy
need workload evidence before that contract changes. The 1.0 contract keeps the queue unbounded only
if the measurement shows that this is acceptable; a default bound after 1.0 would be a behaviour
change. This measurement is that evidence. An opt-in bound, if one is wanted, follows after 1.0.

Evidence

  • src/OpenCode.Sdk/Internal/TerminalReceivePump.cs:12: Channel.CreateUnbounded; :152: one
    16 KiB receive buffer per connection (src/OpenCode.Sdk/Internal/TerminalSocketBounds.cs:19).
  • docs/adr/0023-terminal-consumer-cancellation.md:7-11.
  • docs/ROADMAP.md:92-93 ("a bound for the terminal receive queue, which is unbounded today").
  • tests/OpenCode.Sdk.Performance.Tests/Benchmarks/PtySessionReadBenchmarks.cs and
    PersistentPtySessionReadBenchmarks.cs measure receive and decode only.

Done when

  • Numbers for the three consumer patterns on Windows (and on Linux if cheap), with the harness
    committed.
  • A written conclusion: the unbounded default stands for 1.0, or a bound is needed, with the
    evidence; the contract sentence in client-runtime.md matches it.

Activity

  1. added this to the 1.0 milestone on Oct 14, 2026
  2. Blind-Striker commented on Oct 15, 2026

    @Blind-Striker
    CollaboratorAuthor

    Status (Surface lane, 2026-10-15): not started. The lane's queue went to #175/#176 (network timeout, reconnect), and the road-to-1.0 stop plan defers new work until after the cross-model review. A stale worktree exists (perf/pty-queue-184 on an old master, no commits); whoever picks this up should re-branch from master. No decision is pending on it.

  3. Blind-Striker commented on Oct 15, 2026

    @Blind-Striker
    CollaboratorAuthor

    Scope decision (2026-10-15, the lead, under the maintainer's 'finish what's in flight'): this measurement is not part of the before-refactor baseline. It needs a macro harness that does not exist yet (a socket that outpaces its consumer, with queue length and retained/peak memory over time), which is new code. It waits for the Faz 3 decisions. If Faz 3 decides to change the terminal receive queue, the harness is built and this baseline taken first, before anyone touches that code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    performanceSpeed / allocation work

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions