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 ¶
- func Check(ec *Collector, fn func() error)
- func Collect[T any](ec *Collector) func(T, error) T
- func Consume(ctx context.Context, iter *fun.Iterator[error]) error
- func IteratorHook[T any](ec *Collector) fun.Observer[*fun.Iterator[T]]
- func Join(errs ...error) error
- func Recover(ec *Collector)
- func RecoverHook(ec *Collector, hook func())
- func Recovery(ob fun.Observer[error])
- func Safe[T any](ec *Collector, fn func() T) T
- func Stream(ctx context.Context, errCh <-chan error) error
- func When(ec *Collector, cond bool, val any)
- func Whenf(ec *Collector, cond bool, val string, args ...any)
- func WithTime(ec *Collector, err error)
- func Wrap(err error, annotation string) errordeprecated
- func Wrapf(err error, tmpl string, args ...any) errordeprecated
- type Collector
- func (ec *Collector) Add(err error)
- func (ec *Collector) HasErrors() bool
- func (ec *Collector) Iterator() *fun.Iterator[error]
- func (ec *Collector) Len() int
- func (ec *Collector) Observer() fun.Observer[error]
- func (ec *Collector) Producer() fun.Producer[[]error]
- func (ec *Collector) Resolve() error
- type Stack
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Check ¶ added in v0.4.0
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
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{}
size := erc.Collect[int](ec)(actor(Configuration{}))
}
func Consume ¶ added in v0.6.3
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
IteratorHook adds errors to an iterator from a collector when the iterator closes.
func Join ¶ added in v0.10.0
Join takes a slice of errors and converts it into an *erc.Stack typed error.
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 Recovery ¶ added in v0.9.4
Recovery catches a panic, turns it into an error and passes it to the provided observer function.
func Safe ¶ added in v0.2.0
Safe provides similar semantics fun.Safe, but creates an error from the panic value and adds it to the error collector.
func Stream ¶ added in v0.6.1
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
When is a helper function, typcially 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
Whenf conditionally creates and adds an error to the collector, as When, and with a similar use case, but permits Sprintf/Errorf formating.
func WithTime ¶ added in v0.2.0
WithTime adds the error to the collector, only if the error is nil, and annotates that error object with a timestmap using the ers.WithTime helper. Access the timestamp using ers.GetTime()
func Wrap
deprecated
added in
v0.8.0
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
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 (*Collector) HasErrors ¶
HasErrors returns true if there are any underlying errors, and false otherwise.
func (*Collector) Iterator ¶
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
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, the number may not
func (*Collector) Observer ¶ added in v0.10.0
Obesrver returns the collector's Add method as a fun.Observer[error] object for integration and use with the function types.
func (*Collector) Producer ¶ added in v0.10.0
Producer returns a function that is generally equivalent to Collector.Resolve(); however, the errors are returned as an Unwound/Unwrapped slice of errors, rather than the ers.Stack object. Additionally, the producer can return an error if the context is canceled.
type Stack ¶
type Stack struct {
// contains filtered or unexported fields
}
Stack represents the error type returned by an ErrorCollector when it has more than one error. The implementation provides support for errors.Unwrap and errors.Is, and provides an Errors() method which returns a slice of the constituent errors for additional use.
func (*Stack) As ¶ added in v0.2.0
As calls errors.As on the underlying error to provied compatibility with errors.As, which takes advantage of this interface.
func (*Stack) Error ¶
Error produces the aggregated error strings from this method. If the error at the current layer is nil.
func (*Stack) Is ¶
Is calls errors.Is on the underlying error to provied compatibility with errors.Is, which takes advantage of this interface.
func (*Stack) Iterator ¶
Iterator returns an iterator object over the contents of the stack. While the content of the iterator is immutable and will not observe new errors added to the stack, the iterator itself is not safe for concurrent access, and must only be used from one goroutine, or with a synchronized approach. You may create multiple Iterators on the same stack without issue.
Source Files