Define Server.Stop

[bradfitz]

Server.Stop is somewhat ill-defined:

https://godoc.org/google.golang.org/grpc#Server.Stop

Stop stops the gRPC server. Once Stop returns, the server stops accepting connection requests and closes all the connected connections.

Several things are unclear from that text:

• is it a graceful shutdown? That is, does it abort RPCs in progress? The wording "Once Stop returns" suggests it may take awhile, which makes me think it might be graceful.
• what order do events occur in? The text says "Once stop returns, the server stops...", suggesting that Stop returns first, and then begins stopping things, but that is not how the code reads. Is the code correct, or is the documentation correct? Either the code or docs should be changed to match.

If my understanding of the code is correct, and I don't misunderstand the intentions of this method, I think better wording might be:

Stop forcefully stops the gRPC server. It immediately closes all open connections and open listeners and then returns. Active RPCs are not notified of shutdown. It is used primarily by tests to clean up.

Is that accurate?

[iamqizhao]

no, it is not accurate. It would be

Stop forcefully stops the gRPC server. It immediately closes all open connections and open listeners, and abort all active RPCs, and then returns.

#147 has been opened for graceful shutdown.

[bradfitz]

Your proposed wording update invites more questions: if it immediately closes all open connections, how does it then later abort all active RPCs?

What does aborting mean?

[iamqizhao]

It cancels all active RPCs on server side. It does not notify client (no RST_STREAM sent). The client side pending rpcs will get notified by a connection error.

[bradfitz]

Great. Let's put that in docs.

[iamqizhao]

sure, a PR will be out soon.