Context package

Characteristics

• To be used with blocking calls
• Immutable: only way to modify a context is to derive a sub-context
• Hierarchical: operations on a high-level context trickle down to derived contexts
• Standard glue between various APIs, or candidate for such

Deadlines

• Go already had I/O deadline APIs and timer channels
• Context is a generic mechanism
• Context combines layers of deadline configurations

Cancellation

• Could be accomplished with plain channels etc.
• Context hides complexity caused by nesting
• Go APIs haven't traditionally given much thought to graceful shutdown
• Context promotes cancellation awareness, thanks to the common API
• Benefits architecture of non-trivial apps which are not expected to run forever

Values

• Values stored in a context transit the call stack transparently
• Strong decoupling thanks to lexically scoped keys
• Solves similar problems as thread-local storage
• Request-scoped storage
• Not specific to a thread or a goroutine

Building blocks

• Context interface and factory functions
• Convention: pass context as first function argument

func Foo(ctx Context, ...)

Example: Top level

func main() {
    ctx := context.Background() // No timeout, cancellation, or values

    app(ctx)
}

Example: Reacting to events

func app(ctx Context) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    go waitForSignalAndInvoke(os.Interrupt, cancel)

    doStuff(ctx)
}

func waitForSignalAndInvoke(number os.Signal, cancel context.CancelFunc) {
    c := make(chan os.Signal)
    signal.Notify(c, number)
    <-c
    cancel()
}

Example: API call with a deadline

func doStuff(ctx Context) (err error) {
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    result, err := api.PerformOperation(ctx, 10, 20)
    if err != nil {
        return
    }

    fmt.Println(result)
    return
}

Example: Implementation of a blocking API

func PerformOperation(ctx Context, x, y int) (result int, err error) {
    performance := startPerforming(x, y)

    select {
    case result, _ = <-performance.resultChannel:
        return

    case <-ctx.Done(): // Timed out or cancelled?
        err = ctx.Err()
        performance.abort()
        return
    }
}

API implementation support

• Context.Done() channel will be closed on deadline or cancellation
• A channel may be read concurrently
• A closed channel may be read repeatedly
• Context.Deadline() value may be used with readers/writers, but it doesn't respect cancellation

Supported by net package

since 1.7:

Dialer.DialContext(ctx Context, net, addr string) (Conn, error)

since 1.8:

Resolver.LookupAddr(ctx Context, addr string) (names []string, err error)
Resolver.LookupCNAME(ctx Context, host string) (cname string, err error)
Resolver.LookupHost(ctx Context, host string) (addrs []string, err error)
...

Supported by net/http package

since 1.7:

Request.WithContext(ctx Context) *Request
Request.Context() Context
ServerContextKey
LocalAddrContextKey

since 1.8:

Server.Shutdown(ctx Context) error

Supported by os/exec package

since 1.7:

CommandContext(ctx Context, name string, arg ...string) *Cmd

Supported by database/sql package

since 1.8:

DB.QueryContext(ctx Context, query string, args ...interface{}) (*Rows, error)
...

Thoughts

• Simple, but high-impact if supported widely
• Violates the single responsibility principle... by definition
• Value API's role is unclear, and controversial

Thank you