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, ec *Collector, iter *fun.Iterator[error])
- func IteratorHook[T any](ec *Collector) fun.Handler[*fun.Iterator[T]]
- func Recover(ec *Collector)
- func RecoverHook(ec *Collector, hook func())
- func Stream(ctx context.Context, ec *Collector, errCh <-chan error)
- func When(ec *Collector, cond bool, val any)
- func Whenf(ec *Collector, cond bool, val string, args ...any)
- func WithRecoverCall(ec *Collector, fn func())
- func WithRecoverDo[T any](ec *Collector, fn func() T) T
- func WithTime(ec *Collector, err error)deprecated
- 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) Future() fun.Future[error]
- func (ec *Collector) Handler() fun.Handler[error]
- func (ec *Collector) HasErrors() bool
- func (ec *Collector) Iterator() *fun.Iterator[error]
- func (ec *Collector) Len() int
- func (ec *Collector) Ok() bool
- func (ec *Collector) Resolve() error
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{}
resolveSize := erc.Collect[int](ec)
size := resolveSize(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 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
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, 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
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
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
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
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 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) Future ¶ added in v0.10.4
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
Obesrver returns the collector's Add method as a fun.Handler[error] object for integration and use with the function types.
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, Len is not updated beyond the current level. In this way Len really reports "height," but this is the same for the top level.
Source Files