Standard library · Time and concurrency

ctx

A context for cancellation and deadlines, passed from the main piece of work down to the smaller ones.

import ctx

A context tells long-running work when to stop: either someone called Cancel, or its deadline passed. Contexts form a tree: you start from Background and make a child each time with WithCancel, WithTimeout or WithDeadline.

Cancelling a context ends all its children, but not its parent. The work should check IsDone from time to time, or wait on it with Wait. Free each context with Free when you are done with it, children before parents.

Use a context when work that may take long has to stop early: a request whose client went away, a batch job with a time budget, a background thread at shutdown. It is built on sync and works across threads. For one stop flag and nothing else, an atomic.Flag is enough; to pass results back, use a chan.

The things people get wrong:

  • Expecting a context to interrupt a call. No standard library function takes one: a network request, a file read or a sync.SleepMs runs to its end. Check IsDone between steps, sleep with Wait, and give network calls their own timeout options.
  • Freeing in the wrong order. A child keeps a copy of its parent that points at the parent's memory, and freeing the root destroys the lock the whole tree shares. Free children first, the root last, each exactly once.
  • Assuming the deadlines follow a steady clock. They are measured with sync.NowMs, which on Linux and macOS is the wall clock, so setting the system time moves them.

Guide: one context per request

The usual shape is one context for a whole piece of work, such as an HTTP request or a batch job, and a child for every smaller task it starts. When the request is cancelled, every task under it sees IsDone turn true, while work hanging from another branch keeps going. The program below builds that tree and cancels the request in the middle.

ctx-guide-tree.salam
import ctx

func show(name: str, c: ctx.Context):
    if ctx.IsDone(c):
        println name, "stopped:", ctx.Err(c)
    else:
        println name, "running"
    end
end

func main:
    root := ctx.Background()
    request := ctx.WithCancel(root)
    db_query := ctx.WithCancel(request)
    cache := ctx.WithCancel(request)
    audit := ctx.WithCancel(root)

    ctx.Cancel(request)

    show("request", request)
    show("db query", db_query)
    show("cache", cache)
    show("audit", audit)
    show("root", root)

    ctx.Free(audit)
    ctx.Free(cache)
    ctx.Free(db_query)
    ctx.Free(request)
    ctx.Free(root)
end
Outputrequest stopped: cancelled db query stopped: cancelled cache stopped: cancelled audit running root running

Cancelling goes down the tree, never up: root and audit are untouched. That is why each task should get its own child instead of sharing the parent: you can stop one task alone by cancelling its child, or all of them by cancelling the parent.

Guide: check between steps

A context does not stop anything by force. The work has to look at it, and the right place is between steps, before each item of a loop or before each slow call. Pass the context as the first argument of every function that may take long, and return early when it is done.

ctx-guide-steps.salam
import ctx

func copy_files(c: ctx.Context, files: Vector<str>): int:
    mut copied := 0
    each name in files:
        if ctx.IsDone(c):
            println "  stopped before", name, "(" + ctx.Err(c) + ")"
            ret copied
        end
        println "  copied", name
        copied++
    end
    ret copied
end

func main:
    mut files := Vector {} as Vector<str>
    files.Push("a.txt")
    files.Push("b.txt")
    files.Push("c.txt")
    root := ctx.Background()

    println "normal run:"
    live := ctx.WithCancel(root)
    println "  total", copy_files(live, files)

    println "cancelled by the user:"
    stopped := ctx.WithCancel(root)
    ctx.Cancel(stopped)
    println "  total", copy_files(stopped, files)

    println "deadline already passed:"
    late := ctx.WithDeadline(root, 1)
    println "  total", copy_files(late, files)

    ctx.Free(late)
    ctx.Free(stopped)
    ctx.Free(live)
    ctx.Free(root)
    files.Free()
end
Outputnormal run: copied a.txt copied b.txt copied c.txt total 3 cancelled by the user: stopped before a.txt (cancelled) total 0 deadline already passed: stopped before a.txt (deadline exceeded) total 0

The same function serves all three cases, and the caller decides which one applies. Err tells the two reasons apart: cancelled when someone called Cancel, deadline exceeded when the time ran out. WithDeadline(root, 1) uses an instant long past, so its context is done from the start.

Guide: time budgets

A child can never outlive its parent. A child with a longer timeout than its parent still ends at the parent's deadline, and Deadline reports the nearest deadline of the context and all its parents. A child with a shorter timeout ends earlier on its own, and its parent goes on.

ctx-guide-budget.salam
import ctx

func main:
    root := ctx.Background()
    request := ctx.WithTimeout(root, 2000)
    lookup := ctx.WithTimeout(request, 60000)
    quick := ctx.WithTimeout(request, 50)

    println "root has a deadline:", ctx.Deadline(root) != 0
    println "lookup keeps the request budget:", ctx.Deadline(lookup) == ctx.Deadline(request)
    println "quick is tighter:", ctx.Deadline(quick) < ctx.Deadline(request)

    println "quick finished within 1 s:", ctx.Wait(quick, 1000), ctx.Err(quick)
    println "request still running:", not ctx.IsDone(request)

    ctx.Free(quick)
    ctx.Free(lookup)
    ctx.Free(request)
    ctx.Free(root)
end
Outputroot has a deadline: false lookup keeps the request budget: true quick is tighter: true quick finished within 1 s: true deadline exceeded request still running: true

So a request can get a total budget of two seconds at the top, and a step deep inside can ask for a minute without breaking it. Wait returns true as soon as the context finishes, here after about 50 milliseconds, and false if its own time limit ran out first.

Guide: stopping a thread

A context is safe to share between threads, so it is the clean way to tell a background thread to stop. The thread loops until IsDone is true and sleeps with Wait between rounds, so a Cancel from the main thread wakes it at once instead of after its next sleep.

ctx-guide-worker.salam
import ctx
import sync

mut root := ctx.Background()
mut job := ctx.WithCancel(root)
mut wg := sync.NewWaitGroup()
mut finished := false

func worker():
    until ctx.IsDone(job):
        _ := ctx.Wait(job, 100)
    end
    finished = true
    sync.Done(wg)
end

func main:
    sync.Add(wg, 1)
    t := spawn(worker)
    sync.SleepMs(50)
    println "asking the worker to stop"
    ctx.Cancel(job)
    sync.Wait(wg)
    join(t)
    println "worker finished:", finished, "reason:", ctx.Err(job)

    sync.DestroyWaitGroup(wg)
    ctx.Free(job)
    ctx.Free(root)
end
Outputasking the worker to stop worker finished: true reason: cancelled

A loop that calls sync.SleepMs instead of Wait would also stop, but only after the sleep ends. Free the context only after the thread is joined, since the thread still reads it until it returns.

Which function for which job

You wantUse
A root for a new treeBackground, which never finishes by itself
A task you stop by handWithCancel, then Cancel
A task with a time limitWithTimeout(parent, ms)
A task that must end at a fixed timeWithDeadline(parent, at_ms) with an instant from sync.NowMs
To check without blockingIsDone, and Err for the reason
To sleep but wake on cancelWait(c, ms)

Two mistakes are common. Freeing a parent while its children are still in use leaves them pointing at freed memory, so free children first. And a context only helps when the work checks it: a long call that never looks at IsDone runs to the end however early you cancel.

Types

Context

struct Context
A context.
NameTypeDescription
statei64*The internal state: cancelled, the deadline and whether there is one.
parentContext*The parent context, or null for the root.
musync.MutexThe lock every context in one tree shares.
cvsync.CondVarThe condition variable that cancellation wakes.
is_rootbool = falseWhether this context is the root.
ctx-Context.salam
import ctx

func main:
    root := ctx.Background()
    cancellable := ctx.WithCancel(root)
    timed := ctx.WithTimeout(cancellable, 30)
    println ctx.IsDone(timed), "[" + ctx.Err(timed) + "]", ctx.Deadline(timed) > 0, ctx.Deadline(root)
    println ctx.Wait(timed, 10)
    println ctx.Wait(timed, 1000), ctx.Err(timed)
    ctx.Cancel(cancellable)
    println ctx.IsDone(cancellable), ctx.Err(cancellable), ctx.IsDone(root)
    past := ctx.WithDeadline(root, 1)
    println ctx.IsDone(past), ctx.Err(past)
    ctx.Free(past)
    ctx.Free(timed)
    ctx.Free(cancellable)
    ctx.Free(root)
end
Outputfalse [] true 0 false true deadline exceeded true cancelled false true deadline exceeded

Functions

Background

func Background(): Context
The root context, which never finishes by itself.

The example for this item is shown with the ones above: ctx-Context.salam

WithCancel

func WithCancel(parent: Context): Context
A child that ends when Cancel is called.

The example for this item is shown with the ones above: ctx-Context.salam

WithTimeout

func WithTimeout(parent: Context, ms: i64): Context
A child that ends ms milliseconds from now.

The example for this item is shown with the ones above: ctx-Context.salam

WithDeadline

func WithDeadline(parent: Context, at_ms: i64): Context
A child that ends at the instant at_ms, in milliseconds, as sync.NowMs gives it.

The example for this item is shown with the ones above: ctx-Context.salam

Cancel

func Cancel(c: Context)
Ends the context and all its children and wakes everything waiting.

The example for this item is shown with the ones above: ctx-Context.salam

IsDone

func IsDone(c: Context): bool
True when the context, or one of its parents, has been cancelled or has passed its deadline.

The example for this item is shown with the ones above: ctx-Context.salam

Err

func Err(c: Context): str
Why it finished: cancelled or deadline exceeded, or an empty string while it is still running.

The example for this item is shown with the ones above: ctx-Context.salam

Deadline

func Deadline(c: Context): i64
The nearest deadline in the context and its parents, in milliseconds, or zero when there is none.

The example for this item is shown with the ones above: ctx-Context.salam

Wait

func Wait(c: Context, ms: i64): bool
Waits at most ms milliseconds for the context to finish and says whether it did.

The example for this item is shown with the ones above: ctx-Context.salam

Free

func Free(c: Context)
Releases the context's memory.

The example for this item is shown with the ones above: ctx-Context.salam