context.Context, l'annulation qui descend context.Context, cancellation flowing down

context.Context est le câble qui traverse les couches : du handler HTTP jusqu'à la requête SQL. Premier argument, jamais stocké, toujours propagé. Quand le haut annule, tout ce qui en dépend l'apprend par Done(). context.Context is the cable threading through layers: from the HTTP handler down to the SQL query. First argument, never stored, always propagated. When the top cancels, everything below hears it through Done().

Audience
Dev qui stocke ctx dans une struct, ou dont les goroutines ne s'arrêtent pas quand le client raccroche Dev who stores ctx in a struct, or whose goroutines don't stop when the client hangs up
ChapitresChapters
5
LectureReading
≈ 17 min
NiveauLevel
●●○○
Date
Mar 2028 Mar 2028

contextAnnulation

SommaireContents ·
№ 01CadrageFraming3 min

context.Context est le câble qui descend de couche en couche. Premier argument, jamais stocké, toujours propagé.context.Context is the cable threading down layer by layer. First argument, never stored, always propagated.

Les volumes précédents ont couvert comment une fonction gère sa propre sortie — defer, capture, recover. Mais un programme concurrent réel n'est pas une fonction : c'est un arbre de goroutines lancé pour une même tâche. Un handler HTTP appelle un service, qui interroge une base, qui démarre deux goroutines de cache. Quand le client raccroche — ou que le délai expire — tout ce travail doit cesser. Personne ne peut appeler individuellement chaque goroutine. Il faut un signal qui descend : context.Context est exactement ce signal. Un contexte est une valeur immuable qui forme un arbre : context.Background() est la racine, et chaque dérivé — WithCancel, WithTimeout, WithValue — crée un nœud fils. Quand un nœud est annulé, tous ses descendants le savent immédiatement via leur canal Done(). Le contexte n'est pas un objet global, une variable d'environnement, ni un champ de struct : c'est le premier argument de chaque fonction qui fait du travail annulable. La convention Go est stricte : ctx context.Context, toujours en tête de signature, toujours passé explicitement. Ce qui semble verbeux est en réalité une propriété de sécurité : chaque site d'appel voit qu'il participe à une annulation, et choisit consciemment quel contexte transmettre.Previous volumes covered how a function manages its own exit — defer, capture, recover. But a real concurrent program isn't a function: it's a tree of goroutines launched for one task. An HTTP handler calls a service, which queries a database, which starts two cache goroutines. When the client hangs up — or the deadline expires — all that work must cease. Nobody can call each goroutine individually. You need a signal that flows down: context.Context is exactly that signal. A context is an immutable value forming a tree: context.Background() is the root, and each derivative — WithCancel, WithTimeout, WithValue — creates a child node. When a node is canceled, all its descendants know immediately via their Done() channel. A context is not a global object, an environment variable, or a struct field: it's the first argument of every function doing cancelable work. The Go convention is strict: ctx context.Context, always first in the signature, always passed explicitly. What seems verbose is actually a safety property: every call site sees that it participates in a cancellation, and consciously chooses which context to forward.

Le câble qui traverse les couchesThe cable threading through the layers
// Le câble traverse les couches : on ne le stocke jamais, on le passe.
func handleSearch(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()              // racine : le contexte de la requête HTTP
    results, err := search(ctx, r.URL.Query().Get("q"))
    // …
}

func search(ctx context.Context, query string) ([]Result, error) {
    rows, err := db.QueryContext(ctx, "SELECT …", query)  // ctx descend jusqu'à SQL
    if err != nil { return nil, err }
    // …
}
Un arbre de contextesA tree of contexts
context.Background()
la racine
↓
r.Context()
la requête HTTP
↓
WithCancel / WithTimeout
les fils

Annuler un nœud parent propage le signal à tous ses descendants. Jamais l'inverse. Le contexte descend, l'annulation descend.Canceling a parent node propagates the signal to all its descendants. Never the reverse. The context flows down, cancellation flows down.

Le réflexe du numéroThe issue's reflex

« Est-ce que cette fonction fait du travail qui peut durer ? Si oui, elle accepte un ctx en premier argument et le passe à ses sous-appels. » context.Context n'est pas une option — c'est le fil conducteur de toute opération annulable, de la requête HTTP jusqu'au dernier appel SQL. Une fonction qui l'ignore isole une partie du travail du signal d'annulation — et cette partie continuera à tourner même après que tout le reste s'est arrêté."Does this function do work that can last? If yes, it takes a ctx as first argument and passes it to its sub-calls." context.Context is not an option — it's the conductor of every cancelable operation, from the HTTP request down to the last SQL call. A function that ignores it isolates part of the work from the cancellation signal — and that part will keep running even after everything else has stopped.

Pourquoi immuable ?Why immutable?

Un contexte ne se modifie jamais en place. WithCancel, WithTimeout et WithValue créent chacun un nouveau contexte-fils qui pointe vers son parent. Cette immuabilité garantit qu'un fils ne peut pas altérer son parent : la couche service peut restreindre son délai sans risquer d'annuler le contexte du handler. L'arbre ne peut être élagué que depuis la racine vers les feuilles, jamais l'inverse. C'est ce qui rend la propagation sûre dans un programme concurrent : plusieurs goroutines peuvent lire le même contexte simultanément, sans synchronisation, car rien ne l'écrit.A context never mutates in place. WithCancel, WithTimeout, and WithValue each create a new child context pointing to its parent. This immutability guarantees a child can't alter its parent: the service layer can tighten its deadline without risking canceling the handler's context. The tree can only be pruned from root toward leaves, never the reverse. That's what makes propagation safe in a concurrent program: multiple goroutines can read the same context simultaneously, without synchronization, because nothing writes to it.

№ 02La surpriseThe surprise4 min

Stocker un context.Context dans une struct, c'est figer un signal qui devait rester vivant.Storing a context.Context in a struct freezes a signal that was meant to stay alive.

Le premier réflexe, en arrivant de langages où on stocke l'état dans des objets, est de coller le contexte dans une struct pour ne pas avoir à le passer partout. Un Server avec son ctx, un Client avec son ctx de connexion — ça paraît propre et pratique. C'est l'antipattern que la documentation officielle de Go nomme explicitement. Voici pourquoi. Un contexte porte le signal d'annulation d'une opération précise, à un instant précis. Quand on démarre un Server, on lui donne le contexte du démarrage — un contexte de vie du service, pas d'une requête individuelle. Mais quand un client appelle Query, c'est une nouvelle opération, avec son propre cycle de vie : le client peut raccrocher, son délai peut expirer, son contexte peut être annulé. Si on utilise s.ctx — le contexte du démarrage — au lieu du contexte de la requête, on perd toute cette information. La requête SQL continuera à tourner même si le client est parti depuis longtemps, consommant des ressources pour un travail dont le résultat n'intéresse plus personne. Le contexte de démarrage du service vit des heures ou des jours ; le contexte d'une requête vit des millisecondes. Les mélanger, c'est confondre deux durées de vie que Go distingue précisément pour cette raison.The first reflex, coming from languages where state is stored in objects, is to put the context in a struct so you don't have to pass it everywhere. A Server with its ctx, a Client with its connection ctx — it seems clean and convenient. It's the antipattern the official Go documentation names explicitly. Here's why. A context carries the cancellation signal for a specific operation, at a specific instant. When you start a Server, you give it the startup context — a service-lifetime context, not an individual request's. But when a client calls Query, that's a new operation, with its own lifecycle: the client may hang up, their deadline may expire, their context may be canceled. If you use s.ctx — the startup context — instead of the request's context, you lose all that information. The SQL query will keep running even if the client left long ago, consuming resources for work whose result nobody cares about anymore. A service's startup context lives hours or days; a request's context lives milliseconds. Mixing them is confusing two lifetimes that Go distinguishes precisely for this reason.

Le contexte figé : la requête ignore que le client est partiThe frozen context: the query ignores the client left
type Server struct {
    db  *sql.DB
    ctx context.Context   // ← ANTIPATTERN : contexte stocké dans la struct
}

func NewServer(ctx context.Context, db *sql.DB) *Server {
    return &Server{ctx: ctx, db: db}
}

func (s *Server) Query(q string) ([]Row, error) {
    // s.ctx est le contexte de l'initialisation, pas de la requête en cours.
    // Si le client de CETTE requête raccroche, s.ctx ne le sait pas.
    return s.db.QueryContext(s.ctx, q)
}

s.ctx est né à la création du serveur. Il ne connaît pas l'annulation de la requête courante. La requête SQL s'exécutera jusqu'à son terme même si le client a fermé sa connexion — parce que le contexte écouté est celui du service entier, pas de l'opération. On perd la propriété la plus importante de context.Context : l'arrêt coordonné dès que le travail devient inutile.s.ctx was born when the server was created. It doesn't know about the current request's cancellation. The SQL query will run to completion even if the client closed the connection — because the context being listened to is the whole service's, not the operation's. You lose context.Context's most important property: coordinated stop the moment work becomes useless.

La règle de la doc officielle GoThe official Go doc rule

« Do not store Contexts inside a struct type; instead, pass a Context explicitly to each function that needs it. » — pkg.go.dev/context. Ce n'est pas une recommandation de style, c'est une propriété de correction : un contexte stocké ne correspond plus à l'opération en cours. La verbosité de passer ctx partout est le prix de la lisibilité — chaque site d'appel rend explicite qu'il participe à l'annulation."Do not store Contexts inside a struct type; instead, pass a Context explicitly to each function that needs it." — pkg.go.dev/context. This is not a style recommendation, it's a correctness property: a stored context no longer matches the current operation. The verbosity of passing ctx everywhere is the price of readability — every call site makes explicit that it participates in cancellation.

Un contexte stocké dans une struct ne vieillira jamais avec la requête. Le ctx en argument EST la requête — vivant, annulable, juste.A context stored in a struct will never age with the request. The ctx argument IS the request — alive, cancelable, right.
№ 03La mécaniqueThe mechanics5 min

WithCancel crée un fils annulable. Done() expose le channel qu'on écoute dans un select pour répondre à l'annulation.WithCancel creates a cancelable child. Done() exposes the channel you listen to in a select to respond to cancellation.

L'annulation dans Go n'est pas une exception, un signal Unix, ni une valeur magique : c'est un channel. context.WithCancel crée un contexte-fils et une fonction cancel. Quand cancel() est appelée — ou quand le parent est annulé — le channel renvoyé par ctx.Done() est fermé. Un channel fermé est lisible immédiatement par tous ses lecteurs, simultanément et sans synchronisation : c'est le mécanisme de diffusion idéal pour un signal à sens unique. Pour répondre à l'annulation, on écoute ctx.Done() dans un select aux côtés des autres opérations — un résultat qui arrive, un timer, n'importe quoi. Le select débloque sur la première case prête : si c'est ctx.Done(), on sait que quelqu'un a annulé la chaîne, on lit ctx.Err() pour savoir pourquoi — context.Canceled si c'est une annulation explicite, context.DeadlineExceeded si c'est un délai — et on remonte cette erreur. Le defer cancel() est non négociable : créer un contexte-fils sans annuler alloue des ressources dans l'arbre des contextes qui ne seront jamais libérées si le contexte parent reste vivant. C'est une fuite de goroutine au sens large. Pour les boucles longues sans select naturel, on vérifie ctx.Done() en début d'itération avec un select non-bloquant — default vide — pour ne pas bloquer l'itération elle-même mais détecter rapidement une annulation.Cancellation in Go is not an exception, a Unix signal, or a magic value: it's a channel. context.WithCancel creates a child context and a cancel function. When cancel() is called — or when the parent is canceled — the channel returned by ctx.Done() is closed. A closed channel is immediately readable by all readers, simultaneously and without synchronization: it's the ideal broadcast mechanism for a one-way signal. To respond to cancellation, you listen to ctx.Done() in a select alongside other operations — a result arriving, a timer, anything. The select unblocks on the first ready case: if it's ctx.Done(), you know someone canceled the chain, you read ctx.Err() to know why — context.Canceled for an explicit cancellation, context.DeadlineExceeded for a deadline — and you surface that error. The defer cancel() is non-negotiable: creating a child context without canceling it allocates resources in the context tree that will never be freed if the parent context stays alive. It's a goroutine leak in the broad sense. For long loops without a natural select, check ctx.Done() at the start of each iteration with a non-blocking select — empty default — so as not to block the iteration itself but quickly detect cancellation.

WithCancel + defer cancel() + select sur Done()WithCancel + defer cancel() + select on Done()
func doWork(ctx context.Context) error {
    ctx, cancel := context.WithCancel(ctx)   // crée un fils annulable
    defer cancel()                           // libère les ressources du fils quoi qu'il arrive

    resultCh := make(chan Result, 1)
    go func() {
        resultCh <- compute()   // travail long dans une goroutine
    }()

    select {
    case r := <-resultCh:
        return process(r)
    case <-ctx.Done():          // parent annulé (ou cancel() appelé)
        return ctx.Err()        // context.Canceled ou context.DeadlineExceeded
    }
}

Trois gestes, dans l'ordre. context.WithCancel(ctx) crée un fils dans l'arbre d'annulation. defer cancel() garantit la libération par toute sortie. Le select sur ctx.Done() est le point d'écoute : si le channel se ferme avant que le résultat n'arrive, la fonction sort avec ctx.Err() — la même erreur que les couches supérieures pourront inspecter. C'est symétrique : ce qu'on remonte est ce que le parent a fait descendre.Three gestures, in order. context.WithCancel(ctx) creates a child in the cancellation tree. defer cancel() guarantees release through any exit. The select on ctx.Done() is the listening point: if the channel closes before the result arrives, the function exits with ctx.Err() — the same error upper layers will be able to inspect. It's symmetric: what you surface is what the parent made descend.

ctx.Done() est un channel fermé au bon moment. Un select dessus est tout ce qu'il faut pour répondre à l'annulation.ctx.Done() is a channel closed at the right moment. A select on it is all you need to respond to cancellation.
№ 04Le piègeThe trap4 min

Ne pas propager le ctx aux sous-appels crée des goroutines sourdes à l'annulation — elles travaillent pour personne.Not propagating ctx to sub-calls creates goroutines deaf to cancellation — they work for nobody.

La convention du premier argument ne vaut que si on la respecte à chaque maillon. Le piège classique : on accepte un ctx dans un handler, puis on appelle des fonctions qui l'ignorent — soit parce qu'elles ne l'acceptent pas, soit parce qu'on a oublié de le passer. Le résultat est subtil mais coûteux. Le client envoie une requête, raccroche immédiatement. Le serveur ne l'apprend que par le ctx de la requête, désormais annulé. Mais le code lancé pour cette requête, qui appelle des fonctions sans ctx, continue à tourner. Elles tiennent des connexions de base de données, des fichiers ouverts, des slots de pool. Multiplié par des milliers de requêtes annulées, c'est une pression croissante sur les ressources jusqu'au crash. L'antipattern a plusieurs formes : passer context.Background() à la place du ctx reçu (équivalent à couper le fil), ignorer le ctx dans la goroutine lancée en go func(), ou appeler db.Exec au lieu de db.ExecContext. La bibliothèque standard Go a pris soin d'offrir des variantes *Context pour toutes les opérations longues — http.NewRequestWithContext, db.QueryContext, exec.CommandContext, net.Dialer.DialContext — précisément pour permettre cette propagation. Toute API standard qui existe en variante *Context s'utilise avec cette variante quand on a un ctx.The first-argument convention only holds if you respect it at every link. The classic trap: you accept a ctx in a handler, then call functions that ignore it — either because they don't accept it, or because you forgot to pass it. The result is subtle but costly. The client sends a request, hangs up immediately. The server only learns of it through the request's ctx, now canceled. But the code launched for that request, calling functions without ctx, keeps running. They hold database connections, open files, pool slots. Multiplied by thousands of canceled requests, that's growing pressure on resources until a crash. The antipattern has several forms: passing context.Background() instead of the received ctx (equivalent to cutting the wire), ignoring the ctx in the goroutine launched with go func(), or calling db.Exec instead of db.ExecContext. The Go standard library has carefully offered *Context variants for all long operations — http.NewRequestWithContext, db.QueryContext, exec.CommandContext, net.Dialer.DialContext — precisely to allow this propagation. Any standard API that exists in a *Context variant uses that variant when you have a ctx.

Le ctx s'arrête à la frontière du handler — store ne l'entend pasThe ctx stops at the handler boundary — store never hears it
func handleUpload(w http.ResponseWriter, r *http.Request) {
    data, _ := io.ReadAll(r.Body)

    // ctx de la requête HTTP... mais on ne le passe pas.
    if err := store(data); err != nil {   // store ignore le ctx
        log.Println(err)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

func store(data []byte) error {
    // Pas de ctx : si le client annule, ce travail continue jusqu'au bout.
    _, err := db.Exec("INSERT INTO uploads VALUES (?)", data)
    return err
}

store ne prend pas de ctx. Quand le client annule, le handler poursuit son INSERT jusqu'à la fin — elle n'a aucun moyen d'apprendre l'annulation. C'est un travail orphelin : il consomme une connexion de pool, un slot de workers, et produit un résultat que personne ne lira. À grande échelle, ces travaux sourds épuisent les ressources même sous une charge nominale, parce que le ratio annulations/succès est toujours non nul.store takes no ctx. When the client cancels, the handler carries on with its INSERT to completion — it has no way to hear the cancellation. It's orphaned work: it consumes a pool connection, a worker slot, and produces a result nobody will read. At scale, this deaf work exhausts resources even under nominal load, because the cancellation-to-success ratio is never zero.

La liste de contrôleThe checklist

Trois vérifications à faire à chaque revue : 1. Toute goroutine lancée reçoit-elle le ctx ? 2. Toute API standard longue est-elle appelée avec sa variante *Context ? 3. Nulle part on ne remplace ctx par context.Background() sauf à la racine. Ces trois questions suffisent à identifier 90 % des fuites de context dans une revue de code.Three checks to do at each review: 1. Does every spawned goroutine receive the ctx? 2. Is every long standard API called with its *Context variant? 3. Nowhere is ctx replaced by context.Background() except at the root. These three questions are enough to identify 90% of context leaks in a code review.

context.Background() et context.TODO()context.Background() and context.TODO()

context.Background() est la racine immuable : on l'utilise au point d'entrée du programme, dans main ou dans un test de haut niveau. context.TODO() est un marqueur temporaire qui dit « ici il faudrait un vrai ctx, mais je ne sais pas encore lequel ». Les deux ne propagent aucun signal d'annulation. Utiliser context.Background() au milieu d'un handler, c'est couper délibérément le fil — la goroutine fille devient sourde au contexte de la requête. C'est le geste qui transforme une propagation correcte en travail orphelin.context.Background() is the immutable root: use it at the program's entry point, in main or a top-level test. context.TODO() is a temporary marker saying 'here we'd need a real ctx, but I don't know which yet.' Both propagate no cancellation signal. Using context.Background() in the middle of a handler deliberately cuts the wire — the child goroutine becomes deaf to the request's context. It's the gesture that turns correct propagation into orphaned work.

Passer ctx jusqu'à l'avant-dernière couche ne suffit pas. Le fil doit atteindre le dernier appel bloquant — la base, le réseau, le fichier.Passing ctx to the second-to-last layer isn't enough. The wire must reach the last blocking call — the database, the network, the file.
№ 05Bilan & éditoWrap-up & editorial2 min

context.Context n'est pas une option de plomberie. C'est le câble qui rend le travail coordonné possible — et l'ignorer crée du travail pour personne.context.Context isn't a plumbing option. It's the cable that makes coordinated work possible — and ignoring it creates work for nobody.

Ce numéro a posé les fondations du volume 8 : context.Context comme câble d'annulation qui traverse les couches, du handler HTTP jusqu'à la requête SQL. Un contexte forme un arbre immuable : quand un nœud est annulé, tous ses descendants l'apprennent via ctx.Done(), un channel fermé qu'on écoute dans un select. La convention du premier argument — ctx context.Context toujours en tête de signature — n'est pas une règle de style, c'est la propriété qui rend visible chaque participation à l'annulation. Stocker ctx dans une struct brise la correspondance entre le signal et l'opération : le contexte figé du service remplace le contexte vivant de la requête. Ignorer ctx dans un sous-appel, ou préférer db.Exec à db.ExecContext, crée du travail orphelin qui continue après que le client est parti. Les deux variantes produisent la même conséquence : des goroutines qui travaillent pour personne, tenant des ressources pour un résultat que personne n'attend. Le numéro suivant porte sur la dimension temporelle de l'annulation : comment poser une limite de temps à un arbre de goroutines, pourquoi defer cancel() n'est pas optionnel, et ce qui se passe quand le délai expire avant que le travail ne soit terminé.This issue laid the foundations of volume 8: context.Context as a cancellation cable threading through layers, from the HTTP handler down to the SQL query. A context forms an immutable tree: when a node is canceled, all its descendants learn it via ctx.Done(), a closed channel you listen to in a select. The first-argument convention — ctx context.Context always first in the signature — is not a style rule, it's the property that makes visible each participation in cancellation. Storing ctx in a struct breaks the correspondence between signal and operation: the service's frozen context replaces the request's live one. Ignoring ctx in a sub-call, or preferring db.Exec over db.ExecContext, creates orphaned work that continues after the client has left. Both variants produce the same consequence: goroutines working for nobody, holding resources for a result nobody awaits. The next issue covers the temporal dimension of cancellation: how to put a time limit on a tree of goroutines, why defer cancel() isn't optional, and what happens when the deadline expires before the work is done.

L'idéeThe ideaLa règleThe ruleSi tu la ratesIf you miss it
Le câbleThe cablectx en premier argument de toute fonction qui fait du travail long ou I/O.ctx as first argument to every function doing long work or I/O.Des opérations sourdes à l'annulation du programme.Operations deaf to the program's cancellation.
Jamais stockéNever storedPas de ctx dans une struct — le passer à chaque appel.No ctx in a struct — pass it to every call.Un contexte figé qui ne correspond plus à l'opération en cours.A frozen context that no longer matches the current operation.
Done() + selectDone() + selectÉcouter ctx.Done() dans un select ; remonter ctx.Err().Listen to ctx.Done() in a select; surface ctx.Err().Un appel bloquant qui ne peut pas être interrompu par l'annulation.A blocking call that can't be interrupted by cancellation.
Variantes *Context*Context variantsToujours ExecContext, QueryContext, NewRequestWithContext — jamais la variante sans ctx.Always ExecContext, QueryContext, NewRequestWithContext — never the ctx-free variant.Le fil coupé au dernier mètre : l'opération la plus longue est sourde.The wire cut at the last meter: the longest operation is deaf.
Un programme qui passe ctx jusqu'à l'avant-dernier appel n'est pas concurrent-safe. Le câble doit atteindre l'opération qui bloque — pas s'arrêter devant elle.A program that passes ctx down to the second-to-last call isn't concurrency-safe. The wire must reach the blocking operation — not stop before it.
Mot de l'éditeur · ouverture du volume 8From the editor · opening volume 8

Le volume 8 commence où le volume 7 s'arrêtait : coordonner les sorties entre goroutines, pas seulement à l'intérieur d'une.Volume 8 starts where volume 7 left off: coordinating exits across goroutines, not just within one.

Vol. 7 s'est terminé sur un constat : recover protège une pile, defer nettoie une fonction, mais aucun des deux ne sait parler à dix goroutines. La fin du dernier chapitre pointait vers context.Context comme le câble qui porte ce signal. Ce premier numéro du volume 8 a posé ce câble : sa structure d'arbre immuable, sa convention d'usage, les deux façons les plus communes de le perdre en route. Les fondations sont là. Il reste deux dimensions à explorer. La première est le temps : comment poser une limite temporelle à un arbre de goroutines, pourquoi WithTimeout et WithDeadline sont deux façons d'exprimer la même chose, et pourquoi defer cancel() n'est jamais optionnel. La seconde est la donnée : comment glisser un request ID ou un trace ID dans le contexte, pourquoi les clés doivent être typées et non des strings nues, et où s'arrête la légitimité de WithValue — parce qu'un contexte n'est pas un sac à injection. Deux numéros pour fermer le volume : le temps d'abord, la donnée ensuite.Vol. 7 ended on a finding: recover protects one stack, defer cleans one function, but neither knows how to speak to ten goroutines. The last chapter's ending pointed to context.Context as the cable carrying that signal. This first volume 8 issue laid that cable: its immutable tree structure, its usage convention, the two most common ways to lose it in transit. The foundations are there. Two dimensions remain to explore. The first is time: how to put a time limit on a tree of goroutines, why WithTimeout and WithDeadline are two ways of expressing the same thing, and why defer cancel() is never optional. The second is data: how to slip a request ID or trace ID into the context, why keys must be typed rather than bare strings, and where WithValue's legitimacy ends — because a context is not an injection bag. Two issues to close the volume: time first, data next.