Home / Docs / Specification / 27. Tasks and time

27.7 tasks and start

Release v0.4.0
  1. Grammar (ADR 0117 rule 7). In edition 0.4:

    ebnf
    statement  = ... | 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 ] ;
    una
    tasks at most 100 at once
      for job in jobs
        start run_job(job)
          if error use log_failure(job)
    • The words. tasks begins a statement when, at the start of a statement, a newline and an indented block, or the word at, follow it. start begins a statement when, at the start of a statement, a name, a capability reference or attempt follows it. Elsewhere both are names: start(x), start = v and a block that ends with tasks keep their meaning. Before edition 0.4, such a line is U0101.
    • Values. A block whose last line is a tasks or a start has the value unit (spec/17 §1).
  2. Static semantics.

    • Where start stands. In the block of a tasks statement, at any depth of for, if, when and for ever there; outside the block of any tasks, inside a task within it (a branch of together or first of, the body of a together for), or inside a lambda, which can be called once the statement has ended, it is U2035 at start. It refers to the innermost tasks whose block holds it.
    • No with on start. A with clause on start is U2035 at the binding: a with scopes 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 the tasks statement; one installed inside the started function belongs to its task.
    • The bound is an Int (U2001) that MUST be at least 1, a refinement obligation at the bound (U5001), evaluated once, before the block. Without it, the bound is max(64, M), M being --max-memory in 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 together branch (spec/19 §2 rules 1, 3 and 4): assigning, or passing as edit or take, a binding declared outside it is U2023. It has type Unit (U2011), and it MUST NOT fail after its handling clauses (U3029): a call that can fail without if error use or attempt, if error pass, if error fail and if none fail are each U3029. A started call of a function that says diverges needs diverges on the enclosing function (U3027), also inside the body of a for ever or a task, since the tasks statement waits for it.
  3. Information flow (ADR 0117 IF1, IF6). A started task runs under the program counter of its start, as a together branch does (spec/19 §3 rule 1). The block of a tasks statement, 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 or start expressions can reach an operation of Http raises L_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 a start waits at its bound, and the statement at its end, is timing, out of model (spec/13 §6).

  4. Dynamics.

    • The block runs in the current task. start e starts a task for e and 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 a start under a raised program counter ran can make a later public start wait, 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 stop or skip of 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 ends interrupted (§6 rule 7), and the statement fails or stops once they have all stopped. When the stop is the cut of a within around 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 own TimedOut, and a request still queued for a helper fails with TimedOut too, never sent: never interrupted, 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-depth or 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 of main does: 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_count started tasks at once, read when the run starts. A start past it aborts the run with U6003 at the start, this `start` exceeds the N started tasks this system allows at once, never with a failed mapping. A start whose stack cannot be mapped aborts the run with U6003 at the start.
    • A host stop reaches the for ever loops 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.
  5. Paths. The k-th task started by the c-th tasks statement that the task p runs has the path p.s<c>.<k>, and s<c>.<k> in the root task, with c and k counted from 1. The paths of public code are unique, and differ from those of together and first of; those of quiet code are not (below).

    • Quiet code (S-39, S-40, spec/26 §6 rule 4). A tasks statement inside a quiet expression is not counted, as a race is not (§6 rule 5): its path part is qs, with no c, and a later public statement keeps its c. A start inside a quiet expression, which a start under a raised program counter is in a public statement too (S-40, #1512), is not counted either: its task has the path p.s<c>.q, or p.qs.q in a quiet statement, with no k. Since #1684 a start under a program counter above internal is U4002 in any case (§8 rule 5), so quiet tasks stand under internal data at most. So whether a start under a raised branch ran moves neither k for a later public start of the same statement, nor the worker that k places 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 its start in the program (§1 rule 2). This is a known cost, in quiet code only: every task one quiet start starts, such as those of a quiet for loop in a tasks statement, runs on one worker, since no count of quiet starts 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.
  6. Verification (ADR 0117 Verification). Each started expression is verified alone, in the context of its start, as a together branch is (spec/19 §4 rule 1). The block is verified as a block in the current task. A start gives no fact, and no fact about an outer binding changes across it.

  7. Core (spec/09). A tasks statement is tasks(b) e, b the bound, an atom bound before it, or none, and e its block, which returns the tuple of the outer bindings it updates, rebound after the statement (spec/17 §4); an exit of an enclosing loop in e crosses the statement. start e is start(e), e desugared with its deadline and handling clauses and closed over the bindings before it.

  8. Report (ADR 0117 rule 13). The report's out_of_model list (spec/13 §6) holds "waits at limits and at start".

  9. Costs (ADR 0117 Costs). A start takes 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 a tasks statement pays nothing for this section.