defer, panic and recover

Three keywords that look like finally, throw and catch and are not. The resemblance is close enough to mislead, which is why they get a chapter.

defer: cleanup that cannot be forgotten

defer schedules a function call to run when the surrounding functionreturns, by any path.

func readConfig(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()     // runs on every return below, and on a panic

    // twenty lines with six return statements
    return nil
}

Write the defer immediately after the thing that needs cleaning up. That adjacency is the point: open and close are one line apart, so a reviewer can see the pair without scrolling.

The three rules of defer

One: arguments are evaluated immediately, the call happens later.

func main() {
    msg := "first"
    defer fmt.Println(msg)   // prints "first", not "second"
    msg = "second"
}

msg was read when the defer statement ran. To defer the evaluation, wrap it in a closure:

defer func() { fmt.Println(msg) }()   // prints "second"

Two: deferred calls run last in, first out.

for i := 0; i < 3; i++ {
    defer fmt.Println(i)
}
// prints 2, then 1, then 0

This is right for cleanup: resources are released in the reverse of the order they were acquired, like unwinding a stack.

Three: defer is function-scoped, not block-scoped.

func processAll(paths []string) error {
    for _, p := range paths {
        f, err := os.Open(p)
        if err != nil {
            return err
        }
        defer f.Close()     // does NOT run at the end of this iteration
        // ... use f
    }
    return nil
}

for _, p := range paths {
    if err := processOne(p); err != nil {
        return err
    }
}

func processOne(p string) error {
    f, err := os.Open(p)
    if err != nil {
        return err
    }
    defer f.Close()     // runs when processOne returns
    // ... use f
    return nil
}

defer can change the return value

A deferred closure can modify a named return value after the returnstatement has chosen it. This is the one legitimate use of named returns.

func doWork() (err error) {
    defer func() {
        if err != nil {
            err = fmt.Errorf("doWork: %w", err)
        }
    }()

    return doSomethingThatFails()    // gets wrapped on the way out
}

Used sparingly this is tidy. Used often it makes a function's return value hard to trace, so prefer explicit wrapping at each return unless you have many of them.

defer and errors from Close

A deferred Close discards its error, which is usually fine for reading and sometimes wrong for writing: a failed Close on a file you wrote may mean the data never reached the disk.

func writeReport(path string, data []byte) (err error) {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer func() {
        if cerr := f.Close(); cerr != nil && err == nil {
            err = fmt.Errorf("closing %s: %w", path, cerr)
        }
    }()

    _, err = f.Write(data)
    return err
}

That is verbose and correct. For a read-only file, defer f.Close() is accepted practice and nobody will object.

panic: stop, this should not have happened

panic unwinds the stack, running deferred functions as it goes, and if it reaches the top of a goroutine the program crashes with a stack trace.

func main() {
    defer fmt.Println("this still runs")
    panic("something impossible")
}

this still runs
panic: something impossible

goroutine 1 [running]:
main.main()
    /tmp/main.go:7 +0x65
exit status 2

Go panics on its own for a handful of runtime faults: nil pointer dereference, index out of range, division by zero, sending on a closed channel, and writing to a nil map.

recover: only for a boundary

recover stops a panic, and it only works inside a deferred function.

func safe() (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("recovered: %v", r)
        }
    }()

    panic("boom")
}

err := safe()
fmt.Println(err)    // recovered: boom

There are exactly two good reasons to use it.

One: a server that must not die because one request was bad. A panic in one handler should return 500 for that request, not take down the process serving everybody else.

func Recover(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                log.Printf("panic on %s %s: %v\n%s",
                    r.Method, r.URL.Path, rec, debug.Stack())
                http.Error(w, "internal server error",
                    http.StatusInternalServerError)
            }
        }()
        next.ServeHTTP(w, r)
    })
}

Log the stack. A recovered panic with no stack trace is a bug you will never find. Every Go web framework ships this middleware, Gin included, and Grit wires it in for you.

Two: a library turning an internal panic into an error at its edge. Some parsers panic internally to unwind out of deep recursion, then recover at the public function and return an error. The caller never sees a panic. This is legitimate and rare.

func main() {
    defer func() { recover() }()     // does not help
    go func() {
        panic("in a goroutine")      // kills the whole program
    }()
    time.Sleep(time.Second)
}

package main

import (
    "errors"
    "fmt"
    "strings"
)

type Job struct {
    Name string
    Run  func() error
}

// runOne is the boundary. Whatever the job does, this returns an error
// rather than letting a panic escape.
func runOne(j Job) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("job %q panicked: %v", j.Name, r)
        }
    }()
    defer fmt.Printf("  [%s] finished\n", j.Name)   // runs even on panic

    if j.Run == nil {
        return errors.New("job has no work")
    }
    return j.Run()
}

func runAll(jobs []Job) (failed int) {
    for _, j := range jobs {
        fmt.Printf("running %s\n", j.Name)
        if err := runOne(j); err != nil {
            fmt.Println("  error:", err)
            failed++
        }
    }
    return failed
}

func main() {
    jobs := []Job{
        {Name: "ok", Run: func() error { return nil }},
        {Name: "fails", Run: func() error {
            return errors.New("disk full")
        }},
        {Name: "panics", Run: func() error {
            var m map[string]int
            m["boom"] = 1              // panic: assignment to nil map
            return nil
        }},
        {Name: "index", Run: func() error {
            s := []int{1, 2, 3}
            fmt.Println(s[10])         // panic: index out of range
            return nil
        }},
        {Name: "no work"},
        {Name: "still runs", Run: func() error {
            fmt.Println("  the runner survived four failures")
            return nil
        }},
    }

    failed := runAll(jobs)
    fmt.Printf("\n%d of %d jobs failed\n", failed, len(jobs))
    _ = strings.TrimSpace("")
}

Assignment

Commit your work with the message Defer - Assignment One, exactly as written, so the leaderboard can score it.