base: github.com/grailbio/base/errors Index | Files

package errors

import "github.com/grailbio/base/errors"

Package errors implements an error type that defines standard interpretable error codes for common error conditions. Errors also contain interpretable severities, so that error-producing operations can be retried in consistent ways. Errors returned by this package can also be chained: thus attributing one error to another. It is inspired by the error packages of both the Upspin and Reflow projects, but generalizes and simplifies these.

Errors are safely serialized with Gob, and can thus retain semantics across process boundaries.

TODO(marius): standardize translating AWS errors into *errors.Error.

Index

Package Files

errors.go once.go

Variables

var Separator = ":\n\t"

Separator defines the separation string inserted between chained errors in error messages.

func E Uses

func E(args ...interface{}) error

E constructs a new errors from the provided arguments. It is meant as a convenient way to construct, annotate, and wrap errors.

Arguments are interpreted according to their types:

- Kind: sets the Error's kind
- Severity: set the Error's severity
- string: sets the Error's message; multiple strings are
  separated by a single space
- *Error: copies the error and sets the error's cause
- error: sets the Error's cause

If an unrecognized argument type is encountered, an error with kind Invalid is returned.

If a kind is not provided, but an underlying error is, E attempts to interpret the underlying error according to a set of conventions, in order:

- If the os.IsNotExist(error) returns true, its kind is set to NotExist.
- If the error is context.Canceled, its kind is set to Canceled.
- If the error implements interface { Timeout() bool } and
Timeout() returns true, then its kind is set to Timeout
- If the error implements interface { Temporary() bool } and
Temporary() returns true, then its severity is set to at least
Temporary.

If the underlying error is another *Error, and a kind is not provided, the returned error inherits that error's kind.

func Is Uses

func Is(kind Kind, err error) bool

Is tells whether an error has a specified kind, except for the indeterminate kind Other. In the case an error has kind Other, the chain is traversed until a non-Other error is encountered.

func IsTemporary Uses

func IsTemporary(err error) bool

IsTemporary tells whether the provided error is likely temporary.

func Match Uses

func Match(err1, err2 error) bool

Match tells whether every nonempty field in err1 matches the corresponding fields in err2. The comparison recurses on chained errors. Match is designed to aid in testing errors.

func New Uses

func New(msg string) error

New is synonymous with errors.New, and is provided here so that users need only import one errors package.

func Visit Uses

func Visit(err error, callback func(err error))

Visit calls the given function for every error object in the chain, including itself. Recursion stops after the function finds an error object of type other than *Error.

type Error Uses

type Error struct {
    // Kind is the error's type.
    Kind Kind
    // Severity is an optional severity.
    Severity Severity
    // Message is an optional error message associated with this error.
    Message string
    // Err is the error that caused this error, if any.
    // Errors can form chains through Err: the full chain is printed
    // by Error().
    Err error
}

Error is the standard error type, carrying a kind (error code), message (error message), and potentially an underlying error. Errors should be constructed by errors.E, which interprets arguments according to a set of rules.

Errors may be serialized and deserialized with gob. When this is done, underlying errors do not survive in full fidelity: they are converted to their error strings and returned as opaque errors.

func Recover Uses

func Recover(err error) *Error

Recover recovers any error into an *Error. If the passed-in Error is already an error, it is simply returned; otherwise it is wrapped in an error.

func (*Error) Error Uses

func (e *Error) Error() string

Error returns a human readable string describing this error. It uses the separator defined by errors.Separator.

func (*Error) GobDecode Uses

func (e *Error) GobDecode(p []byte) error

GobDecode decodes an error encoded by GobEncode.

func (*Error) GobEncode Uses

func (e *Error) GobEncode() ([]byte, error)

GobEncode encodes the error for gob. Since underlying errors may be interfaces unknown to gob, Error's gob encoding replaces these with error strings.

func (*Error) Temporary Uses

func (e *Error) Temporary() bool

Temporary tells whether this error is temporary.

func (*Error) Timeout Uses

func (e *Error) Timeout() bool

Timeout tells whether this error is a timeout error.

type Kind Uses

type Kind int

Kind defines the type of error. Kinds are semantically meaningful, and may be interpreted by the receiver of an error (e.g., to determine whether an operation should be retried).

const (
    // Other indicates an unknown error.
    Other Kind = iota
    // Canceled indicates a context cancellation.
    Canceled
    // Timeout indicates an operation time out.
    Timeout
    // NotExist indicates a nonexistent resources.
    NotExist
    // NotAllowed indicates a permission failure.
    NotAllowed
    // NotSupported indicates an unsupported operation.
    NotSupported
    // Exists indicates that a resource already exists.
    Exists
    // Integrity indicates an integrity failure.
    Integrity
    // Unavailable indicates that a resource was unavailable.
    Unavailable
    // Invalid indicates that the caller supplied invalid parameters.
    Invalid
    // Net indicates a network error.
    Net
    // TooManyTries indicates a retry budget was exhausted.
    TooManyTries
    // Precondition indicates that a precondition was not met.
    Precondition
    // OOM indicates that an OOM condition was encountered.
    OOM
    // Remote indicates an error returned by an RPC, as distinct from errors in
    // the machinery to execute the RPC, e.g. network issues, machine health,
    // etc.
    Remote
)

func (Kind) String Uses

func (k Kind) String() string

String returns a human-readable explanation of the error kind k.

type Once Uses

type Once struct {
    // Ignored is a list of errors that will be dropped in Set(). Ignored
    // typically includes io.EOF.
    Ignored []error
    // contains filtered or unexported fields
}

Once captures at most one error. Errors are safely set across multiple goroutines.

A zero Once is ready to use.

Example:

var e errors.Once
e.Set(errors.New("test error 0"))

func (*Once) Err Uses

func (e *Once) Err() error

Err returns the first non-nil error passed to Set. Calling Err is cheap (~1ns).

func (*Once) Set Uses

func (e *Once) Set(err error)

Set sets this instance's error to err. Only the first error is set; subsequent calls are ignored.

type Severity Uses

type Severity int

Severity defines an Error's severity. An Error's severity determines whether an error-producing operation may be retried or not.

const (
    // Retriable indicates that the failing operation can be safely retried,
    // regardless of application context.
    Retriable Severity = -2
    // Temporary indicates that the underlying error condition is likely
    // temporary, and can be possibly be retried. However, such errors
    // should be retried in an application specific context.
    Temporary Severity = -1
    // Unknown indicates the error's severity is unknown. This is the default
    // severity level.
    Unknown Severity = 0
    // Fatal indicates that the underlying error condition is unrecoverable;
    // retrying is unlikely to help.
    Fatal Severity = 1
)

func (Severity) String Uses

func (s Severity) String() string

String returns a human-readable explanation of the error severity s.

Package errors imports 12 packages (graph) and is imported by 32 packages. Updated 2019-10-16. Refresh now. Tools for package owners.