---
title: "27.6 first of"
url: https://una-lang.org/en/docs/spec/27-tasks-and-time/6-first-of/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/27-tasks-and-time.md
---

# 27.6 first of

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.
