22. Concurrency
Most of a program's life is spent waiting — for the disk, the network, the user. The CPU sits idle while that happens. This chapter shows how Sprig puts that waiting time to work by doing several things at once, and which traps await when tasks touch the same data.
In this chapter you will learn to:
- what a thread and "blocking" mean, and why many threads became cheap in JDK 21;
- start tasks and collect results with a
@std/concurrentscope; - pass values between tasks through a channel;
- guard atomic counts with a counter, and shared containers with a lock;
- why a top-level
varis shared between tasks, and when it races; - how a failed task's error reaches you.
22.1 Threads and blocking
Why. By default every line you write runs in order: the next line starts when the previous one finishes. A thread is another line of execution, so two threads make progress at the same time. When a task is stuck waiting (the term is blocking, for instance waiting on a network reply), the operating system can park it and let other threads use the CPU.
Since JDK 21, Java has virtual threads: starting ten thousand blocking tasks costs about what ten cost. That is why Sprig does not invent async/await syntax; it gives you "run a function value on another thread", packaged in the bundled @std/concurrent module.
Two waits at the same time:
import "@std/concurrent.spr" as concurrent
func nap(label: String) -> String:
concurrent.sleep(10)
return label
func both(s: concurrent.Scope) -> String throws Error:
let first = concurrent.spawn(s, fn() => nap("tick"))
let second = concurrent.spawn(s, fn() => nap("tack"))
return first.await() + " " + second.await()
print(concurrent.scope(both))tick tacknap("tick")andnap("tack")each wait 10 milliseconds. Both tasks are started before either is awaited, so the two waits overlap: the total is not 20 milliseconds.first.await()andsecond.await()fetch the results in source order, so the joined text is alwaystick tack; whichever task finishes first does not matter.
22.2 A scope owns its tasks
Why. A background task whose result nobody waits for can be lost when the program ends. Sprig's answer is the scope: it owns every task started inside it and waits for all of them before it is done.
import "@std/concurrent.spr" as concurrent
func word_count(line: String) -> Int:
return line.split(" ").size()
# The scope body is a named function passed by reference; its s owns the tasks started inside.
func count_two(s: concurrent.Scope) -> Int throws Error:
let first = concurrent.spawn(s, fn() => word_count("the quick brown fox"))
let second = concurrent.spawn(s, fn() => word_count("a lazy dog"))
return first.await() + second.await()
print(concurrent.scope(count_two))
print(concurrent.parallel_map(["a b", "c d e"], fn(line: String) => word_count(line)))7
[2, 3]concurrent.scope(count_two)creates a fresh scopes, hands it tocount_two, and returns whatever it returns.count_twois a named function passed by reference (chapter 15's function references).concurrent.spawn(s, fn() => word_count("..."))starts a task and returns aTask[Int]. A task body is a function value with a result and no thrown errors.await()waits for that task's result. The scope guarantees: whenscopereturns, every task started inside it has ended.- Line 4,
concurrent.parallel_map(...), is the everyday shortcut: one task per element, results in element order once all have ended.
22.3 Channels: passing values between tasks
Why. Tasks constantly need to hand data to each other, but they must not read a variable another task is changing. A channel is a bounded queue: one side sends, the other receives; when it is full the sender waits, when it is empty the receiver waits.
import "@std/concurrent.spr" as concurrent
# A capacity-4 channel: a producer task sends, the main thread receives until close and drain.
let lines = concurrent.channel[String](4)
func produce() -> Int:
lines.send("one")
lines.send("two")
lines.send("three")
lines.close()
return 3
func drain(s: concurrent.Scope) -> Int throws Error:
let producer = concurrent.spawn(s, produce)
var received = 0
while true:
let line = lines.receive()
if line == null:
break
print("got " + line)
received += 1
return producer.await() + received
print(concurrent.scope(drain))got one
got two
got three
6concurrent.channel[String](4): capacity 4, and the element type must be written.- The producer task
sends three values and callsclose(); the main threadreceives in awhile true:loop andbreaks onnull— a channel never carriesnull, sonullhas exactly one meaning: "closed and drained". - When
scope(drain)ends,producehas ended;producer.await()returns3, and adding the three received values prints6. sendblocks while the channel is full andtry_senddoes not;receive()blocks while empty andreceive_within(millis)waits at most that long.
22.4 Counters, locks and shared state
Why. When two tasks change one number at once, the read-modify-write steps can interleave and updates go missing. Sprig ships two tools: the atomic counter, and a lock guarding a section of code.
import "@std/concurrent.spr" as concurrent
# Four tasks add a thousand times each: counter is atomic, the shared MutableList is lock-guarded.
let hits = concurrent.counter(0)
let seen: MutableList[Int] = []
let guard = concurrent.lock()
func work(id: Int) -> Int:
var i = 0
while i < 1000:
hits.increment()
i += 1
guard.run(fn() => seen.append(id))
return id
func run_all(s: concurrent.Scope) -> List[Int] throws Error:
let tasks: MutableList[concurrent.Task[Int]] = []
for id in [1, 2, 3, 4]:
tasks.append(concurrent.spawn(s, fn() => work(id)))
return concurrent.await_all(tasks)
print(concurrent.scope(run_all))
print(hits.get())
print(seen.size())[1, 2, 3, 4]
4000
4concurrent.counter(0)is an atomicInt: four tasks eachincrementa thousand times and the result is exactly 4000. A counter also hasadd,get,setandcompare_and_set.- The shared
MutableListis guarded byconcurrent.lock():guard.run(fn() => seen.append(id))runs the append while holding the lock, so four tasks never step on each other. - Each task's own local
var iis visible only to that task and needs no protection.
A top-level var is visible to every task
Chapter 15 said a lambda cannot capture a function's var local:
func count_up() -> Int:
var counter = 0
let bump = fn() => counter + 1
return bump()SPR-TYPE-CAPTURE [TYPE] main.spr:3:16: Lambda captures mutable local 'counter'
hint: Copy it into a 'let' binding before the lambda, or use a class field.But a top-level var is not a local variable — it is module state. A lambda can read it and write it, and it is exactly what tasks share:
import "@std/concurrent.spr" as concurrent
var greeting = "hello"
func set_hello() -> Unit:
greeting = "HELLO"
func set_it(s: concurrent.Scope) -> Unit throws Error:
let job = concurrent.run(s, fn() => set_hello())
job.await()
print(greeting)
concurrent.scope_run(set_it)HELLOOnly one task writes here, so the result is certain: the main thread prints after the task has finished. With two tasks writing the same top-level var, the final value depends on scheduling and cannot be predicted. Shared mutable state should become a concurrent.counter (atomic), be wrapped in a concurrent.lock, or be avoided by letting each task write only its own local value and collecting results with await().
22.5 When a task fails
Why. A task runs on another thread, and a failure must not vanish silently. A task body has type fn() -> T with no throws, so errors are handled in the named function it calls:
import "@std/concurrent.spr" as concurrent
func parse_count(text: String) -> Int throws Error:
let n = text.toIntOrNull()
if n == null:
throw Error("not a number: " + text)
return n
# A task body has no throws, so handle errors in the named function it calls.
func count_or_zero(text: String) -> Int:
try:
return parse_count(text)
catch problem: Error:
print("skipped: " + problem.message)
return 0
func count_all(s: concurrent.Scope) -> List[Int] throws Error:
let tasks: MutableList[concurrent.Task[Int]] = []
for text in ["3", "x", "5"]:
tasks.append(concurrent.spawn(s, fn() => count_or_zero(text)))
return concurrent.await_all(tasks)
print(concurrent.scope(count_all))skipped: not a number: x
[3, 0, 5]count_or_zerodoes its owntry/catch, prints a line and returns 0 on failure, so the task always succeeds.- The first task failure cancels the scope's other tasks and is rethrown by
scope()as anError.await_or(fallback)only keeps the wait from throwing; it cannot save the scope: to end successfully, a failure must be handled inside the task body. - Cancellation is cooperative:
cancel()interrupts the task's thread, taking effect insleep,awaitand a blockingreceive.
When an error does escape a task body, await() rethrows it. A Sprig Error keeps its own message:
import "@std/concurrent.spr" as concurrent
let letters = concurrent.channel[Int](1)
letters.close()
func send_anyway() -> Int:
letters.send(1)
return 0
func body(s: concurrent.Scope) -> Int throws Error:
let task = concurrent.spawn(s, send_anyway)
return task.await()
try:
print(concurrent.scope(body))
catch problem: Error:
print("caught: " + problem.message)caught: channel is closedsend on a closed channel raises an Error in the task body, and await() hands it out unchanged with the message channel is closed. Only a Java exception escaping a task body is wrapped, with a message starting task failed:.
22.6 Tasks with no result: run and scope_run
Why. Unit is not a value (chapter 7), so a "do something, return nothing" task cannot be a Task[Unit]. Such work uses run, and such a scope body uses scope_run:
import "@std/concurrent.spr" as concurrent
func announce(line: String) -> Unit:
print("> " + line)
func announce_all(s: concurrent.Scope) -> Unit throws Error:
let job = concurrent.run(s, fn() => announce("ready"))
job.await()
concurrent.scope_run(announce_all)> readyconcurrent.run(s, work)starts afn() -> Unitand returns aJob.job.await()waits for it and throwsErroron failure;cancel(),is_done()and the rest matchTask.scope_run(body)isscope()for a body that returns nothing: it waits for every task and job, and the first failure cancels the rest and is rethrown.
22.7 Why there is no async/await
In other languages async colors a function: an async function can only be awaited inside another async function, splitting a codebase in two. Those languages did that because their threads were expensive. Once JVM virtual threads make blocking cheap, a task is just "an ordinary function running on another thread": no new syntax, no function colors. The structure comes from scopes.
What does not exist yet: a Task has no then, so composition goes through await_all, channels and plain functions; a scope has no timeout budget of its own.
Coming from another language?
From JavaScript or Python: there is no event loop and no await keyword. spawn starts something like a coroutine and await() waits for it; the difference is that a Sprig task really runs on a thread, so blocking Java calls (JDBC, HTTP, files) work unchanged inside one.
Summary
- Concurrency is the bundled
@std/concurrentmodule; a task is a function value on a virtual thread. - A
scopeowns its tasks and waits for all of them;spawn/awaitfetch results, andparallel_mapparallelizes a loop in one line. - Channels carry values:
send,receive,close;nullmeans closed and drained. - Count with
counter, guard shared containers and fields withlock; a top-levelvaris module state and races when tasks write it together. - A task body cannot use
throws: handle errors in the function it calls. The first failure cancels the scope.
Exercises
Exercise 1 (easy). Use parallel_map to double each number in [1, 2, 3] and print the result. Hint: the lambda parameter type must be written: fn(n: Int) => ....
Answer
import "@std/concurrent.spr" as concurrent
let doubled = concurrent.parallel_map([1, 2, 3], fn(n: Int) => n * 2)
print(doubled)[2, 4, 6]Results come back in element order, no matter which task finished first.
Exercise 2 (medium). Have one task send 10, 20 and 30 through a channel, and sum them on the main thread. Hint: channel[Int](8), close() after sending; end the loop on null; start the unit-returning producer with run.
Answer
import "@std/concurrent.spr" as concurrent
let numbers = concurrent.channel[Int](8)
func produce() -> Unit:
numbers.send(10)
numbers.send(20)
numbers.send(30)
numbers.close()
func total(s: concurrent.Scope) -> Int throws Error:
let job = concurrent.run(s, produce)
var sum = 0
while true:
let next = numbers.receive()
if next == null:
break
sum += next
job.await()
return sum
print(concurrent.scope(total))60while true: with if next == null: break is the standard consumption loop; the job.await() is good manners even though the scope would wait anyway.
Exercise 3 (medium). Have three tasks increment one counter a thousand times each, then print each task's return value and the counter's final value. Hint: concurrent.counter(0), increment(), spawn, await_all.
Answer
import "@std/concurrent.spr" as concurrent
let hits = concurrent.counter(0)
func bump() -> Int:
var i = 0
while i < 1000:
hits.increment()
i += 1
return i
func run_all(s: concurrent.Scope) -> List[Int] throws Error:
let tasks: MutableList[concurrent.Task[Int]] = []
for id in [1, 2, 3]:
tasks.append(concurrent.spawn(s, fn() => bump()))
return concurrent.await_all(tasks)
print(concurrent.scope(run_all))
print(hits.get())[1000, 1000, 1000]
3000The counter's add is atomic, so interleaving tasks lose no updates; await_all returns results in task order.
Exercise 4 (harder). Create a pool of two platform threads, use spawn_on to have three tasks each return id * 10, and print the results in order. Hint: concurrent.pool(2), spawn_on(s, pool, ...), then pool.shutdown().
Answer
import "@std/concurrent.spr" as concurrent
func work(id: Int) -> Int:
return id * 10
func run_all(s: concurrent.Scope) -> List[Int] throws Error:
let pool = concurrent.pool(2)
let tasks: MutableList[concurrent.Task[Int]] = []
for id in [1, 2, 3]:
tasks.append(concurrent.spawn_on(s, pool, fn() => work(id)))
let results = concurrent.await_all(tasks)
pool.shutdown()
return results
print(concurrent.scope(run_all))[10, 20, 30]The pool limits CPU-bound work to two threads at a time while the tasks still belong to the scope; after shutdown() the pool takes no new tasks and the running ones finish normally.
Next chapter: Tools and AI assistants — letting the compiler explain the problem for you.
