async

Documentation

Overview

Package async provides functionality for working with async operations.

Index

• type Group
  • func (g *Group[T]) Queue(f func(context.Context) (T, error))
  • func (g *Group[T]) SetCancelOnError(b bool)
  • func (g *Group[T]) SetLocking(enabled bool)
  • func (g *Group[T]) SetMaxGoroutines(n int)
  • func (g *Group[T]) SetTimeout(d time.Duration)
  • func (g *Group[T]) Wait(ctx context.Context) ([]T, error)
  • func (g *Group[T]) WaitLax(ctx context.Context) []Result[T]
• type Result

Examples

• Group (Parallel)

Types

type Group

type Group[T any] struct {
	// contains filtered or unexported fields
}

Group is used to manage a group of goroutines that are concurrently running sub-operations that are part of the same overall operation.

A zero value Group is a valid Group that has no max goroutines, does not cancel on error, and has no timeout.

A Group can be reused after a call to Wait.

A Group must not be copied after first use.

Example (Parallel)

Parallel illustrates the use of a Group for synchronizing a simple parallel operation.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cszatmary/goutils/async"
)

func main() {
	updateService := func(_ context.Context, service string) (string, error) {
		return fmt.Sprintf("service %s updated", service), nil
	}

	services := []string{"A", "B", "C"}
	var g async.Group[string]
	for _, s := range services {
		s := s // https://golang.org/doc/faq#closures_and_goroutines
		g.Queue(func(ctx context.Context) (string, error) {
			return updateService(ctx, s)
		})
	}
	results, err := g.Wait(context.TODO())
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		return
	}
	for _, result := range results {
		fmt.Println(result)
	}

}

Output:

service A updated
service B updated
service C updated

func (*Group[T]) Queue

func (g *Group[T]) Queue(f func(context.Context) (T, error))

Queue queues a function to be run in a goroutine. Once all desired functions have been queued, execute them by calling Wait.

func (*Group[T]) SetCancelOnError

func (g *Group[T]) SetCancelOnError(b bool)

SetCancelOnError determines how the Group should behave if a goroutine results in an error.

If the value is true, all running goroutines will be cancelled and the first error will be returned by Wait.

If the value is false, all other running goroutines will continue and will return an errors.List containing any errors from each function.

func (*Group[T]) SetLocking

func (g *Group[T]) SetLocking(enabled bool)

SetLocking controls if a lock should be used on Group methods.

By default Group uses locking to ensure that it is safe to use across multiple goroutines. However, if the Group is only be used on a single goroutine this can be unnecessary overhead. By passing false the locking can be disabled.

func (*Group[T]) SetMaxGoroutines

func (g *Group[T]) SetMaxGoroutines(n int)

SetMaxGoroutines sets the max number of active goroutines that are allowed. If the value is zero or negative, there will be no limit on the number of active goroutines.

func (*Group[T]) SetTimeout

func (g *Group[T]) SetTimeout(d time.Duration)

Timeout sets a timeout after which any running goroutines will be cancelled. If the value is zero or negative, no timeout will be set.

func (*Group[T]) Wait

func (g *Group[T]) Wait(ctx context.Context) ([]T, error)

Wait executes all the queued functions, each of them in their own goroutines, and waits for them to complete. It then returns a list of results and any errors that occurred.

The returned results will be in the same order that calls to Queue were made. If an error occurred, the result slice will be nil.

If the Group was configured to cancel on the first error, if a goroutine errors all others will be cancelled and the returned error will be the first error that occurred. Otherwise, all goroutines will run to completion, and the returned error will be an errors.List containing each error. The errors will not be in any particular order.

func (*Group[T]) WaitLax

func (g *Group[T]) WaitLax(ctx context.Context) []Result[T]

WaitLax is similar to Wait but returns a slice of Result values containing the returned value and error, if any, from each goroutine. This can be useful if you wish to get a list of partial results and errors associated with each goroutine.

The CancelOnError option does not apply to WaitLax, since it will always wait for all goroutines and return all results.

type Result

type Result[T any] struct {
	// Value is the value returned from the goroutine.
	Value T
	// Err is the error returned from the goroutine. If no error occurred it will be nil.
	Err error
	// contains filtered or unexported fields
}

Result contains the result of a goroutine that was ran. It is returned by Group.WaitLax.