oklog/run

A run.Group is a mechanism to orchestrate multiple goroutines as a single unit. You manage lifecycles by adding actors to a zero-value run.Group.

An actor consists of two functions:

1. An execute function: This function runs synchronously within its own goroutine.
2. An interrupt function: This function is called when any actor in the group exits. Its purpose is to signal the execute function to return (e.g., by closing a connection or canceling a context).

When you call Run(), the group concurrently executes all actors. The group waits until the first actor exits, then invokes the interrupt functions for all other actors. Run() only returns to the caller once all actors have fully returned.

You can use run.Group to ensure that a process tied to a context.Context is canceled when the group shuts down. The interrupt function should call the context's cancel function.

ctx, cancel := context.WithCancel(context.Background())
g.Add(func() error {
	return myProcess(ctx, ...)
}, func(error) {
	cancel()
})

When running a network service, use the net.Listener.Close() method in the interrupt function to force the server's ListenAndServe loop to exit.

ln, _ := net.Listen("tcp", ":8080")
g.Add(func() error {
	return http.Serve(ln, nil)
}, func(error) {
	ln.Close()
})

To shut down an http.Server gracefully, use the Shutdown method within the interrupt function. This typically involves creating a context with a timeout to ensure the shutdown process does not hang indefinitely.

httpServer := &http.Server{
	Addr:    "localhost:8080",
	Handler: ...,
}
g.Add(func() error {
	return httpServer.ListenAndServe()
}, func(error) {
	ctx, cancel := context.WithTimeout(context.TODO(), 3*time.Second)
	defer cancel()
	httpServer.Shutdown(ctx)
})

For tasks involving stream processing (like a scanner on a connection), use the Close() method of the io.ReadCloser in the interrupt function to terminate the processing loop.

var conn io.ReadCloser = ...
g.Add(func() error {
	s := bufio.NewScanner(conn)
	for s.Scan() {
		println(s.Text())
	}
	return s.Err()
}, func(error) {
	conn.Close()
})

Use SignalHandler(ctx context.Context, signals ...os.Signal) to create an actor that terminates when the process receives one of the specified signals, or when the parent context is canceled.

• If no signals are provided, the actor terminates on any signal (per signal.Notify behavior).
• If a signal is received, execute returns a SignalError containing the received signal.
• If the context is canceled, execute returns the context error.
• The interrupt function cancels the internal context used by the handler.

When using SignalHandler, if the actor terminates due to a received signal, the execute function returns a SignalError.

Because of the way SignalError is implemented, you should use errors.Is(err, ErrSignal) to check if the error was caused by a signal. Only use errors.As if you specifically need to access the Signal field within the SignalError struct.

The Run method starts all registered actors concurrently.

Behavior:

• If no actors have been added, Run returns nil immediately.
• It blocks until all actors have exited.
• When the first actor returns, Run triggers the interrupt function for all other actors, passing the first actor's error to them.
• It returns the error produced by the first actor that exited.

func (g *Group) Run() error

The SignalError type is returned by SignalHandler when a signal triggers termination. It contains the specific os.Signal that was received.

type SignalError struct {
	Signal os.Signal
}

The ErrSignal variable is the sentinel error used to identify errors returned by SignalHandler when a signal is received. Use errors.Is(err, run.ErrSignal) to detect it.

var ErrSignal = errors.New("signal error")