os/signal: add NotifyContext function

[henvic]

As previously discussed on issues such as #21521 and #16472, or on several other places handling POSIX signals through context seems to be somewhat useful (and a little bit hard to do correctly?), and I would like to propose a way to handle it by adding a new signal.WithContext function.

There's also an idea to improve the current approach to handling signals (see #21521 (comment)). I didn't give it a try yet, unfortunately. I only found the earlier proposals here after trying to write some code, so I decided to create this new issue anyway to share my idea.

People using some sort of it or talking about the subject:

• https://github.com/henvic/ctxsignal (package I wrote a while ago)
• https://twitter.com/dmitshur/status/1227777318162030592 (thread)
• https://twitter.com/matryer/status/869096368039710720 (thread)
• Make Ctrl+C cancel the context.Context (blog post)
• oklog/run@9c53bcd
• https://github.com/FiloSottile/mostly-harmless/blob/22c6a9e08ad95b602b470652ad2d401d8750e264/covfefe/covfefe.go#L118-L139
• https://github.com/shurcooL/home/blob/d0f5a32e4901b05ae9979b1a9e7b67caba549778/main.go#L61-L73
• https://github.com/search?l=Go&p=1&q=context+signal&type=Repositories lists 18 other packages for the same thing.

[gopherbot]

Change https://golang.org/cl/219640 mentions this issue: os/signal: add WithContext to control single usage signals easily.

[henvic]

Also please notice that this change would, unfortunately, require introducing packages time and context as dependencies for package os/signal.

[ianlancetaylor]

Could you describe the new function in this issue, so that we don't have to figure it out from the CL? Thanks.

[henvic]

The new function receives a parent context and a variadic number of signals that can be used to cancel this context. When a parent context is canceled or when one of the signals is handled, the context is canceled.

Example of handling cancelation of a slow process through SIGTERM and SIGINT:

func main() {
	ctx, cancel := signal.WithContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
	defer cancel()

	// ...
	slow.Run(ctx)
	cancel()

	// to verify if the slow function was terminated by a signal, we can use:
	var sigErr signal.ContextError
	if errors.As(ctx.Err(), &sigErr) {
		fmt.Printf("slow function terminated by signal %q\n")
	}
}

On another side, we have the example shown for https://golang.org/pkg/net/http/#Server.Shutdown that, in my opinion, would not be simplified by this.

[robpike]

Perhaps this should be a function of the context package instead, since it creates a context and it's pretty much all about contexts.

ctx, cancel := context.Signal(context.Background(), syscall.SIGTERM, syscall.SIGINT)

Not sure it's the right idea at all, just throwing it out there.

[mattn]

If several packages handle same signal, and runtime does not handle those contexts equally, context.Signal won't work correctly, I think. If runtime does not handle them, context.Signals is not best way . The os/signal package has the potential feeling for us that it is only used in applications, but the context package is used by everyone. So I'm thinking signal.WithContext is better since it make users known that we should do it in only one place. (But I'm also not sure this is right idea)

[rsc]

To be clear, the runtime does already broadcast signals to anyone who has signed up to hear about them, using signal.Notify. So this could be done as a separate package without worrying about other possible uses of os/signal.

context.WithCancelSignal seems like the clearest name, and it would appear right next to context.WithCancel in the docs.

/cc @Sajmani for thoughts

[rsc]

It sounds like maybe we have converged on context.WithCancelSignal. I've retitled.
Based on the discussion above, this seems like a likely accept.

[henvic]

Great! Thanks for the feedback. I'll try to send a new CL proposing an implementation for a context.WithCancelSignal command Monday.