Ayush Maurya

Posted on Oct 2

Understanding Go's Context Package

#go #backend #requestforpost

I still see many developers struggling with Go’s context package. It can be confusing not just for newcomers, but even for those who’ve been writing Go for a while.

I mostly work in frontend, and during my time with Node.js, I never encountered anything quite like Go’s context.

This guide will help you understand it better. By the end, you’ll know exactly what you’re doing — and why — whenever you use it.

Why Do We Need Context?

Instead of starting with what context is, let’s look at the problem it solves.

Imagine you need batteries for your remote control car, so you ask a friend to go buy them. But just as they leave, you find batteries in your drawer. Now you want your friend to stop and come back.

For this to work, your friend must be aware of the situation in your room.

In Go terms:

Your “room” is like the background context — the environment your operations run in.
Your friend’s awareness of whether to continue or stop the trip is like a cancelable context.

Another example: imagine a function that compresses an image. You don’t want to wait 20 seconds for it to finish. If it completes in 10 seconds, great; if not, you want the ability to cancel the operation.

This is exactly what Go’s context allows you to do: propagate deadlines, cancellations, and request-scoped values across your functions.

A Simple Example: Lucky Numbers

Let’s start simple. Here’s a function that just returns a lucky number:

package main

import (
    "fmt"
)

func main() {
    d, err := requestLuckyNumber()
    if err != nil {
        fmt.Println("Request failed")
        return
    }
    fmt.Println(d)
}

func requestLuckyNumber() (int, error) {
    luckyNumber := 666
    return luckyNumber, nil
}

Nothing fancy here — it always returns 666.

Now let’s turn this into a little game: we want the function to return the lucky number only if it completes within 500ms. If it takes longer, we cancel it and return an error.

This is where context comes in.

Creating a Context with Timeout

We can create a timeout context like this:

ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
defer cancel()

context.Background() is the root context. Think of it as your “room.”
WithTimeout creates a child context that automatically cancels after 500ms.
cancel is a function to manually cancel the context (cleanup resources, stop goroutines, etc.).
Always defer cancel() to avoid leaks.

Using Context in Your Function

Now let’s modify our function to respect this context:

func request(ctx context.Context) (int, error) {
    ch := make(chan int, 1)

    go func() {
        // Simulate some work
        time.Sleep(500 * time.Millisecond)
        ch <- 666
    }()

    for {
        select {
        case <-ctx.Done():
            return 0, ctx.Err() // context canceled or timed out
        case result := <-ch:
            return result, nil
        }
    }
}

What’s happening here:

We run the “work” in a goroutine.
The select statement listens for two cases:
- <-ctx.Done() → fires if the context is canceled or times out.
- result := <-ch → fires when the work completes.

If the work finishes on time, we get our lucky number. Otherwise, the function exits early with an error.

Putting It All Together

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 600*time.Millisecond)
    defer cancel()

    d, err := request(ctx)
    if err != nil {
        fmt.Println("Request failed:", err)
        return
    }

    fmt.Println("Lucky number is:", d)
}

Now your function respects the 600ms limit. If the task takes too long, it gracefully cancels.

Other Useful Context Functions

context.WithCancel → Manually cancel a context from another goroutine.
context.WithDeadline → Cancel automatically at a specific time.
context.WithValue → Pass request-scoped values down the call chain.

Example:

ctx := context.WithValue(context.Background(), "userID", 42)
user := ctx.Value("userID").(int)
fmt.Println(user) // 42

⚠️ Tip: Only use WithValue for request-scoped data, not for optional parameters.

Summary

context helps control long-running operations with cancellation and timeouts.
Always pass context explicitly to functions that may need it.
Use WithTimeout, WithCancel, and WithDeadline for control.
Avoid using WithValue for configuration — it’s meant only for request-scoped data.

By understanding context, you can write Go programs that are safer, cleaner, and more responsive — avoiding goroutine leaks and stuck operations.

💡 If you found this useful, leave a comment or share it. Feedback keeps me motivated to write more content like this!

DEV Community