---
title: "27.7 tasks and start"
url: https://una-lang.org/en/docs/spec/27-tasks-and-time/7-tasks-and-start/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/27-tasks-and-time.md
---

# 27.7 tasks and start

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 `start`s 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.
