Forem: Vladislav Semenkov

Cascading context cancellation in Go: from source code to production patterns

Vladislav Semenkov — Sun, 29 Jun 2025 07:11:04 +0000

This time, I would like to delve deeper into the work of the internal interaction of the context from the prism of its cancellation, so this article is a continuation of the previous one.

Cancellation as explicit

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    go func() {
        if err := worker(ctx); err != nil {
            log.Printf("worker is executed: %v", err)
        }
    }()

    time.Sleep(time.Second)

    cancel()

    time.Sleep(2 * time.Second)
}

func worker(ctx context.Context) error {
    select {
    case <-time.After(5 * time.Second):
        return nil
    case <-ctx.Done():
        log.Printf("worker is cancelled, err: %v", ctx.Err())

        return ctx.Err()
    }
}

For clarity, I have prepared a simple example that demonstrates how to cancel the context. What will this piece of code output?

worker cancelled, err: context canceled
worked is executed: context canceled

The CancelFunc function informs the operation about the shutdown, but does not wait for its completion. It can be called simultaneously by several subroutines. After the first call, subsequent calls do nothing.

It does not contain a "special" internal implementation, it just checks whether the context is parent and calls propagateCancel.

What happens in this piece of code step by step:

1) creating a context with cancellation
2) we call goroutine in the background, which performs a "certain" worker in itself
3) we are waiting for the time to work for the worker
4) cancel the context

We have written the simplest example of how context cancellation works.

How did the context know to close Done?

Let's dig inside the propagateCancel method itself.

The signature of this method itself includes 2 parameters.

1) the Context interface itself
2) The canceler interface

Let me remind you what the Context interface itself looks like.:

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

The canceler itself:

type canceler interface {
    cancel(removeFromParent bool, err, cause error)
    Done() <-chan struct{}
}

Do not forget that there are internal structures in the context itself, while the cancellation context comes from cancelCtx. propagate itself:

func (c *cancelCtx) propagateCancel(parent Context, child canceler) {
    // assigning a parent context to the current cancellation context
    c.Context = parent

    // if the parent context does not support undo (its Done method returns nil), the method terminates.
    done := parent.Done()
    if done == nil {
        return // the parent is never cancelled
    }

    select {
    case <-done:
        // the parent has already been canceled
        child.cancel(false, parent.Err(), Cause(parent))
        return
    default:
    }

    // adding the child context to the children list of the parent context so that it can be canceled along with the parent context.
    if p, ok := parentCancelCtx(parent); ok {
        // the parent is *cancelCtx, or is it derived from it
        p.mu.Lock()
        if p.err != nil {
            // the parent has already been canceled
            child.cancel(false, p.err, p.cause)
        } else {
            if p.children == nil {
                p.children = make(map[canceler]struct{})
            }
            p.children[child] = struct{}{}
        }
        p.mu.Unlock()
        return
    }

    if a, ok := parent.(afterFuncer); ok {
        // parent implements the AfterFunc method
        c.mu.Lock()
        stop := a.AfterFunc(func() {
            child.cancel(false, parent.Err(), Cause(parent))
        })
        c.Context = stopCtx{
            Context: parent,
            stop:    stop,
        }
        c.mu.Unlock()
        return
    }

    // if none of the previous conditions is met,
    // the method starts a new routine, which waits for a signal to 
    cancel
   // the parent context and, if received, cancels the child context.
    goroutines.Add(1)
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err(), Cause(parent))
        case <-child.Done():
        }
    }()
}

propagateCancel organizes the cancellation of the child element in the presence of the parent, sets the parent context cancelCtx. Thus, the propagateCancel method ensures that the cancellation of the parent context is correctly transmitted to all child contexts, ensuring consistency and simplifying lifetime management of related operations.
As can be seen from the source code of cancelCtx creation, the internal cancelCtx signaling depends on the Done channel. If you want to cancel this context, you need to block everything <-c.Done (). The easiest way is to close this channel or replace it with an already closed channel.

It is important to remember: Every cancelCtx has a map children, and when the context is canceled, it is iterated over it, as can be seen from the source code. That is, the scheme of an approximate interaction may look like this:

Parent (cancelCtx) -> Child(timerCtx) -> GrandChild(cancelCtx)

But you may ask, since the map itself is not visible, what is the internal structure of the context?

type cancelCtx struct {
    Context

    mu       sync.Mutex 
    done     atomic.Value
    children map[canceler]struct{} 
    err      atomic.Value
    cause    error
}

Everything is quite simple here, we use the mutex so that there is no race, the rest of the fields are used for their intended purpose, I analyzed the very inside of the cancellation context and other contexts in the last article, I advise you to familiarize yourself, as I would like to touch on the practical aspect.

WithCancelCause

This context is primarily needed to create a context with a "reason" if we want to return a custom error in it, which can be useful to use in specific queue processing locations in production code, where we need to properly consolidate errors related to context cancellation.

func main() {
    base := context.Background()

    ctx1, cancel1 := context.WithCancel(base)
        cancel1()

    fmt.Println("With cancellation:")
        fmt.Printf("Error() = %v\n", ctx1.Err())
        fmt.Printf("Cause() =%v\n\n", context.Cause(ctx1))

    ctx2, cancel2 := context.WithCancelCause(base)
        cancel2(errors.New("some kind of error"))

    fmt.Println("Cancelled for the reason:")
        fmt.Printf("Error = %v\n", ctx2.Err())
        fmt.Printf("Reason = %v\n\n", context.Cause(ctx2))

    child, _ := context.WithTimeout(ctx2, 0)
        fmt.Println("Child context:")
        fmt.Printf("Error = %v\n", child.Err())
    fmt.Printf("Reason = %v\n", context.Cause(child))
}

Output:

With cancellation:
Err() = context cancelled
Cause() = context canceled

With cancellation due to:
Error = context cancelled
Reason = some kind of error

Child context:
Error = context cancelled
Reason = some kind of error

Cause() propagates down the context tree - child contexts roughly "inherit" the cause.

What if we try to call cancel(nil)?

Then everything will be fine in terms of processing, since the context will keep the context cancelled.

What can be emphasized?

1) We have the very fact of canceling Err(), which is compatible with versions when cause did not exist yet.
2) Cause can be used for detailed diagnostics.

Access from multiple goroutines

By itself, ctx.Done() is safe to call from multiple goroutines.

Because:

1) The channel that returns ctx.Done is closed once at the moment of the first successful context cancellation.

2) To prevent a race, as I described above, the context uses mutexes and atomics.

Important points:

1) You can wait for cancellation from as many locations as you like
2) You can also call Err from several goroutines, since atomic is used.
3) You can cancel the context everywhere, but it will only work once)

AfterFunc

It is a convenient thing to execute any code when context is canceled.

stopRollback := context.AfterFunc(ctx, func() {
    log.Printf("ctx is cancelled")
    _ = tx.Rollback()
})

// smth buisnes logic

if stopped := stopRollback(); stopped {
    log.Print("commit is executed")
}

We use it if we want to do rollback and other things through the context, when canceling it, or use it as a context handler that you don't know about yet.

1) Does not block the current routine, runs in a new one
2) There is no conflict between multiple AfterFunc
3) If the context has already been canceled, it starts instantly.
4) It can save you from deadlock if, for example, you forgot to unlock the mutex by timeout.

The AfterFunc function accepts a function that will be executed after the context is terminated, including when the timeout expires. If the context has already ended, the function will start immediately. The function is executed in a separate thread. At the same time, every call AfterFunc is performed independently of the others.
AfterFunc returns the stop function. When the stop function is called, the connection between the function and the context is broken. If the context is already in the state Done and the function has already been started, or if the function has already been stopped, the stop function returns false.
The function exits if the value is true. The stop function does not wait for the function to complete, so it is recommended to explicitly interact with it to monitor the status.

Do not forget to remove the stop after completing the work. If you need synchronicity, you need to do it yourself.

Also, do not forget, if you use AfterFunc, that the function or method must be impodent, otherwise a race may happen. Because the context is canceled and the function starts at the same moment when stop() is called. For example, tx.Rollback() is already impodent, so everything is fine, but when working with a file, you need to add sync.Once().

WithoutCancel

After many interviews with people for the middle position and above, I noticed that many people do not know about its existence. In general, almost 90 percent of the articles in which the context was specified were simply avoided, but in general it is understandable, a new method that appeared relatively recently. I will not talk about him and will insert a quote from my last article.

WithoutCancel is useful in situations where certain operations must complete regardless of the state of the parent context. This can be useful for background tasks, logging, caching, and any other tasks that need to be completed even if the main operation is canceled, such as a rollback operation.
The context does not return Deadline or Err. The Done channel value is nil. Reading from it will cause the program to lock.

Timers

There is also a cancellation with a deadline and a timeout, which are essentially the same thing under the hood, just different types, but that's it - tmerCtx

WithDeadline(parent Context, d time.Time) (Context, CancelFunc) - creates a child context using the cancel method from the parent context, except that the context will be automatically canceled when the specified time is reached.
context.WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) is the same as WithDeadline, except that it specifies the timeout from the current time.

`cancelCtx` patterns

Let's start with simple rules for how your contexts work:

ctx, cancel := context.WithTimeout(parent, 100*time.Millisecond)
defer cancel()

defer cancel() immediately after WithCancel, WithTimeout. If not called, the child context and its timers will hang until the parent is canceled and flow through memory.

The simplest example:

func main() {
    fmt.Println("goroutines before:", runtime.NumGoroutine())

    for i := 0; i < 500; i++ {
        ctx, _ := context.WithTimeout(context.Background(), time.Minute)
        go func() { <-ctx.Done() }() // each creates a timer and a routine
    }

    fmt.Println("goroutines after :", runtime.NumGoroutine())

    time.Sleep(2 * time.Second)
}}

Output:

goroutines before: 1
goroutines after : 501

Close the workers cascadingly, since one cancel in the parents closes the Done channel for all descendants.

go worker(ctx) // <-ctx.Done()
...
cancel()

WithTimeout and WithDeadline will automatically cancel the request, even if you forgot to call cancel()

ctx, cancel := context.WithTimeout(ctx, 1*time.Second)
defer cancel()
res, err := httpClient.Do(req.WithContext(ctx))

Do not forget to wrap the context after WithoutCancel into a child context with the cancellation time!

The rest of the patterns are used as a "base" if you are familiar with the definition and operation of the context itself and are common.

closedchan

Initially, the package contains a closed channel so that the first context cancellation takes place without unnecessary allocations and without double closure. When cancelCtx.cancel is called for the first time, it checks whether the done channel has not yet been created, otherwise, instead of make(chan struct{}), it simply writes a link to an already closed closedchan.

Why is this necessary?:

We avoid allocation so that we use a ready-made object.
There is no panic if we call close again. All post calls will see that it indicates a closed channel.
Serves only for the cancel signal

Conclusion

The article turned out to be succinct and uncomplicated, where the main aspects of context cancellation were touched upon, if there are any suggestions for improving the article or adding it, I will gladly accept suggestions! Thanks to everyone who read it to the end!

Juggling Memory: Arenas in Golang

Vladislav Semenkov — Sat, 28 Jun 2025 23:48:58 +0000

Greetings, in a highly loaded environment, large allocation often strongly affects the processing speed of a particular part of the service, in order to more finely control memory, arenas have appeared. How do they turn on? It's simple, you need the GOEXPERIMENT=arenas flag. Let's take an example of how memory works with "tiny objects".

The route of the "tiny object"

The so-called "tiny allocator" is responsible for "tiny objects" in Golang. How does it work?

In golang, all tiny objects go through the path: tiny allocator -> cache -> span pool (with tiny Span Class) - heap.

A tiny object, in turn, is considered an object that is less than 16 bytes, if you look at the source code, you can see why you chose such a constant:

// Size of the memory block used for combining (maxTinySize) is tunable.
// Current setting is 16 bytes, which relates to 2x worst case memory
// wastage (when all but one subobjects are unreachable).
// 8 bytes would result in no wastage at all, but provides less
// opportunities for combining.
// 32 bytes provides more opportunities for combining,
// but can lead to 4x worst case wastage.
// The best case winning is 8x regardless of block size.

Everything is done primarily for optimization.

All these actions are inside a single P, so the allocation of a tiny object is very insignificant. The GC intervenes only twice per cycle: stop the world, at the beginning and end of the marking (termination), and a concurrent mark runs between them. Simply put, an automatic mark and sweep is used. In turn, in the arena, many objects are poured into one span and given to runtime in one operation, our GC does not interfere and we ourselves have to monitor the lifecycle.

Arena objects do not participate in tri-color until Free, where only the pointer is shifted without global structures inside the allocated span

Span

Earlier in the article, I mentioned "Span", what is it in the classical sense of Go?

Span is a continuous sequence of pages, a minimal block that the allocation and GC operators operate on inside the heap.

When there are no free cells of the required size in the local mcache, it takes a completely free span from the mcentral and divides it with a bump pointer for objects.

mcentral, when it no longer has enough memory, requests a new span from the global page manager mheap. It, in turn, reserves N pages in the page heap.

We can discuss this topic in more detail in the following articles, but we won't dwell on it for now.

The first steps

First, let's turn on our arenas:

 export GOEXPERIMENT=arenas

Preface: for large objects, go allocates its own mspan (set of pages) and returns come from the global mheap. Let's take an example using bench + arenas:

func nsPerAlloc(b *testing.B) {
    b.ReportMetric(float64(b.Elapsed().Nanoseconds())/M, "ns/alloc")
}

type Big [1 << 20]byte
const M = 10_000

func BenchmarkHeapBig(b *testing.B) {
    for i := 0; i < b.N; i++ {
        buffers := make([]*Big, M)

        for j := 0; j < M; j++ {
            buf := new(Big)
            buf[0] = byte(j)
            buffers[j] = buf
        }
    }

    nsPerAlloc(b)
}

func BenchmarkArenaBig(b *testing.B) {
    for i := 0; i < b.N; i++ {
        a := arena.NewArena()
        buffers := make([]*Big, M)

        for j := 0; j < M; j++ {
            buf := arena.New[Big](a)
            buf[0] = byte(j)
            buffers[j] = buf
        }

        a.Free()
    }

    nsPerAlloc(b)
}

goos: darwin
goarch: arm64
pkg: a
cpu: Apple M3 Pro
BenchmarkHeapBig-11                 28        1843796832 ns/op           5162629 ns/alloc     10485842133 B/op           10001 allocs/op
BenchmarkArenaBig-11                 1        1314971541 ns/op            131497 ns/alloc     11800062248 B/op            1445 allocs/op
PASS
ok      a       53.578s

Why is that?

1) each large object in runtime follows the path of a large allocation with span allocation, 10k allocations - 10k sys calls
2) the arena, in turn, reserves a large span and small allocations for slice headers

How to work with arenas?

Here is a sample code that covers the basic API for working with them:

type Point struct {
    x, y int
}

const N = 1_000

func main() {
    a := arena.NewArena() // creating
    defer a.Free() // release

    p := arena.New[Point](a) // allocation to the structure
    p.x, p.y = 10, 20

    points := arena.MakeSlice[Point](a, 0, 100) // a slice inside the same arena

    for i := 0; i < 10; i++ {
        pt := arena.New[Point](a)
        pt.x, pt.y = i, i*i

        points = append(points, *pt)
    }

    heapPoints := arena.Clone(points) // now the whole slice is in heap

    fmt.Println("first =", heapPoints, "len =", len(heapPoints))
}

go run tiny.go
first = [{0 0} {1 1} {2 4} {3 9} {4 16} {5 25} {6 36} {7 49} {8 64} {9 81}] len = 10

The arenas inside

The arena itself stores a pointer inside itself

type Arena struct {
  a unsafe.Pointer
}

In turn, NewArena calls the runtime_arena_newArena() unsafe.Pointer. Which allocates one shared mspan across a shared heap.

How does the GC see the arena?

the peculiarity of the arena, as I noted above, is that the GC does not scan the arena and does not allow objects to it, because it marks it as noscan.

After Free, the GC starts viewing the arena as an object and the arena itself is marked as a zombie

the sweep-worker, after the mark-term, translates span to idle and memory can be transferred to a regular heap, reuse just happens after the next GC cycle.

There is another feature related to the fact that it has a finalizer, which is needed if the developer does not call Free, then runtime will catch it.

`arena.New[T](a)`

the runtime_arena_arena_New call gets the type via reflect.Type

It takes into account alignment, copies the zero-word and simply shifts the bump pointer.

`arena.MakeSlice[T](a,len,cap)`

reserves the backing array with the same bump pointer, but places the slice header in the regular heap
to optimize GC inside the chunk: Pointer-full objects grow from bottom to top, Pointer-free objects grow from top to bottom. This gives runtime the right to finish scanning earlier and skip clearing the bitmap for clean memory areas.

Clone

Copies the type to a regular heap via runtime_arena_heapify, zeroing out all connections to the arena.

As a result:

data lives arbitrarily long.
the GC starts scanning them as an ordinary object.
it is also worth considering that if Clone is forgotten or the object is being used after Free, the program crashes with SIGSEGV, which makes it easy for us to track such frauds with the past address space.

When to use the arenas?

when you need to process large data in one request, for example, a large short-lived buffer and you need to release it all at once.
large objects of different sizes, so as not to generate sync.Pool, and as we know, the GC can release them at the wrong moment ;)
if we use arenas, it's best to use the build tag, because they may be removed in the future, as written in the comments to the source code themselves.

When not to use the arenas?

multiple fixed buffers, sync.Pool will do it faster, the bench will show it very well
objects live longer than the request
and most importantly, the arena is not thread-safe, so it's better to limit it to running it in a single goroutine.

That's it:(

I hope you enjoyed this article, if you have any suggestions or improvements on the article, write! I will be grateful!