Skip to content

Add ReadBuffer(): reads into buffers of the poller, on every backend - #209

Draft
resetius wants to merge 1 commit into
masterfrom
read-buffer-common
Draft

resetius wants to merge 1 commit into
masterfrom
read-buffer-common

Conversation

@resetius

@resetius resetius commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Adds co_await handle.ReadBuffer(): a read into a buffer of the poller instead of the caller's memory. This is step 1 of 3 of the design approved in the tracker (multishot reads on TUring need the backend to own the buffer).

API (additive, nothing existing changes):

  • TReadBuffer: move-only lease. Data() gives the bytes not consumed, Consume(n) drops the first n, the destructor gives the buffer back. An empty lease is the end of the stream; errors throw std::system_error.
  • TPollerBase::ConfigureReadBuffers(TReadBufferConfig): BufferSize 16 KiB, Count 1024, PerSocketLimit 8 (used by the read-ahead pollers in the next PRs). Memory is allocated at the first ReadBuffer(), pages are touched only when used.
  • ReadBuffer() on TSocket/TFileHandle and on the poller-driven handles.

This PR has one implementation for every backend: ReadSome() of the handle into a buffer acquired from the pool, waiting again after a spurious wake-up. TUring and TIOCp use it too for now. The next PRs, stacked on this one, add the read-ahead: multishot recv/read into a buffer ring on TUring, one WSARecv per socket on IOCP.

ReadSome() is not touched on any backend: no new branch, no lookup, no allocation. Only a poller that reads ahead has a queue of leases, so the ReadSome() adapter over that queue comes with the TUring PR. Here ReadSome() after ReadBuffer() simply reads the next bytes, so the order is kept by construction.

Reuse of existing primitives

  • The pool is a TArena: the free-list core of TArenaAllocator, moved into a non-template class with a runtime slot size and an optional limit on pools. TArenaAllocator<T, PoolSize> is now a thin wrapper over it, with the same interface and behaviour; Allocate() gets one compare, only when the free list is empty.
  • The read buffers use one pool of Count slots, so a buffer also has an index (Slot(i), Index(p)). The uring buffer ring needs that: one region, addressed by the 16-bit buffer id in the CQE.
  • The backend side uses the Acquire/Commit vocabulary of TZeroCopyLineSplitter and TZeroCopyEnvelopeReader(V2), and Release of TPodAllocator: Acquire(lease) gives the span to read into, Commit(lease, n) publishes the bytes read (Commit(id, n) for a buffer the kernel picked), Release(id) gives a buffer back. The consumer side is Data()/Consume(n).
  • Not reused, and why:
    • The chunks of TZeroCopyEnvelopeReaderV2 are separate 1 MiB allocations with one writer each, not one region with ids.
    • TPodAllocator is plain new/delete for variable-size blobs.
  • Possible follow-up: the actors' zero-copy reader could take its chunks from a TArena of 1 MiB slots. Its blobs would need a refcounted lease, and read-ahead into such big buffers would need IOU_PBUF_RING_INC.

Details:

  • All buffers leased: ReadBuffer() throws std::errc::no_buffer_space.
  • Asserts: a lease is returned on the poller's thread and before the poller is destroyed.
  • Like ReadSome(), ReadBuffer() tries the read first on the readiness pollers.

Tests (all pollers of each platform): end of stream, read error (RST), Consume() and moves, order when mixing ReadSome() and ReadBuffer(), all buffers leased plus a 256 KiB transfer through 2 buffers, close while a reader waits, reader destroyed while waiting, pipes and regular files.

Regression check of plain ReadSome(), master 85489f0 vs this PR b6ccea4, Release.

  • Bench: examples/bench -n 1024 -w 100000, single, 25 runs per invocation. Median of the per-run p50 over alternating repetitions, min-max in brackets.
  • Cycles/hop: perf stat cycles:u+cycles:k of -w 100000 minus -w 100, per hop.
  • rpi5: Cortex-A76, Linux 7.3, GCC 15.3, taskset -c 3. Mac: Apple M5 Pro, macOS 26.6, Apple clang 21.
backend host repetitions master this PR PR/master
kqueue Mac 11 0.594 µs/hop (0.592-0.609) 0.594 (0.592-0.610) 1.00
epoll rpi5 7 1.701 µs/hop (1.688-1.721) 1.691 (1.686-1.708) 0.99
epoll, cycles/hop user+kernel rpi5 7 4106 (4042-4218) 4073 (4045-4191) 0.99

Actor bench (ping_actors, 10 nodes, inflight 1024, 10M messages), msg/s, median of 7:

backend master this PR PR/master
kqueue (Mac) 2 173 930 (2 127 670-2 184 130) 2 185 410 (2 148 180-2 192 710) 1.01
epoll (rpi5) 813 543 (811 152-822 266) 858 903 (841 024-869 029) 1.06

The +6% on the epoll actor bench came with the TArena change; the first version of this PR, without it, gave 818k vs 824k. It is likely memory layout, not a real speed-up.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Unit Test Results (MacOS)

278 tests  +24   278 ✅ +24   32s ⏱️ ±0s
  4 suites ± 0     0 💤 ± 0 
  4 files   ± 0     0 ❌ ± 0 

Results for commit b6ccea4. ± Comparison against base commit 85489f0.

♻️ This comment has been updated with latest results.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Unit Test Results (Linux)

365 tests  +32   365 ✅ +32   30s ⏱️ +7s
  4 suites ± 0     0 💤 ± 0 
  4 files   ± 0     0 ❌ ± 0 

Results for commit b6ccea4. ± Comparison against base commit 85489f0.

♻️ This comment has been updated with latest results.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Unit Test Results (Windows)

203 tests  +28   203 ✅ +28   50s ⏱️ +6s
  4 suites ± 0     0 💤 ± 0 
  4 files   ± 0     0 ❌ ± 0 

Results for commit b6ccea4. ± Comparison against base commit 85489f0.

♻️ This comment has been updated with latest results.

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