Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RESP decode ownership and copy evidence

RespCodec deliberately copies one complete, bounded frame after preflight. It does not copy the entire unread receive buffer, and it does not claim a zero-copy decode path. This page records why that ownership model is the current production choice and how to reproduce its evidence.

Decision

The historical decoder passed src.clone().freeze() to resp-rs for every reply. BytesMut::clone() copies the full unread slice, so a batch of equal frames caused the shrinking remainder to be copied repeatedly. The current decoder first determines the complete frame extent, copies only those bytes, parses that immutable frame, and advances the receive buffer only after parse success. Total parser-input copying is therefore linear in decoded wire bytes.

A split_to(frame_len).freeze() design removes that copy and is faster in the focused harness, but it couples response lifetime to receive-buffer lifetime. A small response retained after the unread tail is drained can pin the entire original allocation. It also complicates the codec’s promise that parse errors leave input unchanged: restoring an already-split prefix requires rebuilding the buffer on the exceptional path.

The bounded first-frame copy is the selected tradeoff because it:

  • avoids the historical quadratic copied-byte mechanism;
  • limits a retained response to frame-sized backing storage rather than the whole receive batch;
  • preserves unchanged bytes on incomplete input and all errors; and
  • requires no unsafe code in the production protocol crate.

The first-frame implementation arrived with the earlier bounded-preflight work. The evidence here validates and regression-tests that choice; it is not a claim that this evidence round alone produced an end-to-end client speedup.

Retained evidence

The checked raw evidence was recorded on macOS arm64 at source b7256ba04acda830368632af1f2450f746029c81 with Rust 1.98.1, Cargo 1.98.1, bytes 1.12.1, resp-rs 0.1.8, tokio-util 0.7.19, and Criterion 0.5.1. The source tree was clean when the run began. Allocation values are requested layout bytes observed through an instrumented System allocator, not RSS. “Allocated” is the sum of successful initial layout sizes plus positive growth during reallocation; “live” is the change in requested live layout bytes. Neither value includes allocator metadata or size-class rounding. Durations are 30 raw within-process samples of 20 iterations with allocation instrumentation active. They are directional mechanism evidence, not Redis client throughput or a cross-host performance claim.

The retained-batch rows below keep every decoded frame until the batch is complete. “Copied wire” counts only bytes copied to create parser input; “allocated” and “live” also include the requested layout sizes for receive storage, Frame values, and aggregate vectors.

Scenario and strategyCopied wireAllocated through decodeLive after decodeMedian time
512 five-byte replies; historical whole-buffer copy656,640 B708,352 B708,352 B54,307 ns
512 five-byte replies; production first-frame copy2,560 B54,272 B54,272 B39,685 ns
512 five-byte replies; split/shared comparison0 B39,464 B39,464 B12,722 ns
128 mixed replies (71,296 wire bytes); historical whole-buffer copy4,630,640 B4,718,832 B3,576,560 B99,510 ns
128 mixed replies; production first-frame copy71,296 B158,720 B158,544 B16,425 ns
128 mixed replies; split/shared comparison0 B85,160 B85,160 B6,389 ns

The lifetime counterexample is the reason the fastest microbenchmark strategy is not the production default. The input contains a 23-byte first frame and a 262,155-byte unread tail. After the unread buffer is dropped while the head frame remains alive:

StrategyCopied wireBytes pinned by the retained headMedian time
Historical whole-buffer copy262,178 B262,202 B8,819 ns
Production first-frame copy23 B47 B3,275 ns
Split/shared comparison0 B262,218 B3,637 ns

These numbers should not be extrapolated to a complete Redis workload. The production path also performs the bounded preflight scan, while the comparison strategies receive known fixture extents. Later parser or buffer changes should rerun the same artifact rather than preserving these numbers as a permanent marketing baseline.

Regression and benchmark coverage

The protocol unit suite counts both completed materializations and their exact wire bytes. A mixed pipeline containing binary bulk data, a push, scalars, and an aggregate proves that production materializes the sum of frame sizes once, not the sum of shrinking unread suffixes. A byte-at-a-time case proves that no copy happens until a frame is complete. Existing boundary tests continue to cover limits, malformed input, unchanged error bytes, binary payloads, pushes, and response order.

Criterion now includes:

  • dropped and batch-retained lifetimes for 100 simple replies;
  • dropped and batch-retained mixed payloads from zero through 4 KiB; and
  • a smaller mixed fixture with payloads through 256 bytes, delivered in 1-, 7-, 64-, and 1,024-byte fragments.

The raw allocation artifact repeats those four fragment sizes over the same smaller 112-frame fixture, retains the decoded batch, and records receive-buffer reallocations, net acquired requested layout bytes, and the change in requested live layout bytes. Every fragmentation plan decodes frames equivalent to the contiguous production path and reports exactly one frame’s wire bytes per completed materialization.

Delivery chunkCopied wireAllocated through decodeBuffer reallocationsMedian time
1 B5,616 B20,720 B686,262 ns
7 B5,616 B20,720 B624,997 ns
64 B5,616 B20,720 B312,590 ns
1,024 B5,616 B22,256 B111,136 ns

To reproduce the checked allocation/copy artifact from a clean checkout, use an absolute output path because Cargo runs the custom benchmark from the package directory:

evidence_output="$PWD/conformance/codec-copy-evidence.json"
cargo bench -p redis-tower-protocol --bench codec_allocation -- \
  --evidence --samples 30 --iterations 20 --check \
  --output "$evidence_output"

The --check mode verifies equivalent decoded frames, exact deterministic copy counts, lower production allocation than the historical mechanism, and the retained-tail tradeoff. cargo test --benches runs a short silent smoke; an explicit --evidence invocation is required for retained timing samples. Run the Criterion timing suite separately with:

cargo bench -p redis-tower-protocol --bench codec