Home / Docs / Language guide / Expressions and control flow
together
What it does
From edition 0.2, together runs independent work as concurrent tasks, pieces of work that may run at the same time, and every task ends before its block does. The result is that of running the tasks one after another, in order, stopping at the first failure, and the reported trace (the record of what the program did outside itself) lists each task's events in index order, whatever the interleaving, the order in which the tasks' steps happened to mix.
Learn more: Running work at the same time: together.
togetherwith two or moreletbranches runs each branch as a task. The branches' bindings are in scope after the block.together for x in xsruns one task per element, and gives the list of their results in element order.
module shop
pub capability Warehouse
op stock_level() -> Int
pub largest_stock() -> Int
uses @east: Warehouse[stock_level]
uses @west: Warehouse[stock_level]
=
together
let east = stock_level() with @warehouse = @east
let west = stock_level() with @warehouse = @west
max(east, b: west)
stock_level() -> Int
uses @warehouse: Warehouse[stock_level]
=
@warehouse.stock_level()Forms
In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.
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 ;togetheris a statement: its body holds onlyletstatements, at least two. Eachlet, with itswithbindings and handling clauses, is a branch.together forstands where a block expression can: as the value of aletor of an assignment, or as the last line of a block. Its body is a block whose final expression is the element's result.
Examples
One task per element, with failures passed on:
module shop
pub kind FetchError = Missing | Gone
fetch_price(sku: Int) -> Int
fails FetchError
=
if sku < 0
fail Missing
else
sku * 10
pub prices(skus: List[Int]) -> List[Int]
fails FetchError
=
let found = together for sku in skus
fetch_price(sku)
if error pass
foundA together with one branch is rejected: write a plain let:
-- fails with U2024
module shop
pub prepare(units: Int) -> Int
=
together
let boxes = units + 1
boxesEdge cases
A task cannot change outer bindings. It captures the values it reads, as a lambda does. Assigning a binding declared outside it, or passing one as edit or take, is rejected; return the new value from the task instead:
-- fails with U2023
module shop
pub sum_skus(skus: List[Int]) -> Int
=
let edit total = 0
let copies = together for sku in skus
total = total + sku
sku
totalThe outer code may update its own bindings after the block, from the branches' results:
module shop
pub prepare(units: Int) -> Int
=
let edit total = 0
together
let boxes = units + 1
let labels = units + 2
total = boxes + labels
totalFurther rules:
- Scope. A branch sees the bindings in scope before the block, and none of its siblings'.
- Failure and cancellation. When a task fails, every task after it is canceled, and the block fails with the failure of the lowest-indexed task that failed. Cancellation is cooperative, which means a task is never stopped in the middle of a step: a canceled task stops at its next call, operation or loop iteration, and effects already performed stay.
- The trace of a block is the traces of its tasks in index order, whatever the interleaving.
- Verification. Each branch is verified with the facts known before the block and none of its siblings'.
- Labels. Each branch runs under the block's program counter (the label of the conditions that decide whether a line runs; see Branches and failures: implicit flows). A
together forover a labeled list, or a range with labeled bounds, runs its body under that label, sofailand calls that can fail are U4002 there. - Timing. The relative order of the effects of different tasks, and how far a canceled task got, depend on timing. In editions
0.2and0.3timing is out of the model. Edition0.4adds time limits and races, and gives each of their sites a timing label that the checker enforces (see Tasks and time). - No task values. No value stands for a task, to keep or pass on: every task ends before its block does. In editions
0.2and0.3there are no other tasks, no races, no timeouts and no channels. Edition0.4adds tasks that only have effects (tasksandstart), a time limit (within) and a race (first of), described in Tasks and time. - A statement, not an expression.
let x = togetherwith branches is U0101: writetogether forto build a list.
Diagnostics
- U0101:
togetherwith branches written as an expression. - U0103:
togetherin edition0.1, where it is reserved. - U2023: a task that assigns, edits or takes a binding declared outside it.
- U2024: a
togetherbody with a statement other thanlet, or fewer than two branches. - U4002: a failure in a task under a labeled program counter.
Edition
together exists from edition 0.2 on. In edition 0.1 it is reserved:
-- edition 0.1
-- fails with U0103
module shop
pub hash_skus(skus: List[Int]) -> List[Int]
=
let codes = together for sku in skus
sku * sku
codesNormative source
- spec/19 §1: syntax and rules 1 to 6; spec/19 §2: static semantics; spec/19 §3: information flow; spec/19 §4: verification.
- spec/19 §6: dynamic semantics; spec/19 §7: traces.
- spec/17 §5 rule 4: captures, as for lambdas.
- Decision record: ADR 0065, for structured concurrency.