concurrentloop

README

concurrentloop

concurrentloop provides a function to call a function concurrently powered by generics, channels, and goroutines.

Install

$ go get github.com/thalesfsp/concurrentloop

Specific version

Example: $ go get github.com/thalesfsp/concurrentloop@v1.2.0

Usage

See example_test.go, and concurrentloop_test.go file.

Documentation

Run $ make doc or check out online.

Development

Check out CONTRIBUTION.

Release

1. Update CHANGELOG accordingly.
2. Once changes from MR are merged.
3. Tag and release.

Roadmap

Check out CHANGELOG.

Documentation

Overview

Package concurrentloop provides a function to call a function concurrently powered by generics, channels, and goroutines.

Index

• func ExecuteCh[T any](ctx context.Context, fns []ExecuteFunc[T]) chan ResultCh[T]
• func RemoveZeroValues[T any](removeZeroValues bool, results []T) []T
• type Errors
  • func Execute[T any](ctx context.Context, fns []ExecuteFunc[T]) ([]T, Errors)
  • func Map[T any, Result any](ctx context.Context, sl []T, f MapFunc[T, Result], opts ...Func) ([]Result, Errors)
  • func (e Errors) Error() string
• type ExecuteFunc
• type Func
  • func WithConcurrency(concurrency int) Func
  • func WithLimit(limit int) Func
  • func WithRemoveZeroValues(remove bool) Func
• type MapFunc
• type Option
• type ResultCh

Functions

func ExecuteCh

func ExecuteCh[T any](ctx context.Context, fns []ExecuteFunc[T]) chan ResultCh[T]

ExecuteCh calls the `fns` concurrently.

NOTE: It's the caller's responsibility to close the channel.

func RemoveZeroValues

func RemoveZeroValues[T any](removeZeroValues bool, results []T) []T

RemoveZeroValues removes zero values from the results.

Types

type Errors

type Errors []error

Errors is a slice of errors.

func Execute

func Execute[T any](ctx context.Context, fns []ExecuteFunc[T]) ([]T, Errors)

Execute calls the `fns` concurrently, and returns the results and any errors that occurred. The function blocks until all executions have completed.

NOTE: Order is may preserved.

func Map

func Map[T any, Result any](
	ctx context.Context,
	sl []T,
	f MapFunc[T, Result],
	opts ...Func,
) ([]Result, Errors)

Map concurrently applies a function `f` to each element in the slice `sl` and returns the resulting slice and any errors that occurred. `f` should be of type MapFunc, a function which takes a context and an element of type `T` and returns a result of type `Result` and an error.

The function takes an optional number of `Func` options that allow you to customize the behavior of the function.

If an error occurs during execution of `f`, it is stored and returned along with the results. The order of the results matches the order of the input slice.

If any of the operations are cancelled by the context, the function will panic.

Usage example:

type MyStruct struct { ... }

func process(ctx context.Context, s MyStruct) (ResultType, error) { ... }

sl := []MyStruct{...}
ctx := context.Background()
results, errs := Map(ctx, sl, process)

if errs != nil {
    // handle errors
}

// process results

Note: Because the function executes concurrently, the functions you provide must be safe for concurrent use.

func (Errors) Error

func (e Errors) Error() string

Error returns a string representation of the combined errors in the `Errors` slice, separated by commas. This method satisfies the `error` interface.

type ExecuteFunc

type ExecuteFunc[T any] func(context.Context) (T, error)

ExecuteFunc is the type of the function that will be executed concurrently for each element in a slice of type `T`. The function takes a `context.Context` and a value of type `T`, and returns a value of type `Result` and an error value.

type Func

type Func func(o Option) Option

Func allows to specify message's options.

func WithConcurrency

func WithConcurrency(concurrency int) Func

WithConcurrency sets the concurrency.

func WithLimit

func WithLimit(limit int) Func

WithLimit sets the max amount of results to collect before stopping the loop.

func WithRemoveZeroValues

func WithRemoveZeroValues(remove bool) Func

WithRemoveZeroValues if set to true removes zero values from the results.

type MapFunc

type MapFunc[T any, Result any] func(context.Context, T) (Result, error)

MapFunc is the type of the function that will be executed concurrently for each element in a slice of type `T`. The function takes a `context.Context` and a value of type `T`, and returns a value of type `Result` and an error value.

type Option

type Option struct {
	// Concurrency is the number of concurrent goroutines that will be used.
	Concurrency int

	// The max amount of results to collect before
	Limit int

	// RemoveZeroValues indicates whether to remove zero values from the results.
	RemoveZeroValues bool
}

Option for the concurrent loop.

type ResultCh

type ResultCh[T any] struct {
	Error  error
	Index  int
	Output T
}

ResultCh receives the result from the channel.