Home / Docs / Specification / 27. Tasks and time
27.7 tasks and start
-
Grammar (ADR 0117 rule 7). In edition
0.4:ebnfstatement = ... | tasks_stmt | start_stmt ; tasks_stmt = "tasks" [ "at" "most" add_expr "at" "once" ] NEWLINE INDENT block DEDENT ; start_stmt = "start" line_expr [ "within" add_expr ] NEWLINE [ INDENT handling { handling } DEDENT ] ;unatasks at most 100 at once for job in jobs start run_job(job) if error use log_failure(job)- The words.
tasksbegins a statement when, at the start of a statement, a newline and an indented block, or the wordat, follow it.startbegins a statement when, at the start of a statement, a name, a capability reference orattemptfollows it. Elsewhere both are names:start(x),start = vand a block that ends withtaskskeep their meaning. Before edition0.4, such a line is U0101. - Values. A block whose last line is a
tasksor astarthas the valueunit(spec/17 §1).
- The words.
-
Static semantics.
- Where
startstands. In the block of atasksstatement, at any depth offor,if,whenandfor everthere; outside the block of anytasks, inside a task within it (a branch oftogetherorfirst of, the body of atogether for), or inside a lambda, which can be called once the statement has ended, it is U2035 atstart. It refers to the innermosttaskswhose block holds it. - No
withonstart. Awithclause onstartis U2035 at the binding: awithscopes over its statement, and the task outlives the statement. A handler that started tasks share is installed around the call of the function that holds thetasksstatement; one installed inside the started function belongs to its task. - The bound is an
Int(U2001) that MUST be at least 1, arefinementobligation at the bound (U5001), evaluated once, before the block. Without it, the bound ismax(64, M),Mbeing--max-memoryin MiB, and on Linux at most the cap of rule 4. - The started expression is a task, with the scope, capture and capability rules of a
togetherbranch (spec/19 §2 rules 1, 3 and 4): assigning, or passing aseditortake, a binding declared outside it is U2023. It has typeUnit(U2011), and it MUST NOT fail after its handling clauses (U3029): a call that can fail withoutif error useorattempt,if error pass,if error failandif none failare each U3029. A started call of a function that saysdivergesneedsdivergeson the enclosing function (U3027), also inside the body of afor everor a task, since thetasksstatement waits for it.
- Where
-
Information flow (ADR 0117 IF1, IF6). A started task runs under the program counter of its
start, as atogetherbranch does (spec/19 §3 rule 1). The block of atasksstatement, and the functions it calls, run beside its tasks, so the timing labelτ_conc(§11) covers them: the block is a part of the statement. A statement whose block orstartexpressions can reach an operation ofHttpraisesL_res(spec/26 §7 rule 5, item 6) to its own timing label and itsτ_conc, since a cancellation can leave its tasks' requests on their helpers (§2 rule 4). How long astartwaits at its bound, and the statement at its end, is timing, out of model (spec/13 §6). -
Dynamics.
- The block runs in the current task.
start estarts a task foreand goes on; when as many tasks of its statement run as its bound, it first waits until one ends. A task started in quiet code (§7 rule 5) counts against the bound as any other does, so whether astartunder a raised program counter ran can make a later publicstartwait, which in the interpreter reorders the public events: an open channel (#1545, spec/26 §6 rule 4; a proposed amendment,docs/plan/0117-quiet-bounds-amendment-draft.md, would bound quiet tasks apart). - The statement ends once its block has ended and every task it started has ended, also when the block is left by
stoporskipof an enclosing loop. - A block that fails or stops (a failure, a cut of a
within, a cancellation) cancels every task the statement started (spec/19 §6 rule 4): each stops at its next check point, an interruptible operation it waits on endsinterrupted(§6 rule 7), and the statement fails or stops once they have all stopped. When the stop is the cut of awithinaround the statement, a task waiting on a request is not woken: it waits for its request, on its helper or on the reactor, which ends at that same deadline at its next I/O step with its ownTimedOut, and a request still queued for a helper fails withTimedOuttoo, never sent: neverinterrupted, whichever path ran it (§2 rule 4). A canceled task leaves its frames by the failure path, as a cut does (§5 rule 5), so it holds no memory after the statement. - A started task that runs too deep, past
--task-depthor short of its stack, in itself or in a task of a block it runs, ends alone: its events end with{"seq": n, "task": "<path>", "outcome": {"kind": "aborted"}}, stderr gets one line,[U6003] Error: the started task <path> ended alone: <message> at <file>:<line>:<column>, and the other tasks run on. Any other abort of a started task ends the whole run, as an abort ofmaindoes: the run's memory budget (U6003), a header value (U6004), host text (U6005), the hard stop (U6007). - The cap. On Linux each task's stack takes two memory mappings, so a run holds at most a quarter of
vm.max_map_countstarted tasks at once, read when the run starts. Astartpast it aborts the run with U6003 at thestart,this `start` exceeds the N started tasks this system allows at once, never with a failed mapping. Astartwhose stack cannot be mapped aborts the run with U6003 at thestart. - A host stop reaches the
for everloops of the block and of the started tasks, at the start of their next iteration (spec/26 §6); the other started tasks run on, the statement waiting for them, until the hard stop. - No handler instance outlives its statement: a started task uses the capabilities in scope at its
start, which the statement around it keeps alive until the task has ended.
- The block runs in the current task.
-
Paths. The
k-th task started by thec-thtasksstatement that the taskpruns has the pathp.s<c>.<k>, ands<c>.<k>in the root task, withcandkcounted from 1. The paths of public code are unique, and differ from those oftogetherandfirst of; those of quiet code are not (below).- Quiet code (S-39, S-40, spec/26 §6 rule 4). A
tasksstatement inside aquietexpression is not counted, as a race is not (§6 rule 5): its path part isqs, with noc, and a later public statement keeps itsc. Astartinside aquietexpression, which astartunder a raised program counter is in apublicstatement too (S-40, #1512), is not counted either: its task has the pathp.s<c>.q, orp.qs.qin a quiet statement, with nok. Since #1684 astartunder a program counter aboveinternalis U4002 in any case (§8 rule 5), so quiet tasks stand underinternaldata at most. So whether astartunder a raised branch ran moves neitherkfor a later publicstartof the same statement, nor the worker thatkplaces it on (§1 rule 2), nor the path of a later quiet task, whose events may occur whatever the secret (spec/26 §6 rule 4). Paths in quiet code are not unique: the quiet tasks of one statement share theirs, which only the events of quiet code carry. A quiet task is placed by the position of itsstartin the program (§1 rule 2). This is a known cost, in quiet code only: every task one quietstartstarts, such as those of a quietforloop in atasksstatement, runs on one worker, since no count of quietstarts can place them without showing how many ran. Two quiet tasks that run too deep write the same U6003 line, which names their shared path.
- Quiet code (S-39, S-40, spec/26 §6 rule 4). A
-
Verification (ADR 0117 Verification). Each started expression is verified alone, in the context of its
start, as atogetherbranch is (spec/19 §4 rule 1). The block is verified as a block in the current task. Astartgives no fact, and no fact about an outer binding changes across it. -
Core (spec/09). A
tasksstatement istasks(b) e,bthe bound, an atom bound before it, or none, andeits block, which returns the tuple of the outer bindings it updates, rebound after the statement (spec/17 §4); anexitof an enclosing loop inecrosses the statement.start eisstart(e),edesugared with its deadline and handling clauses and closed over the bindings before it. -
Report (ADR 0117 rule 13). The report's
out_of_modellist (spec/13 §6) holds "waits at limits and atstart". -
Costs (ADR 0117 Costs). A
starttakes O(1), besides the copies of its captures (ADR 0113) and a stack from a pool in O(log k); one at its bound parks in O(1) and is woken in O(1). The end of a statement costs O(1) per task that ended. A program without atasksstatement pays nothing for this section.