Diego Fernando

Understanding the Context package in Go

2022-10-09T10:05:00-03:00

Over the past few months I've been putting more effort into studying Go. I'll admit it's not my first contact with the language — back in 2017 I had the chance to run an introductory workshop at a university symposium. Even though it isn't new to me, I had to revisit a few concepts. The context.Context package is one of them. So, let's go!

Looking at the official documentation, we find the following excerpt:

“Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes”.

In other words, Context lets you create deadlines and execution-scoped values for the processes it's shared with. That magic happens because Context uses channels to send signals to processes, and those processes, in turn, listen for these instructions to control stop actions.

A classic example of its use is when making requests to external APIs, where we want to cap how long we wait for a response. There are other situations where it comes in handy too, such as controlling how long an instruction is allowed to run, or setting a deadline for a database query, for example. In short, there are plenty of possibilities.

Starting a Context#

Before detailing the types of Context, it's important to understand how it's initialized. Every Context has to be initialized empty at some point in its lifecycle before it can be used. The Go documentation itself discourages passing nil as a parameter in situations that require one. There are two ways to initialize it — context.Background() and context.TODO():

context.Background()#

package main

import (
    "context"
    "fmt"
)

func main() {
    ctx := context.Background()
    fmt.Println(ctx)
}

context.Background() returns a non-nil, empty Context. It's normally used by the project's main function or entrypoint.

context.TODO()#

package main

import (
    "context"
    "fmt"
)

func main() {
    ctx := context.TODO()
    fmt.Println(ctx)
}

Just like its predecessor, context.TODO() also returns a non-nil, empty Context. The main difference is that it's used when it isn't clear yet which context should be used, or when one isn't available yet.

Types of Context#

There are basically three types of Context:

Cancellation Signals
Deadline
Request-scoped values

Cancellation Signals#

The Cancellation Signals type defines a Context whose execution can be interrupted through a command. In this case, the instruction follows its normal flow until, at some point in the code, it's told to stop. Here's an example implementation:

package main

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

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

    go executeFunction(ctx)
    time.Sleep(3 * time.Second)
    cancel()
    time.Sleep(1 * time.Second)
}

func executeFunction(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("Stopping code execution...")
            return
        default:
            time.Sleep(1 * time.Second)
            fmt.Println("Running at", time.Now())
        }
    }
}

Before explaining the main() function, let's first understand executeFunction(), since it's the one that receives instructions from the Context. Once it receives a context.Context parameter, it runs an infinite loop where, as soon as it receives the stop signal from the context, it prints “Stopping code execution...” and ends its execution with an explicit return. Otherwise, it keeps running and printing “Running at [time]”. The select statement works like a kind of switch-case, but applied to signals coming from channels, which is the case with Contexts. As we can see, the stop signal in the code is given by the ctx.Done() instruction.

Back in the main() function, the first thing we do is create a Context with context.Background(). After that, we use the context.WithCancel() function, passing in our base context. It gives us back a new context and a second value we call cancel. That's essential for stopping the instructions tied to this context. While we run executeFunction() asynchronously, we wait three seconds and then force its cancellation with the cancel() instruction — yes, that same one we got from the context :) .

The result of running this will look something like the log below:

Running at 2022-10-09 16:15:46.80042576 -0300 -03 m=+1.000598497
Running at 2022-10-09 16:15:47.801454038 -0300 -03 m=+2.001626779
Running at 2022-10-09 16:15:48.801876258 -0300 -03 m=+3.002048999
Stopping code execution...

Deadline#

As the name suggests, a Deadline Context caps how long an instruction or process is allowed to run. That lets us tell the application how long a given piece of code is allowed to take. There are two different functions for working with Deadline:

context.WithDeadline() — sets a fixed point in time.
- Example: the context has until 10 PM on October 9th, 2022 to finish executing.
context.WithTimeout() — sets a duration counted from the moment it's created.
- Example: the context has 4 minutes from now to finish executing.

context.WithDeadline()#

Let's take the same code from before and tweak a few parts:

package main

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

func main() {
    ctx := context.Background()
    deadline := time.Now().Add(3 * time.Second)
    ctx, cancel := context.WithDeadline(ctx, deadline)

    defer cancel()

    executeFunction(ctx)
}

func executeFunction(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("Stopping code execution...")
            return
        default:
            time.Sleep(1 * time.Second)
            fmt.Println("Running at", time.Now())
        }
    }
}

We create a new deadline variable by adding three seconds to the current time and pass it to context.WithDeadline(). This way, the executeFunction() call is interrupted once that three-second window has passed.

Running the code above produces output similar to this:

Running at 2022-10-09 17:30:50.492897161 -0300 -03 m=+1.000190057
Running at 2022-10-09 17:30:51.493583512 -0300 -03 m=+2.000876359
Running at 2022-10-09 17:30:52.493694606 -0300 -03 m=+3.000987449
Running at 2022-10-09 17:30:53.493795753 -0300 -03 m=+4.001088530
Stopping code execution…

context.WithTimeout()#

We can use context.WithTimeout() to produce the same behavior. Just swap lines 11 and 12 for:

deadline := 3 * time.Second
ctx, cancel := context.WithTimeout(ctx, deadline)

The difference from the previous code is that now we no longer need to calculate the current instant plus three seconds. The output is the same.

One interesting detail in this structure is that we also call cancel(), but with the defer keyword to make sure it runs last. Even though we're capping the execution time, we can also cancel the instruction early at any point, overriding the time-limit rule, just like explained in the Cancellation Signals section.

Request-scoped value#

Besides controlling execution time and stopping, Context can also pass key-value values down to child instructions. This concept matters because it works regardless of whether the call to those instructions is synchronous or asynchronous. These values are stored inside the context and are immutable. Let's walk through the code below, a synchronous example:

package main

import (
    "context"
    "fmt"
)

func main() {
    ctx := context.Background()
    ctx = context.WithValue(ctx, "sessionId", "Session123")
    showValue(ctx)
}

func showValue(ctx context.Context) {
    fmt.Println(ctx.Value("sessionId"))
    addKeyValue(&ctx, "typeError", "ErrorType123")
    fmt.Println(ctx.Value("typeError"))
}

func addKeyValue(ctx *context.Context, key interface{}, value interface{}) {
    *ctx = context.WithValue(*ctx, key, value)
}

We define the initial, empty context with context.Background(). After that, we create a new context from that initial one with context.WithValue(), adding a couple of sample values along the way. Since those values are stored in the Context, we can read them elsewhere in the program with ctx.Value(), passing in the matching key. If that key doesn't exist, the return value is nil. It's also possible to add new values to a context by calling context.WithValue() again, passing in the previous context and reassigning it to itself.

Other scenarios#

Context's use cases aren't limited to what's covered here. These days, Go libraries — standard or third-party — often require passing a Context into their functions. The goal of this post was to understand its fundamentals and common uses.

See you next time :)

References#

[PT] Entendendo o package Context em Go

2022-10-09T10:05:00-03:00

Nos últimos meses tenho voltado meus esforços para o estudo da linguagem Go. Confesso que não é meu primeiro contato com a linguagem – lá em 2017 tive a oportunidade de apresentar um minicurso introdutório em um simpósio universitário. Apesar de não ser uma novidade, precisei revisitar alguns conceitos. O pacote context.Context é um deles. Então, let's go!

Olhando para a documentação oficial, temos o seguinte trecho:

“Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes”.

Ou seja, o Context permite a criação de prazos e valores de escopo de execução aos processos em que ele é compartilhado. Essa mágica acontece pelo fato que o Context usa channels para enviar sinais aos processos, e esses processos por sua vez, escutam essas instruções controlando ações de parada.

Um exemplo clássico de seu uso é em situações de requisições para API’s externas onde queremos delimitar um tempo de espera pela resposta. Também existem outras situações que podemos nos beneficiar do seu uso, tais como controlar o tempo limite de processamento de instruções e determinar prazo de execução de query ao banco de dados, por exemplo. Enfim, são várias as possibilidades.

Iniciando um Context#

Antes de começarmos a detalhar os tipos de Context, é importante entendermos como se dá a sua inicialização. Todo Context para ser usado, deve ser inicializado vazio em algum momento do ciclo de vida. A própria documentação do Go desencoraja passar nil como parâmetro em situações que o requerem. Existem duas formas de inicializá-lo - context.Background() e context.TODO():

context.Background()#

package main

import (
    "context"
    "fmt"
)

func main() {
    ctx := context.Background()
    fmt.Println(ctx)
}

O context.Backgroud() nos retorna um Context não nulo e vazio. Normalmente é usado pela função principal ou entrypoint do projeto.

context.TODO()#

package main

import (
    "context"
    "fmt"
)

func main() {
    ctx := context.TODO()
    fmt.Println(ctx)
}

Assim como seu antecessor, o context.TODO() também nos retorna um Context não nulo e vazio. A principal diferença é que o seu uso se dá quando não estiver claro o contexto que se deve usar ou ele ainda não estiver disponível.

Tipos de Context#

Existem basicamente três tipos de Context:

Cancellation Signals
Deadline
Request-scoped values

Cancellation Signals#

O tipo Cancellation Signals define um Context que pode ter sua execução interrompida através de um comando. Neste caso, a instrução segue o fluxo normal até que em certo ponto do código seja dada a sua parada. A seguir, um exemplo de implementação:

package main

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

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

    go executeFunction(ctx)
    time.Sleep(3 * time.Second)
    cancel()
    time.Sleep(1 * time.Second)
}

func executeFunction(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("Stopping code execution...")
            return
        default:
            time.Sleep(1 * time.Second)
            fmt.Println("Running at", time.Now())
        }
    }
}

Antes de explicar a função main(), vamos entender primeiro a função executeFunction(), pois ela irá receber instruções do Context. Ao receber um parâmetro do tipo context.Context fazemos um loop infinito, onde, assim que receber o sinal de parada vindo do contexto, ela irá apresentar o texto “Stopping code execution...” e terminará sua execução através de um return explícito. Caso contrário, seguirá sua execução apresentando “Running at [horário]”. O comando select funciona como uma espécie de switch-case, porém aplicado ao sinais provenientes de channels, como é o caso de Contexts. Como percebemos, o sinal de parada no código é dado pela instrução ctx.Done().

Retornando para a função main(), a primeira coisa que fazemos é definir um Context através do context.Backgroud(). Após isso, usamos a função context.WithCancel() passando o nosso contexto base. Ele nos devolve um novo contexto e uma segunda instrução que chamamos de cancel. Ela é essencial para definir a parada das instruções que estão ligadas a este contexto. Enquanto executamos a função executeFunction() de forma assíncrona, esperamos três segundos para forçar seu cancelamento com a instrução cancel() - aquela mesmo que recebemos do contexto :) .

O resultado da execução será semelhante ao log abaixo:

Running at 2022-10-09 16:15:46.80042576 -0300 -03 m=+1.000598497
Running at 2022-10-09 16:15:47.801454038 -0300 -03 m=+2.001626779
Running at 2022-10-09 16:15:48.801876258 -0300 -03 m=+3.002048999
Stopping code execution...

Deadline#

Como o próprio termo sugere, um Context do tipo Deadline delimita o tempo de execução de uma instrução ou processo. Podemos então informar para a aplicação até quando determinado código pode demorar. Temos duas funções diferentes para trabalhar com Deadline:

context.WithDeadline() - É definido um valor de tempo fixo.
- Exemplo: o contexto tem até as 22h do dia 09 de outubro de 2022 para ser executado.
context.WithTimeout() - É definido um valor de tempo a partir do instante que foi instanciado.
- Exemplo: o contexto tem 4 minutos a partir de agora para ser executado.

context.WithDeadline()#

Vamos então pegar o mesmo código anterior e alterar alguns trechos:

package main

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

func main() {
    ctx := context.Background()
    deadline := time.Now().Add(3 * time.Second)
    ctx, cancel := context.WithDeadline(ctx, deadline)

    defer cancel()

    executeFunction(ctx)
}

func executeFunction(ctx context.Context) {
    for {
        select {
        case <-ctx.Done():
            fmt.Println("Stopping code execution...")
            return
        default:
            time.Sleep(1 * time.Second)
            fmt.Println("Running at", time.Now())
        }
    }
}

Instanciamos uma nova variável deadline somando três segundos ao tempo de agora e passamos ela para a função context.WithDeadLine(). Dessa forma a instrução da função executeFunction() será interrompida após o intervalo de três segundos.

O resultado da execução do código acima será semelhante a seguinte saída:

Running at 2022-10-09 17:30:50.492897161 -0300 -03 m=+1.000190057
Running at 2022-10-09 17:30:51.493583512 -0300 -03 m=+2.000876359
Running at 2022-10-09 17:30:52.493694606 -0300 -03 m=+3.000987449
Running at 2022-10-09 17:30:53.493795753 -0300 -03 m=+4.001088530
Stopping code execution…

context.WithTimeout()#

Podemos usar a função context.WithTimeout() para produzir o mesmo comportamento. Basta alterarmos as linhas 11 e 12 por:

deadline := 3 * time.Second
ctx, cancel := context.WithTimeout(ctx, deadline)

A diferença, para o código anterior é que, agora, não precisamos mais fazer o cálculo do instante atual somado com os três segundos. A saída será a mesma.

Um ponto curioso nessa estrutura é que executamos também o cancel(), porém com a palavra-chave defer para assegurar que ele será a última coisa a ser executada. Apesar de estarmos delimitando o tempo de execução, podemos também antecipar o cancelamento da instrução a qualquer momento se sobrepondo a regra do limite de tempo, assim como explicado na seção Cancellation Signals.

Request-scoped value#

Além de controlar tempo de execução e parada, com Context também é possível passar valores no estilo chave-valor para instruções filhas. Esse conceito é importante pois ele funciona independente se a chamada para as instruções é síncrona ou assíncrona. Esses valores ficam salvos dentro do contexto e são imutáveis. Vamos detalhar o código abaixo um modelo síncrono:

package main

import (
    "context"
    "fmt"
)

func main() {
    ctx := context.Background()
    ctx = context.WithValue(ctx, "sessionId", "Session123")
    showValue(ctx)
}

func showValue(ctx context.Context) {
    fmt.Println(ctx.Value("sessionId"))
    addKeyValue(&ctx, "typeError", "ErrorType123")
    fmt.Println(ctx.Value("typeError"))
}

func addKeyValue(ctx *context.Context, key interface{}, value interface{}) {
    *ctx = context.WithValue(*ctx, key, value)
}

Definimos o contexto inicial vazio com context.Background(). Após isso, criamos um novo contexto a partir do inicial com context.WithValue() e já também adicionamos valores fictícios ao contexto. Como esses valores ficam guardados no Context, podemos acessá-los em outra parte no programa com a função ctx.Value() passando a chave correspondente. Caso essa chave não exista o retorno é nil. Também é possível adicionar novos valores a um contexto criando um context.WithValues() passando o contexto anterior e atualizando ele próprio.

Demais cenários#

Os casos de uso do Context não se limitam aos aqui apresentados. Atualmente, as bibliotecas em Go, sejam nativas ou não requerem passar Context em suas instruções. O objetivo desse post foi entender a sua base e seus usos comuns.

Até a próxima :)

Diego Fernando

Understanding the Context package in Go

Starting a Context#

context.Background()#

context.TODO()#

Types of Context#

Cancellation Signals#

Deadline#

context.WithDeadline()#

context.WithTimeout()#

Request-scoped value#

Other scenarios#

References#

[PT] Entendendo o package Context em Go

Iniciando um Context#

context.Background()#

context.TODO()#

Tipos de Context#

Cancellation Signals#

Deadline#

context.WithDeadline()#

context.WithTimeout()#

Request-scoped value#

Demais cenários#

Referências#