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 CheckCtx(ctx context.Context, ec *Collector, fn func(context.Context) error)
- func CheckWait(ec *Collector, fn fun.WorkerFunc) fun.WaitFunc
- func CheckWhen(ec *Collector, cond bool, fn func() error)
- func Collapse(errs ...error) error
- func CollapseFrom(ec *Collector, errs []error)
- func CollapseInto(ec *Collector, errs ...error)
- func Collect[T any](ec *Collector) func(T, error) T
- func Consume(ctx context.Context, iter fun.Iterator[error]) error
- func ConsumeAll(ec *Collector, iter fun.Iterator[error]) fun.WaitFunc
- func ConsumeProcess(ctx context.Context, ec *Collector, iter fun.Iterator[error]) fun.WaitFunc
- func ContextExpired(err error) bool
- func GetTime(err error) time.Time
- func Merge(err1, err2 error) error
- func Recover(ec *Collector)
- func RecoverHook(ec *Collector, hook func())
- func Safe[T any](ec *Collector, fn func() T) T
- func Stream(ctx context.Context, errCh <-chan error) error
- func StreamAll(ec *Collector, errCh <-chan error) fun.WaitFunc
- func StreamOne(ec *Collector, errCh <-chan error) fun.WaitFunc
- func StreamProcess(ctx context.Context, ec *Collector, errCh <-chan error) fun.WaitFunc
- func Time(err error) error
- func Unwind(err 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) error
- func Wrapf(err error, tmpl string, args ...any) error
- type Collector
- 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 CheckCtx ¶
CheckCtx executes a simple function that takes a context and if it returns an error, adds it to the collector, primarily for use in defer statements.
func CheckWait ¶ added in v0.7.0
func CheckWait(ec *Collector, fn fun.WorkerFunc) fun.WaitFunc
CheckWait returns a fun.WaitFunc for a function that returns an error, with the error consumed by the collector.
func CheckWhen ¶ added in v0.8.4
CheckWhen executes a simple function and if it returns an error, adds it to the collector, primarily for use in defer statements.
func Collapse ¶ added in v0.6.1
Collapse takes a slice of errors and converts it into an *erc.Stack typed error.
func CollapseFrom ¶ added in v0.6.1
CollapseFrom is a helper that adds a slice of errors to the provided Collector.
func CollapseInto ¶ added in v0.6.1
CollapseInto is a helper that has the same semantics and calling pattern as Collapse, but collapses those errors into the provided Collector.
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 fun.Must 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.
func ConsumeAll ¶ added in v0.6.3
ConsumeAll adds all errors in the input iterator and returns a wait function that blocks until the iterator is exhausted. ConsumeAll does not begin processing the iterator until the wait function is called.
func ConsumeProcess ¶ added in v0.6.3
ConsumeProcess adds all errors in the iterator to the provided collector and returns a wait function that blocks until the iterator has been exhausted. This error processing work happens in a different go routine, and the fun.WaitFunc blocks until this goroutine has returned.
func ContextExpired ¶ added in v0.2.0
ContextExpired checks an error to see if it, or any of it's parent contexts signal that a context has expired. This covers both canceled contexts and ones which have exceeded their deadlines.
func GetTime ¶ added in v0.2.0
GetTime unwraps the error looking for an error type that implements the timestamp interface:
interface{ Time() time.Time }
and, if so returns the output of that method. Otherwise, GetTime returns a zeroed time object. Any Error implementation can implement this interface, though the Timestamp type provides a basic implementation.
func Merge ¶ added in v0.6.1
Merge produces a single error from two input errors. The output error behaves correctly for errors.Is and errors.As and Unwrap() calls, for both errors, checked in order.
If both errors are of the same root type and you investigate the output error with errors.As, the first error's value will be used.
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 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.
func StreamAll ¶ added in v0.6.3
StreamAll collects all errors from an error channel and adds them to the provided collector. StreamAll returns a fun.WaitFunc that blocks the error channel is closed or its context is canceled.
func StreamOne ¶ added in v0.6.3
StreamOne returns a fun.WaitFunc that blocks until a single error is set to the error channel and adds that to the collector.
func StreamProcess ¶ added in v0.6.1
StreamProcess is a non-blocking helper that starts a background goroutine to process the contents of an error channel. The function returned will block until the channel is closed or the context is canceled and can be used to wait for the background operation to be complete.
func Time ¶ added in v0.2.0
Time wraps an error with a timestamp implementation. The output of time.Now will be captured when Time returns, and can be accessed via the GetTime method or using the '%+v' formatting argument.
The Timestamp errors, correctly supports errors.Is and errors.As, passing through to the wrapped error.
func Unwind ¶ added in v0.4.0
Unwind converts an error into a slice of errors in two cases: First, if an error is an *erc.Stack, Unwind will return a slice with all constituent errors. Second, if the error is wrapped, Unwind will unwrap the error object adding every intermediate error.
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 the Timestamp type implemented in this package.
func Wrap ¶ 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.
func Wrapf ¶ 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.
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. While the iterator isn't safe for current access from multiple go routines, the sequence of errors stored are not modified after creation.
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