Why must an io.Writer implementation not retain or modify the caller's slice p after Write returns?

## The clause The `io` package documents a duty on the *implementer* of `Read` and `Write`, not on the caller. For `Write` it reads, in substance: `Write` must not modify the slice data, even temporarily, and implementations must not retain `p`. `Read` carries the matching sentence: implementations must not retain `p`. "Retain" means keep a reference that outlives the call -- storing it in a struct field, appending it to a slice of pending chunks, sending it on a channel, or capturing it in a closure that runs later. Once `Write` returns, the implementation must be finished with those bytes. ## Why the rule exists The whole design of `io` is built on the caller owning and reusing the memory. `io.Copy` allocates a single scratch slice and loops: read into it, write from it, read into it again. The second read overwrites the same backing array the previous `Write` was given. An implementation that kept that slice is now looking at the *next* chunk of the stream, or at a half-overwritten mixture of two chunks. That produces a bug with a distinctive shape. Small inputs work, because everything fits in one iteration and there is never a second read to overwrite anything. Large inputs corrupt -- and often corrupt differently on every run, because the corruption depends on how the reader chunked the data and on goroutine timing. Nothing panics; the destination simply contains bytes that never appeared in the source, or the same 32 KiB twice. If the retained slice is read from a different goroutine than the one refilling it, this is not merely a logic bug but an unsynchronised concurrent access to the same memory. `go build -race` / `go test -race` will report it as a data race, with both stacks -- which is usually the fastest way to find it, because the corrupted output alone rarely points at the guilty `Write`. ## The "even temporarily" part The `Write` contract goes further than "do not keep it": it forbids modifying `p` at all, including a change you undo before returning. A tempting trick when framing a protocol is to write a length prefix into the front of the caller's slice, send it, then restore the original bytes. That is forbidden, and for good reason -- the caller may be writing the same slice to several destinations, or may be sharing it read-only with another goroutine that is entitled to assume nobody mutates it. The caller's data is input, not scratch space. ## Doing it correctly If your implementation genuinely needs the bytes after `Write` returns -- an asynchronous flusher, a retry queue, an in-memory accumulator -- copy them into memory you own: ```go b := make([]byte, len(p)) copy(b, p) ``` or, equivalently, `b := append([]byte(nil), p...)`. If allocation per write is too expensive, take the destination slice from a pool you manage and return it when the flush completes. The cost of that copy is precisely the cost of the guarantee you are making; there is no way to keep the caller's memory and stay inside the contract. Note also the appending trap: `w.pending = append(w.pending, p...)` copies the bytes and is fine, while `w.chunks = append(w.chunks, p)` stores the slice header itself and is a violation. The two lines differ by three characters. ## The mirror image on the reader side A `Read` implementation must not keep `p` either. A reader that stashes the caller's slice and fills it later -- from a background goroutine, or on the next call -- writes into memory the caller may have already handed elsewhere, reused for another stream, or shrunk. The caller is entitled to do anything it likes with `p` the moment `Read` returns. The symmetric duty on the *caller* side is not to look at `p[n:]`. Those bytes are whatever was left over from previous use; the implementation makes no promise about them. ## Reviewing for it When you review an `io.Writer` or `io.Reader` implementation that another team will use, this is the first thing to check, because the compiler cannot. Look for `p` escaping the method body: stored in a field, sent on a channel, captured by a goroutine, appended as a whole slice, or passed to something that outlives the call. `go build -gcflags=-m` reporting that `p` escapes to the heap is a useful hint that something is holding on to it, though not proof on its own. And document your own types' behaviour explicitly when you accept a slice outside the `io` interfaces. The `io` rule is a convention people rely on precisely because it is uniform; a type that quietly breaks it will be misused by everyone who assumes the standard shape.