erc

package
v0.10.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 14, 2024 License: Apache-2.0 Imports: 5 Imported by: 46

Documentation

Overview

Package erc provides a simple/fast error aggregation tool for collecting and aggregating errors. The tools are compatible with go's native error wrapping, and are generally safe for use from multiple goroutines, so can simplify error collection patterns in worker-pool patterns.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Check added in v0.4.0

func Check(ec *Collector, fn func() error)

Check executes a simple function and if it returns an error, adds it to the collector, primarily for use in defer statements.

func Collect added in v0.8.4

func Collect[T any](ec *Collector) func(T, error) T

Collect produces a function that will collect the error from a function and add it to the collector returning the result. Use this, like risky.Force to delay handling an error while also avoiding declaring an extra error variable, without dropping the error entirely.

For example:

func actor(conf Configuration) (int, error) { return 42, nil}

func main() {
    ec := &erc.Collector{}
    resolveSize := erc.Collect[int](ec)
    size := resolveSize(actor(Configuration{}))
}

func Consume added in v0.6.3

func Consume(ctx context.Context, ec *Collector, iter *fun.Iterator[error])

Consume iterates through all errors in the fun.Iterator and returning the aggregated (*erc.Stack) error for these errors.

Because Consume() is a fun.ProcessFunc you can convert this into fun.Worker and fun.Operation objects as needed.

func IteratorHook added in v0.10.0

func IteratorHook[T any](ec *Collector) fun.Handler[*fun.Iterator[T]]

IteratorHook adds errors to an iterator from a collector when the iterator closes.

func Recover

func Recover(ec *Collector)

Recover calls the builtin recover() function and converts it to an error that is populated in the collector. Run RecoverHook in defer statements.

func RecoverHook added in v0.2.0

func RecoverHook(ec *Collector, hook func())

RecoverHook runs adds the output of recover() to the error collector, and runs the specified hook if. If there was no panic, this function is a noop. Run RecoverHook in defer statements.

func Stream added in v0.6.1

func Stream(ctx context.Context, ec *Collector, errCh <-chan error)

Stream collects all errors from an error channel, and returns the aggregated error. Stream blocks until the context expires (but does not add a context cancellation error) or the error channel is closed.

Because Stream() is a fun.ProcessFunc you can convert this into fun.Worker and fun.Operation objects as needed.

func When added in v0.2.0

func When(ec *Collector, cond bool, val any)

When is a helper function, typically useful for improving the readability of validation code. If the condition is true, then When creates an error with the string value and adds it to the Collector.

func Whenf added in v0.2.0

func Whenf(ec *Collector, cond bool, val string, args ...any)

Whenf conditionally creates and adds an error to the collector, as When, and with a similar use case, but permits Sprintf/Errorf formating.

func WithRecoverCall added in v0.10.5

func WithRecoverCall(ec *Collector, fn func())

WithRecoverCall calls the provided function and returns its output to the caller.

func WithRecoverDo added in v0.10.5

func WithRecoverDo[T any](ec *Collector, fn func() T) T

WithRecoverDo runs the provided function, and catches a panic, if necessary and adds that panic to the collector. If there is no panic, The return value is the return value of the provided function.

func WithTime deprecated added in v0.2.0

func WithTime(ec *Collector, err error)

WithTime adds the error to the collector, only if the error is nil, and annotates that error object with a timestamp using the ers.WithTime helper. Access the timestamp using ers.GetTime()

Deprecated: Use ers.WithTime instead. Non-collector helper functions and types were moved to ers from erc.

func Wrap deprecated added in v0.8.0

func Wrap(err error, annotation string) error

Wrap produces a wrapped error if the err is non-nil, wrapping the error with the provided annotation. When the error is nil, Wrap returns nil.

This, roughly mirrors the usage "github/pkg/errors.Wrap" but taking advantage of newer standard library error wrapping.

Deprecated: Use ers.Wrap instead. Non-collector helper functions and types were moved to ers from erc.

func Wrapf deprecated added in v0.8.0

func Wrapf(err error, tmpl string, args ...any) error

Wrapf produces a wrapped error, if the error is non-nil, with a formated wrap annotation. When the error is nil, Wrapf does not build an error and returns nil.

This, roughly mirrors the usage "github/pkg/errors.Wrapf" but taking advantage of newer standard library error wrapping.

Deprecated: Use ers.Wrapf instead. Non-collector helper functions and types were moved to ers from erc.

Types

type Collector

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

Collector is a simplified version of the error collector in github.com/tychoish/emt. The collector is thread safe and aggregates errors which can be resolved as a single error. The constituent errors (and flattened, in the case of wrapped errors), are an *erc.Stack object, which can be introspected as needed.

func New added in v0.10.4

func New() *Collector

New constructs an empty Collector. Collectors can be used without any special construction, but this function is shorter.

func (*Collector) Add

func (ec *Collector) Add(err error)

Add collects an error if that error is non-nil.

func (*Collector) Future added in v0.10.4

func (ec *Collector) Future() fun.Future[error]

Future returns a function that is generally equivalent to Collector.Resolve(); however, the errors are returned as an unwound slice of errors, rather than the ers.Stack object.

func (*Collector) Handler added in v0.10.2

func (ec *Collector) Handler() fun.Handler[error]

Obesrver returns the collector's Add method as a fun.Handler[error] object for integration and use with the function types.

func (*Collector) HasErrors

func (ec *Collector) HasErrors() bool

HasErrors returns true if there are any underlying errors, and false otherwise.

func (*Collector) Iterator

func (ec *Collector) Iterator() *fun.Iterator[error]

Iterator produces an iterator for all errors present in the collector. The iterator proceeds from the current error to the oldest error, and will not observe new errors added to the collector.

func (*Collector) Len added in v0.10.0

func (ec *Collector) Len() int

Len reports on the total number of non-nil errors collected. The count tracks a cached size of the *erc.Stack, giving Len() stable performance characteristics; however, because the Collector unwrap and merge Stack and other { Unwrap() []error } errors, Len is not updated beyond the current level. In this way Len really reports "height," but this is the same for the top level.

func (*Collector) Ok added in v0.10.9

func (ec *Collector) Ok() bool

Ok returns true if there are any underlying errors, and false otherwise.

func (*Collector) Resolve

func (ec *Collector) Resolve() error

Resolve returns an error of type *erc.Stack, or nil if there have been no errors added. The error stack respects errors.Is and errors.As, and can be iterated or used in combination with ers.Unwind() to introspect the available errors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL