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: