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.SleepMsruns to its end. CheckIsDonebetween steps, sleep withWait, 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.
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)
endCancelling 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.
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()
endThe 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.
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)
endSo 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.
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)
endA 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 want | Use |
|---|---|
| A root for a new tree | Background, which never finishes by itself |
| A task you stop by hand | WithCancel, then Cancel |
| A task with a time limit | WithTimeout(parent, ms) |
| A task that must end at a fixed time | WithDeadline(parent, at_ms) with an instant from sync.NowMs |
| To check without blocking | IsDone, and Err for the reason |
| To sleep but wake on cancel | Wait(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| Name | Type | Description |
|---|---|---|
state | i64* | The internal state: cancelled, the deadline and whether there is one. |
parent | Context* | The parent context, or null for the root. |
mu | sync.Mutex | The lock every context in one tree shares. |
cv | sync.CondVar | The condition variable that cancellation wakes. |
is_root | bool = false | Whether this context is the root. |
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)
endFunctions
Background
func Background(): ContextThe example for this item is shown with the ones above: ctx-Context.salam
WithCancel
func WithCancel(parent: Context): ContextCancel is called.The example for this item is shown with the ones above: ctx-Context.salam
WithTimeout
func WithTimeout(parent: Context, ms: i64): Contextms 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): Contextat_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)The example for this item is shown with the ones above: ctx-Context.salam
IsDone
func IsDone(c: Context): boolThe example for this item is shown with the ones above: ctx-Context.salam
Err
func Err(c: Context): strcancelled 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): i64The example for this item is shown with the ones above: ctx-Context.salam
Wait
func Wait(c: Context, ms: i64): boolms 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)The example for this item is shown with the ones above: ctx-Context.salam