io: explain what (0,nil) means from Read

Also add a new variable ErrNoProgress that io.Readers can use to
report ineffectual Read calls.
Fixes #5310.

R=golang-dev, dsymonds, bradfitz
CC=golang-dev
https://golang.org/cl/8845043

diff --git a/src/pkg/io/io.go b/src/pkg/io/io.go
index f901afe423648ee1201bffb80ef1586688a5dee4..ec2cd6056fe66a0b5fc7bce18f150cfb3b07a816 100644 (file)
--- a/src/pkg/io/io.go
+++ b/src/pkg/io/io.go
@@ -34,6 +34,11 @@ var EOF = errors.New("EOF")
 // middle of reading a fixed-size block or data structure.
 var ErrUnexpectedEOF = errors.New("unexpected EOF")
 
+// ErrNoProgress is returned by some clients of an io.Reader when
+// many calls to Read have failed to return any data or error,
+// usually the sign of a broken io.Reader implementation.
+var ErrNoProgress = errors.New("multiple Read calls return no data or error")
+
 // Reader is the interface that wraps the basic Read method.
 //
 // Read reads up to len(p) bytes into p.  It returns the number of bytes
@@ -55,6 +60,10 @@ var ErrUnexpectedEOF = errors.New("unexpected EOF")
 // considering the error err.  Doing so correctly handles I/O errors
 // that happen after reading some bytes and also both of the
 // allowed EOF behaviors.
+//
+// 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.
 type Reader interface {
        Read(p []byte) (n int, err error)
 }