Docs Go exécutables : Package context

Q: À quoi sert context en Go ?

Un context.Context indique à une fonction, et à tout ce qu'elle appelle, quand abandonner : parce que l'appelant a annulé, parce qu'une échéance est passée, ou parce que le client s'est déconnecté. Il peut aussi transporter des valeurs liées à la requête, comme un identifiant de requête. Par convention, c'est le premier paramètre, nommé ctx.

Q: Quelle est la différence entre context.Background et context.TODO ?

Les deux renvoient un context vide qui n'est jamais annulé et n'a ni échéance ni valeurs. Ils se comportent de façon identique. Background() est la racine pour main, les tests et l'initialisation de haut niveau. TODO() marque un endroit où un vrai context devrait être passé mais où le code environnant n'en a pas encore, ce qui le rend facile à retrouver plus tard.

Q: Pourquoi faut-il appeler cancel après context.WithTimeout ?

WithTimeout, WithDeadline et WithCancel enregistrent le nouveau context auprès de son parent et peuvent démarrer un timer. Appeler cancel libère ces ressources dès que vous avez terminé, au lieu d'attendre que le timeout expire ou que le parent soit annulé. Écrivez defer cancel() juste après la création ; go vet avertit quand une fonction cancel est ignorée.

Q: Que signifie « context deadline exceeded » en Go ?

C'est le texte de context.DeadlineExceeded, l'erreur que renvoie ctx.Err() une fois l'échéance d'un context passée. Les fonctions qui respectent le context, comme les clients HTTP et les drivers de base de données, la renvoient (souvent enveloppée) quand elles manquent de temps. Testez-la avec errors.Is(err, context.DeadlineExceeded).

Q: Faut-il utiliser context.WithValue pour passer des paramètres ?

Non. Réservez-le aux données liées à la requête qui traversent les frontières d'API et que les fonctions intermédiaires n'ont pas à connaître, comme un identifiant de trace ou un utilisateur authentifié. Tout ce dont une fonction a besoin pour faire son travail va dans ses paramètres, là où le compilateur le vérifie.

Un timeout en dix lignes

Le rôle de context.Context est de dire au code quand s'arrêter. Ici, une opération lente dispose de 50 ms et abandonne quand le context le demande :

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

Le premier appel se termine en 10 ms et renvoie rows <nil>. Le second aurait besoin de 200 ms, mais le context expire à 50 ms (comptées depuis sa création), donc il renvoie context deadline exceeded.

Rien n'est arrêté de force. Go n'a aucun moyen de tuer une goroutine depuis l'extérieur. Un context est un signal, et le code doit le vérifier : en faisant un select sur ctx.Done(), en vérifiant ctx.Err() entre deux étapes, ou en passant ctx à des appels de bibliothèque (http.NewRequestWithContext, db.QueryContext, exec.CommandContext) qui le vérifient pour vous.

L'interface Context

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

Méthode	Renvoie
`Done()`	un channel fermé quand le context est annulé ou expire (`nil` pour un context qui ne peut jamais être annulé)
`Err()`	`nil` tant qu'il est actif, puis `context.Canceled` ou `context.DeadlineExceeded`
`Deadline()`	l'échéance et `true`, ou `ok == false` s'il n'y en a pas
`Value(key)`	la valeur stockée sous `key` dans ce context ou un ancêtre, ou `nil`

Les contexts sont immuables. Vous n'en modifiez jamais un ; vous en dérivez un enfant avec l'une des fonctions With, et l'enfant ajoute un signal d'annulation, une échéance ou une valeur.

D'où vient un context

Tout arbre de contexts part d'une racine :

context.Background() pour main, init, les tests et l'initialisation de haut niveau des serveurs.
context.TODO() quand une fonction devrait prendre un context mais que l'appelant n'en a pas encore. Il se comporte exactement comme Background ; le nom sert de repère pour un refactoring futur.

Dans un handler HTTP, vous ne créez pas de racine. Vous utilisez r.Context(), que le serveur annule quand le client se déconnecte ou que le handler retourne.

WithCancel : arrêter à la demande

context.WithCancel renvoie un context enfant et une fonction cancel. Appeler cancel ferme le channel Done de l'enfant et les channels Done de tout ce qui en dérive.

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

L'envoi du producteur se trouve dans un select à côté de ctx.Done(). C'est ce qui lui permet de s'arrêter : un simple out <- i bloquerait indéfiniment dès que le consommateur cesse de lire, et la goroutine fuirait. Le for range nums final attend que le producteur ait fermé le channel. Pendant ce vidage, le producteur peut encore réussir à envoyer une ou deux valeurs, car quand les deux cas de son select sont prêts, Go en choisit un au hasard ; l'annulation est rapide, pas instantanée.

cancel peut être appelée plusieurs fois et depuis n'importe quelle goroutine. Seul le premier appel a un effet.

WithTimeout et WithDeadline

WithTimeout(parent, d) équivaut à WithDeadline(parent, time.Now().Add(d)). Utilisez un timeout pour « au maximum cette durée » et une échéance quand vous avez une heure absolue.

Une fois le délai passé, Done se ferme et Err renvoie context.DeadlineExceeded. Si cancel est appelée avant, Err renvoie context.Canceled. Vérifiez lequel avec errors.Is, car les bibliothèques enveloppent généralement l'erreur :

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

Appelez toujours cancel, même pour un timeout qui expirera tout seul. Le context garde un timer et une place chez son parent jusqu'à ce que l'un des deux se produise, et defer cancel() libère les deux dès que la fonction retourne. go vet signale une fonction cancel ignorée : the cancel function returned by context.WithTimeout should be called, not discarded, to avoid a context leak.

Les enfants ne survivent pas à leurs parents

Les contexts forment un arbre. Annuler un parent annule tous ses descendants. Un enfant peut avoir une échéance plus courte que son parent, jamais plus longue : l'échéance la plus proche l'emporte toujours.

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

C'est ce qui rend les contexts utiles à travers les couches. Un handler HTTP reçoit un context qui meurt avec la requête ; un appel à la base de données trois couches plus bas en dérive un timeout de 2 secondes. Si le client raccroche au bout de 100 ms, la requête SQL est annulée à ce moment-là, pas deux secondes plus tard.

Faites toujours un select sur ctx.Done() quand vous bloquez

Toute goroutine qui attend (un envoi sur un channel, une réception, un timer) devrait attendre ctx.Done() en même temps. Pour les boucles qui consomment du CPU sans jamais bloquer, vérifiez ctx.Err() de temps en temps :

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

Utilisez time.After dans un select pour une attente simple, mais préférez un timer que vous pouvez arrêter (ou un timeout de context) quand l'attente risque d'être souvent annulée.

Causes d'annulation (Go 1.20 et 1.21)

ctx.Err() dit seulement canceled ou deadline exceeded. Pour enregistrer pourquoi, utilisez les 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 est arrivée avec Go 1.20, WithTimeoutCause et WithDeadlineCause avec Go 1.21. Err continue de renvoyer les valeurs standard pour que les vérifications existantes fonctionnent toujours ; context.Cause donne le détail.

WithValue, avec modération

context.WithValue(parent, key, value) attache une valeur. ctx.Value(key) la recherche en remontant la chaîne des parents.

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
}

Règles pour les valeurs :

Utilisez un type non exporté pour les clés, jamais une simple string. Deux packages qui utilisent tous deux "user" s'écraseraient mutuellement. (go vet ne le détecte pas ; staticcheck si.)
Encapsulez l'accès dans des fonctions typées comme WithRequestID et RequestID, pour que les appelants ne voient jamais any ni la clé.
Ne stockez que des données liées à la requête qui traversent des API : identifiants de trace et de requête, utilisateur authentifié, logger. Jamais des paramètres optionnels, des connexions à la base ou de la configuration. Ceux-là vont dans des arguments de fonction ou des champs de struct, où le compilateur peut les vérifier et les lecteurs les voir.
La recherche remonte la chaîne un parent à la fois, donc chaque valeur ajoutée rallonge d'un cran la recherche des autres.

Conventions

ctx context.Context est le premier paramètre de toute fonction qui fait des E/S, bloque, ou appelle quelque chose qui le fait : func Fetch(ctx context.Context, url string) error.
Ne stockez pas un context dans une struct. Passez-le à chaque appel de méthode. Un context appartient à une opération, et une struct lui survit généralement. (L'exception est un type qui représente une seule opération, comme http.Request.)
Ne passez jamais nil comme context. Utilisez context.TODO() si vous n'avez rien de mieux.
Renvoyez ctx.Err(), ou enveloppez-la avec %w, quand vous vous arrêtez à cause du context, pour que les appelants distinguent un timeout d'un vrai échec.

Le context dans les serveurs et clients HTTP

Côté serveur : r.Context() est annulé quand le client se déconnecte, quand le handler retourne, ou quand un flux HTTP/2 est réinitialisé. Côté client : http.NewRequestWithContext fait respecter un timeout ou une annulation à la requête. Ce programme fait tourner les deux côtés via 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)
}

Le client abandonne à 50 ms et ferme la connexion. Le serveur s'en aperçoit, le context de sa requête est annulé, et le handler s'arrête au lieu de passer 450 millisecondes de plus sur un rapport que personne ne lira. Dans un vrai handler, vous passez r.Context() à chaque appel à la base de données et à chaque appel HTTP, et ils s'arrêtent tous ensemble.

Autres fonctions utiles (Go 1.21)

context.WithoutCancel(ctx) renvoie un context avec les mêmes valeurs, qui n'est pas annulé quand ctx l'est. Utilisez-le pour un travail qui doit se terminer après la fin de la requête, comme l'écriture d'un journal d'audit.
context.AfterFunc(ctx, f) exécute f dans sa propre goroutine une fois ctx terminé, et renvoie une fonction stop pour le désinscrire.

Erreurs courantes

Ne pas appeler cancel. Faites toujours defer cancel() juste après WithCancel, WithTimeout ou WithDeadline.
Lancer une goroutine qui ignore ctx. Si elle bloque sans select sur ctx.Done(), l'annulation n'a aucun effet et la goroutine fuit.
Créer un nouveau context.Background() au fond d'une chaîne d'appels. Cela coupe le lien avec l'échéance et l'annulation de l'appelant. Passez le ctx que vous avez reçu.
Comparer les erreurs avec ==. Utilisez errors.Is(err, context.DeadlineExceeded) ; la plupart des bibliothèques l'enveloppent.
Utiliser WithValue pour des dépendances. Une connexion à la base cachée dans un context est un paramètre que le compilateur ne peut plus vérifier.
S'attendre à une annulation instantanée. Le code ne s'en aperçoit qu'à sa prochaine vérification. Une longue boucle sans vérification continue de tourner.

Questions fréquentes

À quoi sert context en Go ?

Un context.Context indique à une fonction, et à tout ce qu'elle appelle, quand abandonner : parce que l'appelant a annulé, parce qu'une échéance est passée, ou parce que le client s'est déconnecté. Il peut aussi transporter des valeurs liées à la requête, comme un identifiant de requête. Par convention, c'est le premier paramètre, nommé ctx.

Quelle est la différence entre context.Background et context.TODO ?

Les deux renvoient un context vide qui n'est jamais annulé et n'a ni échéance ni valeurs. Ils se comportent de façon identique. Background() est la racine pour main, les tests et l'initialisation de haut niveau. TODO() marque un endroit où un vrai context devrait être passé mais où le code environnant n'en a pas encore, ce qui le rend facile à retrouver plus tard.

Pourquoi faut-il appeler cancel après context.WithTimeout ?

WithTimeout, WithDeadline et WithCancel enregistrent le nouveau context auprès de son parent et peuvent démarrer un timer. Appeler cancel libère ces ressources dès que vous avez terminé, au lieu d'attendre que le timeout expire ou que le parent soit annulé. Écrivez defer cancel() juste après la création ; go vet avertit quand une fonction cancel est ignorée.

Que signifie « context deadline exceeded » en Go ?

C'est le texte de context.DeadlineExceeded, l'erreur que renvoie ctx.Err() une fois l'échéance d'un context passée. Les fonctions qui respectent le context, comme les clients HTTP et les drivers de base de données, la renvoient (souvent enveloppée) quand elles manquent de temps. Testez-la avec errors.Is(err, context.DeadlineExceeded).

Faut-il utiliser context.WithValue pour passer des paramètres ?

Non. Réservez-le aux données liées à la requête qui traversent les frontières d'API et que les fonctions intermédiaires n'ont pas à connaître, comme un identifiant de trace ou un utilisateur authentifié. Tout ce dont une fonction a besoin pour faire son travail va dans ses paramètres, là où le compilateur le vérifie.

Concepts liés