Mastering Go's Context: Controlling Goroutine Lifecycles and Request Cancellation

1 What is Context

When analyzing gRPC generated code, the first parameter of interface functions is usually ctx context.Context. Many developers are unclear about the purpose of this design. In Go, a Context represents the execution state or snapshot of a program unit, often translated as “上下文”. It is used to pass request‑scoped data and cancellation signals across Goroutines.

Each Goroutine receives a Context variable that encapsulates the current execution state. When a network request arrives, a root Context is created and passed to all Goroutines handling the request. If the request is cancelled or times out, all derived Goroutines should be terminated.

2 The context package

The Go designers anticipated the need for shared data and cancellation across Goroutines. The context package (originally golang.org/x/net/context) provides this mechanism. By passing a Context, callers can signal expiration or cancellation to downstream calls.

Since Go 1.7 the package moved into the standard library under context. Compatibility wrappers remain in golang.org/x/net/context with files go17.go and pre_go17.go.

The core of the package is the Context interface:

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key interface{}) interface{}
}

Deadline

returns a timeout deadline for operations. Done returns a channel that is closed when the Context is cancelled or expires. Err reports why the Context was cancelled. Value stores request‑scoped data safely across Goroutines.

The Context itself cannot be modified; instead, derived Contexts are created with functions that return a new Context and a CancelFunc to control its lifetime.

3 Using Context

A root Context is obtained via context.Background(), which cannot be cancelled and carries no values. Child Contexts are created with:

func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, deadline time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
func WithValue(parent Context, key interface{}, val interface{}) Context

These functions copy the parent Context and add cancellation, deadline, or value information. The returned CancelFunc allows the parent to cancel the derived Context, causing all its children to stop.

Goroutines should monitor ctx.Done() and exit when the channel is closed. Values added with WithValue are retrieved via ctx.Value(key), and are safe for concurrent access.

3.1 Summary

A Context’s lifetime usually matches a single request.

Pass the existing Context to new Goroutines or create a child Context.

Context can store multiple values safely across Goroutines.

Creating a child Context also provides a cancellation function, giving the parent control over its children.

4 Usage Principles

Programs should follow these rules:

Do not store Contexts in structs; pass them explicitly as the first parameter, typically named ctx.

Never pass a nil Context; use context.TODO if unsure.

Use Context values only for request‑scoped data, not optional parameters.

Contexts are safe for simultaneous use by multiple Goroutines.