rungroup

README

rungroup

Rungroup provides a way to group the lifecycle of goroutines together. See godoc for all the documentation.

This project is released under GNU Affero General Public License v3.0, see LICENCE file in this repo for more info.

Documentation

Overview

Package rungroup allows goroutines to share the same lifecycle.

Like https://pkg.go.dev/golang.org/x/sync/errgroup, rungroup allows to create a handler that allows to run given functions in parallel with goroutines. It tries to be as close to the interface of errgroup but handles the cancelation of its routines and treatment of errors differently.

Differences to errgroup

Goroutine function gets a context as first argument, a new group does not get handled to the caller with the groups context. By default all routines get canceled as soon as one routine return, regardless if the error is nil or not. This can be overridden per routine. errgroup only cancels on the first non nil error. All non nil errors are returned to the creator of the group. errgroup only returns the first error and drops the rest.

Index

• func NeverCancel(o *optionSet)
• func NoCancelOnSuccess(o *optionSet)
• type Error
  • func (e Error) Error() string
• type Function
• type Group
  • func New(ctx context.Context) *Group
  • func (g *Group) Go(fnc Function, opts ...Option)
  • func (g *Group) Wait() error
• type Option

Examples

• Group

Functions

func NeverCancel

func NeverCancel(o *optionSet)

NeverCancel prevents goroutines spawned with Group.Go to cancel the group context in any case. Default is to cancel the group context on return regardless of the returned error.

func NoCancelOnSuccess

func NoCancelOnSuccess(o *optionSet)

NoCancelOnSuccess prevents goroutines spawned with Group.Go to cancel the group context when they return a non nil error. Default is to cancel the group context on return regardless of the returned error.

Types

type Error

type Error struct {
	Errs []error
}

Error wraps multiple errors into one error instance. It does not support unwrapping since the current interface design of Go allows only for one child of an error to be unwrapped. If you need to know the concrete types please go over Errs manually.

func (Error) Error

func (e Error) Error() string

type Function

type Function func(context.Context) error

Function specifies the signature of functions that can be run via the group.

type Group

type Group struct {
	// contains filtered or unexported fields
}

Group represents a set of goroutines which lifecycles are bound to each other.

Example

package main

import (
	"context"
	"errors"
	"fmt"

	"eqrx.net/rungroup"
)

var (
	ErrEgg     = errors.New("the egg came first")
	ErrChicken = errors.New("the chicken came first")
)

func main() {
	// Create a new group instance. Normally you would you current in here so the group gets canceled when it does.
	group := rungroup.New(context.Background())

	// This routine immediately return without error and causes the group context to be cancelled.
	// Since the error is nil it will not be added to the error list.
	group.Go(func(c context.Context) error { return nil })

	// Routine returns immediately with an error: The group gets cancelled and the error gets added to the list.
	group.Go(func(c context.Context) error { return ErrEgg })

	// Return immediately but do not cancel other routines. This is done by not returning an error
	// and starting with rungroup.NoCancelOnSucess set.
	group.Go(func(c context.Context) error { return nil }, rungroup.NoCancelOnSuccess)

	// When a routine returns with an error the context will be canceled,
	// regardless if rungroup.NoCancelOnSucess is set or not.
	group.Go(func(c context.Context) error { return ErrChicken }, rungroup.NoCancelOnSuccess)

	// Wait until the context of the group is canceled and return the context error.
	// Since the context is already done returning from here will not affect the context,
	// the error is stored though.
	group.Go(func(ctx context.Context) error {
		<-ctx.Done()

		fmt.Println("the question has been answered!")

		return nil
	})

	// Wait for all routines to finish and get all errors in a bundle. This bundled error does have a Unwrap method
	// since Go wrapping only supports for unwrap a single error and the code can't decide for you which one is the
	// most relevant. In case you want to handle all returned errors you may iterate over them. If you print or wrap
	// it, all wrapped errors will be printed.
	//
	// ... and yes, this chicken-egg-solver heavily favours the egg.
	if err := group.Wait(); err != nil {
		fmt.Printf("the error group failed: %v", err)
	}
}

func New

func New(ctx context.Context) *Group

New creates group for goroutine management. The context passed as parameter ctx with be taken as parent for the group context. Canceling it will cancel all spawned goroutines. ctx must not be nil.

func (*Group) Go

func (g *Group) Go(fnc Function, opts ...Option)

Go spawns a goroutine and calls the function fnc with it. The context of the group is passed as the first argument to it.

When any routine spawned by Go return, the following things happen: Panics are not recovered. If the returned error value of fnc is non nil it is stored for retrieval by Wait. Depending on the given options the group context is on returned depending of the error. Default options cause the context always to be canceled.

As long as no call from Wait has returned, Go may be called by any goroutines at the same time. Passing nil as fnc or part of opts is not allowed.

func (*Group) Wait

func (g *Group) Wait() error

Wait block until all goroutines of the group have returned to it and returns *Error if any error was returned returned by the routines. This method must not be called by multiple goroutines at the same time. After this call returnes, the group may not be reused.

type Option

type Option func(o *optionSet)

Option modifies the settings of a spawned routine with Group.Go.