tweak graceful shutdown example to exit after soft shutdown

[bgentry]

As I was updating the docs to account for #79, I realized I had removed the ability for the graceful shutdown example to cleanly exit if the soft shutdown succeeded. It never will succeed in this example, but for users following the code it seems worth accounting for it with the flow.

This gets a little wonky with the logic and the structuring in a single goroutine, but I think this is correct:

• If we have a non-nil error that's not a context cancellation or timeout, panic because that shouldn't happen.
• If we have a nil error, return immediately because that means shutdown was successful.
• Otherwise, carry on because soft shutdown was not successful and we're going to need to try a hard shutdown.

[bgentry]

@brandur on a related note, prior to release we removed an API on Client exposing the channel for shutdown done. Looking at the example code, I'm wondering if we should add that back? It increases surface area slightly, but also makes using it easier because you no longer need to allocate a new channel to indicate when shutdown is complete.

[brandur]

@brandur on a related note, prior to release we removed an API on Client exposing the channel for shutdown done. Looking at the example code, I'm wondering if we should add that back? It increases surface area slightly, but also makes using it easier because you no longer need to allocate a new channel to indicate when shutdown is complete.

Wait ... did this revert the blocks-until-stop semantics of Stop? If so, I think we need to do some more work here.

[bgentry]

The stop methods as of #79 block until shutdown is complete or the user-provided context is cancelled/timed out. I’m fairly sure that’s what #78 was asking for and it seems like the correct behavior to me (what’s the point of that context otherwise, and it simplifies control flow to not have them block on a cancelled context per the shortened examples).

Can you elaborate on what more work you’re imagining?

My comment above was about the fact that the shutdown examples still need to allocate a channel that’s used to determine when shutdown is complete. River already has such a channel internally so it would simplify usage and shorten these examples if it was re-exposed.

[brandur]

Talked over Slack, and I think we're roughly on the same page with this. The new channel wouldn't be required per se, but provided to simplify the graceful shutdown code somewhat. After thinking about it a little more, seems okay to me.

I'd vote we call a new channel Stopped instead of Done just so it fits in more nicely in the function list next to Stop and is easy to find.