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

diff --git a/src/pkg/io/io.go b/src/pkg/io/io.go
index 022fdb676453949e197e7350824cb179ea114fdc..e8bbad537c61f81c690a3d72294fdd26351cd12c 100644 (file)
--- 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)
 }