Return the cancel function from tools.ContextWithQuitSignals

I was annoyed at documenting the weirdness of how to use it with
context.WithCancel, this way there's no ordering concern and it's all
one line.

You can safely ignore the cancel func most of the time as well because
usually when this context is cancelled the process ends very soon and
the memory will be cleaned up that way.

Author: fsmv

assimilate/embedassimilate/assimilate.go

@@ -56,7 +56,7 @@ func Run(ctx context.Context, flags *flag.FlagSet, args []string) {
 		log.Fatal(err)
 	}
 	var wg sync.WaitGroup
-	ctx = tools.ContextWithQuitSignals(context.Background())
+	ctx, _ = tools.ContextWithQuitSignals(context.Background())
 	errCount := 0
 	for i, requestText := range flags.Args() {
 		registration := &gate.RegisterRequest{}

host/embedhost/host.go

@@ -92,7 +92,7 @@ func Run(ctx context.Context, flags *flag.FlagSet, args []string) {
 	}
 
 	// Setup graceful stopping
-	ctx = tools.ContextWithQuitSignals(context.Background())
+	ctx, _ = tools.ContextWithQuitSignals(context.Background())
 
 	// Register the reverse proxy pattern with portal.
 	// Only blocks until the initial registration is done, then keeps renewing.

portal/gate/example_client_test.go

@@ -18,13 +18,9 @@ var pattern = flag.String("pattern", "/hello/", "The path to register with porta
 func Example() {
 	flag.Parse()
 
-	// Setup graceful stopping
-	//   - Call stop() to trigger a full server graceful shutdown
-	//   - When ctrl+C or other OS quit signals are sent ctx is cancelled
-	//   - If you start other background tasks, use wg.Add(1) and wg.Done() and
-	//     exit when ctx.Done() is closed to participate in the graceful shutdown.
-	ctx, stop := context.WithCancelCause(context.Background())
-	ctx = tools.ContextWithQuitSignals(ctx)
+	// Create a context for the server that will be cancelled when the process is
+	// signalled to exit. You can call stop(nil) to gracefully stop the server.
+	ctx, stop := tools.ContextWithQuitSignals(context.Background())
 
 	// Remove the optional URL prefix from the pattern (http.Handle doesn't understand it)
 	_, path := gate.ParsePattern(*pattern)

spawn/embedspawn/spawn.go

@@ -182,7 +182,7 @@ func Run(ctx context.Context, flagset *flag.FlagSet, args []string) {
 
 	quit := make(chan struct{})
 	tools.CloseOnQuitSignals(quit)
-	ctx = tools.ContextWithQuitSignals(context.Background())
+	ctx, _ = tools.ContextWithQuitSignals(context.Background())
 
 	children := newChildren(quit)
 	go children.MonitorDeaths(quit)

tools/signals.go

@@ -53,23 +53,13 @@ func CloseOnQuitSignals(quit chan struct{}) {
 //
 // Catches: SIGINT, SIGKILL, SIGTERM, SIGHUP
 //
-// To also have a global stop function it's cleanest to do:
-//
-//	ctx, stop := context.WithCancel(context.Background())
-//	ctx = tools.ContextWithQuitSignals(ctx)
-//	defer stop()
-//
-// Since this signals the signal handler goroutine to shutdown and close
-// channels. However it's not a problem to let the runtime exit without
-// signaling this cleanup and do it in one line:
-//
-//	ctx, stop := context.WithCancel(tools.ContextWithQuitSignals(context.Background()))
-//	defer stop()
-func ContextWithQuitSignals(ctx context.Context) context.Context {
+// Canceling this context releases resources associated with it, so code should
+// call cancel as soon as the operations running in this Context complete.
+func ContextWithQuitSignals(ctx context.Context) (context.Context, context.CancelCauseFunc) {
 	ret, cancel := context.WithCancelCause(ctx)
 	go func() {
 		onQuitSignals(ret.Done(), cancel)
 		cancel(context.Cause(ret))
 	}()
-	return ret
+	return ret, cancel
 }