Background

Regarding Go’s Context, I have only written one article: Printing All Context Values in Go, and that was quite a while ago. Over time, through continuous use of Go, I have gained a deeper understanding of Context. I wanted to expand on this topic, but modifying the previous article didn’t seem appropriate, so I decided to write a new one in a more systematic way.

Common Uses of Context

First, I learned that Context was not introduced at the inception of Go; it was added in Go 1.7. The motivation behind its addition was to solve issues related to cross-goroutine collaboration and information passing. This is reflected in its interface, which includes the following functions:

func WithValue(parent Context, key, val any) Context
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)

These interfaces highlight the primary uses of Context. Below, I provide examples to illustrate their application.

Passing Information

Here is a simple example of passing information through Context:

[root@liqiang.io]# cat example0.go
func main() {
    type favContextKey string
    f := func(ctx context.Context, k interface{}) {
        if v := ctx.Value(k); v != nil {
            fmt.Println("found value:", v)
            return
        }
        fmt.Println("key not found:", k)
    }
    k := favContextKey("language")
    ctx := context.WithValue(context.Background(), k, "Go")
    f(ctx, k)
    f(ctx, "language")
}

The output of this example is:

[root@liqiang.io]# go run example0.go
found value: Go
key not found: language

From the output, you can see that although the key “language” is used in both cases, one retrieves a value while the other does not. This demonstrates that Context keys use strict type comparison. I will discuss this topic further in the future, but if you’re interested, you can check out this document: Go Comparison Operators.

To ensure consistency when storing and retrieving values from Context, it is common practice to define keys as constants, often provided through an SDK. A simplified approach looks like this:

[root@liqiang.io]# cat example1.go
func businessCode(ctx context.Context) {
    val := ctx.Value(sdk.CtxKeyHello)
    if val == nil{
        fmt.Println("value not found in context")
    } else {
        fmt.Println("value found in context ", val.(string))
    }
}

Some developers prefer encapsulating Context operations within an interface, such as:

[root@liqiang.io]# cat example2.go
import "context"
type ContextOperator interface {
    WithHello(ctx context.Context, value interface{})
    GetHello(ctx context.Context)
}

This hides implementation details from users and prevents them from handling Context keys directly, but it is usually used in SDK implementations.

Time Control

In concurrent programming, a common issue is managing concurrency. Suppose we start multiple goroutines to perform a task, but if any of them fail, we may want the others to terminate early. Context can help us manage this, as shown in the following example:

[root@liqiang.io]# cat main.go
func main() {
    ctx, cancel := context.WithCancel(context.Background())
    wg := sync.WaitGroup{}
    wg.Add(3)
    go func() {
        defer wg.Done()
        println("goroutine 1 start")
        <-ctx.Done()
        println("goroutine 1 done")
    }()
    go func() {
        defer wg.Done()
        println("goroutine 2 start")
        <-ctx.Done()
        println("goroutine 2 done")
    }()
    go func() {
        defer wg.Done()
        println("goroutine 3 start")
        time.Sleep(1 * time.Second)
        cancel()
        println("goroutine 3 fail, canceled")
    }()
    wg.Wait()
    println("main done")
}

Here, three goroutines are started. The third one calls cancel() to cancel the context, notifying the first two to terminate early.

Structure of Context

You might have some questions about how Context works internally. For example:

• If multiple Cancel Contexts are nested, does canceling one affect all?
• If I add a new key/value pair to a Context, does it overwrite an existing key?

To answer these questions, we need to examine the source code.

cancelCtx

[root@liqiang.io]# cat context.go
func withCancel(parent Context) *cancelCtx {
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    c := &cancelCtx{}
    c.propagateCancel(parent, c)
    return c
}

A cancelCtx is structured as a tree:

Diagram: Context Tree Structure
Image source: Understanding Context Package in Golang

timerCtx

[root@liqiang.io]# cat context.go
type timerCtx struct {
    cancelCtx
    timer *time.Timer
    deadline time.Time
}

valueCtx

[root@liqiang.io]# cat context.go
type valueCtx struct {
    Context
    key, val any
}
func WithValue(parent Context, key, val any) Context {
    return &valueCtx{parent, key, val}
}

The valueCtx implementation shows that retrieving values from a Go Context involves traversing a linked list, making it inefficient. Therefore, storing key-value pairs in Context should be minimized.

Cross-Process Context Transmission

Contexts are useful within a single process, but what if we need to transmit them across processes, such as in RPC calls? We need to:

1. Determine which key-value pairs to pass.
2. Attach them to the inter-process message.
3. Extract them from the message and restore the Context.

This article explores different approaches to implementing cross-process Context transmission in Go, including timeout handling, cancellation, and best practices.

Identifying Which Key-Value Pairs to Transmit

There are two common approaches:

• Full Transmission: All key-value pairs are transmitted without filtering (rarely used).
• Selective Transmission: Only specific key-value pairs are transmitted (more common).

Selective transmission can be implemented in various ways. One method is using Getter and Setter functions to control which key-value pairs are passed, ensuring consistency and preventing arbitrary modifications. However, this approach requires version updates when new keys need to be supported.

In the open-source RPC framework Kitex, a special key is used to store and pass key-value pairs. This simplifies transmission but can cause issues with service governance, such as key conflicts and length restrictions.

Transmission Protocol

After deciding which key-value pairs to transmit, we need to consider how to transmit them. The implementation varies depending on the protocol:

• HTTP: Headers are a natural choice but have limitations (e.g., ASCII-only support, length restrictions).
• RPC Protocols: Some implementations embed metadata in the request/response body, which complicates service governance.

A common approach is to include metadata in an RPC metadata structure. For example, Kitex uses TTHeader for this purpose. However, different companies implement it in different ways:

• Some teams assign each key to a separate field in the metadata structure.
• Some teams package all key-value pairs into a single metadata field.
• Some teams use a hybrid approach, storing specific keys in separate fields while placing the remaining key-value pairs into a metadata field.

Parsing Key-Value Pairs

When receiving a cross-process message, we must parse the message and extract the transmitted key-value pairs. The method used for parsing is closely tied to how the key-value pairs were transmitted, so the choice of transmission approach directly determines the parsing method. This step does not offer much flexibility and is largely dictated by the first two steps.

A Simple Implementation

After introducing so much, let’s take an example using the Context Operator and assume that we are passing context between two HTTP services. I’ll introduce a simple implementation. First, my Context Operator looks like this:

[root@liqiang.io]# cat example2.go
type ContextOperator interface {
    WithHello(ctx context.Context, value interface{})
    WithWorld(ctx context.Context, value interface{})
    GetHello(ctx context.Context)
    GetWorld(ctx context.Context)
    Marshal() ([]byte, error)
    Unmarshal([]byte) error
}

Sending a Request

When the Client Service is ready to send a request, it needs a middleware to perform context marshaling. The code might look like this:

[root@liqiang.io]# cat example2.go
const contextHeader = "liqiang-io-context"
type Transport struct {
    rt http.RoundTripper
    co ContextOperator
}
func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error) {
    ctx, err := t.co.Marshal(r.Context())
    if err == nil {
        r.Header.Add(contextHeader, string(ctx))
    }
    return http.DefaultTransport.RoundTrip(r)
}

Here, the Context value is placed in the HTTP request and sent out. The Marshal implementation can be very simple, just string concatenation:

[root@liqiang.io]# cat example2.go
func (o *ctxOp) Marshal(ctx context.Context) ([]byte, error) {
    var rtns []string
    if hello := o.GetHello(ctx); hello != nil {
        rtns = append(rtns, "hello="+*hello)
    }
    if world := o.GetWorld(ctx); world != nil {
        rtns = append(rtns, "world="+*world)
    }
    return []byte(strings.Join(rtns, string([]rune{0}))), nil
}

Receiving a Request

On the server side, after receiving the HTTP request, we perform the opposite operation by wrapping the HTTP Handler:

[root@liqiang.io]# cat example2.go
type wrapperHandler struct {
    h  http.Handler
    co ContextOperator
}
func (h *wrapperHandler) ServeHTTP(resp http.ResponseWriter, req *http.Request) {
    ctxVal := req.Header.Get(contextHeader)
    ctx, err := h.co.Unmarshal([]byte(ctxVal))
    if err == nil {
        req = req.WithContext(ctx)
    }
    h.h.ServeHTTP(resp, req)
}
func NewWrapperHandler(h http.Handler) http.Handler {
    return &wrapperHandler{
        h: h,
    }
}

Similarly, the Unmarshal operation is simply string decomposition:

[root@liqiang.io]# cat example2.go
func (o *ctxOp) Unmarshal(content []byte) (context.Context, error) {
    vals := strings.Split(string(content), string([]rune{0}))
    ctx := context.Background()
    for _, val := range vals {
        switch val {
        case "hello":
            ctx = o.WithHello(ctx, val)
        case "world":
            ctx = o.WithWorld(ctx, val)
        }
    }
    return ctx, nil
}

Passing Cancel and Timeout

At first glance, the above example seems to have implemented context passing. However, in reality, it does not cover the full capabilities of Go’s context, especially its most commonly used features: WithTimeout and WithCancel.

Cancel

The WithCancel function might seem straightforward—it cancels a cross-process request. However, in practice, it’s more complex than expected because Go’s default networking library does not support context.

Let’s look at the net.Conn interface:

[root@liqiang.io]# cat net/net.go
type Conn interface {
    Read(b []byte) (n int, err error)
    Write(b []byte) (n int, err error)
    Close() error
}

As we can see, there’s no way to control read or write using context. So when passing a Cancel across processes, it’s not feasible with the default networking interface. Because of this limitation, developers have found some workarounds. Below are two common patterns:

Goroutine Pattern

Since goroutines are lightweight in Go, one common approach is:

[root@liqiang.io]# cat example3.go
import "context"
func passCancel1(ctx context.Context) {
    var networkDone chan struct{}
    go func() {
        // network operation 1
        networkDone <- struct{}{}
    }()
    select {
    case <-ctx.Done():
        // canceled
    case <-networkDone:
        // completed normally
    }
    return
}

However, this approach has a risk of goroutine leaks, so careful handling is required.

Busy-Wait Pattern

Another approach is to set a very short timeout for network operations. If the operation completes before cancellation, it’s normal; otherwise, it’s considered canceled.

[root@liqiang.io]# cat example4.go
func networkProcess(ctx context.Context) {
    for {
        conn.SetReadDeadline(time.Now().Add(time.Microsecond * 20))
        readBytes, err := conn.Read(buffer)
        if err != nil {
            return
        }
        if readBytes > 0 {
            return
        }
        select {
        case <-ctx.Done():
        default:
            continue
        }
    }
}

This method has an obvious drawback—it wastes a lot of CPU resources. The fundamental issue is that network operations don’t recognize Cancel Context. Therefore, in practice, passing cancelable contexts between processes is rare, while timeout usage is more common.

Timeout

Passing a Timeout Context is similar to passing context values, but with a key difference: when process A passes the timeout to process B, process B must be able to apply the timeout correctly.

In the in-process context implementation, timeoutCtx is essentially a Deadline Context. Let’s look at how Deadline Context is implemented:

[root@liqiang.io]# cat context/context.go
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
    ... ...
    dur := time.Until(d)
    ... ...
    if c.err == nil {
        c.timer = time.AfterFunc(dur, func() {
            c.cancel(true, DeadlineExceeded)
        })
    }
    return c, func() { c.cancel(true, Canceled) }
}

We can see that Deadline is implemented using a timer that automatically cancels the context when it expires.

At first glance, it seems simple—just pass the deadline value to the remote process, like this:

[root@liqiang.io]# cat exmaple2.go
func (o *ctxOp) Marshal(ctx context.Context) ([]byte, error) {
    var rtns []string
    if hello := o.GetHello(ctx); hello != nil {
        rtns = append(rtns, "hello="+*hello)
    }
    if world := o.GetWorld(ctx); world != nil {
        rtns = append(rtns, "world="+*world)
    }
    if dl, ok := ctx.Deadline(); ok {
        rtns = append(rtns, "deadline="+strconv.FormatInt(dl.UnixMilli(), 10))
    }
    return []byte(strings.Join(rtns, string([]rune{0}))), nil
}
func (o *ctxOp) Unmarshal(content []byte) (context.Context, context.CancelFunc, error) {
    vals := strings.Split(string(content), string([]rune{0}))
    ctx := context.Background()
    var cancel context.CancelFunc
    for _, val := range vals {
        switch val {
        case "hello":
            ctx = o.WithHello(ctx, val)
        case "world":
            ctx = o.WithWorld(ctx, val)
        case "deadline":
            i, err := strconv.ParseInt(val, 10, 64)
            if err == nil {
                t := time.Unix(i/1e9, i%1e9)
                ctx, cancel = context.WithDeadline(ctx, t)
            }
        }
    }
    return ctx, cancel, nil
}

However, this approach has a major issue in a distributed environment: it relies on UNIX timestamps, which means both machines must be perfectly time-synchronized. Otherwise, the timeout might trigger too early or too late.

A better approach is to pass relative time. For example, if process A sets an initial timeout of 5000ms and has already used 500ms, then it should pass 4500ms to process B. To account for network latency, process A might extend its wait time slightly (e.g., 4550ms instead of 4500ms).

Ref

• context package
• Go Concurrency Patterns: Context