Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

io: Documentation of the io package at website is contrary to its documentation in comments inside source code. #59254

Closed
vault-thirteen opened this issue Mar 26, 2023 · 5 comments

Comments

@vault-thirteen
Copy link

What version of Go are you using (go version)?

go version go1.20.2 windows/amd64

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

O.S. is Microsoft Windows 10.
CPU uses Intel x86-64 (a.k.a. AMD64) architecture.

What did you do?

Documentation of the io package at website states following.

An instance of this general case is that a Reader returning a non-zero number of bytes at the end of the input stream may return either err == EOF or err == nil. The next Read should return 0, EOF.

Documentation of the same io package in comments inside the source code states following.

EOF is the error returned by Read when no more input is available.

What did you expect to see?

I expect to see no controversy in documentation.

What did you see instead?

I saw the controversy in documentation.

@seankhliao
Copy link
Member

There is no conflict between the 2 statements.

Unlike many projects, the Go project does not use GitHub Issues for general discussion or asking questions. GitHub Issues are used for tracking bugs and proposals only.

For questions please refer to https://github.com/golang/go/wiki/Questions

@vault-thirteen
Copy link
Author

If there is no controversy then why is the io.EOF error not returned by some readers implementing the io.Reader interface when no more input is available ? Its description says that it is returned when no more input is available.

An example of such behaviour may be found in the bytes.Reader, which does not return the io.EOF when no more input is available. I described it in the issue 59253, #59253.

@ianlancetaylor
Copy link
Contributor

@vault-thirteen The bytes.Reader.Read method does return io.EOF when no more data is available. I think you may be saying that you that if a Read method is asked for four bytes, and there are only two bytes available before end-of-file, then the Read method should return 2, io.EOF. In fact, at least for bytes.Reader.Read, it returns 2, nil, and then on the next call returns 0, io.EOF. Both behaviors are permitted by the definition of io.Reader. And while the former behavior is possible for some implementations of io.Reader, it is not possible for all of them, at least not without introducing other undesirable side effects such as unexpected delays when reading from a network socket.

@vault-thirteen
Copy link
Author

Hello there, @ianlancetaylor.
I think that your definition of "no more input is available" differs from mine.

I think that "no more input is available" means the following:
when there is a sudden end in the data stream, which happens before we have read the requested number of bytes.
For example, we want to read 3 bytes, but the stream only has 2 bytes. After those 2 bytes no more bytes in the stream exist, and for me it is this "no more input".

@ianlancetaylor
Copy link
Contributor

What does that mean on a network socket, where you don't know whether the data stream is finished or not until you receive another package?

In any case this issue is not a good place to discuss this topic. Please see https://go.dev/wiki/Questions if you want to continue.

@golang golang locked and limited conversation to collaborators Mar 28, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants