Docs ejecutables de Go: Paquete context

Q: ¿Para qué sirve context en Go?

Un context.Context le dice a una función, y a todo lo que esta llama, cuándo rendirse: porque quien llama canceló, porque pasó un deadline o porque el cliente se desconectó. También puede transportar valores asociados a la petición, como un ID de petición. Por convención es el primer parámetro y se llama ctx.

Q: ¿Qué diferencia hay entre context.Background y context.TODO?

Las dos devuelven un context vacío que nunca se cancela y no tiene deadline ni valores. Se comportan igual. Background() es la raíz para main, los tests y la configuración de nivel superior. TODO() marca un sitio donde debería pasarse un context real pero el código de alrededor todavía no tiene uno, lo que facilita encontrarlo después.

Q: ¿Por qué tengo que llamar a cancel después de context.WithTimeout?

WithTimeout, WithDeadline y WithCancel registran el nuevo context en su padre y pueden arrancar un temporizador. Llamar a cancel libera esos recursos en cuanto terminas, en lugar de cuando salta el timeout o se cancela el padre. Escribe defer cancel() justo después de crearlo; go vet avisa cuando se descarta una función cancel.

Q: ¿Qué significa "context deadline exceeded" en Go?

Es el texto de context.DeadlineExceeded, el error que devuelve ctx.Err() una vez que ha pasado el deadline de un context. Las funciones que respetan el context, como los clientes HTTP y los drivers de base de datos, lo devuelven (a menudo envuelto) cuando se quedan sin tiempo. Compruébalo con errors.Is(err, context.DeadlineExceeded).

Q: ¿Debo usar context.WithValue para pasar parámetros?

No. Úsalo solo para datos de la petición que atraviesan límites de API y que las funciones intermedias no necesitan conocer, como un ID de traza o el usuario autenticado. Todo lo que una función necesita para hacer su trabajo va en sus parámetros, donde el compilador lo comprueba.

Un timeout en diez líneas

El trabajo de context.Context es decirle al código cuándo parar. Aquí una operación lenta tiene 50 ms y se rinde cuando el context lo indica:

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)
}

La primera llamada termina en 10 ms y devuelve rows <nil>. La segunda necesitaría 200 ms, pero el context expira a los 50 ms (contados desde que se creó), así que devuelve context deadline exceeded.

Nada se detiene a la fuerza. Go no tiene forma de matar una goroutine desde fuera. Un context es una señal, y el código tiene que comprobarla: haciendo select sobre ctx.Done(), comprobando ctx.Err() entre pasos o pasando ctx a llamadas de librería (http.NewRequestWithContext, db.QueryContext, exec.CommandContext) que lo comprueban por ti.

La interfaz Context

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

Método	Devuelve
`Done()`	un channel que se cierra cuando el context se cancela o expira (`nil` para un context que nunca se puede cancelar)
`Err()`	`nil` mientras está activo, luego `context.Canceled` o `context.DeadlineExceeded`
`Deadline()`	el deadline y `true`, o `ok == false` si no hay
`Value(key)`	el valor guardado bajo `key` en este context o en un ancestro, o `nil`

Los contexts son inmutables. Nunca cambias uno; derivas un hijo con una de las funciones With, y el hijo añade una señal de cancelación, un deadline o un valor.

De dónde sale un context

Todo árbol de contexts empieza en una raíz:

context.Background() para main, init, los tests y la configuración de nivel superior de los servidores.
context.TODO() cuando una función debería recibir un context pero quien la llama todavía no tiene uno. Se comporta exactamente igual que Background; el nombre es una marca para refactorizar más adelante.

Dentro de un handler HTTP no creas una raíz. Usas r.Context(), que el servidor cancela cuando el cliente se desconecta o el handler retorna.

WithCancel: parar cuando quieras

context.WithCancel devuelve un context hijo y una función cancel. Llamar a cancel cierra el channel Done del hijo y los channels Done de todo lo que derive de él.

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())
}

El envío del productor está en un select junto a ctx.Done(). Eso es lo que le permite parar: un out <- i a secas se bloquearía para siempre en cuanto el consumidor dejara de leer, y la goroutine se fugaría. El for range nums final espera hasta que el productor ha cerrado el channel. Mientras se vacía, el productor todavía puede llegar a enviar un valor o dos, porque cuando los dos casos de su select están listos Go elige uno al azar; la cancelación es rápida, no instantánea.

Se puede llamar a cancel más de una vez y desde cualquier goroutine. Solo la primera llamada hace algo.

WithTimeout y WithDeadline

WithTimeout(parent, d) equivale a WithDeadline(parent, time.Now().Add(d)). Usa un timeout para "como mucho este tiempo" y un deadline cuando tengas una hora absoluta.

Cuando pasa el tiempo, Done se cierra y Err devuelve context.DeadlineExceeded. Si antes se llama a cancel, Err devuelve context.Canceled. Comprueba cuál con errors.Is, porque las librerías suelen envolver el error:

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))
}

Llama siempre a cancel, incluso con un timeout que saltará solo. El context mantiene un temporizador y un hueco en su padre hasta que ocurre una de las dos cosas, y defer cancel() libera ambos en cuanto la función retorna. go vet informa de una función cancel descartada: the cancel function returned by context.WithTimeout should be called, not discarded, to avoid a context leak.

Los hijos no pueden sobrevivir a sus padres

Los contexts forman un árbol. Cancelar un padre cancela a todos sus descendientes. Un hijo puede tener un deadline más corto que su padre, nunca más largo: siempre gana el deadline más temprano.

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())
}

Esto es lo que hace útiles a los contexts entre capas. Un handler HTTP recibe un context que muere con la petición; una llamada a la base de datos tres capas más abajo deriva de él un timeout de 2 segundos. Si el cliente cuelga a los 100 ms, la consulta se cancela en ese momento, no dos segundos después.

Haz siempre select sobre ctx.Done() cuando te bloquees

Cualquier goroutine que espera (un envío a un channel, una recepción, un temporizador) debería esperar a la vez en ctx.Done(). En bucles de cómputo que nunca se bloquean, comprueba ctx.Err() de vez en cuando:

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

Usa time.After dentro de un select para una espera sencilla, pero prefiere un temporizador que puedas detener (o un timeout de context) cuando la espera pueda cancelarse a menudo.

Causas de cancelación (Go 1.20 y 1.21)

ctx.Err() solo dice canceled o deadline exceeded. Para registrar el motivo, usa las 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 llegó en Go 1.20, y WithTimeoutCause y WithDeadlineCause en Go 1.21. Err sigue devolviendo los valores estándar para que las comprobaciones existentes sigan funcionando; context.Cause da el detalle.

WithValue, con moderación

context.WithValue(parent, key, value) adjunta un valor. ctx.Value(key) lo busca subiendo por la cadena de padres.

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
}

Reglas para los valores:

Usa un tipo no exportado para las claves, nunca un string a secas. Dos paquetes que usen "user" se sobrescribirían. (go vet no lo detecta; staticcheck sí.)
Envuelve el acceso en funciones auxiliares tipadas como WithRequestID y RequestID, para que quien llama nunca vea any ni la clave.
Guarda solo datos de la petición que atraviesan APIs: IDs de traza y de petición, el usuario autenticado, un logger. Nunca parámetros opcionales, conexiones a la base de datos ni configuración. Eso va en argumentos de función o campos de struct, donde el compilador puede comprobarlo y quien lee el código puede verlo.
La búsqueda recorre la cadena de padre en padre, así que cada valor que añades alarga un paso la búsqueda de los demás.

Convenciones

ctx context.Context es el primer parámetro de cualquier función que hace I/O, se bloquea o llama a algo que lo hace: func Fetch(ctx context.Context, url string) error.
No guardes un context en un struct. Pásalo en cada llamada a método. Un context pertenece a una operación, y un struct suele vivir más que ella. (La excepción es un tipo que representa una sola operación, como http.Request.)
Nunca pases nil como context. Usa context.TODO() si no tienes nada mejor.
Devuelve ctx.Err(), o envuélvelo con %w, cuando pares por el context, para que quien llama pueda distinguir un timeout de un fallo real.

Context en servidores y clientes HTTP

En el servidor: r.Context() se cancela cuando el cliente se desconecta, cuando el handler retorna o cuando se reinicia un stream HTTP/2. En el cliente: http.NewRequestWithContext hace que la petición respete un timeout o una cancelación. Este programa ejecuta los dos extremos mediante 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)
}

El cliente se rinde a los 50 ms y cierra la conexión. El servidor lo nota, su context de petición se cancela y el handler se detiene en lugar de dedicar 450 milisegundos más a un informe que nadie va a leer. En un handler real pasas r.Context() a cada llamada a la base de datos y HTTP, y todas se detienen a la vez.

Otras funciones auxiliares (Go 1.21)

context.WithoutCancel(ctx) devuelve un context con los mismos valores que no se cancela cuando se cancela ctx. Úsalo para trabajo que debe terminar después de que acabe la petición, como escribir un log de auditoría.
context.AfterFunc(ctx, f) ejecuta f en su propia goroutine cuando ctx termina, y devuelve una función stop para anular el registro.

Errores comunes

No llamar a cancel. Haz siempre defer cancel() justo después de WithCancel, WithTimeout o WithDeadline.
Lanzar una goroutine que ignora ctx. Si se bloquea sin hacer select sobre ctx.Done(), cancelar no hace nada y la goroutine se fuga.
Crear un context.Background() nuevo en lo profundo de una cadena de llamadas. Corta el vínculo con el deadline y la cancelación de quien llama. Pasa el ctx que recibiste.
Comparar errores con ==. Usa errors.Is(err, context.DeadlineExceeded); la mayoría de librerías lo envuelven.
Usar WithValue para dependencias. Una conexión a la base de datos escondida en un context es un parámetro que el compilador ya no puede comprobar.
Esperar que la cancelación sea instantánea. El código solo se entera en su siguiente comprobación. Un bucle largo sin comprobación sigue ejecutándose.

Preguntas frecuentes

¿Para qué sirve context en Go?

Un context.Context le dice a una función, y a todo lo que esta llama, cuándo rendirse: porque quien llama canceló, porque pasó un deadline o porque el cliente se desconectó. También puede transportar valores asociados a la petición, como un ID de petición. Por convención es el primer parámetro y se llama ctx.

¿Qué diferencia hay entre context.Background y context.TODO?

Las dos devuelven un context vacío que nunca se cancela y no tiene deadline ni valores. Se comportan igual. Background() es la raíz para main, los tests y la configuración de nivel superior. TODO() marca un sitio donde debería pasarse un context real pero el código de alrededor todavía no tiene uno, lo que facilita encontrarlo después.

¿Por qué tengo que llamar a cancel después de context.WithTimeout?

WithTimeout, WithDeadline y WithCancel registran el nuevo context en su padre y pueden arrancar un temporizador. Llamar a cancel libera esos recursos en cuanto terminas, en lugar de cuando salta el timeout o se cancela el padre. Escribe defer cancel() justo después de crearlo; go vet avisa cuando se descarta una función cancel.

¿Qué significa "context deadline exceeded" en Go?

Es el texto de context.DeadlineExceeded, el error que devuelve ctx.Err() una vez que ha pasado el deadline de un context. Las funciones que respetan el context, como los clientes HTTP y los drivers de base de datos, lo devuelven (a menudo envuelto) cuando se quedan sin tiempo. Compruébalo con errors.Is(err, context.DeadlineExceeded).

¿Debo usar context.WithValue para pasar parámetros?

No. Úsalo solo para datos de la petición que atraviesan límites de API y que las funciones intermedias no necesitan conocer, como un ID de traza o el usuario autenticado. Todo lo que una función necesita para hacer su trabajo va en sus parámetros, donde el compilador lo comprueba.

Conceptos relacionados