What does a pipeline stage that takes the chunk buffer's owning handle by value promise its caller about that buffer?

## The signature is the contract In a single-ownership design, how a stage accepts the chunk buffer is a design statement that the compiler enforces. There are two owning positions and they say opposite things: - **Takes the owning handle as a parameter.** The stage assumes the release duty. The caller's handle is spent at the call site, and the stage decides everything after that — release it, park it in a queue, hand it further down the pipeline. - **Returns an owning handle.** The duty travels back out to the caller, which is now the one obliged to release it, or to move it on again. A third category exists — a non-owning parameter, where the duty stays with the caller and the stage may only look — but its rules are a separate subject. What matters here is that the owning positions carry a promise, and that the promise is machine-checked rather than documented. ## What the caller reads off it | The stage's shape | Who releases | Caller's handle afterwards | What it is for | |---|---|---|---| | Takes the owning handle | the stage | spent; reassign before reuse | consuming handoff down the pipeline | | Takes and returns a handle | the caller, after it comes back | usable again once reassigned | transform, then give it back | | Returns a handle only | the caller | n/a — the caller receives ownership | a producing stage, such as the reader | The value of this is that questions which otherwise need a convention — who frees this, may I keep using it, is it safe to hold this across a suspension — are answered by the declaration. Nobody has to grep for a comment. ## The error path is where the design shows A stage that took ownership and then fails is holding a buffer the caller can no longer see. It has three honest options: 1. **Release it and return a plain error.** Simple, and correct when the payload is cheap to reproduce. The caller retries from scratch, reallocating and refilling. 2. **Return ownership alongside the error.** The failure value carries the buffer back. The caller can retry immediately against the same bytes, which for a 32 MiB chunk read off a network is a large saving and, in a streaming source, may be the only option because the bytes cannot be read twice. 3. **Park it for a later retry the stage itself drives.** Now the stage owns a growing set of buffers, and the footprint of that set has to be bounded or it becomes the pipeline's memory incident. The defect to avoid is a fourth: taking ownership and then silently doing neither — returning an error while dropping the buffer on a path where the caller believed it was retained, or worse, holding it forever in a failure record nobody drains. ## Designing a stage interface A small set of rules covers most of it: - Take ownership when the stage genuinely **consumes** the buffer; do not take it just because it is convenient. - If the caller needs the buffer afterwards, either **return it** or do not take it — never expect the caller to reach for a spent handle. - Decide the **failure contract once**, for every stage in the pipeline, so retry logic is uniform. - Keep the transfer **at the end of the caller's scope** so no stale use can creep in later. - Name the direction in the interface, not in prose — a signature that moves ownership one way and a comment that claims another is a bug in waiting. ## Why interviewers ask this It separates engineers who see ownership as a memory-safety mechanic from engineers who see it as an interface design tool. The first group can explain what a move does; the second group can tell you what a stage's signature obliges both sides to do, what happens to a 32 MiB buffer when that stage throws an error, and why the answer should be the same across every stage in the pipeline. The second answer is the one that predicts whether a retry path leaks.