context: timeouts and cancellation

The problem

A user opens a page; your handler calls a database and two other services. The user closes the tab after one second. Without a way to say "stop", all that work keeps running for nothing, using connections and CPU. Or a bank API hangs, and your request waits forever. You need a way to say "give up after 2 seconds" or "the caller is gone, stop now", across every function and goroutine involved. That is context.

Creating contexts

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel() // ALWAYS: releases resources even if work finishes early

err := chargeCard(ctx, 49900)
if errors.Is(err, context.DeadlineExceeded) {
	fmt.Println("bank too slow, try again")
}

Listening for cancellation

ctx.Done() returns a channel that is closed when the context is cancelled or its deadline passes. ctx.Err() then says why: context.Canceled or context.DeadlineExceeded. Long-running code checks Done in a select.

func chargeCard(ctx context.Context, paise int64) error {
	result := make(chan error, 1)
	go func() {
		time.Sleep(3 * time.Second) // pretend slow bank call
		result <- nil
	}()
	select {
	case err := <-result:
		return err
	case <-ctx.Done():
		return ctx.Err() // context.DeadlineExceeded or context.Canceled
	}
}

func processAll(ctx context.Context, ids []int) error {
	for _, id := range ids {
		if err := ctx.Err(); err != nil {
			return err // stop between items once cancelled
		}
		process(id)
	}
	return nil
}

Contexts form a tree

Every derived context has a parent. Cancelling a parent cancels all its children, but cancelling a child does not affect the parent. A child's deadline can be shorter than its parent's, never longer: the earliest deadline wins.

Where contexts come from in real code

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context() // cancelled if the client disconnects

	ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
	defer cancel()

	row := db.QueryRowContext(ctx, "SELECT name FROM users WHERE id = $1", 42)
	// ...
	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/rates", nil)
	// resp, err := client.Do(req)
	_ = row
	_ = req
}

The rules

1. Pass ctx as the first parameter, named ctx: func Charge(ctx context.Context, amount int64) error.
2. Do not store a context in a struct field; pass it to each call that needs it.
3. Always call cancel, usually with defer, right after creating a cancellable context.
4. Never pass a nil context. Use context.Background() or context.TODO().
5. Use WithValue only for request-scoped data that crosses API boundaries (request ID, auth info), never for optional function parameters. Use your own unexported key type to avoid clashes.