Home / Docs / Language guide / Expressions and control flow

together

Release v0.4.0Edition 0.2 and laterU0101U0103U2023U2024U4002

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.

una
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.

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 ;

Examples

One task per element, with failures passed on:

una
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
  found

A together with one branch is rejected: write a plain let:

una
-- fails with U2024
module shop

pub prepare(units: Int) -> Int
=
  together
    let boxes = units + 1
  boxes

Edge 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:

una
-- 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
  total

The outer code may update its own bindings after the block, from the branches' results:

una
module shop

pub prepare(units: Int) -> Int
=
  let edit total = 0
  together
    let boxes = units + 1
    let labels = units + 2
  total = boxes + labels
  total

Further rules:

Diagnostics

Edition

together exists from edition 0.2 on. In edition 0.1 it is reserved:

una
-- 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
  codes

Normative source