Skip to content
Snippets Groups Projects
Select Git revision
  • 5f2212da202ed2d4221b94b5f3954f1aa700ef7d
  • without_tipselection default
  • develop protected
  • fix/grafana-local-dashboard
  • wasp
  • fix/dashboard-explorer-freeze
  • master
  • feat/timerqueue
  • test/sync_debug_and_650
  • feat/sync_revamp_inv
  • wip/sync
  • tool/db-recovery
  • portcheck/fix
  • fix/synchronization
  • feat/new-dashboard-analysis
  • feat/refactored-analysis-dashboard
  • feat/new-analysis-dashboard
  • test/demo-prometheus-fpc
  • prometheus_metrics
  • wip/analysis-server
  • merge/fpc-test-value-transfer
  • v0.2.2
  • v0.2.1
  • v0.2.0
  • v0.1.3
  • v0.1.2
  • v0.1.1
  • v0.1.0
28 results

errors.go

Blame
  • user avatar
    capossele authored
    0ac0ba45
    History
    errors.go 8.21 KiB
    // Package errors provides simple error handling primitives.
    //
    // The traditional error handling idiom in Go is roughly akin to
    //
    //     if err != nil {
    //             return err
    //     }
    //
    // which when applied recursively up the call stack results in error reports
    // without context or debugging information. The errors package allows
    // programmers to add context to the failure path in their code in a way
    // that does not destroy the original value of the error.
    //
    // Adding context to an error
    //
    // The errors.Wrap function returns a new error that adds context to the
    // original error by recording a stack trace at the point Wrap is called,
    // together with the supplied message. For example
    //
    //     _, err := ioutil.ReadAll(r)
    //     if err != nil {
    //             return errors.Wrap(err, "read failed")
    //     }
    //
    // If additional control is required, the errors.WithStack and
    // errors.WithMessage functions destructure errors.Wrap into its component
    // operations: annotating an error with a stack trace and with a message,
    // respectively.
    //
    // Retrieving the cause of an error
    //
    // Using errors.Wrap constructs a stack of errors, adding context to the
    // preceding error. Depending on the nature of the error it may be necessary
    // to reverse the operation of errors.Wrap to retrieve the original error
    // for inspection. Any error value which implements this interface
    //
    //     type causer interface {
    //             Cause() error
    //     }
    //
    // can be inspected by errors.Cause. errors.Cause will recursively retrieve
    // the topmost error that does not implement causer, which is assumed to be
    // the original cause. For example:
    //
    //     switch err := errors.Cause(err).(type) {
    //     case *MyError:
    //             // handle specifically
    //     default:
    //             // unknown error
    //     }
    //
    // Although the causer interface is not exported by this package, it is
    // considered a part of its stable public interface.
    //
    // Formatted printing of errors
    //
    // All error values returned from this package implement fmt.Formatter and can
    // be formatted by the fmt package. The following verbs are supported:
    //
    //     %s    print the error. If the error has a Cause it will be
    //           printed recursively.
    //     %v    see %s
    //     %+v   extended format. Each Frame of the error's StackTrace will
    //           be printed in detail.
    //
    // Retrieving the stack trace of an error or wrapper
    //
    // New, Errorf, Wrap, and Wrapf record a stack trace at the point they are
    // invoked. This information can be retrieved with the following interface:
    //
    //     type stackTracer interface {
    //             StackTrace() errors.StackTrace
    //     }
    //
    // The returned errors.StackTrace type is defined as
    //
    //     type StackTrace []Frame
    //
    // The Frame type represents a call site in the stack trace. Frame supports
    // the fmt.Formatter interface that can be used for printing information about
    // the stack trace of this error. For example:
    //
    //     if err, ok := err.(stackTracer); ok {
    //             for _, f := range err.StackTrace() {
    //                     fmt.Printf("%+s:%d\n", f, f)
    //             }
    //     }
    //
    // Although the stackTracer interface is not exported by this package, it is
    // considered a part of its stable public interface.
    //
    // See the documentation for Frame.Format for more details.
    package errors
    
    import (
    	"fmt"
    	"io"
    )
    
    var idCounter = 0
    
    // New returns an error with the supplied message.
    // New also records the stack trace at the point it was called.
    func New(message string) *fundamental {
    	idCounter++
    
    	return &fundamental{
    		id:    idCounter,
    		msg:   message,
    		stack: Callers(),
    	}
    }
    
    // Errorf formats according to a format specifier and returns the string
    // as a value that satisfies error.
    // Errorf also records the stack trace at the point it was called.
    func Errorf(format string, args ...interface{}) IdentifiableError {
    	idCounter++
    
    	return &fundamental{
    		id:    idCounter,
    		msg:   fmt.Sprintf(format, args...),
    		stack: Callers(),
    	}
    }
    
    // fundamental is an error that has a message and a stack, but no caller.
    type fundamental struct {
    	id  int
    	msg string
    	*stack
    }
    
    func (f *fundamental) Derive(msg string) *fundamental {
    	return &fundamental{
    		id:    f.id,
    		msg:   msg,
    		stack: Callers(),
    	}
    }
    
    func (f *fundamental) Error() string { return f.msg }
    
    func (f *fundamental) Equals(err IdentifiableError) bool {
    	return f.id == err.Id()
    }
    
    func (f *fundamental) Id() int {
    	return f.id
    }
    
    func (f *fundamental) Format(s fmt.State, verb rune) {
    	switch verb {
    	case 'v':
    		if s.Flag('+') {
    			io.WriteString(s, f.msg)
    			f.stack.Format(s, verb)
    			return
    		}
    		fallthrough
    	case 's':
    		io.WriteString(s, f.msg)
    	case 'q':
    		fmt.Fprintf(s, "%q", f.msg)
    	}
    }
    
    // WithStack annotates err with a stack trace at the point WithStack was called.
    // If err is nil, WithStack returns nil.
    func WithStack(err error) IdentifiableError {
    	if err == nil {
    		return nil
    	}
    
    	idCounter++
    
    	return &withStack{
    		idCounter,
    		err,
    		Callers(),
    	}
    }
    
    type withStack struct {
    	int
    	error
    	*stack
    }
    
    func (w *withStack) Equals(err IdentifiableError) bool {
    	return w.int == err.Id()
    }
    
    func (w *withStack) Id() int {
    	return w.int
    }
    
    func (w *withStack) Derive(err error, message string) *withStack {
    	if err == nil {
    		return nil
    	}
    	return &withStack{
    		w.int,
    		&withMessage{
    			cause: err,
    			msg:   message,
    		},
    		Callers(),
    	}
    }
    
    func (w *withStack) Cause() error { return w.error }
    
    func (w *withStack) Format(s fmt.State, verb rune) {
    	switch verb {
    	case 'v':
    		if s.Flag('+') {
    			fmt.Fprintf(s, "%+v", w.Cause())
    			w.stack.Format(s, verb)
    			return
    		}
    		fallthrough
    	case 's':
    		io.WriteString(s, w.Error())
    	case 'q':
    		fmt.Fprintf(s, "%q", w.Error())
    	}
    }
    
    // Wrap returns an error annotating err with a stack trace
    // at the point Wrap is called, and the supplied message.
    // If err is nil, Wrap returns nil.
    func Wrap(err error, message string) *withStack {
    	if err == nil {
    		return nil
    	}
    	err = &withMessage{
    		cause: err,
    		msg:   message,
    	}
    
    	idCounter++
    
    	return &withStack{
    		idCounter,
    		err,
    		Callers(),
    	}
    }
    
    // Wrapf returns an error annotating err with a stack trace
    // at the point Wrapf is called, and the format specifier.
    // If err is nil, Wrapf returns nil.
    func Wrapf(err error, format string, args ...interface{}) IdentifiableError {
    	if err == nil {
    		return nil
    	}
    	err = &withMessage{
    		cause: err,
    		msg:   fmt.Sprintf(format, args...),
    	}
    
    	idCounter++
    
    	return &withStack{
    		idCounter,
    		err,
    		Callers(),
    	}
    }
    
    // WithMessage annotates err with a new message.
    // If err is nil, WithMessage returns nil.
    func WithMessage(err error, message string) IdentifiableError {
    	if err == nil {
    		return nil
    	}
    
    	idCounter++
    
    	return &withMessage{
    		id:    idCounter,
    		cause: err,
    		msg:   message,
    	}
    }
    
    // WithMessagef annotates err with the format specifier.
    // If err is nil, WithMessagef returns nil.
    func WithMessagef(err error, format string, args ...interface{}) IdentifiableError {
    	if err == nil {
    		return nil
    	}
    
    	idCounter++
    
    	return &withMessage{
    		id:    idCounter,
    		cause: err,
    		msg:   fmt.Sprintf(format, args...),
    	}
    }
    
    type withMessage struct {
    	id    int
    	cause error
    	msg   string
    }
    
    func (w *withMessage) Equals(err IdentifiableError) bool {
    	return w.id == err.Id()
    }
    
    func (w *withMessage) Id() int {
    	return w.id
    }
    
    func (w *withMessage) Error() string { return w.msg + ": " + w.cause.Error() }
    func (w *withMessage) Cause() error  { return w.cause }
    
    func (w *withMessage) Format(s fmt.State, verb rune) {
    	switch verb {
    	case 'v':
    		if s.Flag('+') {
    			fmt.Fprintf(s, "%+v\n", w.Cause())
    			io.WriteString(s, w.msg)
    			return
    		}
    		fallthrough
    	case 's', 'q':
    		io.WriteString(s, w.Error())
    	}
    }
    
    // Cause returns the underlying cause of the error, if possible.
    // An error value has a cause if it implements the following
    // interface:
    //
    //     type causer interface {
    //            Cause() error
    //     }
    //
    // If the error does not implement Cause, the original error will
    // be returned. If the error is nil, nil will be returned without further
    // investigation.
    func Cause(err error) error {
    	type causer interface {
    		Cause() error
    	}
    
    	for err != nil {
    		cause, ok := err.(causer)
    		if !ok {
    			break
    		}
    		err = cause.Cause()
    	}
    	return err
    }
    
    type IdentifiableError interface {
    	Error() string
    	Equals(identifiableError IdentifiableError) bool
    	Id() int
    }