Docs executáveis de Go: Pacote context

Q: Para que serve o context em Go?

Um context.Context diz a uma função, e a tudo o que ela chama, quando desistir: porque quem chamou cancelou, porque um prazo passou ou porque o cliente se desconectou. Ele também pode carregar valores do escopo da requisição, como um ID de requisição. Por convenção, é o primeiro parâmetro e se chama ctx.

Q: Qual a diferença entre context.Background e context.TODO?

Os dois devolvem um context vazio, que nunca é cancelado e não tem prazo nem valores. Eles se comportam de forma idêntica. Background() é a raiz para o main, os testes e a configuração de nível superior. TODO() marca um lugar onde um context de verdade deveria ser passado, mas o código ao redor ainda não tem um, o que facilita encontrá-lo depois.

Q: Por que preciso chamar cancel depois de context.WithTimeout?

WithTimeout, WithDeadline e WithCancel registram o novo context no pai e podem iniciar um timer. Chamar cancel libera esses recursos assim que você termina, em vez de quando o timeout dispara ou o pai é cancelado. Escreva defer cancel() logo depois de criá-lo; o go vet avisa quando uma função cancel é descartada.

Q: O que significa "context deadline exceeded" em Go?

É o texto de context.DeadlineExceeded, o erro que ctx.Err() devolve quando o prazo de um context passou. Funções que respeitam o context, como clientes HTTP e drivers de banco de dados, o devolvem (muitas vezes empacotado) quando o tempo acaba. Verifique com errors.Is(err, context.DeadlineExceeded).

Q: Devo usar context.WithValue para passar parâmetros?

Não. Use-o só para dados do escopo da requisição que atravessam fronteiras de API e que as funções no meio do caminho não precisam conhecer, como um trace ID ou o usuário autenticado. Tudo o que uma função precisa para fazer o seu trabalho pertence aos parâmetros dela, onde o compilador verifica.

Um timeout em dez linhas

A função do context.Context é dizer ao código quando parar. Aqui uma operação lenta recebe 50 ms e desiste quando o context manda:

package main

import (
	"context"
	"fmt"
	"time"
)

func slowQuery(ctx context.Context, d time.Duration) (string, error) {
	select {
	case <-time.After(d): // stands in for real work
		return "rows", nil
	case <-ctx.Done():
		return "", ctx.Err()
	}
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()

	res, err := slowQuery(ctx, 10*time.Millisecond)
	fmt.Println("fast query:", res, err)

	res, err = slowQuery(ctx, 200*time.Millisecond)
	fmt.Println("slow query:", res, err)
}

A primeira chamada termina em 10 ms e devolve rows <nil>. A segunda precisaria de 200 ms, mas o context expira em 50 ms (contados a partir da criação dele), então ela devolve context deadline exceeded.

Nada é interrompido à força. O Go não tem como matar uma goroutine de fora. Um context é um sinal, e o código precisa verificá-lo: fazendo select em ctx.Done(), verificando ctx.Err() entre as etapas ou passando ctx para chamadas de biblioteca (http.NewRequestWithContext, db.QueryContext, exec.CommandContext) que verificam por você.

A interface Context

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

Método	Devolve
`Done()`	um channel que é fechado quando o context é cancelado ou expira (`nil` para um context que nunca pode ser cancelado)
`Err()`	`nil` enquanto ativo, depois `context.Canceled` ou `context.DeadlineExceeded`
`Deadline()`	o prazo e `true`, ou `ok == false` se não houver prazo
`Value(key)`	o valor guardado sob `key` neste context ou em um ancestral, ou `nil`

Contexts são imutáveis. Você nunca altera um; você deriva um filho dele com uma das funções With, e o filho acrescenta um sinal de cancelamento, um prazo ou um valor.

De onde vem um context

Toda árvore de contexts começa em uma raiz:

context.Background() para o main, o init, os testes e a configuração de nível superior de servidores.
context.TODO() quando uma função deveria receber um context, mas quem chama ainda não tem um. Ele se comporta exatamente como o Background; o nome é uma marca para refatoração futura.

Dentro de um handler HTTP você não cria uma raiz. Você usa r.Context(), que o servidor cancela quando o cliente se desconecta ou quando o handler retorna.

WithCancel: parar sob demanda

context.WithCancel devolve um context filho e uma função cancel. Chamar cancel fecha o channel Done do filho e os channels Done de tudo o que foi derivado dele.

package main

import (
	"context"
	"fmt"
)

func producer(ctx context.Context, out chan<- int) {
	defer close(out)
	for i := 1; ; i++ {
		select {
		case out <- i:
		case <-ctx.Done():
			return // stop and close out
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	nums := make(chan int)
	go producer(ctx, nums)

	sum := 0
	for n := range nums {
		sum += n
		if n == 5 {
			cancel() // the consumer has what it needs
			break
		}
	}
	fmt.Println("sum of first five:", sum)

	for range nums { // wait until the producer has closed the channel
	}
	fmt.Println("producer has exited:", ctx.Err())
}

O envio do produtor fica em um select ao lado de ctx.Done(). É isso que permite que ele pare: um out <- i puro bloquearia para sempre assim que o consumidor parasse de ler, e a goroutine vazaria. O for range nums final espera até o produtor fechar o channel. Enquanto ele esvazia, o produtor ainda pode conseguir enviar um ou dois valores, porque quando os dois cases do select estão prontos o Go escolhe um ao acaso; o cancelamento é rápido, não instantâneo.

cancel pode ser chamada mais de uma vez e de qualquer goroutine. Só a primeira chamada faz algo.

WithTimeout e WithDeadline

WithTimeout(parent, d) é WithDeadline(parent, time.Now().Add(d)). Use um timeout para "no máximo este tempo" e um deadline quando você tem um horário absoluto.

Quando o tempo passa, Done fecha e Err devolve context.DeadlineExceeded. Se cancel for chamada antes, Err devolve context.Canceled. Verifique qual dos dois com errors.Is, porque as bibliotecas costumam empacotar o erro:

package main

import (
	"context"
	"errors"
	"fmt"
	"time"
)

func work(ctx context.Context) error {
	select {
	case <-time.After(100 * time.Millisecond):
		return nil
	case <-ctx.Done():
		return fmt.Errorf("work: %w", ctx.Err())
	}
}

func describe(err error) string {
	switch {
	case err == nil:
		return "finished"
	case errors.Is(err, context.DeadlineExceeded):
		return "timed out: " + err.Error()
	case errors.Is(err, context.Canceled):
		return "cancelled: " + err.Error()
	default:
		return "failed: " + err.Error()
	}
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
	defer cancel()
	fmt.Println(describe(work(ctx)))

	ctx2, cancel2 := context.WithCancel(context.Background())
	cancel2()
	fmt.Println(describe(work(ctx2)))

	deadline, ok := ctx.Deadline()
	fmt.Println("has deadline:", ok, "in the past:", time.Now().After(deadline))
}

Sempre chame cancel, mesmo para um timeout que vai disparar sozinho. O context segura um timer e uma posição no pai até que uma dessas coisas aconteça, e defer cancel() libera os dois assim que a função retorna. O go vet reporta uma função cancel descartada: the cancel function returned by context.WithTimeout should be called, not discarded, to avoid a context leak.

Filhos não sobrevivem aos pais

Contexts formam uma árvore. Cancelar um pai cancela todos os descendentes. Um filho pode ter um prazo mais curto que o do pai, nunca mais longo: o prazo mais cedo sempre vence.

package main

import (
	"context"
	"fmt"
	"time"
)

func main() {
	parent, cancelParent := context.WithTimeout(context.Background(), 30*time.Millisecond)
	defer cancelParent()

	// Asking for 10 seconds does not extend the parent's 30 ms.
	child, cancelChild := context.WithTimeout(parent, 10*time.Second)
	defer cancelChild()

	d, _ := child.Deadline()
	fmt.Println("child deadline is within 30ms:", time.Until(d) <= 30*time.Millisecond)

	<-child.Done()
	fmt.Println("child:", child.Err())

	// Cancelling a child never affects the parent.
	p2, cancelP2 := context.WithCancel(context.Background())
	defer cancelP2()
	c2, cancelC2 := context.WithCancel(p2)
	cancelC2()
	fmt.Println("c2:", c2.Err(), "| p2:", p2.Err())
}

É isso que torna os contexts úteis entre camadas. Um handler HTTP recebe um context que morre junto com a requisição; uma chamada de banco de dados três camadas abaixo deriva dele um timeout de 2 segundos. Se o cliente desligar depois de 100 ms, a consulta é cancelada nesse momento, não dois segundos depois.

Sempre faça select em ctx.Done() quando bloquear

Qualquer goroutine que espera (em um envio de channel, um recebimento, um timer) deve esperar em ctx.Done() ao mesmo tempo. Para laços que só usam CPU e nunca bloqueiam, verifique ctx.Err() de tempos em tempos:

for i, item := range items {
	if i%1000 == 0 {
		if err := ctx.Err(); err != nil {
			return err
		}
	}
	process(item)
}

Use time.After dentro de um select para uma espera simples, mas prefira um timer que você pode parar (ou um timeout de context) quando a espera puder ser cancelada com frequência.

Causas de cancelamento (Go 1.20 e 1.21)

ctx.Err() só diz canceled ou deadline exceeded. Para registrar o porquê, use as variantes Cause:

package main

import (
	"context"
	"errors"
	"fmt"
)

var errShutdown = errors.New("server shutting down")

func main() {
	ctx, cancel := context.WithCancelCause(context.Background())
	cancel(errShutdown)

	fmt.Println("Err:  ", ctx.Err())
	fmt.Println("Cause:", context.Cause(ctx))
	fmt.Println("is shutdown:", errors.Is(context.Cause(ctx), errShutdown))
}

WithCancelCause chegou no Go 1.20, e WithTimeoutCause e WithDeadlineCause no Go 1.21. Err continua devolvendo os valores padrão para que as verificações existentes continuem funcionando; context.Cause dá o detalhe.

WithValue, com moderação

context.WithValue(parent, key, value) anexa um valor. ctx.Value(key) o procura pela cadeia de pais.

package main

import (
	"context"
	"fmt"
)

// An unexported key type: no other package can collide with it.
type ctxKey int

const requestIDKey ctxKey = 0

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
}

func handle(ctx context.Context) {
	fmt.Printf("[%s] handling request\n", RequestID(ctx))
}

func main() {
	ctx := WithRequestID(context.Background(), "req-42")
	handle(ctx)
	handle(context.Background()) // no ID set: empty string
}

Regras para valores:

Use um tipo não exportado para as chaves, nunca uma string simples. Dois pacotes que usam "user" sobrescreveriam um ao outro. (O go vet não pega isso; o staticcheck pega.)
Envolva o acesso em funções auxiliares tipadas como WithRequestID e RequestID, para que quem chama nunca veja any nem a chave.
Guarde só dados do escopo da requisição que atravessam APIs: IDs de trace e de requisição, o usuário autenticado, um logger. Nunca parâmetros opcionais, conexões de banco de dados ou configuração. Esses pertencem aos argumentos de função ou a campos de struct, onde o compilador consegue verificá-los e quem lê consegue vê-los.
A busca percorre a cadeia um pai de cada vez, então cada valor que você acrescenta deixa a busca pelos outros um passo mais longa.

Convenções

ctx context.Context é o primeiro parâmetro de qualquer função que faz I/O, bloqueia ou chama algo que faz isso: func Fetch(ctx context.Context, url string) error.
Não guarde um context em uma struct. Passe-o em cada chamada de método. Um context pertence a uma operação, e uma struct normalmente vive mais que ela. (A exceção é um tipo que representa uma única operação, como http.Request.)
Nunca passe nil como context. Use context.TODO() se não tiver nada melhor.
Devolva ctx.Err(), ou empacote-o com %w, quando você parar por causa do context, para que quem chama consiga diferenciar um timeout de uma falha real.

Context em servidores e clientes HTTP

Do lado do servidor: r.Context() é cancelado quando o cliente se desconecta, quando o handler retorna ou quando um stream HTTP/2 é resetado. Do lado do cliente: http.NewRequestWithContext faz a requisição respeitar um timeout ou um cancelamento. Este programa executa as duas pontas por meio do httptest:

package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"time"
)

func main() {
	serverSaw := make(chan error, 1)

	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		select {
		case <-time.After(500 * time.Millisecond): // a slow report
			fmt.Fprintln(w, "report ready")
			serverSaw <- nil
		case <-r.Context().Done():
			serverSaw <- r.Context().Err() // client went away: stop working
		}
	}))
	defer srv.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL, nil)
	if err != nil {
		panic(err)
	}
	resp, err := http.DefaultClient.Do(req)
	if err == nil {
		body, _ := io.ReadAll(resp.Body)
		resp.Body.Close()
		fmt.Print("client got: ", string(body))
	} else {
		fmt.Println("client: deadline exceeded:", errors.Is(err, context.DeadlineExceeded))
	}

	fmt.Println("server handler stopped with:", <-serverSaw)
}

O cliente desiste em 50 ms e fecha a conexão. O servidor percebe, o context da requisição é cancelado, e o handler para em vez de gastar mais 450 milissegundos em um relatório que ninguém vai ler. Em um handler real, você passa r.Context() para todas as chamadas de banco de dados e HTTP, e todas param juntas.

Outras funções auxiliares (Go 1.21)

context.WithoutCancel(ctx) devolve um context com os mesmos valores, mas que não é cancelado quando ctx é. Use-o para trabalho que precisa terminar depois do fim da requisição, como gravar um log de auditoria.
context.AfterFunc(ctx, f) executa f na sua própria goroutine quando ctx termina, e devolve uma função stop para cancelar o registro.

Erros comuns

Não chamar cancel. Sempre use defer cancel() logo depois de WithCancel, WithTimeout ou WithDeadline.
Iniciar uma goroutine que ignora o ctx. Se ela bloqueia sem fazer select em ctx.Done(), cancelar não faz nada e a goroutine vaza.
Criar um context.Background() novo no fundo de uma cadeia de chamadas. Isso corta a ligação com o prazo e o cancelamento de quem chamou. Passe o ctx que você recebeu.
Comparar erros com ==. Use errors.Is(err, context.DeadlineExceeded); a maioria das bibliotecas o empacota.
Usar WithValue para dependências. Uma conexão de banco escondida em um context é um parâmetro que o compilador não consegue mais verificar.
Esperar que o cancelamento seja instantâneo. O código só percebe na próxima verificação. Um laço longo sem verificação continua executando.

Perguntas frequentes

Para que serve o context em Go?

Um context.Context diz a uma função, e a tudo o que ela chama, quando desistir: porque quem chamou cancelou, porque um prazo passou ou porque o cliente se desconectou. Ele também pode carregar valores do escopo da requisição, como um ID de requisição. Por convenção, é o primeiro parâmetro e se chama ctx.

Qual a diferença entre context.Background e context.TODO?

Os dois devolvem um context vazio, que nunca é cancelado e não tem prazo nem valores. Eles se comportam de forma idêntica. Background() é a raiz para o main, os testes e a configuração de nível superior. TODO() marca um lugar onde um context de verdade deveria ser passado, mas o código ao redor ainda não tem um, o que facilita encontrá-lo depois.

Por que preciso chamar cancel depois de context.WithTimeout?

WithTimeout, WithDeadline e WithCancel registram o novo context no pai e podem iniciar um timer. Chamar cancel libera esses recursos assim que você termina, em vez de quando o timeout dispara ou o pai é cancelado. Escreva defer cancel() logo depois de criá-lo; o go vet avisa quando uma função cancel é descartada.

O que significa "context deadline exceeded" em Go?

É o texto de context.DeadlineExceeded, o erro que ctx.Err() devolve quando o prazo de um context passou. Funções que respeitam o context, como clientes HTTP e drivers de banco de dados, o devolvem (muitas vezes empacotado) quando o tempo acaba. Verifique com errors.Is(err, context.DeadlineExceeded).

Devo usar context.WithValue para passar parâmetros?

Não. Use-o só para dados do escopo da requisição que atravessam fronteiras de API e que as funções no meio do caminho não precisam conhecer, como um trace ID ou o usuário autenticado. Tudo o que uma função precisa para fazer o seu trabalho pertence aos parâmetros dela, onde o compilador verifica.

Conceitos relacionados