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
net/http: imprecise description of the return values of HTTP serve functions #26267
Comments
I think "always" is a description of the "non-nil" quality of the error as opposed to a description of the "return" of the error. In other words, any error that is returned is guaranteed to be non-nil. It is probably not meant to guarantee that the function returns - I don't know if we can guarantee that any function in the standard library returns. But perhaps there's a way to remove this ambiguity in a similarly concise fashion. |
Perhaps the sentences could be reworded, like:
|
Change https://golang.org/cl/122465 mentions this issue: |
I've sent a small CL above with the proposed change. More broadly, I've filed #26268 to look into all the other cases of "always returns X" in the standard library. |
Closing, just like #26268. See Russ's point there. We didn't reach consensus, and it doesn't look like we found a wording that was considerably better. |
What version of Go are you using (
go version
)?go version go1.10.3 darwin/amd64
In
net.http
package, there are following fucntions/methods related to serve HTTP:Except the first one, all docs for those functiosn/methods say something like
always returns a non-nil error
. But if such a function/method is terminated by a signal which is a common way to terminate a HTTP server, it will not return. For example, consider the following go codehttp.go
:A
SIGINT
signal will terminate the program andhttp.ListenAndServe
will not return.Only if
srv
is teriminated by Server.Shutdown,srv.ListenAndServe
will return.I think that the descripion
always returns a non-nil error
should mention this behaviour. Otherwise, people will tend to write the following code:They are hoping that
Serve
will return. But it will not sinceShutdown
is not used in a way descripted inShutdown
's example code.The text was updated successfully, but these errors were encountered: