Documentation

Overview

    Package verror implements an error reporting mechanism that works across programming environments, and a set of common errors. It captures the location and parameters of the error call site to aid debugging. Rudimentary i18n support is provided, but now that more comprehensive i18n packages are available its use is deprecated and it will be removed in the near future; consequently Register and New are deprecated in favour of NewIDAction/NewID, IDAction.Errorf and IDAction.Message. Errorf is not intended or localization, whereas Message accepts a preformatted message to allow for localization via an alternative package/framework. The Convert function is also deprecated in favour of capturing non-verror error instances via Errorf, that is, IDAction.Errorf(ctx, "%v", err) should be used to create verror.E's from errors from other packages.

    NOTE that the deprecated i18n support will be removed in the near future.

    Each error has an identifier string, which is used for equality checks. E.g. a Javascript client can check if a Go server returned a NoExist error by checking the string identifier. Error identifier strings start with the VDL package path to ensure uniqueness, e.g. "v.io/v23/verror.NoExist". The NewID and NewIDAction functions automatically prepend the package path of the caller to the specified ID if it is not already included.

    Each error contains an action, which is the suggested action for a typical client to perform upon receiving the error. E.g. some action codes represent whether to retry the operation after receiving the error.

    Each error also contains a list of typed parameters, and an error message. The error message may be created in three ways:

    1. Via the Errorf method using fmt.Sprintf formatting.
    2. Via the Message method where the error message is preformatted and the
       parameter list is recorded.
    3. The error message is created by looking up a format string keyed on the error
       identifier, and applying the parameters to the format string.  This enables
       error messages to be generated in different languages. Note that this
       method is now deprecated.
    

    Contemporary Example:

    To define a new error identifier, for example "someNewError", the code that originates the error is expected to declare a variable like this:

    var someNewError = verror.Register("someNewError", NoRetry)
    ...
    return someNewError.Errorf(ctx, "my error message: %v", err)
    

    Alternatively, to use golang.org/x/text/messsage for localization:

    p := message.NewPrinter(language.BritishEnglish)
    msg := p.Sprintf("invalid name: %v: %v", name, err)
    return someNewError.Message(ctx, msg, name, err)
    

    The verror implementation supports errors.Is and errors.Unwrap. Note that errors.Unwrap provides access to 'sub-errors' as well as to chained instances of error. verror.WithSubErrors can be used to add additional 'sub-errors' to an existing error and these may be of type SubErr or any other error.

    Deprecated Usage Example:

    To define a new error identifier, for example "someNewError", client code is expected to declare a variable like this:

    var someNewError = verror.Register("someNewError", NoRetry,
                                       "{1} {2} English text for new error")
    

    Text for other languages can be added to the default i18n Catalogue. Note that verror.Register will determine the name of the calling package and prepend it to 'someNewError'.

    If the error should cause a client to retry, consider replacing "NoRetry" with one of the other Action codes below.

    Errors are given parameters when used. Conventionally, the first parameter is the name of the component (typically server or binary name), and the second is the name of the operation (such as an RPC or subcommand) that encountered the error. Other parameters typically identify the object(s) on which the error occurred. This convention is normally applied by New(), which fetches the language, component name and operation name from the context.T:

    err = verror.New(someNewError, ctx, "object_on_which_error_occurred")
    

    The ExplicitNew() call can be used to specify these things explicitly:

    err = verror.ExplicitNew(someNewError, i18n.GetLangID(ctx),
            "my_component", "op_name", "procedure_name", "object_name")
    

    If the language, component and/or operation name are unknown, use i18n.NoLangID or the empty string, respectively.

    Because of the convention for the first two parameters, messages in the catalogue typically look like this (at least for left-to-right languages):

    {1} {2} The new error {_}
    

    The tokens {1}, {2}, etc. refer to the first and second positional parameters respectively, while {_} is replaced by the positional parameters not explicitly referred to elsewhere in the message. Thus, given the parameters above, this would lead to the output:

    my_component op_name The new error object_name
    

    If a substring is of the form {:<number>}, {<number>:}, {:<number>:}, {:_}, {_:}, or {:_:}, and the corresponding parameters are not the empty string, the parameter is preceded by ": " or followed by ":" or both, respectively. For example, if the format:

    {3:} foo {2} bar{:_} ({3})
    

    is used with the cat.Format example above, it yields:

    3rd: foo 2nd bar: 1st 4th (3rd)
    

    The Convert() and ExplicitConvert() calls are like New() and ExplicitNew(), but convert existing errors (with their parameters, if applicable) to verror errors with given language, component name, and operation name, if non-empty values for these are provided. They also add a PC to a list of PC values to assist developers hunting for the error.

    If the context.T specified with New() or Convert() is nil, a default context is used, set by SetDefaultContext(). This can be used in standalone programmes, or in anciliary threads not associated with an RPC. The user might do the following to get the language from the environment, and the programme name from Args[0]:

    ctx := runtime.NewContext()
    ctx = i18n.WithLangID(ctx, i18n.LangIDFromEnv())
    ctx = verror.WithComponentName(ctx, os.Args[0])
    verror.SetDefaultContext(ctx)
    

    A standalone tool might set the operation name to be a subcommand name, if any. If the default context has not been set, the error generated has no language, component and operation values; they will be filled in by the first Convert() call that does have these values.

    nolint:golint

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    
    	// ErrUnknown means the error has no known Id.  A more specific error should
    	// always be used, if possible.  Unknown is typically only used when
    	// automatically converting errors that do not contain an Id.
    	ErrUnknown = NewIDAction("v.io/v23/verror.Unknown", NoRetry)
    	// ErrInternal means an internal error has occurred.  A more specific error
    	// should always be used, if possible.
    	ErrInternal = NewIDAction("v.io/v23/verror.Internal", NoRetry)
    	// ErrNotImplemented means that the request type is valid but that the method to
    	// handle the request has not been implemented.
    	ErrNotImplemented = NewIDAction("v.io/v23/verror.NotImplemented", NoRetry)
    	// ErrEndOfFile means the end-of-file has been reached; more generally, no more
    	// input data is available.
    	ErrEndOfFile = NewIDAction("v.io/v23/verror.EndOfFile", NoRetry)
    	// ErrBadArg means the arguments to an operation are invalid or incorrectly
    	// formatted.
    	ErrBadArg = NewIDAction("v.io/v23/verror.BadArg", NoRetry)
    	// ErrBadState means an operation was attempted on an object while the object was
    	// in an incompatible state.
    	ErrBadState = NewIDAction("v.io/v23/verror.BadState", NoRetry)
    	// ErrBadVersion means the version presented by the client (e.g. to a service
    	// that supports content-hash-based caching or atomic read-modify-write) was
    	// out of date or otherwise invalid, likely because some other request caused
    	// the version at the server to change. The client should get a fresh version
    	// and try again.
    	ErrBadVersion = NewIDAction("v.io/v23/verror.BadVersion", NoRetry)
    	// ErrExist means that the requested item already exists; typically returned when
    	// an attempt to create an item fails because it already exists.
    	ErrExist = NewIDAction("v.io/v23/verror.Exist", NoRetry)
    	// ErrNoExist means that the requested item does not exist; typically returned
    	// when an attempt to lookup an item fails because it does not exist.
    	ErrNoExist       = NewIDAction("v.io/v23/verror.NoExist", NoRetry)
    	ErrUnknownMethod = NewIDAction("v.io/v23/verror.UnknownMethod", NoRetry)
    	ErrUnknownSuffix = NewIDAction("v.io/v23/verror.UnknownSuffix", NoRetry)
    	// ErrNoExistOrNoAccess means that either the requested item does not exist, or
    	// is inaccessible.  Typically returned when the distinction between existence
    	// and inaccessiblity should be hidden to preserve privacy.
    	ErrNoExistOrNoAccess = NewIDAction("v.io/v23/verror.NoExistOrNoAccess", NoRetry)
    	// ErrNoServers means a name was resolved to unusable or inaccessible servers.
    	ErrNoServers = NewIDAction("v.io/v23/verror.NoServers", RetryRefetch)
    	// ErrNoAccess means the server does not authorize the client for access.
    	ErrNoAccess = NewIDAction("v.io/v23/verror.NoAccess", RetryRefetch)
    	// ErrNotTrusted means the client does not trust the server.
    	ErrNotTrusted = NewIDAction("v.io/v23/verror.NotTrusted", RetryRefetch)
    	// ErrAborted means that an operation was not completed because it was aborted by
    	// the receiver.  A more specific error should be used if it would help the
    	// caller decide how to proceed.
    	ErrAborted = NewIDAction("v.io/v23/verror.Aborted", NoRetry)
    	// ErrBadProtocol means that an operation was not completed because of a protocol
    	// or codec error.
    	ErrBadProtocol = NewIDAction("v.io/v23/verror.BadProtocol", NoRetry)
    	// ErrCanceled means that an operation was not completed because it was
    	// explicitly cancelled by the caller.
    	ErrCanceled = NewIDAction("v.io/v23/verror.Canceled", NoRetry)
    	// ErrTimeout means that an operation was not completed before the time deadline
    	// for the operation.
    	ErrTimeout = NewIDAction("v.io/v23/verror.Timeout", NoRetry)
    )

    Functions

    func AddSubErrs

    func AddSubErrs(err error, ctx *context.T, errors ...SubErr) error

      AddSubErrs is like ExplicitAddSubErrs, but uses the provided context to obtain the langID, componentName, and opName values.

      func Convert

      func Convert(idAction IDAction, ctx *context.T, err error) error

        Convert is like ExplicitConvert(), but obtains the language, component and operation names from the specified context.T. ctx may be nil.

        func DebugString

        func DebugString(err error) string

          DebugString returns a more verbose string representation of an error, perhaps more thorough than one might present to an end user, but useful for debugging by a developer.

          func ErrorFromNative

          func ErrorFromNative(wire **vdl.WireError, native error) error

            ErrorFromNative converts from the native to wire representation of errors.

            func ErrorToNative

            func ErrorToNative(wire *vdl.WireError, native *error) error

              ErrorToNative converts from the wire to native representation of errors.

              func Errorf

              func Errorf(ctx *context.T, format string, params ...interface{}) error

                Errorf is like ErrUnknown.Errorf.

                func ErrorfAborted

                func ErrorfAborted(ctx *context.T, format string) error

                  ErrorfAborted calls ErrAborted.Errorf with the supplied arguments.

                  func ErrorfBadArg

                  func ErrorfBadArg(ctx *context.T, format string) error

                    ErrorfBadArg calls ErrBadArg.Errorf with the supplied arguments.

                    func ErrorfBadProtocol

                    func ErrorfBadProtocol(ctx *context.T, format string) error

                      ErrorfBadProtocol calls ErrBadProtocol.Errorf with the supplied arguments.

                      func ErrorfBadState

                      func ErrorfBadState(ctx *context.T, format string) error

                        ErrorfBadState calls ErrBadState.Errorf with the supplied arguments.

                        func ErrorfBadVersion

                        func ErrorfBadVersion(ctx *context.T, format string) error

                          ErrorfBadVersion calls ErrBadVersion.Errorf with the supplied arguments.

                          func ErrorfCanceled

                          func ErrorfCanceled(ctx *context.T, format string) error

                            ErrorfCanceled calls ErrCanceled.Errorf with the supplied arguments.

                            func ErrorfEndOfFile

                            func ErrorfEndOfFile(ctx *context.T, format string) error

                              ErrorfEndOfFile calls ErrEndOfFile.Errorf with the supplied arguments.

                              func ErrorfExist

                              func ErrorfExist(ctx *context.T, format string) error

                                ErrorfExist calls ErrExist.Errorf with the supplied arguments.

                                func ErrorfInternal

                                func ErrorfInternal(ctx *context.T, format string) error

                                  ErrorfInternal calls ErrInternal.Errorf with the supplied arguments.

                                  func ErrorfNoAccess

                                  func ErrorfNoAccess(ctx *context.T, format string) error

                                    ErrorfNoAccess calls ErrNoAccess.Errorf with the supplied arguments.

                                    func ErrorfNoExist

                                    func ErrorfNoExist(ctx *context.T, format string) error

                                      ErrorfNoExist calls ErrNoExist.Errorf with the supplied arguments.

                                      func ErrorfNoExistOrNoAccess

                                      func ErrorfNoExistOrNoAccess(ctx *context.T, format string) error

                                        ErrorfNoExistOrNoAccess calls ErrNoExistOrNoAccess.Errorf with the supplied arguments.

                                        func ErrorfNoServers

                                        func ErrorfNoServers(ctx *context.T, format string) error

                                          ErrorfNoServers calls ErrNoServers.Errorf with the supplied arguments.

                                          func ErrorfNotImplemented

                                          func ErrorfNotImplemented(ctx *context.T, format string) error

                                            ErrorfNotImplemented calls ErrNotImplemented.Errorf with the supplied arguments.

                                            func ErrorfNotTrusted

                                            func ErrorfNotTrusted(ctx *context.T, format string) error

                                              ErrorfNotTrusted calls ErrNotTrusted.Errorf with the supplied arguments.

                                              func ErrorfTimeout

                                              func ErrorfTimeout(ctx *context.T, format string) error

                                                ErrorfTimeout calls ErrTimeout.Errorf with the supplied arguments.

                                                func ErrorfUnknown

                                                func ErrorfUnknown(ctx *context.T, format string) error

                                                  ErrorfUnknown calls ErrUnknown.Errorf with the supplied arguments.

                                                  func ErrorfUnknownMethod

                                                  func ErrorfUnknownMethod(ctx *context.T, format string) error

                                                    ErrorfUnknownMethod calls ErrUnknownMethod.Errorf with the supplied arguments.

                                                    func ErrorfUnknownSuffix

                                                    func ErrorfUnknownSuffix(ctx *context.T, format string) error

                                                      ErrorfUnknownSuffix calls ErrUnknownSuffix.Errorf with the supplied arguments.

                                                      func ExplicitAddSubErrs

                                                      func ExplicitAddSubErrs(err error, langID i18n.LangID, componentName string, opName string, errors ...SubErr) error

                                                        ExplicitAddSubErrs returns a copy of err with supplied errors appended as subordinate errors. Requires that errors[i].Err!=nil for 0<=i<len(errors).

                                                        func ExplicitConvert

                                                        func ExplicitConvert(idAction IDAction, langID i18n.LangID, componentName string, opName string, err error) error

                                                          ExplicitConvert converts a regular err into an E error, setting its IDAction to idAction. If err is already an E, it returns err or an equivalent value without changing its type, but potentially changing the language, component or operation if langID!=i18n.NoLangID, componentName!="" or opName!="" respectively. The caller's PC is added to the error's stack.

                                                          func ExplicitNew

                                                          func ExplicitNew(idAction IDAction, langID i18n.LangID, componentName string, opName string, v ...interface{}) error

                                                            ExplicitNew returns an error with the given ID, with an error string in the chosen language. The component and operation name are included the first and second parameters of the error. Other parameters are taken from v[]. The parameters are formatted into the message according to i18n.Cat().Format. The caller's PC is added to the error's stack. If the parameter list contains an instance of verror.E, then the stack of the first, and only the first, occurrence of such an instance, will be chained to the stack of this newly created error.

                                                            func FromWire

                                                            func FromWire(wire *vdl.WireError) error

                                                              FromWire is a convenience for generated code to convert wire errors into native errors.

                                                              func IsAny

                                                              func IsAny(err error) bool

                                                                IsAny returns true if err is any instance of a verror.E regardless of its ID.

                                                                func Message

                                                                func Message(ctx *context.T, msg string, params ...interface{}) error

                                                                  Message is like ErrUnknown.Message.

                                                                  func MessageAborted

                                                                  func MessageAborted(ctx *context.T, message string) error

                                                                    MessageAborted calls ErrAborted.Message with the supplied arguments.

                                                                    func MessageBadArg

                                                                    func MessageBadArg(ctx *context.T, message string) error

                                                                      MessageBadArg calls ErrBadArg.Message with the supplied arguments.

                                                                      func MessageBadProtocol

                                                                      func MessageBadProtocol(ctx *context.T, message string) error

                                                                        MessageBadProtocol calls ErrBadProtocol.Message with the supplied arguments.

                                                                        func MessageBadState

                                                                        func MessageBadState(ctx *context.T, message string) error

                                                                          MessageBadState calls ErrBadState.Message with the supplied arguments.

                                                                          func MessageBadVersion

                                                                          func MessageBadVersion(ctx *context.T, message string) error

                                                                            MessageBadVersion calls ErrBadVersion.Message with the supplied arguments.

                                                                            func MessageCanceled

                                                                            func MessageCanceled(ctx *context.T, message string) error

                                                                              MessageCanceled calls ErrCanceled.Message with the supplied arguments.

                                                                              func MessageEndOfFile

                                                                              func MessageEndOfFile(ctx *context.T, message string) error

                                                                                MessageEndOfFile calls ErrEndOfFile.Message with the supplied arguments.

                                                                                func MessageExist

                                                                                func MessageExist(ctx *context.T, message string) error

                                                                                  MessageExist calls ErrExist.Message with the supplied arguments.

                                                                                  func MessageInternal

                                                                                  func MessageInternal(ctx *context.T, message string) error

                                                                                    MessageInternal calls ErrInternal.Message with the supplied arguments.

                                                                                    func MessageNoAccess

                                                                                    func MessageNoAccess(ctx *context.T, message string) error

                                                                                      MessageNoAccess calls ErrNoAccess.Message with the supplied arguments.

                                                                                      func MessageNoExist

                                                                                      func MessageNoExist(ctx *context.T, message string) error

                                                                                        MessageNoExist calls ErrNoExist.Message with the supplied arguments.

                                                                                        func MessageNoExistOrNoAccess

                                                                                        func MessageNoExistOrNoAccess(ctx *context.T, message string) error

                                                                                          MessageNoExistOrNoAccess calls ErrNoExistOrNoAccess.Message with the supplied arguments.

                                                                                          func MessageNoServers

                                                                                          func MessageNoServers(ctx *context.T, message string) error

                                                                                            MessageNoServers calls ErrNoServers.Message with the supplied arguments.

                                                                                            func MessageNotImplemented

                                                                                            func MessageNotImplemented(ctx *context.T, message string) error

                                                                                              MessageNotImplemented calls ErrNotImplemented.Message with the supplied arguments.

                                                                                              func MessageNotTrusted

                                                                                              func MessageNotTrusted(ctx *context.T, message string) error

                                                                                                MessageNotTrusted calls ErrNotTrusted.Message with the supplied arguments.

                                                                                                func MessageTimeout

                                                                                                func MessageTimeout(ctx *context.T, message string) error

                                                                                                  MessageTimeout calls ErrTimeout.Message with the supplied arguments.

                                                                                                  func MessageUnknown

                                                                                                  func MessageUnknown(ctx *context.T, message string) error

                                                                                                    MessageUnknown calls ErrUnknown.Message with the supplied arguments.

                                                                                                    func MessageUnknownMethod

                                                                                                    func MessageUnknownMethod(ctx *context.T, message string) error

                                                                                                      MessageUnknownMethod calls ErrUnknownMethod.Message with the supplied arguments.

                                                                                                      func MessageUnknownSuffix

                                                                                                      func MessageUnknownSuffix(ctx *context.T, message string) error

                                                                                                        MessageUnknownSuffix calls ErrUnknownSuffix.Message with the supplied arguments.

                                                                                                        func New

                                                                                                        func New(idAction IDAction, ctx *context.T, v ...interface{}) error

                                                                                                          New is like ExplicitNew(), but obtains the language, component name, and operation name from the specified context.T. ctx may be nil.

                                                                                                          func NewErrAborted

                                                                                                          func NewErrAborted(ctx *context.T) error

                                                                                                            NewErrAborted returns an error with the ErrAborted ID. Deprecated: this function will be removed in the future, use ErrorfAborted or MessageAborted instead.

                                                                                                            func NewErrBadArg

                                                                                                            func NewErrBadArg(ctx *context.T) error

                                                                                                              NewErrBadArg returns an error with the ErrBadArg ID. Deprecated: this function will be removed in the future, use ErrorfBadArg or MessageBadArg instead.

                                                                                                              func NewErrBadProtocol

                                                                                                              func NewErrBadProtocol(ctx *context.T) error

                                                                                                                NewErrBadProtocol returns an error with the ErrBadProtocol ID. Deprecated: this function will be removed in the future, use ErrorfBadProtocol or MessageBadProtocol instead.

                                                                                                                func NewErrBadState

                                                                                                                func NewErrBadState(ctx *context.T) error

                                                                                                                  NewErrBadState returns an error with the ErrBadState ID. Deprecated: this function will be removed in the future, use ErrorfBadState or MessageBadState instead.

                                                                                                                  func NewErrBadVersion

                                                                                                                  func NewErrBadVersion(ctx *context.T) error

                                                                                                                    NewErrBadVersion returns an error with the ErrBadVersion ID. Deprecated: this function will be removed in the future, use ErrorfBadVersion or MessageBadVersion instead.

                                                                                                                    func NewErrCanceled

                                                                                                                    func NewErrCanceled(ctx *context.T) error

                                                                                                                      NewErrCanceled returns an error with the ErrCanceled ID. Deprecated: this function will be removed in the future, use ErrorfCanceled or MessageCanceled instead.

                                                                                                                      func NewErrEndOfFile

                                                                                                                      func NewErrEndOfFile(ctx *context.T) error

                                                                                                                        NewErrEndOfFile returns an error with the ErrEndOfFile ID. Deprecated: this function will be removed in the future, use ErrorfEndOfFile or MessageEndOfFile instead.

                                                                                                                        func NewErrExist

                                                                                                                        func NewErrExist(ctx *context.T) error

                                                                                                                          NewErrExist returns an error with the ErrExist ID. Deprecated: this function will be removed in the future, use ErrorfExist or MessageExist instead.

                                                                                                                          func NewErrInternal

                                                                                                                          func NewErrInternal(ctx *context.T) error

                                                                                                                            NewErrInternal returns an error with the ErrInternal ID. Deprecated: this function will be removed in the future, use ErrorfInternal or MessageInternal instead.

                                                                                                                            func NewErrNoAccess

                                                                                                                            func NewErrNoAccess(ctx *context.T) error

                                                                                                                              NewErrNoAccess returns an error with the ErrNoAccess ID. Deprecated: this function will be removed in the future, use ErrorfNoAccess or MessageNoAccess instead.

                                                                                                                              func NewErrNoExist

                                                                                                                              func NewErrNoExist(ctx *context.T) error

                                                                                                                                NewErrNoExist returns an error with the ErrNoExist ID. Deprecated: this function will be removed in the future, use ErrorfNoExist or MessageNoExist instead.

                                                                                                                                func NewErrNoExistOrNoAccess

                                                                                                                                func NewErrNoExistOrNoAccess(ctx *context.T) error

                                                                                                                                  NewErrNoExistOrNoAccess returns an error with the ErrNoExistOrNoAccess ID. Deprecated: this function will be removed in the future, use ErrorfNoExistOrNoAccess or MessageNoExistOrNoAccess instead.

                                                                                                                                  func NewErrNoServers

                                                                                                                                  func NewErrNoServers(ctx *context.T) error

                                                                                                                                    NewErrNoServers returns an error with the ErrNoServers ID. Deprecated: this function will be removed in the future, use ErrorfNoServers or MessageNoServers instead.

                                                                                                                                    func NewErrNotImplemented

                                                                                                                                    func NewErrNotImplemented(ctx *context.T) error

                                                                                                                                      NewErrNotImplemented returns an error with the ErrNotImplemented ID. Deprecated: this function will be removed in the future, use ErrorfNotImplemented or MessageNotImplemented instead.

                                                                                                                                      func NewErrNotTrusted

                                                                                                                                      func NewErrNotTrusted(ctx *context.T) error

                                                                                                                                        NewErrNotTrusted returns an error with the ErrNotTrusted ID. Deprecated: this function will be removed in the future, use ErrorfNotTrusted or MessageNotTrusted instead.

                                                                                                                                        func NewErrTimeout

                                                                                                                                        func NewErrTimeout(ctx *context.T) error

                                                                                                                                          NewErrTimeout returns an error with the ErrTimeout ID. Deprecated: this function will be removed in the future, use ErrorfTimeout or MessageTimeout instead.

                                                                                                                                          func NewErrUnknown

                                                                                                                                          func NewErrUnknown(ctx *context.T) error

                                                                                                                                            NewErrUnknown returns an error with the ErrUnknown ID. Deprecated: this function will be removed in the future, use ErrorfUnknown or MessageUnknown instead.

                                                                                                                                            func NewErrUnknownMethod

                                                                                                                                            func NewErrUnknownMethod(ctx *context.T) error

                                                                                                                                              NewErrUnknownMethod returns an error with the ErrUnknownMethod ID. Deprecated: this function will be removed in the future, use ErrorfUnknownMethod or MessageUnknownMethod instead.

                                                                                                                                              func NewErrUnknownSuffix

                                                                                                                                              func NewErrUnknownSuffix(ctx *context.T) error

                                                                                                                                                NewErrUnknownSuffix returns an error with the ErrUnknownSuffix ID. Deprecated: this function will be removed in the future, use ErrorfUnknownSuffix or MessageUnknownSuffix instead.

                                                                                                                                                func Params

                                                                                                                                                func Params(err error) []interface{}

                                                                                                                                                  Params returns the ParameterList stored in err if it's an instance of verror.E, nil otherwise.

                                                                                                                                                  func ParamsErrAborted

                                                                                                                                                  func ParamsErrAborted(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                    ParamsErrAborted extracts the expected parameters from the error's ParameterList.

                                                                                                                                                    func ParamsErrBadArg

                                                                                                                                                    func ParamsErrBadArg(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                      ParamsErrBadArg extracts the expected parameters from the error's ParameterList.

                                                                                                                                                      func ParamsErrBadProtocol

                                                                                                                                                      func ParamsErrBadProtocol(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                        ParamsErrBadProtocol extracts the expected parameters from the error's ParameterList.

                                                                                                                                                        func ParamsErrBadState

                                                                                                                                                        func ParamsErrBadState(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                          ParamsErrBadState extracts the expected parameters from the error's ParameterList.

                                                                                                                                                          func ParamsErrBadVersion

                                                                                                                                                          func ParamsErrBadVersion(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                            ParamsErrBadVersion extracts the expected parameters from the error's ParameterList.

                                                                                                                                                            func ParamsErrCanceled

                                                                                                                                                            func ParamsErrCanceled(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                              ParamsErrCanceled extracts the expected parameters from the error's ParameterList.

                                                                                                                                                              func ParamsErrEndOfFile

                                                                                                                                                              func ParamsErrEndOfFile(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                ParamsErrEndOfFile extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                func ParamsErrExist

                                                                                                                                                                func ParamsErrExist(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                  ParamsErrExist extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                  func ParamsErrInternal

                                                                                                                                                                  func ParamsErrInternal(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                    ParamsErrInternal extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                    func ParamsErrNoAccess

                                                                                                                                                                    func ParamsErrNoAccess(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                      ParamsErrNoAccess extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                      func ParamsErrNoExist

                                                                                                                                                                      func ParamsErrNoExist(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                        ParamsErrNoExist extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                        func ParamsErrNoExistOrNoAccess

                                                                                                                                                                        func ParamsErrNoExistOrNoAccess(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                          ParamsErrNoExistOrNoAccess extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                          func ParamsErrNoServers

                                                                                                                                                                          func ParamsErrNoServers(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                            ParamsErrNoServers extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                            func ParamsErrNotImplemented

                                                                                                                                                                            func ParamsErrNotImplemented(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                              ParamsErrNotImplemented extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                              func ParamsErrNotTrusted

                                                                                                                                                                              func ParamsErrNotTrusted(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                                ParamsErrNotTrusted extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                                func ParamsErrTimeout

                                                                                                                                                                                func ParamsErrTimeout(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                                  ParamsErrTimeout extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                                  func ParamsErrUnknown

                                                                                                                                                                                  func ParamsErrUnknown(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                                    ParamsErrUnknown extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                                    func ParamsErrUnknownMethod

                                                                                                                                                                                    func ParamsErrUnknownMethod(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                                      ParamsErrUnknownMethod extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                                      func ParamsErrUnknownSuffix

                                                                                                                                                                                      func ParamsErrUnknownSuffix(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

                                                                                                                                                                                        ParamsErrUnknownSuffix extracts the expected parameters from the error's ParameterList.

                                                                                                                                                                                        func SetDefaultContext

                                                                                                                                                                                        func SetDefaultContext(ctx *context.T)

                                                                                                                                                                                          SetDefaultContext sets the default context used when a nil context.T is passed to New() or Convert(). It is typically used in standalone programmes that have no RPC context, or in servers for the context of ancillary threads not associated with any particular RPC.

                                                                                                                                                                                          func StackToText

                                                                                                                                                                                          func StackToText(w io.Writer, stack []uintptr) error

                                                                                                                                                                                            StackToText emits on w a text representation of stack, which is typically obtained from Stack() and represents the source location(s) where an error was generated or passed through in the local address space.

                                                                                                                                                                                            func VDLRead

                                                                                                                                                                                            func VDLRead(dec vdl.Decoder, x *error) error

                                                                                                                                                                                              VDLRead implements the logic to read x from dec.

                                                                                                                                                                                              Unlike regular VDLRead implementations, this handles the case where the decoder contains a nil value, to make code generation simpler.

                                                                                                                                                                                              func VDLWrite

                                                                                                                                                                                              func VDLWrite(enc vdl.Encoder, x error) error

                                                                                                                                                                                                VDLWrite implements the logic to write x to enc.

                                                                                                                                                                                                Unlike regular VDLWrite implementations, this handles the case where x contains a nil value, to make code generation simpler.

                                                                                                                                                                                                func WireFromNative

                                                                                                                                                                                                func WireFromNative(wire *vdl.WireError, native error) error

                                                                                                                                                                                                  WireFromNative converts from the standard go error interface to verror.E, and then to vdl.WireError.

                                                                                                                                                                                                  TODO(toddw): Remove this function after the switch to the new vdl Encoder/Decoder is complete.

                                                                                                                                                                                                  func WireToNative

                                                                                                                                                                                                  func WireToNative(wire vdl.WireError, native *E) error

                                                                                                                                                                                                    WireToNative converts from vdl.WireError to verror.E, which implements the standard go error interface.

                                                                                                                                                                                                    TODO(toddw): Remove this function after the switch to the new vdl Encoder/Decoder is complete.

                                                                                                                                                                                                    func WithComponentName

                                                                                                                                                                                                    func WithComponentName(ctx *context.T, componentName string) *context.T

                                                                                                                                                                                                      WithComponentName returns a context based on ctx that has the componentName that New() and Convert() can use.

                                                                                                                                                                                                      func WithSubErrors

                                                                                                                                                                                                      func WithSubErrors(err error, errors ...error) error

                                                                                                                                                                                                        WithSubErrors returns a new E with the supplied suberrors appended to its parameter list. The results of their Error method are appended to that of err.Error().

                                                                                                                                                                                                        Types

                                                                                                                                                                                                        type ActionCode

                                                                                                                                                                                                        type ActionCode uint32

                                                                                                                                                                                                          An ActionCode represents the action expected to be performed by a typical client receiving an error that perhaps it does not understand.

                                                                                                                                                                                                          const (
                                                                                                                                                                                                          	// Retry actions are encoded in the bottom few bits.
                                                                                                                                                                                                          	RetryActionMask ActionCode = 3
                                                                                                                                                                                                          
                                                                                                                                                                                                          	NoRetry         ActionCode = 0 // Do not retry.
                                                                                                                                                                                                          	RetryConnection ActionCode = 1 // Renew high-level connection/context.
                                                                                                                                                                                                          	RetryRefetch    ActionCode = 2 // Refetch and retry (e.g., out of date HTTP ETag)
                                                                                                                                                                                                          	RetryBackoff    ActionCode = 3 // Backoff and retry a finite number of times.
                                                                                                                                                                                                          )

                                                                                                                                                                                                            Codes for ActionCode.

                                                                                                                                                                                                            func Action

                                                                                                                                                                                                            func Action(err error) ActionCode

                                                                                                                                                                                                              Action returns the action of the given err, or NoRetry if the err has no Action.

                                                                                                                                                                                                              func (ActionCode) RetryAction

                                                                                                                                                                                                              func (ac ActionCode) RetryAction() ActionCode

                                                                                                                                                                                                                RetryAction returns the part of the ActionCode that indicates retry behaviour.

                                                                                                                                                                                                                type E

                                                                                                                                                                                                                type E struct {
                                                                                                                                                                                                                	ID        ID            // The identity of the error.
                                                                                                                                                                                                                	Action    ActionCode    // Default action to take on error.
                                                                                                                                                                                                                	Msg       string        // Error message; empty if no language known.
                                                                                                                                                                                                                	ParamList []interface{} // The variadic parameters given to ExplicitNew().
                                                                                                                                                                                                                	// contains filtered or unexported fields
                                                                                                                                                                                                                }

                                                                                                                                                                                                                  E is the in-memory representation of a verror error.

                                                                                                                                                                                                                  The wire representation is defined as vdl.WireError; values of E type are automatically converted to/from vdl.WireError by VDL and VOM.

                                                                                                                                                                                                                  func (E) Error

                                                                                                                                                                                                                  func (e E) Error() string

                                                                                                                                                                                                                    Error returns the error message; if it has not been formatted for a specific language, a default message containing the error ID and parameters is generated. This method is required to fulfil the error interface.

                                                                                                                                                                                                                    func (E) Is

                                                                                                                                                                                                                    func (e E) Is(err error) bool

                                                                                                                                                                                                                      Is implements the Is method as expected by errors.Is.

                                                                                                                                                                                                                      func (E) Unwrap

                                                                                                                                                                                                                      func (e E) Unwrap() error

                                                                                                                                                                                                                        Unwrap implements the Unwrap method as expected by errors.Unwrap. It returns verror.SubErrors followed by any error recorded with %w for Errorf or the last argument to Message, New or ExplicitNew.

                                                                                                                                                                                                                        func (E) VDLEqual

                                                                                                                                                                                                                        func (e E) VDLEqual(yiface interface{}) bool

                                                                                                                                                                                                                        func (*E) VDLRead

                                                                                                                                                                                                                        func (e *E) VDLRead(dec vdl.Decoder) error

                                                                                                                                                                                                                        func (E) VDLReflect

                                                                                                                                                                                                                        func (E) VDLReflect(struct {
                                                                                                                                                                                                                        	Name string `vdl:"v.io/v23/vdl.WireError"`
                                                                                                                                                                                                                        })

                                                                                                                                                                                                                          TypeOf(verror.E{}) should give vdl.WireError.

                                                                                                                                                                                                                          func (E) VDLWrite

                                                                                                                                                                                                                          func (e E) VDLWrite(enc vdl.Encoder) error

                                                                                                                                                                                                                          type ID

                                                                                                                                                                                                                          type ID string

                                                                                                                                                                                                                            ID is a unique identifier for errors.

                                                                                                                                                                                                                            func ErrorID

                                                                                                                                                                                                                            func ErrorID(err error) ID

                                                                                                                                                                                                                              ErrorID returns the ID of the given err, or Unknown if the err has no ID. If err is nil then ErrorID returns "".

                                                                                                                                                                                                                              func IDPath

                                                                                                                                                                                                                              func IDPath(val interface{}, id string) ID

                                                                                                                                                                                                                                IDPath returns a string of the form <package-path>.<name> where <package-path> is derived from the type of the supplied value. Typical usage would be except that dummy can be replaced by an existing type defined in the package.

                                                                                                                                                                                                                                type dummy int
                                                                                                                                                                                                                                verror.ID(verror.IDPath(dummy(0), "MyError"))
                                                                                                                                                                                                                                

                                                                                                                                                                                                                                type IDAction

                                                                                                                                                                                                                                type IDAction struct {
                                                                                                                                                                                                                                	ID     ID
                                                                                                                                                                                                                                	Action ActionCode
                                                                                                                                                                                                                                }

                                                                                                                                                                                                                                  An IDAction combines a unique identifier ID for errors with an ActionCode. The ID allows stable error checking across different error messages and different address spaces. By convention the format for the identifier is "PKGPATH.NAME" - e.g. ErrIDFoo defined in the "v23/verror" package has id "v23/verror.ErrIDFoo". It is unwise ever to create two IDActions that associate different ActionCodes with the same ID. IDAction implements error so that it may be used with errors.Is.

                                                                                                                                                                                                                                  func NewID

                                                                                                                                                                                                                                  func NewID(id ID) IDAction

                                                                                                                                                                                                                                    NewID creates a new instance of IDAction with the given ID and a NoRetry Action.

                                                                                                                                                                                                                                    func NewIDAction

                                                                                                                                                                                                                                    func NewIDAction(id ID, action ActionCode) IDAction

                                                                                                                                                                                                                                      NewIDAction creates a new instance of IDAction with the given ID and Action field. It should be used when localization support is not required instead of Register. IDPath can be used to

                                                                                                                                                                                                                                      func Register

                                                                                                                                                                                                                                      func Register(id ID, action ActionCode, englishText string) IDAction

                                                                                                                                                                                                                                        Register returns a IDAction with the given ID and Action fields, and inserts a message into the default i18n Catalogue in US English. Other languages can be added by adding to the Catalogue. IDPath can be used to generate an appropriate ID.

                                                                                                                                                                                                                                        func (IDAction) Error

                                                                                                                                                                                                                                        func (id IDAction) Error() string

                                                                                                                                                                                                                                          Error implements error.

                                                                                                                                                                                                                                          func (IDAction) Errorf

                                                                                                                                                                                                                                          func (id IDAction) Errorf(ctx *context.T, format string, params ...interface{}) error

                                                                                                                                                                                                                                            Errorf creates a new verror.E that uses fmt.Errorf style formatting and is not intended for localization. Errorf prepends the component and operation name if they can be extracted from the context. It supports %w for errors.Unwrap which takes precedence over using the last parameter if it's an error as the error to be returned by Unwrap.

                                                                                                                                                                                                                                            func (IDAction) Is

                                                                                                                                                                                                                                            func (id IDAction) Is(err error) bool

                                                                                                                                                                                                                                              Is implements the Is method as expected by errors.Is.

                                                                                                                                                                                                                                              func (IDAction) Message

                                                                                                                                                                                                                                              func (id IDAction) Message(ctx *context.T, msg string, params ...interface{}) error

                                                                                                                                                                                                                                                Message is intended for pre-internationalizated messages. The msg is assumed to be have been preformated and the params are recorded in E.ParamList. If the last parameter is an error it will returned by Unwrap.

                                                                                                                                                                                                                                                type PCs

                                                                                                                                                                                                                                                type PCs []uintptr

                                                                                                                                                                                                                                                  PCs represents a list of PC locations

                                                                                                                                                                                                                                                  func Stack

                                                                                                                                                                                                                                                  func Stack(err error) PCs

                                                                                                                                                                                                                                                    Stack returns the list of PC locations on the stack when this error was first generated within this address space, or an empty list if err is not an E.

                                                                                                                                                                                                                                                    func (PCs) String

                                                                                                                                                                                                                                                    func (st PCs) String() string

                                                                                                                                                                                                                                                    type SubErr

                                                                                                                                                                                                                                                    type SubErr struct {
                                                                                                                                                                                                                                                    	Name    string
                                                                                                                                                                                                                                                    	Err     error
                                                                                                                                                                                                                                                    	Options SubErrOpts
                                                                                                                                                                                                                                                    }

                                                                                                                                                                                                                                                      A SubErr represents a (string, error, int32) triple, It is the element type for SubErrs.

                                                                                                                                                                                                                                                      func (SubErr) Error

                                                                                                                                                                                                                                                      func (subErr SubErr) Error() string

                                                                                                                                                                                                                                                        Error implements error.

                                                                                                                                                                                                                                                        func (SubErr) String

                                                                                                                                                                                                                                                        func (subErr SubErr) String() string

                                                                                                                                                                                                                                                        type SubErrOpts

                                                                                                                                                                                                                                                        type SubErrOpts uint32
                                                                                                                                                                                                                                                        const (
                                                                                                                                                                                                                                                        	// Print, when set in SubErr.Options, tells Error() to print this SubErr.
                                                                                                                                                                                                                                                        	Print SubErrOpts = 0x1
                                                                                                                                                                                                                                                        )

                                                                                                                                                                                                                                                        type SubErrs

                                                                                                                                                                                                                                                        type SubErrs []SubErr

                                                                                                                                                                                                                                                          A SubErrs is a special type that allows clients to include a list of subordinate errors to an error's parameter list. Clients can add a SubErrs to the parameter list directly, via New() or include one in an existing error using AddSubErrs(). Each element of the slice has a name, an error, and an integer that encodes options such as verror.Print as bits set within it. By convention, clients are expected to use name of the form "X=Y" to distinguish their subordinate errors from those of other abstraction layers. For example, a layer reporting on errors in individual blessings in an RPC might use strings like "blessing=<blessing_name>".

                                                                                                                                                                                                                                                          func (SubErrs) String

                                                                                                                                                                                                                                                          func (subErrs SubErrs) String() (result string)

                                                                                                                                                                                                                                                            String is the default printing function for SubErrs.