Home / Docs / Specification / 27. Tasks and time
27.1 Tasks and workers
Release v0.4.0
- Tasks are coroutines. In native code, each task of
togetherandtogether forruns on a coroutine: a stack of its own, which the runtime can suspend and resume on the same thread. A task keeps its own heap, and the copies at its fork and its join are those of spec/19 §8 rule 2 (ADR 0113). - Workers. Coroutines run on
--workersoperating-system threads, the workers, numbered from 0. A task runs on the worker chosen when it is forked, and never moves to another (pinning), so its heap, reference counts and runtime state are only touched by one thread. Placement is structural: a task forked as thei-th part of a block,icounted from 1 (the branch index fortogetherandfirst of, the element index fortogether for, and for a started task its place among thestarts of itstasksstatement, in the order they run, those in quiet code not counted, §7 rule 5; a task started in quiet code counts as the part numbered by the position of itsstartin the program, so all the tasks one quietstartstarts share a worker, a cost of quiet code only), by a task that runs on workerw, runs on worker(w + i) mod N, whereNis--workers(ADR 0116 amendment, P6). The root task counts as worker 0 for placement: it runs on theuna-mainthread, which is not a worker, or, in a program with atasksstatement, on worker 0 itself (rule 3). Choosing it takes O(1) time, and the runtime keeps no placement state across blocks. So a task's worker depends only on the program's structure, never on how many tasks earlier code started: a counter shared by the whole run would carry the number of tasks that code forked into the timing of later blocks, and code that branched onsecretdata would then change the timing of a laterpublicblock, which a deadline turns into a value (ADR 0116 IF6). - The root task runs
mainon a thread of its own, with the stack that--max-depthneeds (spec/16 §3 rule 3), and waits at the join of its tasks. In a program with atasksstatement (§7), the root runs on a coroutine of worker 0 instead, with the same stack, so that it takes turns with the tasks it starts. - Threads start before
main. The executable of a program that holds a task construct, awithinor afor everstarts all its--workersworkers, both helper pools of §2 at their full sizes and the timer thread of §5 beforemainruns (ADR 0116 amendment, P8), andmainbegins once every one of them runs, each worker with the state a task's resume needs already made. Beforemain, every worker has also run one task of a block through the runtime's whole path, from the start's reservation to the join, its closure a closure object copied into the task's heap at the fork, as the closure of every block is, and its value an object copied out of the task's heap and into the root's at the join, so what a task's first run on a worker makes, and the allocations of a task's copies at both ends, have happened whatever earlier code started (#1254): O(N) tasks for N workers, once per run, in batches of 64, with transient memory bounded by one batch. The state of the system allocator, the processor's caches and the host's load remain out of model (ADR 0116 amendment, P12). Whether a thread exists is then never state that earlier code left, possibly code onsecretdata, and no construct pays for starting one: in particular, nowithinstarts the timer thread, whether or not an earlierwithinran. It also fills the pool of task stacks to its 64 stacks, each of the size the largest task asks for, which every later stack has: a construct maps a stack only while more than 64 tasks are live at once, as its own structure decides, never because earlier code started fewer tasks than the pool holds. The pooled stacks are reserved address space; their pages are handed back and they count toward--max-memoryonly as a task uses them (§4). So a program with tasks reserves, beforemain, 64 stacks of the size §4 rule 1 gives for--max-depth, from the program's frame bound (#1152): about 1.6 GiB of address space at the default 10,000 for a frame bound of 1 KiB, and at most the 21 GiB that--max-depthalone gives (spec/16 §3). A system that refuses such a reservation, as Linux can under strict overcommit (vm.overcommit_memory=2), which charges every mapping in full, stops the run with U6003 beforemain; a lower--max-depthshrinks the reservation. A thread that cannot start, or a stack that cannot be mapped, stops the run beforemainwith U6003, exit code 1, and no position. A program that holds none of these constructs makes no worker, no helper and no timer thread, and performs every host operation on its own thread, at no cost. - The interpreter runs the tasks of a block, and the branches of
first of, one after another, in index order, on its one thread (spec/19 §8 rule 1, §6). It runs started tasks on coroutines of that thread, one at a time (§8), with one exception forHttprequests in a run that serves live peers, which may run on helper threads while their tasks park (§8 rule 2). It accepts the flags of §3 and checks them as the executable does.