Learn · step 9 of 9
Work on every core, and what may cross
spawn stays on its spawner's thread and may touch anything; spawn_parallel runs on any core and may capture only what is Share. Server.serve puts every connection on that pool, so its block is checked the same way, and workers: 1 keeps a server on one thread.
What the rule says
III.4 This is the section where the design either beats Go or does not, so it is worth being blunt about where Go actually loses. Not goroutines: they are cheap, the scheduler is good, and nothing here improves on them. Go loses in three places, all of them the same shape: the compiler is not told anything, so the failure shows up at runtime or not at all:III.4 SPEC.md, lines 2711 to 2715
Run it
This step is grounded in samples/iyi/cores.iyi, 126 lines in the repository, read out of the tree when this page is built.
This program does not run in the browser. Locally it is iyi run samples/iyi/cores.iyi.
Every step so far has been about what a module tells the modules that import it. This one is about what a block tells the thread that runs it, and the promise is the same shape: the compiler is told, so a mistake is refused where it is written instead of turning up at runtime, or never.
Two ways to start a task#
g.spawn starts a task on the thread that spawned it. Its tasks take turns
at their parks, never two at the same instant, so a block may append to an
Array it captured and nothing is raced.
seen = [] of Int64
group do |g|
(1..3).each do |n|
g.spawn do
seen << collatz_steps(n.to_i64)
0
end
end
end
puts seen.sorted # => [0, 1, 7]g.spawn_parallel starts a task a pool of worker threads runs, on whichever
core is free, and a task that parks may resume on another one. It is a task
of its group like any other: joined at the group's end, cancelled with it, its
answer through value.
longest = 0_i64
group do |g|
handles = [] of IyiTask(Int64)
4.times do |part|
handles << g.spawn(unit: :new) do
best = 0_i64
start = part.to_i64 * 25_000 + 1
(start..start + 24_999).each { |n| best = collatz_steps(n) if collatz_steps(n) > best }
best
end
end
handles.each do |handle|
steps = handle.value
longest = steps if steps.is_a?(Int64) && steps > longest
end
end
puts longest # => 350, the longest chain below 100,000What changed is what the block may capture. A parallel block may capture only
what is Share: an immutable value, an Atomic, a Mutex, a List, a
Channel of Share values. Each task above captures nothing but its own
part, and builds its answer itself. An answer need not be Share, because
it is handed over once, after the task has ended, and the join orders it.
The pool starts at the first spawn_parallel, with one worker per core the
process may run on. IYI_WORKERS=n in the environment sets the count, and a
program without a parallel task starts no pool at all.
State every core may touch#
A counter that every core adds to is an Atomic, and an Array that every
core appends to sits behind a Mutex. Both are Share, so a parallel block
may capture them, and what is behind the lock is reached only inside lock.
hits = Atomic(Int64).new(0_i64)
paths = Mutex.new { [] of String }A task that waits for a held Mutex parks, as it would on a channel, so the
worker it was on runs other tasks meanwhile.
A server on every core#
std/http's Server.serve runs each connection as a parallel task on the
pool, so a server uses every core without asking. Its block is checked as a
parallel task's is.
Server.serve(listener) do |req|
hits.add(1_i64)
path = req.path
paths.lock { |list| list << path }
if path == "/stop"
stop.send(0)
Response.new(200, "bye")
else
Response.new(200, greeting)
end
endTwo things in that block are there because of the check. The path is copied
into a String before the lock, because a block that runs behind a Mutex
may not capture the request it came from. And the server stops through a
channel: /stop may arrive on any worker, and closing the listener from the
block would capture it, so the block sends on stop and a task beside the
server, on the thread that opened the listener, closes it.
Server.serve(listener, workers: 1) is the server on one thread, the
accepting one. Its block is not checked at all, because nothing it captures
leaves that thread: it may append to an Array, count in a plain variable,
close its own listener. A count in a variable is checked as a pool would be,
since nothing at compile time says it is one.
TLS on every core#
A server's tls: takes config.frozen, a TlsFrozenServerConfig: a copy
of the configuration no property of which changes, which every worker may
read. A TlsServerConfig itself, on more than one worker, is refused at the
argument, naming the same two ways out. serve does not freeze it for you,
because a property assigned while the server runs would reach no worker and
nothing would say so. An identity source goes to frozen as a block, whose
captures are checked like any other.
Module state a call reaches#
The check reads what a block names. A block that calls a method, which reads
a constant, names only the method, and used to compile with nothing said.
Now the compiler walks the calls from the block through the program's own
modules and its packages, and warns at the block for every constant and class
variable it reaches whose type is not Share, once each, by the shortest
path.
Some such state is safe: set once at startup and only read after, or guarded some other way. That is said on its declaration, with the reason as the claim.
# compiler warns, and `@[SafeReach("why")]` on the state says why it is
# safe - a claim the compiler proves, or refuses naming the write.
module samples/cores
import std/http::{HTTP, Response, Server}
import std/socket::{IyiSocket}
import std/mutex::{Mutex}
def collatz_steps(n : Int64) : Int64
steps = 0_i64
while n != 1
n = n % 2 == 0 ? n // 2 : 3 * n + 1
steps += 1
end
steps
end
# 1. `spawn` and `spawn(unit: :new)`.
#
# These `spawn`s append to an `Array` they captured, which is not `Share`, so
# the compiler keeps them on their spawner's thread, where they take turns
# and nothing is raced; `iyi check` notes each one, with why. The tasks
# `spawn(unit: :new)` starts run on whichever core is free; each answers
# its own value, and a task's answer need not be `Share`, because it is
# handed over once, after the task ends.
seen = [] of Int64
group do |g|
(1..3).each do |n|
g.spawn do
seen << collatz_steps(n.to_i64)
0
end
end
end
puts seen.sorted # => [0, 1, 7]
longest = 0_i64
group do |g|
handles = [] of IyiTask(Int64)
4.times do |part|
handles << g.spawn(unit: :new) do
best = 0_i64
start = part.to_i64 * 25_000 + 1
(start..start + 24_999).each { |n| best = collatz_steps(n) if collatz_steps(n) > best }
best
end
end
handles.each do |handle|
steps = handle.value
longest = steps if steps.is_a?(Int64) && steps > longest
end
end
puts longest # => 350, the longest chain below 100,000
# 2. State the pool may share.
#
# A counter that every core adds to is an `Atomic`; an `Array` that every
# core appends to sits behind a `Mutex`. Both are `Share`, so a parallel
# block may capture them.
hits = Atomic(Int64).new(0_i64)
paths = Mutex.new { [] of String }
# 3. Module state a call reaches.
#
# A parallel block that names `GREETING` is refused, because an `Array` is
# not `Share`. One that only calls `greeting` used to compile with nothing
# said; now the compiler warns at the block, naming the path. This constant
# is set before the server starts and only read afterwards, so it says so,
# and the compiler checks it: nothing writes `GREETING` once a parallel
# task can start (SPEC.md III.4.4).
@[SafeReach("set once before the server starts, then only read")]
GREETING = ["hello", "from", "every", "core"]def greeting : String
GREETING.join(" ")
endThe mark quiets the warning for that state alone. A block that names
GREETING itself is still refused, because a block's own text is checked
exactly, and the mark is a claim about calls the compiler cannot follow to the
end. It is a warning rather than a refusal so that nothing that compiled
stops compiling; iyi build --error-on-warnings, or iyi check given the
same, makes it fail a build.
Moving off serve_parallel#
0.19.1 had Server.serve_parallel beside a serve on one thread. It is gone,
with no alias, and serve is the pool. A call to serve_parallel becomes a
call to serve with the same arguments. A serve that was on one thread
needs nothing if its block captures nothing unshareable: it now uses every
core. One whose block captures a Router, an Array, a counter or the
listener it closes, or whose tls: is a TlsServerConfig, either passes
workers: 1 and stays as it was, or moves to what crosses threads: the state
behind a Mutex or in an Atomic, the router to a SharedRouter, the
configuration to config.frozen, and the stop to a Channel, as the server
above does.
Capture what does not cross#
Here is a server whose block appends every path it is asked for to an
Array. On one thread that is fine. On every core two workers could append at
once, and the compiler refuses the capture where it is written, naming both
ways out. After it, the same server reaching a constant through a call, built
to fail on warnings.
Break it
a server's block that captures an Array
# Breaks III.4.4 as III.4.13 applies it: `Server.serve` runs each connection
# on the pool's workers, so its block is checked as `spawn_parallel`'s is,
# and every value it captures must be `Share`. An `Array` is not: two
# workers appending at once would race its size. Everything else here is
# legal, and the refusal names both ways out - the array behind a `Mutex`,
# or `workers: 1`, which keeps the server on one thread.
module diagnostics/share_serve_capture
import std/http::{Response, Server}
import std/socket::{IyiSocket}
seen = [] of String
listener = IyiSocket.listen("127.0.0.1", 0)
Server.serve(listener) do |req|
seen << req.path
Response.new(200, "ok")
end$ IYI_PATH=<iyi>/src iyi build --no-codegen --no-color records/break/share_serve_capture.iyi Showing last frame. Use --error-trace for full trace. In records/break/share_serve_capture.iyi:15:3 15 | seen << req.path ^--- Error: the block Server.serve keeps, which may run on other threads captures `seen : Array(String)`, which is not Share: Array(String)'s field @size is assigned in `append`. Put it behind a lock, a `Mutex(Array(String))` (std/mutex), or pass `workers: 1` so the block runs on one thread (SPEC.md III.4.4)
npm run record:diagnostics.Break it
a server's block that reaches module state through a call
# Breaks III.4.4's reach check: the block names nothing unshareable, but
# `greeting`, which it calls, reads `GREETING`, an `Array` any worker could
# reach while another changes it. The compiler walks the calls from the
# block and warns at the block, by the shortest path. A warning, so the
# build is asked to fail on one: `--error-on-warnings`, as CI would.
# `@[SafeReach("...")]` on the constant, saying why it is safe, quiets it.
module diagnostics/share_reach
import std/http::{Response, Server}
import std/socket::{IyiSocket}
GREETING = ["hello", "from", "every", "core"]
def greeting : String
GREETING.join(" ")
end
listener = IyiSocket.listen("127.0.0.1", 0)
Server.serve(listener) do |req|
Response.new(200, greeting)
end$ IYI_PATH=<iyi>/src iyi build --no-codegen --no-color --error-on-warnings records/break/share_reach.iyi Showing last frame. Use --error-trace for full trace. In records/break/share_reach.iyi:12:1 12 | GREETING = ["hello", "from", "every", "core"] ^ Error: the block Server.serve keeps, which may run on other threads (share_reach.iyi:19) reaches `GREETING : Array(String)` (not Share) through `greeting` → `GREETING.join`, as does 1 other parallel block: Array(String)'s field @size is assigned in `append`. A parallel unit may not reach module state that is not Share (SPEC.md III.4.5). If it is only read, make it a `List(String)` (std/list), which is Share. Keep the value behind a `Mutex` (std/mutex), or, when every thread may reach it safely - every write is before the first parallel task starts, or behind one `Mutex#lock` on a constant or a class variable - say why on the constant: `@[SafeReach("...")]`, which the compiler proves. Nothing writes it once a parallel task may start, so a claim is proven: `iyi fix` adds `@[SafeReach("set before the first parallel task starts, then only read")]`
npm run record:diagnostics.What the rule bought
A data race on a value a block captures does not compile, and a block that reaches shared state through a call is named at the block, with the path, rather than found by a race detector on the run that happened to hit it. A server that was correct on one thread is told exactly what to change before it runs on every core.
Standing on
samples/iyi/cores.iyi- both kinds of task, the state a pool may share, a server on every core that stops through a channel, and a constant marked with why it is safe
src/std/http.iyiServer.serveand itsworkers:argument, and the mark that has its block checked as a parallel task'ssrc/std/mutex.iyi- the lock a waiting task parks on rather than holding its thread
SPEC.md- III.4.4 for what
Shareis and the reach check, III.4.13 for the pool, how many workers it has, and how a task moves between them CHANGELOG.md- the release that made
serverun on every core and removedserve_parallel, with the migration