(improvement) perf: remove copies on the read path (us improvements - x1.5-3.7 speedup!)

[mykaul]

This patch set aims to reduce the memory copies we perform in the read path, to improve overall performance - mainly reduce latency on the processing side of the driver receiving the payload.
This is more effective on larger payloads of course.

⚠️ Updated benchmark note

Re-benchmarked against master (same tool as below - benchmarks/decode_benchmark.py, Cython path, isolated core, 25 iterations + 3 warmup). Most of the originally-claimed 1.5-3.7x speedups did not reproduce:

Scenario	Body Size	master (median)	this PR (median)	Original claim	Re-measured
small_100	7.3 KB	17.1 us	18.8 us	3.7x	0.91x (slower)
medium_1k_256B	273.5 KB	139.5 us	140.3 us	3.6x	0.99x (none)
medium_1k_1KB	1.0 MB	904.7 us	573.2 us	3.5x	1.58x
large_5k_1KB	5.0 MB	5343.2 us	3666.4 us	2.6x	1.46x
large_1k_4KB	3.9 MB	482.7 us	425.0 us	1.9x	1.14x
wide_5k_doubles	586.1 KB	1605.8 us	1637.7 us	1.9x	0.98x (none)
wide_1k_20cols	762.0 KB	951.0 us	973.0 us	1.5x	0.98x (none)
blob_1k_16KB	15.6 MB	14781.7 us	7184.0 us	1.8x	2.06x

Only blob_1k_16KB matches/exceeds its original claim. Four scenarios show no measurable improvement (or a slight regression); the remaining three show a real but smaller 1.1-1.6x. This is the same pattern found on PR #630 (Optimize column_encryption_policy checks in recv_results_rows) — claimed multipliers not holding under careful re-measurement in this environment. The original benchmark table below is retained for history but should not be relied on as-is.

The correctness/robustness value of this PR (reducing allocations and copies on the read path, adding BytesReader test coverage) still stands independent of the exact multiplier.

Original benchmark (see note above)

Comparison to master (Cython path, 10 iterations, CPU pinned, all times in microseconds):

Scenario	Body Size	master (median)	remove_copies (median)	Speedup
small_100	7.3 KB	273.8 us	75.0 us	3.7x
medium_1k_256B	273.5 KB	1906.7 us	536.4 us	3.6x
medium_1k_1KB	1.0 MB	6166.6 us	1740.1 us	3.5x
large_5k_1KB	5.0 MB	24822.5 us	9482.1 us	2.6x
large_1k_4KB	3.9 MB	4575.3 us	2346.7 us	1.9x
wide_5k_doubles	586.1 KB	13539.2 us	7163.0 us	1.9x
wide_1k_20cols	762.0 KB	5858.3 us	3831.4 us	1.5x
blob_1k_16KB	15.6 MB	62233.0 us	34668.1 us	1.8x

(note - we can see that wide_5k_doubles is bottlenecked on something else - CPU processing of this payload - unpacking it. This may be optimized in a different PR)

• I have split my patch into logically separate commits.
• All commit messages clearly explain what they change and why.
• I added relevant tests for new features and bug fixes.
• All commits compile, pass static checks and pass test.
• PR description sums up the changes and reasons why they should be introduced.
• I have provided docstrings for the public items that I want to introduce.
• I have adjusted the documentation in ./docs/source/.
• I added appropriate Fixes: annotations to PR description.

🤖 Generated with Claude Code

[mykaul]

#630 would have helped with wide_5k_doubles of course.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mykaul]

Rebased onto current master (was ~89 commits behind, including the new SCYLLA_USE_METADATA_ID extension work) and force-pushed. Mechanical conflicts were in tests/unit/test_connection.py and tests/unit/test_protocol.py (import lists and appended test classes); resolved by taking the union of both sides.

Since this PR's whole point is removing copies on the hot read path, I went through every copy elimination looking specifically for use-after-free/aliasing risk (a stale reference outliving the buffer it points into, or a reference to something that later gets mutated in place):

• connection.py _read_frame_header / process_io_buffer: now use getbuffer() memoryview slices instead of .read(), but always explicitly del the memoryview before any seek()/reset on the same BytesIO, and the frame body handed to process_msg is still built via bytes(buf[...]) — a real, independent copy. So everything downstream (BytesReader, the Cython row parser) is working from a standalone, immutable buffer, not a view into the connection's rotating I/O buffer.
• row_parser.pyx zero-copy handoff (f.remaining_buffer() → BytesIOReader(buf_data, buf_offset)): BytesIOReader.buf is a cdef bytes field, so Cython keeps a real refcounted reference to the underlying bytes for the reader's lifetime — no dangling pointer even after the outer BytesReader/frame body goes out of scope elsewhere. The exception fallback path also correctly re-derives buf_ptr from the new _initial_offset field (<char*>reader.buf + reader._initial_offset) instead of the old absolute-start reset, which is necessary now that reader.buf is the whole frame body rather than just the row-data suffix.
• Verified empirically too: wrote a throwaway script that runs rows through the real Cython ProtocolHandler (list) and LazyProtocolHandler (generator) paths, drops the original frame bytes object, churns the allocator with a few thousand unrelated buffers + gc.collect(), and confirms row values are still exactly correct. Also forced the except/fallback path (invalid UTF-8 mid-stream) and confirmed it reports the correct column instead of misreading from the wrong offset.

One real gap I did close (amended into Add BytesReader to replace BytesIO in decode_message): BytesReader.__init__ only special-cased memoryview for copying, so a hypothetical caller passing a mutable bytearray would have been aliased rather than copied. No current call site does this (decompressors return bytes, and the sole production caller always builds body via bytes(...)), so it wasn't reachable today, but given the buffer-lifetime theme of this PR it seemed worth closing defensively — it now copies anything that isn't already a plain immutable bytes.

CI: all required checks (Integration tests on libev/asyncio/asyncore × Python 3.11–3.14t, Docs build, security/snyk) are green on the latest push. "Test wheels building" shows red, but it's a startup_failure with zero jobs executed (not even a real check run — it's absent from the PR's merge-blocking status rollup), consistent with an external workflow-dispatch issue rather than anything caused by this change.

Ran the full tests/unit/ suite locally after rebuilding the Cython extensions: 799 passed, 38 skipped (pre-existing, environment-gated), 0 failed.

No open review threads to resolve. Still a draft as requested.

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

This PR reduces memory copying along the driver read/decode path to improve latency and throughput, especially for large payloads, by replacing io.BytesIO-based reads with lighter and more zero-copy-friendly primitives.

Changes:

• Introduces BytesReader and wires it into ProtocolHandler.decode_message() to avoid io.BytesIO(body) copying.
• Adds zero-copy handoff support to the Cython row parser via BytesIOReader(..., offset) and remaining_buffer().
• Optimizes connection buffering/reset and adds unit tests plus an isolated decode benchmark script.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
cassandra/protocol.py	Adds BytesReader and switches decode to use it instead of io.BytesIO.
cassandra/row_parser.pyx	Avoids f.read() copy by using (buffer, offset) handoff into BytesIOReader.
cassandra/bytesio.pyx / cassandra/bytesio.pxd	Adds offset support to BytesIOReader for suffix reads without copying.
cassandra/connection.py	Reduces copies by using getbuffer(), adds _reset_buffer, and bumps recv buffer size.
tests/unit/test_protocol.py	Adds unit tests for BytesReader and end-to-end decode_message coverage.
tests/unit/test_connection.py	Adds tests for _ConnectionIOBuffer._reset_buffer.
tests/unit/test_bytesio_reader.py	Adds Cython-only tests for BytesIOReader offset construction/validation.
benchmarks/decode_benchmark.py	Adds a standalone benchmark to measure decode performance across scenarios.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.