From 87b452537a599522cb155592f1f24bfc8a956e4c Mon Sep 17 00:00:00 2001
From: Brad Fitzpatrick <bradfitz@golang.org>
Date: Mon, 25 Aug 2014 21:38:39 -0700
Subject: [PATCH] io: document that Readers and Writers must not retain buffers

There are both many callers and many implementations of these
interfaces, so make the contract explicit. Callers generally
assume this, and at least the standard library and other
implementations obey this, but it's never stated explicitly,
making it somewhat risky to assume.

LGTM=gri, rsc
R=golang-codereviews, gri
CC=golang-codereviews, r, rsc
https://golang.org/cl/132150043
---
 src/pkg/io/io.go | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/pkg/io/io.go b/src/pkg/io/io.go
index 022fdb67645..e8bbad537c6 100644
--- a/src/pkg/io/io.go
+++ b/src/pkg/io/io.go
@@ -63,7 +63,7 @@ var ErrNoProgress = errors.New("multiple Read calls return no data or error")
 //
 // Implementations of Read are discouraged from returning a
 // zero byte count with a nil error, and callers should treat
-// that situation as a no-op.
+// that situation as a no-op. Implementations must not retain p.
 type Reader interface {
 	Read(p []byte) (n int, err error)
 }
@@ -75,6 +75,8 @@ type Reader interface {
 // and any error encountered that caused the write to stop early.
 // Write must return a non-nil error if it returns n < len(p).
 // Write must not modify the slice data, even temporarily.
+//
+// Implementations must not retain p.
 type Writer interface {
 	Write(p []byte) (n int, err error)
 }
@@ -192,6 +194,8 @@ type WriterTo interface {
 //
 // Clients of ReadAt can execute parallel ReadAt calls on the
 // same input source.
+//
+// Implementations must not retain p.
 type ReaderAt interface {
 	ReadAt(p []byte, off int64) (n int, err error)
 }
@@ -209,6 +213,8 @@ type ReaderAt interface {
 //
 // Clients of WriteAt can execute parallel WriteAt calls on the same
 // destination if the ranges do not overlap.
+//
+// Implementations must not retain p.
 type WriterAt interface {
 	WriteAt(p []byte, off int64) (n int, err error)
 }