Columns › 1. Go foundations › Part 4
Go context: Cancellation, Timeouts and Request-Scoped Values
context:取消、逾時與資料傳遞
This article shows how contexts form a cancellation tree, how WithCancel and WithTimeout carry cancellation and deadlines from an HTTP handler to every goroutine and downstream call, and how to use WithCancelCause, AfterFunc, WithoutCancel and WithValue correctly.
In this article
- What this article solves
- Step 1: The Context interface and the basic rules
- Step 2: WithCancel and the cancellation tree
- Step 3: WithTimeout, WithDeadline and the timeout budget
- Step 4: Explain why with WithCancelCause
- Step 5: AfterFunc: run clean-up on cancellation
- Step 6: WithValue: only for request-scoped data
- Step 7: WithoutCancel: work that must continue after the request ends
- Common pitfalls
- Key takeaways
- Next
In the previous article, “Goroutines, Channels and Concurrency Patterns in Go”, we let the order service look up prices concurrently and process large batches of work with a worker pool, and we used a semaphore to limit concurrency and errors.Join to collect errors. But it left a gap: there was no standard way to tell other goroutines "you can stop now", nor any way to set a time limit on the whole call chain. This article fills that gap with context, which is also what will appear as the first parameter in every HTTP, database and gRPC article that follows.
What this article solves
Imagine a user pressing "Place order" on the checkout page. Once the order service receives the request, it has to look up prices, check stock and call the payment service, and each step may in turn start a few goroutines or send database queries behind the scenes. Several things can happen at this point:
- The user gets impatient and closes the tab. The connection is gone, but the server is still diligently checking stock and calling payment, wasting resources.
- The payment service slows down and one request is stuck for thirty seconds. The upstream gateway gave up at five seconds, but the order service is still waiting.
- Stock for three items is reserved concurrently; the first fails, the other two keep running, and in the end they have to be rolled back one by one.
- You want every log line to carry the request ID, but don't want every function to grow an extra
requestID stringparameter.
What these four problems have in common is that they are all about the lifecycle of a request. context.Context is Go's standard interface for expressing a request's lifecycle, and it carries three things: a cancellation signal, a deadline and request-scoped values. Every potentially blocking API in the standard library (net/http, database/sql, net.Dialer, os/exec) accepts a context, so as long as you pass it all the way down, cancellation and timeouts propagate automatically into every corner.
This article starts from the context interface and introduces, in turn, the cancellation tree, timeouts, cancellation causes, AfterFunc and passing values, and finally how to handle "background work that must continue after the request has ended".
Step 1: The Context interface and the basic rules
context.Context is an interface with only four methods:
| Method | Returns | Purpose |
|---|---|---|
Done() | <-chan struct{} | A channel that is closed on cancellation or timeout, used in select |
Err() | error | nil while still running; afterwards context.Canceled or context.DeadlineExceeded |
Deadline() | time.Time, bool | If there is a deadline, returns it and true |
Value(key) | any | Retrieves a request-scoped value, returning nil if not found |
Done() is the standardised version of the home-made done channel from the previous article: when it is closed, every goroutine waiting on it wakes up at the same time. The difference is that contexts can be derived layer by layer, forming a tree, and cancellation propagates from the top down.
There are a few rules for using context that the community widely follows, and the standard library and most libraries are designed around them:
- The context is a function's first parameter and is called
ctx:func (s *Service) Create(ctx context.Context, o Order) error. - Don't store a context in a struct field; pass it in on every call instead. A context represents the lifecycle of "this one call", and storing it in a struct lets it outlive the request.
- Don't pass a
nilcontext. When you don't know what to use, usecontext.TODO()to mark "to be filled in later"; the real root iscontext.Background(), which usually only appears inmain, initialisation and tests. - Contexts are immutable. Every
With...function returns a new child context without changing the parent, so the same context can safely be used by several goroutines at once.
In an HTTP server you almost never need to create a root context yourself: r.Context() is already the context net/http created for each request, and it is cancelled automatically when the client disconnects or the HTTP/2 stream is reset.
Step 2: WithCancel and the cancellation tree
context.WithCancel(parent) returns a child context and a cancel function. Calling cancel() cancels this child context and all its descendants; when the parent context is cancelled, the child is cancelled too. The reverse is not true: cancelling a child affects neither its parent nor its siblings.
Figure: cancelling the "reserve stock" node ends the three item lookups beneath it together; "pricing" and the root are unaffected. When the root is cancelled, the whole tree ends.
The program below builds a small tree and shows how cancellation propagates downwards. Note that every long-running goroutine uses select to listen on ctx.Done() at the same time; this is the only way to make a goroutine "cancellable": a context only sends a signal, and the goroutine must check it and end itself.
package main
import (
"context"
"fmt"
"sync"
"time"
)
// work simulates a long-running job that checks for the cancellation signal periodically.
func work(ctx context.Context, name string, wg *sync.WaitGroup) {
defer wg.Done()
ticker := time.NewTicker(50 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
fmt.Printf("%-10s stopped: %v\n", name, ctx.Err())
return
case <-ticker.C:
// do a small piece of work
}
}
}
func main() {
root, cancelRoot := context.WithCancel(context.Background())
defer cancelRoot()
pricing, cancelPricing := context.WithCancel(root)
defer cancelPricing()
stock, cancelStock := context.WithCancel(root)
var wg sync.WaitGroup
wg.Add(4)
go work(pricing, "pricing", &wg)
go work(stock, "stock-a", &wg)
go work(stock, "stock-b", &wg)
go work(root, "root-job", &wg)
time.Sleep(120 * time.Millisecond)
fmt.Println("-- cancel stock subtree")
cancelStock() // only stock-a and stock-b stop
time.Sleep(120 * time.Millisecond)
fmt.Println("-- cancel root")
cancelRoot() // everything else stops
wg.Wait()
}Why you must always call cancel
The cancel returned by WithCancel, WithTimeout and WithDeadline must always be called, even if the work completed normally. A child context registers itself under its parent so that the parent can notify it on cancellation; if you don't call cancel, this registration and any associated timer are only released when the parent ends. If the parent is long-lived (such as a service-level context), every request leaves a little debris behind, which builds up into a memory leak. The convention is to defer cancel() immediately after obtaining it, and the lostcancel check in go vet catches cases where you forget. Calling cancel more than once is safe; after the first time it does nothing.
Step 3: WithTimeout, WithDeadline and the timeout budget
context.WithTimeout(parent, d) is equivalent to WithDeadline(parent, time.Now().Add(d)): when the deadline arrives, the context is cancelled automatically and Err() returns context.DeadlineExceeded. The key property is that a child context's deadline is never later than its parent's. If the parent has only 2 seconds left and you set a 5-second timeout on the child, the 2 seconds still apply.
This lets the "timeout budget" pass naturally along the call chain. The gateway sets 3 seconds for the whole request; by the time the order service receives it, some has been used up, and the remaining time is passed down with the context. When the order service calls the payment service, it can set an even shorter limit, to make sure it has time to handle a failure and respond instead of timing out at the same moment as its upstream.
Figure: the gateway allows 3 seconds; the order service sets a separate 1-second limit on the payment call and 500 milliseconds on the database query; when any layer expires, the calls beneath it are cancelled.
In code, the timeout takes effect as long as you pass the context to APIs that accept it:
// Snippet: passing the context to the database and a downstream HTTP call in the order service
func (s *Service) Create(ctx context.Context, o Order) error {
// The database query gets at most 500ms, but never more than the time the request itself has left.
dbCtx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()
if err := s.repo.Insert(dbCtx, o); err != nil { // internally uses db.ExecContext(dbCtx, ...)
return fmt.Errorf("create order %s: %w", o.ID, err)
}
// Call the payment service for at most 1 second.
payCtx, cancelPay := context.WithTimeout(ctx, time.Second)
defer cancelPay()
req, err := http.NewRequestWithContext(payCtx, http.MethodPost, s.paymentURL, body(o))
if err != nil {
return err
}
resp, err := s.client.Do(req)
if errors.Is(err, context.DeadlineExceeded) {
return fmt.Errorf("charge order %s: payment timeout: %w", o.ID, err)
}
if err != nil {
return fmt.Errorf("charge order %s: %w", o.ID, err)
}
defer resp.Body.Close()
// ...
return nil
}Telling who caused the timeout
context.Canceled and context.DeadlineExceeded are both sentinel errors as introduced in the previous article, checked with errors.Is. In practice they mean very different things: Canceled usually means the caller gave up (the client disconnected), which is not a problem with the service itself; logging it at Info is enough, and there's no need to respond (the other side can't receive it any more). DeadlineExceeded means something was too slow, which is worth logging and monitoring. In the boundary translation function from “Error Handling in Go: Wrapping, Sentinels and Custom Types”, a common approach is to map the former to 499 (client closed request, a non-standard but widely used status code) and the latter to 504.
Tip: Timeouts should be set in two places: "closest to the I/O" and "at the entry point of the whole request". Set only at the entry point, a single slow downstream call can eat the entire budget; set only at the I/O, several calls added together can still exceed what the upstream can wait for. How to choose values for each layer, and how they relate to retries, is discussed in depth in “Timeouts, Retries and Circuit Breakers”.
Step 4: Explain why with WithCancelCause
ctx.Err() can only tell you "it was cancelled" or "it timed out", not why. In the example of reserving stock concurrently, when the first item's insufficient stock causes the other jobs to be cancelled, the other goroutines only see context canceled, and the real reason is lost from the logs.
Go 1.20 added context.WithCancelCause: its cancel function takes an error argument, and afterwards anyone can retrieve that cause with context.Cause(ctx), while ctx.Err() still returns context.Canceled, so existing checks don't break. Go 1.21 then added WithTimeoutCause and WithDeadlineCause, which let you specify a cause for a timeout.
Let's rewrite the previous article's "reserve stock concurrently" as "cancel the others on the first failure, and keep the cause":
package main
import (
"context"
"errors"
"fmt"
"sync"
"time"
)
var ErrInsufficientStock = errors.New("inventory: insufficient stock")
// reserve simulates calling the inventory service; it respects cancellation of ctx.
func reserve(ctx context.Context, sku string, d time.Duration) error {
select {
case <-ctx.Done():
return fmt.Errorf("reserve %s: %w", sku, context.Cause(ctx))
case <-time.After(d):
}
if sku == "sold-out" {
return fmt.Errorf("reserve %s: %w", sku, ErrInsufficientStock)
}
return nil
}
// reserveAll reserves all items concurrently; the first error cancels the other jobs and becomes the cancellation cause.
func reserveAll(ctx context.Context, skus map[string]time.Duration) error {
ctx, cancel := context.WithCancelCause(ctx)
defer cancel(nil)
var (
wg sync.WaitGroup
once sync.Once
firstErr error
)
for sku, d := range skus {
wg.Go(func() {
if err := reserve(ctx, sku, d); err != nil {
once.Do(func() {
firstErr = err
cancel(err) // the cause reaches the other goroutines via context.Cause
})
}
})
}
wg.Wait()
return firstErr
}
func main() {
// The whole operation gets at most 1 second; the cause on timeout can be customised too.
ctx, cancel := context.WithTimeoutCause(context.Background(), time.Second,
errors.New("checkout: reservation budget exceeded"))
defer cancel()
err := reserveAll(ctx, map[string]time.Duration{
"book": 300 * time.Millisecond,
"sold-out": 50 * time.Millisecond, // fails quickly
"lamp": 400 * time.Millisecond,
})
fmt.Println("result:", err)
fmt.Println("is insufficient stock:", errors.Is(err, ErrInsufficientStock))
}This program returns after about 50 milliseconds rather than waiting for the slowest 400 milliseconds; the errors returned by the cancelled goroutines wrap the real cause (insufficient stock), not just context canceled. This is exactly what WithContext in golang.org/x/sync/errgroup does: it also uses WithCancelCause internally, so with errgroup you can likewise get the first error through context.Cause.
Step 5: AfterFunc: run clean-up on cancellation
Some blocking operations don't accept a context, such as old-style network protocol libraries, sync.Cond.Wait, or a connection that can only be interrupted with Close(). The common approach used to be to start a separate goroutine that waits on <-ctx.Done() and then calls Close(), but that goroutine is easy to forget to end after the operation completes normally, and it becomes a leak.
context.AfterFunc(ctx, f), added in Go 1.21, standardises this: after ctx ends, it runs f in a new goroutine; it returns a stop function, and calling stop() before f has started cancels the registration and returns true to indicate it was successfully prevented.
// Snippet: making a read that doesn't support context cancellable
func readWithContext(ctx context.Context, conn net.Conn, buf []byte) (int, error) {
// When ctx ends, set the read deadline in the past so the blocked Read returns immediately.
stop := context.AfterFunc(ctx, func() {
conn.SetReadDeadline(time.Unix(1, 0))
})
n, err := conn.Read(buf)
if !stop() {
// stop returned false: AfterFunc has already fired (or is running), so we interrupted the Read.
return n, context.Cause(ctx)
}
return n, err
}AfterFunc is also often used to bridge "cancellation" to other notification mechanisms, such as waking a goroutine waiting on a sync.Cond, or removing yourself from a wait queue when a request is cancelled. It doesn't block the caller, and you don't have to manage that goroutine's lifecycle yourself.
Step 6: WithValue: only for request-scoped data
context.WithValue(parent, key, val) attaches a value to a context, and ctx.Value(key) searches from the current node up through its parents, returning the first matching key it finds.
Figure: when the handler calls ctx.Value(requestIDKey), the search starts at the innermost timeout node and walks upwards, finding the request ID in the node added by the middleware.
This mechanism is very convenient, and also very easy to abuse. To decide whether a value belongs in the context, you can use this table:
| Suitable for the context | Not suitable for the context |
|---|---|
| Request ID, trace information | Database connection pools, logger instances, configuration (pass them via dependency injection) |
| The authenticated user identity, tenant | A function's required parameters (such as the order ID to look up) |
| Request locale, client IP and other information parsed by middleware | Optional parameters, feature flags (they make the function signature lie) |
| Data that crosses API boundaries and matches the request's lifecycle | Mutable state that gets modified |
The principle: if you remove the value, the function should still work correctly (just with less logging or tracing information). If the function stops working without it, it is a required parameter and should be in the function signature, where the compiler can check it for you. Dependencies such as a database connection pool should be passed into structs through constructors, which is explained in detail in “Layered Architecture and Dependency Injection in Go”.
Keys should be unexported custom types
WithValue compares keys with ==. If you use the string "requestID" as a key, any package may use the same string and they overwrite each other. The convention is to define an unexported type in the package as the key and provide exported accessor functions, so that only this package can read and write the value, with type safety guaranteed. The complete program in the next step demonstrates this.
Step 7: WithoutCancel: work that must continue after the request ends
Sometimes, once a request has been handled, there is still work to do that the client shouldn't have to wait for: writing an audit record, sending an "order created" notification. If you start a background goroutine with r.Context() directly, the context is cancelled as soon as the handler returns and the background work fails with it; if you use context.Background() instead, you lose values such as the request ID and the logs no longer line up.
context.WithoutCancel(ctx), added in Go 1.21, solves exactly this problem: the context it returns keeps all of the parent's values but is not cancelled with the parent and has no deadline. Note that once it is detached from cancellation, the work has no time limit at all, so you usually wrap it in a timeout of your own.
The complete program below ties Steps 6 and 7 together: the middleware puts the request ID into the context, the handler and the slog logs read it back, and after responding, the handler writes an audit record using WithoutCancel plus its own timeout.
package main
import (
"context"
"fmt"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"sync"
"time"
)
// ctxKey is an unexported type, so other packages can't create the same key.
type ctxKey int
const requestIDKey ctxKey = iota
func WithRequestID(ctx context.Context, id string) context.Context {
return context.WithValue(ctx, requestIDKey, id)
}
func RequestID(ctx context.Context) string {
id, _ := ctx.Value(requestIDKey).(string)
return id // returns an empty string if absent, so callers still work
}
// requestIDMiddleware is middleware: it takes the request ID from the header or generates one, and puts it in the context.
func requestIDMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.Header.Get("X-Request-ID")
if id == "" {
id = fmt.Sprintf("req-%d", time.Now().UnixNano())
}
next.ServeHTTP(w, r.WithContext(WithRequestID(r.Context(), id)))
})
}
type server struct {
log *slog.Logger
bg sync.WaitGroup // tracks background work; wait for it when the service shuts down
}
func (s *server) writeAudit(ctx context.Context, orderID string) {
select {
case <-time.After(50 * time.Millisecond): // simulate writing to the audit table
s.log.InfoContext(ctx, "audit written", "request_id", RequestID(ctx), "order_id", orderID)
case <-ctx.Done():
s.log.WarnContext(ctx, "audit aborted", "request_id", RequestID(ctx), "cause", context.Cause(ctx))
}
}
func (s *server) createOrder(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
orderID := "o-1001"
s.log.InfoContext(ctx, "order created", "request_id", RequestID(ctx), "order_id", orderID)
// Background work: keep values such as the request ID, but don't cancel with the request; set a separate 2-second limit.
bgCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Second)
s.bg.Go(func() {
defer cancel()
s.writeAudit(bgCtx, orderID)
})
w.WriteHeader(http.StatusCreated)
fmt.Fprintln(w, orderID)
}
func main() {
s := &server{log: slog.New(slog.NewTextHandler(os.Stdout, nil))}
mux := http.NewServeMux()
mux.HandleFunc("POST /orders", s.createOrder)
h := requestIDMiddleware(mux)
req := httptest.NewRequest(http.MethodPost, "/orders", nil)
req.Header.Set("X-Request-ID", "req-abc")
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req) // after the handler returns, r.Context() would be cancelled in a real server
fmt.Print("response: ", rec.Code, " ", rec.Body.String())
s.bg.Wait() // the audit still completes, carrying the same request ID
}A few key points:
- The middleware uses
r.WithContextto create a copy of the request with the new context and passes that down; this is the standard way to attach values in an HTTP handler chain, and “net/http and Middleware in Go” extends it into a full middleware chain. slog'sInfoContextpasses the context to the handler; in practice you often write a customslog.Handlerthat automatically extracts the request ID and trace ID from the context and adds them to every log line, so you don't have to pass"request_id"by hand each time. “Observability in Go: Logs, Metrics and Tracing” implements this handler.- Background work is tracked with a
sync.WaitGroup. When the service shuts down, wait for it to finish or time out, or audit records may be cut off halfway; “Configuration and Graceful Shutdown in Go” connects this up. - A more reliable approach is to hand this kind of "do it later" work to a message queue rather than keeping it in process memory, which is the problem tackled by “Message Queues and Event-Driven Design” and “Distributed Transactions: Sagas and the Outbox Pattern”.
Common pitfalls
- Forgetting to call
cancel: the child context and its timer are only released when the parent ends, so a long-lived parent accumulates leaks.defer cancel()immediately after obtaining it. - Goroutines not checking
ctx.Done(): a context is only a signal; it doesn't forcibly interrupt anything. Long loops and blocking operations must listen for cancellation in aselect, or use APIs that accept a context. - Storing a context in a struct field: its lifecycle becomes tied to the struct and the cancellation semantics become confused. Pass it as the first parameter on every call.
- Continuing to use
r.Context()after the handler returns: background work is cancelled immediately. Usecontext.WithoutCanceland add your own timeout. - Starting background work with
context.Background(): you lose the request ID and trace information, so the logs don't line up; and there is no limit at all either. - Using a string or built-in type as a Value key: different packages may overwrite each other. Use an unexported custom type and provide accessor functions.
- Stuffing dependencies or required parameters into the context: the function signature is no longer honest and the compiler can't check it for you. Only put in request-scoped data that "still works if removed".
- Alerting on
Canceledas a server error: clients giving up is normal and shouldn't trigger alerts;DeadlineExceededis what deserves attention. Distinguish them witherrors.Is. - Setting a longer timeout on a child than its parent and expecting it to apply: deadlines only get shorter, never longer. Work that needs more time should be detached from the request lifecycle (
WithoutCancelor a message queue).
Key takeaways
context.Contextcarries a cancellation signal, a deadline and request-scoped values; it is a function's first parameter,ctx, is not stored in structs, and is never passed asnil.- The
With...functions derive child contexts, forming a cancellation tree: cancellation propagates downwards, not upwards or to siblings; the returnedcancelmust always be called. WithTimeout/WithDeadlinelet the timeout budget pass along the call chain, and a child's deadline is never later than its parent's; distinguishCanceledfromDeadlineExceededwitherrors.Is.WithCancelCause,WithTimeoutCauseandcontext.Causekeep the real reason for cancellation, which suits "the first error cancels the other jobs"; errgroup uses it internally too.AfterFuncruns clean-up when a context ends, which makes blocking operations that don't support context cancellable as well, and the registration is cancelled withstop.WithValueonly holds request-scoped data that still works if removed; keys are unexported custom types with accessor functions.WithoutCancellets background work keep the values but detach from the request's cancellation; remember to add your own timeout and wait for it on shutdown.
Next
With that, all four pieces of Part 1, Go foundations, are in place: modules and directories, errors, concurrency and context. But the order service doesn't yet offer a real HTTP API. The next article, “net/http and Middleware in Go”, uses the standard library's routing and middleware to assemble everything from these four articles into an order API that handles requests, writes logs and translates errors uniformly.