effective-go chapter14

Errors

Library routines must often return some sort of error indication to the caller. As mentioned earlier, Go’s multivalue return makes it easy to return a detailed error description alongside the normal return value. It is good style to use this feature to provide detailed error information. For example, as we’ll see,os.Opendoesn’t just return anilpointer on failure, it also returns an error value that describes what went wrong.

By convention, errors have typeerror, a simple built-in interface.

type error interface {
    Error() string
}

A library writer is free to implement this interface with a richer model under the covers, making it possible not only to see the error but also to provide some context. As mentioned, alongside the usual*os.Filereturn value,os.Openalso returns an error value. If the file is opened successfully, the error will benil, but when there is a problem, it will hold anos.PathError:

// PathError records an error and the operation and
// file path that caused it.
type PathError struct {
    Op string    // "open", "unlink", etc.
    Path string  // The associated file.
    Err error    // Returned by the system call.
}

func (e *PathError) Error() string {
    return e.Op + " " + e.Path + ": " + e.Err.Error()
}

PathError‘sErrorgenerates a string like this:

open /etc/passwx: no such file or directory

Such an error, which includes the problematic file name, the operation, and the operating system error it triggered, is useful even if printed far from the call that caused it; it is much more informative than the plain “no such file or directory”.

When feasible, error strings should identify their origin, such as by having a prefix naming the operation or package that generated the error. For example, in packageimage, the string representation for a decoding error due to an unknown format is “image: unknown format”.

Callers that care about the precise error details can use a type switch or a type assertion to look for specific errors and extract details. ForPathErrorsthis might include examining the internalErrfield for recoverable failures.

for try := 0; try < 2; try++ {
    file, err = os.Create(filename)
    if err == nil {
        return
    }
    if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC {
        deleteTempFiles()  // Recover some space.
        continue
    }
    return
}

The secondifstatement here is anothertype assertion. If it fails,okwill be false, andewill benil. If it succeeds,okwill be true, which means the error was of type*os.PathError, and then so ise, which we can examine for more information about the error.

Panic

The usual way to report an error to a caller is to return anerroras an extra return value. The canonicalReadmethod is a well-known instance; it returns a byte count and anerror. But what if the error is unrecoverable? Sometimes the program simply cannot continue.

For this purpose, there is a built-in functionpanicthat in effect creates a run-time error that will stop the program (but see the next section). The function takes a single argument of arbitrary type—often a string—to be printed as the program dies. It’s also a way to indicate that something impossible has happened, such as exiting an infinite loop.

// A toy implementation of cube root using Newton's method.
func CubeRoot(x float64) float64 {
    z := x/3   // Arbitrary initial value
    for i := 0; i < 1e6; i++ {
        prevz := z
        z -= (z*z*z-x) / (3*z*z)
        if veryClose(z, prevz) {
            return z
        }
    }
    // A million iterations has not converged; something is wrong.
    panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
}

This is only an example but real library functions should avoidpanic. If the problem can be masked or worked around, it’s always better to let things continue to run rather than taking down the whole program. One possible counterexample is during initialization: if the library truly cannot set itself up, it might be reasonable to panic, so to speak.

var user = os.Getenv("USER")

func init() {
    if user == "" {
        panic("no value for $USER")
    }
}

Recover

Whenpanicis called, including implicitly for run-time errors such as indexing a slice out of bounds or failing a type assertion, it immediately stops execution of the current function and begins unwinding the stack of the goroutine, running any deferred functions along the way. If that unwinding reaches the top of the goroutine’s stack, the program dies. However, it is possible to use the built-in functionrecoverto regain control of the goroutine and resume normal execution.

A call torecoverstops the unwinding and returns the argument passed topanic. Because the only code that runs while unwinding is inside deferred functions,recoveris only useful inside deferred functions.

One application ofrecoveris to shut down a failing goroutine inside a server without killing the other executing goroutines.

func server(workChan <-chan *Work) {
    for work := range workChan {
        go safelyDo(work)
    }
}

func safelyDo(work *Work) {
    defer func() {
        if err := recover(); err != nil {
            log.Println("work failed:", err)
        }
    }()
    do(work)
}

In this example, ifdo(work)panics, the result will be logged and the goroutine will exit cleanly without disturbing the others. There’s no need to do anything else in the deferred closure; callingrecoverhandles the condition completely.

Becauserecoveralways returnsnilunless called directly from a deferred function, deferred code can call library routines that themselves usepanicandrecoverwithout failing. As an example, the deferred function insafelyDomight call a logging function before callingrecover, and that logging code would run unaffected by the panicking state.

With our recovery pattern in place, thedofunction (and anything it calls) can get out of any bad situation cleanly by callingpanic. We can use that idea to simplify error handling in complex software. Let’s look at an idealized version of aregexppackage, which reports parsing errors by callingpanicwith a local error type. Here’s the definition ofError, anerrormethod, and theCompilefunction.

// Error is the type of a parse error; it satisfies the error interface.
type Error string
func (e Error) Error() string {
    return string(e)
}

// error is a method of *Regexp that reports parsing errors by
// panicking with an Error.
func (regexp *Regexp) error(err string) {
    panic(Error(err))
}

// Compile returns a parsed representation of the regular expression.
func Compile(str string) (regexp *Regexp, err error) {
    regexp = new(Regexp)
    // doParse will panic if there is a parse error.
    defer func() {
        if e := recover(); e != nil {
            regexp = nil    // Clear return value.
            err = e.(Error) // Will re-panic if not a parse error.
        }
    }()
    return regexp.doParse(str), nil
}

IfdoParsepanics, the recovery block will set the return value tonil—deferred functions can modify named return values. It will then check, in the assignment toerr, that the problem was a parse error by asserting that it has the local typeError. If it does not, the type assertion will fail, causing a run-time error that continues the stack unwinding as though nothing had interrupted it. This check means that if something unexpected happens, such as an index out of bounds, the code will fail even though we are usingpanicandrecoverto handle parse errors.

With error handling in place, theerrormethod (because it’s a method bound to a type, it’s fine, even natural, for it to have the same name as the builtinerrortype) makes it easy to report parse errors without worrying about unwinding the parse stack by hand:

if pos == 0 {
    re.error("'*' illegal at start of expression")
}

Useful though this pattern is, it should be used only within a package.Parseturns its internalpaniccalls intoerrorvalues; it does not exposepanicsto its client. That is a good rule to follow.

By the way, this re-panic idiom changes the panic value if an actual error occurs. However, both the original and new failures will be presented in the crash report, so the root cause of the problem will still be visible. Thus this simple re-panic approach is usually sufficient—it’s a crash after all—but if you want to display only the original value, you can write a little more code to filter unexpected problems and re-panic with the original error. That’s left as an exercise for the reader.

---