Home / Docs / Specification / 27. Tasks and time
27.6 first of
-
Grammar (ADR 0117 rule 6). In edition
0.4,first ofraces its branches, where ablock_exprmay stand: as the value of aletor of an assignment, or as the last line of a block.ebnfblock_expr = when_expr | if_block | together_for | first_of ; first_of = "first" "of" NEWLINE INDENT handled handled { handled } DEDENT ;unalet 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.
firstopens a race only whenofand the end of its line follow it. Anywhere elsefirstandofare names, so the prelude'sfirststays a method. Before edition0.4,first ofdoes not parse (U0101). - Shape. A body with fewer than two branches, or with a line that is not a
handledexpression (alet, a loop, awhen), is U2035 atfirst of.
- The words.
-
Static semantics.
- Tasks. Each branch is a task, with the scope, capture and capability rules of a
togetherbranch (spec/19 §2 rules 1, 3 and 4): it sees the bindings before the block and none of its siblings', and assigning, or passing aseditortake, a binding declared outside it is U2023. It is not a loop body forstopandskip(U2034), and it may not run forever (U3027). - Types. Every branch has one type
T, the type of thefirst 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 useorattemptkeep it from failing.
- Tasks. Each branch is a task, with the scope, capture and capability rules of a
-
Dynamics.
- The branches run concurrently. The first branch to return wins, and every other branch is canceled (spec/19 §6 rule 4). The
first ofends once every branch has returned, failed or stopped, with the winner's value. - A failure cancels nothing. When every branch fails, the
first offails 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
togethertask 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.
- The branches run concurrently. The first branch to return wins, and every other branch is canceled (spec/19 §6 rule 4). The
-
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
--workersis. 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).
-
Paths. The
i-th branch of thec-thfirst ofthat the taskpruns has the pathp.f<c>.<i>, andf<c>.<i>in the root task, withcandicounted from 1. The paths of public code are unique, and differ from the numeric paths oftogether(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 ofinside aquietexpression is not counted, and its branches have the pathsp.qf.<i>, with noc. So whether quiet code ran a race, which may depend on data abovepublic, never movescfor 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.
- Quiet code (S-39, S-40, spec/26 §6 rule 4). A
-
Trace (ADR 0117 rule 10). The events of a
first ofare the winner's, then those of each other branch that started, in index order, each canceled one ending with itscancelledevent (spec/19 §7 rule 3);seqand the installation idswith:<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 itscancelledevent, in index order (§5 rule 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 itscancelledevent 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 oftogethercanceled by a failed sibling lets its operation complete, as spec/19 §6 rule 4 says. -
Information flow (ADR 0117 IF3). Let
tbe the join ofτof every branch,L_resincluded (spec/26 §7 rule 5, item 6). Every branch runs beside the others (ADR 0116, amendment of 2026-10-25, C), sotis 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τ_concof the race at its own site (§11 rule 5), and withL_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 throughctx(§11 rule 4), nottitself (draft amendment notedocs/plan/0116-race-label-note.md). A race whose branches can reach an operation ofHttpraisesL_resto its ownt: 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 thefirst offails does not depend on timing.
- The value is labeled
-
Verification (ADR 0117 Verification). Each branch is verified alone, with the facts known before the block, as a
togetherbranch is (spec/19 §4 rule 1). Each value a branch can return flows intoT, whose refinements are obligations there. The result carries the facts ofTonly. -
Report (ADR 0117 rule 13). The report's
out_of_modellist (spec/13 §6) ends with "waits at limits and atstart" and "which branch offirst ofwins, beyond its label". Itsinformation.timinglist holds eachfirst ofwhosetis abovepublic, as{"construct": "first of", ...}, with its function andt. -
Core (spec/09).
first ofwith the branchess₁tosₙisfirst_of(s₁ | ... | sₙ), eachsᵢdesugared with itswithbindings, deadline and handling clauses, and closed over the bindings before the block. -
Costs (ADR 0117 Costs). A
first ofofnbranches startsntasks, and its decision is one atomic compare-and-swap of the winner, followed by one cancellation of the othern − 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 thekwaits on the race among thewof the process.