bufio: Reader.WriteTo documentation should clarify that multiple calls to the upstream Reader may be made #19092
Description
I am unsure if this is intended behavior (in which case this is a documentation problem), or a bug (in which case it may be a bug and a documentation problem :) ). Please advise (or perhaps it's neither, of course); I have patches for both I can submit.
What version of Go are you using (go version)?
go version devel +d2fea0447f Tue Feb 14 19:44:35 2017 +0000 linux/amd64
What did you do?
- Create a
net.Connthat receives some bytes on the first call to Read, and then holds the connection open (so that you do not receive an io.EOF from a call to Read). - Now wrap it in a
bufio.Reader. - Call
io.Copyon the new buffered reader and copy it somewhere else (into a bytes.Buffer, for example).
What did you expect to see?
I expected the bufio.Reader's WriteTo method to be called, proxy a single call to conn.Read, write that data, and then return.
What did you see instead?
Instead, it attempts to call conn.Read a second time (the behavior is to read until EOF or an error is returned).
This may not be an issue; the documentation for io.WriterTo says:
WriteTo writes data to w until there's no more data to write or when an error occurs.
However, it is unclear to me if "no more data to write" means "until EOF" in the case of the bufio.Reader implementation, or if it means "the buffer was flushed" or, if the buffer was empty, "a successful proxied read call had the read data written".
Personally I expected this to call Read at most once, much like the bufio.Reader's Read method.
I think that this behavior should either be changed to not use fill() (and I am happy to make this change), or the documentation should explicitly say that bufio.Reader's WriteTo method writes until EOF or an error is returned from an upstream Read call.