group

README

group

In server applications you often have multiple long running goroutines that depend on each other, such as storage, a business model and a web server. When one of them fails the others usually can't continue to work, so it would be better to stop the whole program to have a human investigate. With group this is easy to do:

err := group.Run(
  createStorageActor(),
  createModelActor(),
  createServerActor(),
  createInterruptActor(),
)
if err != nil {
  log.Fatal(err)
}

You create actors for the different parts of your program. An actor describes how to run a task and how to interrupt it. You can create an actor with group.New():

func New(execute func() error, interrupt func()) Actor

When you pass actors to group.Run() each actor's execute will be run in its own goroutine. Once one actor returns, all other actors are interrupted. group.Run() then returns the error of the actor that caused the others to be interrupted.

Helper methods

There are a couple of helper methods for creating actors. These are useful if you are using context.Context or a channel to interrupt your goroutines:

func WithContext(ctx context.Context, execute func(context.Context) error) Actor
func WithChannel(execute func(<-chan struct{}) error) Actor

The interrupt methods are automatically added to the actors.

There is also group.Done(error) which returns an actor that immediately returs the given error. This can be useful if you have a problem while creating an actor and have no other way of signalling this error to the calling code.

Documentation

Index

• func Run(actors ...Actor) error
• type Actor
  • func Done(result error) Actor
  • func New(execute func() error, interrupt func()) Actor
  • func WithChannel(execute func(<-chan struct{}) error) Actor
  • func WithContext(ctx context.Context, execute func(context.Context) error) Actor

Functions

func Run

func Run(actors ...Actor) error

Run starts all actors and waits for the first one to finish. Once one actor has returned the others are interrupted. Run then waits for all actors to finish.

Run returns the error of the first actor to finish. If that actor returns nil, then Run will also return nil, even if other actors return a non-nil error.

If Run is called without any actors it will return nil immediately.

Types

type Actor

type Actor interface {
	// Execute runs some computation.
	Execute() error
	// Interrupt stops the actor. Interrupt should not wait for Execute to
	// return and it must be safe to be called multiple times.
	Interrupt()
}

Actor represents a long running task that can be interrupted.

func Done

func Done(result error) Actor

Done returns an actor that immediately returs the given result when executed. This can be used when there is a problem setting up an actor to get the error to the function calling Run.

func New

func New(execute func() error, interrupt func()) Actor

New allows easy creation of an actor from two functions.

func WithChannel

func WithChannel(execute func(<-chan struct{}) error) Actor

WithChannel creates an actor from a function that takes a channel. When the actor is interrupted the channel given to the function is closed.

func WithContext

func WithContext(ctx context.Context, execute func(context.Context) error) Actor

WithContext creates an actor from a context and a function that takes a context.