Home / Docs / Specification / 27. Tasks and time

27.1 Tasks and workers

Release v0.4.0
  1. Tasks are coroutines. In native code, each task of together and together for runs 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).
  2. Workers. Coroutines run on --workers operating-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 the i-th part of a block, i counted from 1 (the branch index for together and first of, the element index for together for, and for a started task its place among the starts of its tasks statement, 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 its start in the program, so all the tasks one quiet start starts share a worker, a cost of quiet code only), by a task that runs on worker w, runs on worker (w + i) mod N, where N is --workers (ADR 0116 amendment, P6). The root task counts as worker 0 for placement: it runs on the una-main thread, which is not a worker, or, in a program with a tasks statement, 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 on secret data would then change the timing of a later public block, which a deadline turns into a value (ADR 0116 IF6).
  3. The root task runs main on a thread of its own, with the stack that --max-depth needs (spec/16 §3 rule 3), and waits at the join of its tasks. In a program with a tasks statement (§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.
  4. Threads start before main. The executable of a program that holds a task construct, a within or a for ever starts all its --workers workers, both helper pools of §2 at their full sizes and the timer thread of §5 before main runs (ADR 0116 amendment, P8), and main begins once every one of them runs, each worker with the state a task's resume needs already made. Before main, 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 on secret data, and no construct pays for starting one: in particular, no within starts the timer thread, whether or not an earlier within ran. 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-memory only as a task uses them (§4). So a program with tasks reserves, before main, 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-depth alone 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 before main; a lower --max-depth shrinks the reservation. A thread that cannot start, or a stack that cannot be mapped, stops the run before main with 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.
  5. 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 for Http requests 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.