Home / Docs / Specification

19. Structured concurrency

Release v0.4.0

Status: Normative, v0.2 (ADR 0065).

A together block runs its branches as concurrent tasks, and together for runs one task per element of a list. Every task ends before its block does, so no task, capability or value outlives the scope that started it. A program's result, and the trace it reports, are those of a sequential run in branch order, so concurrency changes when effects happen but not what a program computes.

Editions. The constructs of this chapter exist only in packages of edition 0.2 and later (spec/13 §7).

1. Syntax

These productions extend spec/02 and spec/17 §1.

ebnf
statement       = let_stmt | assign_stmt | for_stmt | if_stmt | together_stmt | handled ;
together_stmt   = "together" NEWLINE INDENT let_stmt let_stmt { let_stmt } DEDENT ;
block_expr      = when_expr | if_block | together_for ;
together_for    = "together" "for" lower_ident "in" ( line_expr | range_expr ) NEWLINE INDENT block DEDENT ;
una
together
  let north = reading() with @sensor = @north
  let south = reading() with @sensor = @south
let warmest = max(north, b: south)

let pages = together for id in ids
  fetch(id)
    if error pass
  1. Branches. Each let statement of a together_stmt is a branch. Its expression, with its with bindings and its handling clauses, is the branch's task.
  2. together for stands where a block_expr can: as the value of a let or of an assignment, or as the last line of a block. Elsewhere, as a line followed by another line of its block, it is U0101 with the message a `together for` must be the last line of its block or the value of a `let` or of an assignment. Its body is a block, as the body of a for loop (spec/17 §1), whose final expression is the value of the element's task.
  3. Malformed bodies. A together body that holds a statement other than let, or fewer than two let statements, is U2024 at together.
  4. Placement. together followed by a newline is a statement. Written as an expression, as let x = together with branches, it is U0101 with the message `together` with branches is a statement; write `together for` to build a list.
  5. Nesting. A task may contain a together block or a together for, inside a called function or inside the expression of its branch.
  6. There are no task values, no detached tasks, no race or select, no timeouts and no channels. (Edition 0.4, ADR 0117.) first of races branches, within bounds an expression's time, and tasks and start run a dynamic number of tasks, all ended before their statement (spec/27 §5 to §7); there are still no task values and no channels.

2. Static semantics

  1. Scope. A branch's expression sees the bindings in scope before the block, and none of its sibling branches. The bindings of the branches are in scope after the block, in branch order, as consecutive let statements would bind them.
  2. Types. A branch is typed as its let would be outside a together (spec/10). A together for x in xs has type List[T] when xs is a List[S], or a range, and its body has type T with x : S, or, for a range, x of the integer type of its bounds, as in a for loop (spec/17 §4).
  3. Captures (C3). A task captures the values of the outer bindings it reads, as a lambda does (spec/17 §5 rule 4). Inside a branch, or the body of a together for:
    • assigning a binding declared outside the branch, passing it as edit, or passing it as take, is U2023 at the binding;
    • the branch's own bindings, let edit ones included, follow spec/17 unchanged.
  4. Capabilities (C4). A task uses the capabilities of the enclosing function's uses, and the handlers installed around the block, by name, under the rules of spec/05. A parameter named by a uses of or fails of clause (spec/05 §9 rule 9) may be called inside a task. Nothing in a task outlives the block, so authority still flows only downward and T4 holds.
  5. Failures. A branch's failure is the failure of its let after its handling clauses (spec/06 §3): if error pass and if error fail V make the branch fail with the enclosing function's error kind, and if error use or attempt keep it from failing. The body of a together for fails when its block fails. A failing task makes the block fail, with the failure of §6 rule 3, which is a failure of the enclosing function.
  6. Effects. A function's effects are the effects of its tasks, within its uses, as for any expression (spec/05).

3. Information flow

  1. Program counter (C5). Each branch runs under the program counter of the together block. A together for over a list runs its body under the top label of the list, and over a range under the labels of its bounds, since the number of tasks depends on them, as for a for loop (spec/17 §6 rule 3). In that body, fail and calls that can fail are U4002, and every sink must accept the program counter.
  2. Which tasks a failure cancels (§6) depends only on failures, which happen under a public program counter (spec/07 §3 rule 3), and on branch order.
  3. The guarantee. For an observer at label l, T6 (spec/10 §10) holds for the result of the block, and for the sequence of events of each task taken alone, up to where a canceled task stopped. The relative order of the effects of different tasks, and how far a canceled task got, depend on timing. Both are out of model with timing (spec/07 §1), and the report says so (spec/13 §6).

4. Verification (C8)

  1. Each branch is verified as its let would be, in the context of the block: with the facts known before the block, and no facts of its sibling branches.
  2. After the join, each branch's binding carries its facts. The result of a together for carries, for each element, the facts of the element type T, as a list does, and its length is the number of tasks: the length of its list, or for a range a..b the value b - a + 1 when a <= b, and for a..<b the value b - a when a < b, else 0.
  3. No fact about an outer binding changes across the block, since no task can assign it (§2 rule 3).
  4. No new kind of obligation exists, and no contract mentions tasks. This is sound because tasks share no mutable state, and the verifier encodes no world and no order of effects (spec/12 §3).
  5. Termination is not checked (spec/04 §2 rule 3). A task that does not terminate keeps its block from ending.

5. Core IR

Core IR (spec/09) gains two expression forms:

Output
expr        e  ::= ...
                 | let (x₁, ..., xₙ) = together(e₁ ∥ ... ∥ eₙ) in e        n ≥ 2
                 | let x = together_for y in a. e₁ in e
Surface Core IR
together with branches let x₁ = s₁ to let xₙ = sₙ, then the rest e of the block let (x₁, ..., xₙ) = together(s₁ ∥ ... ∥ sₙ) in e, each sᵢ desugared with its with bindings and handling clauses
let x = together for y in xs with body b let x = together_for y in xs. b in ...
together for y in lo..hi as above, over the range's integers in increasing order

Each eᵢ is closed over the bindings before the block and not over the other xⱼ.

6. Dynamic semantics

  1. Tasks and paths. Each eᵢ of a together, and each element of a together_for in list order, is evaluated as a task. Its path is its 1-based index, prefixed by the path of the task that runs the block and a ., as 2.1. Code outside any together runs in the root task, whose path is empty.
  2. E-Together. The tasks run concurrently: their steps may interleave in any order, and the host world W is threaded through their operations in the interleaving that happens. Each task produces its result rᵢ and its own trace tᵢ.
  3. Failure and cancellation (C2).
    • If every task returns, the block returns the tuple of the results, or the list of a together_for in element order.
    • When a task fails, every task after it is canceled. The tasks before it run on, and may fail in turn.
    • Once every task has returned, failed or stopped, the block fails with the failure of the lowest-indexed task that failed.
    • So the result of the block is the result of evaluating the tasks one after another, in order, stopping at the first failure.
    • (v0.2, ADR 0113, 2026-10-16.) In native code, a task that stops with U8001, an internal error of the runtime (spec/13 §5), decides its block before any failure or abort, whatever its index, and cancels every other task of the block, the lower-indexed ones included, so the run ends with U8001 once those tasks reach a check (§8 rule 2). The interpreter makes no such stop.
  4. Cancellation is cooperative. A canceled task stops at its next call, operation or loop iteration. An operation in progress completes, and effects already performed stay (spec/17 §7 rule 2). A canceled task that has not started never starts, and a canceled task's result is dropped. A task after the failed one that had already ended is not canceled: its events stay in the trace, with no cancelled event, and its result is dropped.
  5. The reported trace (C6). The trace of the block is t₁ · t₂ · ... · tₙ, the traces of the tasks in index order, whatever the interleaving. The trace of a canceled task that had started is the prefix it performed, followed by a cancelled event (§7).
  6. The sequential schedule. Evaluating the tasks one after another, in index order, is one legal interleaving. Under it no task after a failed one starts.
  7. Ordered runs. A run is ordered when, in every block it runs, no task after a failed task started. A run in which no block fails is ordered.
  8. Nothing escapes. A block returns or fails only after all its tasks have returned, failed or stopped. Capabilities, handler instances and second-class function values are never used after their scope ends.

7. Traces

These rules extend spec/11 §5.

  1. Task paths. An event produced inside a task gains the field task, its task's path, right after seq. Events of the root task have no task field, so a program without together has the trace of spec/11 §5 unchanged.
  2. Order. Events are listed, and seq numbers them, in the order of §6 rule 5: the events of a block's tasks by task index, each task's events in its own order, nested blocks within their task. The installation ids with:<handler>#<n> count installations in the same order.
  3. Canceled tasks. A started task that is canceled ends with the event {"seq": n, "task": "<path>", "outcome": {"kind": "cancelled"}}, which names no instance, capability, operation or arguments. An operation in progress when the cancellation came keeps its own outcome.
  4. Determinism. The reported trace of an ordered run (§6 rule 7) does not depend on the schedule: it is the trace of the sequential schedule over the same host behavior. In a run that is not ordered, the trace also holds the events that tasks after a failed one performed before they stopped.
  5. Replay. A future una replay (plan/backlog.md) substitutes host results by task path and position within the task.
  6. The order in which the host sees the effects of different tasks, such as the lines two tasks print, is the real interleaving, outside the model (§3 rule 3).

8. Runtimes

  1. The interpreter runs the tasks of a block sequentially, in index order (§6 rule 6). It stays single-threaded and is the deterministic reference of spec/11 §1.
  2. The native backend runs each task on a coroutine, with a stack sized from --max-depth (spec/16 §3 rule 3) and the program's frame bound (spec/27 §4 rule 1), run by one of --workers operating-system threads that it never leaves (spec/27 §1, ADR 0117).
    • Each task has its own heap. At the fork, the values a task captures are copied into its heap, and at the join its result is copied back into the heap of the task that runs the block. Reference counts stay non-atomic (spec/16 §4 rule 1).
    • The grants and keys of the run are read-only, and each task's state holds them.
    • Each task records its events in its own buffer. The join appends the buffers in task order, then numbers seq and the installation ids (§7 rule 2).
    • Each task carries a cancellation entry for its own block and for each block above it, checked at each call, operation and loop iteration: each block keeps the lowest index of a task of it that failed or aborted, and a task after that index is canceled; after a task of the block stops with U8001, every other task of the block is canceled, the lower-indexed ones included (ADR 0113 rule 1). Inside an operation in progress, including the body of a Una handler's operation, only the entries of tasks the operation itself starts are checked: the operation completes and keeps its outcome (§6 rule 4, §7 rule 3), and the cancellation takes effect at the next check after it. The limits of rule 3 still apply inside it.
    • The host capabilities of una-rt are safe to call from several tasks at once. A host operation that may block parks only its own task, while a helper thread performs it (spec/27 §2).
  3. Limits. --max-depth bounds each task's call depth, counted from the depth of the block that started it. --max-memory bounds the heaps of all tasks together (spec/11 §7).
  4. Equivalence (spec/16 §5). For a run that starts tasks:
    • the exit status and the failure MUST equal the interpreter's;
    • on an ordered run (§6 rule 7), the native trace MUST equal the interpreter's;
    • the output, and on a run that is not ordered also the trace, MUST be ones the UAM can produce under some interleaving: each task's lines and events in its own order, and those of different tasks interleaved in any order (§7 rule 6).

9. Reserved words

together becomes a keyword. The table of spec/01 §5, as changed by spec/17 §9, changes as follows:

Keywords Message
parallel, actor reserved for a later version (concurrency beyond together)
async, await not supported; use together

(Edition 0.4, ADR 0117 rule 7.) In edition 0.4, the message of async and await is not supported; use `tasks` and `start`, or `together`.

10. Diagnostic codes

These codes join the registry of spec/13 §4 with their implementation:

Code Domain Meaning
U2023 types A binding declared outside a together branch assigned, or passed as edit or take, inside it
U2024 types A together body with a statement other than let, or fewer than two branches