Home / Docs / Specification / 27. Tasks and time

27.6 first of

Release v0.4.0
  1. Grammar (ADR 0117 rule 6). In edition 0.4, first of races its branches, where a block_expr may stand: as the value of a let or of an assignment, or as the last line of a block.

    ebnf
    block_expr = when_expr | if_block | together_for | first_of ;
    first_of   = "first" "of" NEWLINE INDENT handled handled { handled } DEDENT ;
    una
    let quote = first of
      fetch_quote(url: "https://quotes-a.example/eur")
        if error pass
      fetch_quote(url: "https://quotes-b.example/eur")
        if error pass
    • The words. first opens a race only when of and the end of its line follow it. Anywhere else first and of are names, so the prelude's first stays a method. Before edition 0.4, first of does not parse (U0101).
    • Shape. A body with fewer than two branches, or with a line that is not a handled expression (a let, a loop, a when), is U2035 at first of.
  2. Static semantics.

    • Tasks. Each branch is a task, with the scope, capture and capability rules of a together branch (spec/19 §2 rules 1, 3 and 4): it sees the bindings before the block and none of its siblings', and assigning, or passing as edit or take, a binding declared outside it is U2023. It is not a loop body for stop and skip (U2034), and it may not run forever (U3027).
    • Types. Every branch has one type T, the type of the first of (U2001).
    • Failures. A branch's failure is its expression's failure after its handling clauses (spec/06 §3), so a branch that can fail fails with the function's error kind (U3008), and if error use or attempt keep it from failing.
  3. Dynamics.

    • The branches run concurrently. The first branch to return wins, and every other branch is canceled (spec/19 §6 rule 4). The first of ends once every branch has returned, failed or stopped, with the winner's value.
    • A failure cancels nothing. When every branch fails, the first of fails with the failure of the lowest-indexed branch: all of them have ended by then, so the failure does not depend on timing.
    • A branch that runs too deep, past its depth limit (§3), or out of the run's memory, aborts the run with U6003, as a together task does (spec/19 §8 rule 2).
    • A canceled branch leaves each of its frames by the path a failure takes, releasing the values each one holds, as a cut does (§5 rule 5), so a program whose races keep canceling branches holds no more memory than one whose branches fail. A branch that had already returned or failed when another won is not canceled: its result is dropped.
  4. Schedules.

    • The interpreter runs the branches one after another, in index order, and stops at the first that returns, which is one legal schedule (ADR 0117 rule 11): no branch after it starts.
    • Under virtual time (spec/26 §8), native code runs the branches the same way, each to its end, in index order, up to the first that returns, whatever --workers is. So both engines give the same winner, output, failure and trace (spec/16 §5), also when the branches would end at the same virtual time: a tie goes to the lowest index.
    • Under real time, a run in which the winner decides the outcome is compared only for being an outcome the UAM allows under some timing (ADR 0117 rule 12).
  5. Paths. The i-th branch of the c-th first of that the task p runs has the path p.f<c>.<i>, and f<c>.<i> in the root task, with c and i counted from 1. The paths of public code are unique, and differ from the numeric paths of together (spec/19 §6 rule 1); those of quiet code are not (below).

    • Quiet code (S-39, S-40, spec/26 §6 rule 4). A first of inside a quiet expression is not counted, and its branches have the paths p.qf.<i>, with no c. So whether quiet code ran a race, which may depend on data above public, never moves c for a later public one, nor the path of a later quiet one. A task started in quiet code runs in it (spec/27 §7 rule 3), so none of its races are counted. Paths in quiet code are not unique: two quiet races of one task have the same paths, which only the events of quiet code carry.
  6. Trace (ADR 0117 rule 10). The events of a first of are the winner's, then those of each other branch that started, in index order, each canceled one ending with its cancelled event (spec/19 §7 rule 3); seq and the installation ids with:<handler>#<n> count in that order. When every branch fails, the events are in index order. A branch that never started has no events, unless a cut kept it from starting: a cut ends every branch that has not returned with its cancelled event, in index order (§5 rule 7).

  7. Interruption (ADR 0117 rule 4). An interruptible operation, one of Http (§5 rule 6), that is waiting when its branch is canceled ends at once: its event has the outcome {"kind": "interrupted"}, with its operation and arguments, and the task stops, as at a check point, so its cancelled event follows. Its helper abandons the exchange at its next I/O step (§2 rule 4); what it sent before is an effect in doubt. Only the cancellation of the losers of a race, and of the tasks they started, interrupts a waiting operation: a task of together canceled by a failed sibling lets its operation complete, as spec/19 §6 rule 4 says.

  8. Information flow (ADR 0117 IF3). Let t be the join of τ of every branch, L_res included (spec/26 §7 rule 5, item 6). Every branch runs beside the others (ADR 0116, amendment of 2026-10-25, C), so t is computed once for the whole race: the items of spec/26 §7 rule 5 other than 5 and 6, over the race's code, every branch included, with item 4 as that rule states it (a lambda written at a call counts by its captures and its body, not as ⊤), joined with τ_conc of the race at its own site (§11 rule 5), and with L_res. That is κ(F) ⊔ τ_conc(F) of C with κ(F) taken by IF5 as it stands; the κ of §11 rule 3, which counts a part that calls a prelude function with a function argument as ⊤, is coarser, and it is what the sites inside a branch take through ctx (§11 rule 4), not t itself (draft amendment note docs/plan/0116-race-label-note.md). A race whose branches can reach an operation of Http raises L_res to its own t: a loser's request is cut before its time-out, and its helper's last step runs beside later code.

    • The value is labeled t, besides the labels of the winner's value, since timing decides the winner.
    • The timing floor. Every operation in every branch, and every call with effects, is checked as if it ran under pc ⊔ t: the sinks of spec/07 §7 rule 4 (U4003), and the effect bound of each call (U4002), since a sibling that wins can cut it.
    • The failure follows the rules of together (spec/19 §3 rule 2): whether the first of fails does not depend on timing.
  9. Verification (ADR 0117 Verification). Each branch is verified alone, with the facts known before the block, as a together branch is (spec/19 §4 rule 1). Each value a branch can return flows into T, whose refinements are obligations there. The result carries the facts of T only.

  10. Report (ADR 0117 rule 13). The report's out_of_model list (spec/13 §6) ends with "waits at limits and at start" and "which branch of first of wins, beyond its label". Its information.timing list holds each first of whose t is above public, as {"construct": "first of", ...}, with its function and t.

  11. Core (spec/09). first of with the branches s₁ to sₙ is first_of(s₁ | ... | sₙ), each sᵢ desugared with its with bindings, deadline and handling clauses, and closed over the bindings before the block.

  12. Costs (ADR 0117 Costs). A first of of n branches starts n tasks, and its decision is one atomic compare-and-swap of the winner, followed by one cancellation of the other n − 1: O(n). The join adopts each branch's events once, O(events). Waking the losers parked on a request takes O(k log w), for the k waits on the race among the w of the process.