Home / Learn / 15 Concurrency and parallelism

Release v0.4.0Edition 0.2

15.2 Building a list at the same time: together for

Page 3 of 9

15.2.1 What together for is

together suits a few pieces of work you can name one by one. Often the pieces come from a list: one question per line of an order, one label per SKU. together for runs one task for each element of a list, or for each number of a range, all of them concurrent, and gives the list of their results.

It reads like the for loop of chapter 9, with one difference that matters. A for loop takes its turns one after another, and a turn may change a name declared before the loop with let edit. The tasks of together for run concurrently, and each one gives back a value. together for builds a list: one element per task, in the order of the list it walks.

15.2.2 Why one task per element

A store checks an order of ten lines against its warehouses. Asked one line after another, the check takes ten times as long as one line. The lines do not depend on each other, so they can all be checked at once, and in an executable the check can take about as long as the slowest line. The number of lines is known only when the program runs, so a together block, whose branches are written one by one, cannot do it. together for makes as many tasks as the list has elements.

15.2.3 How to write together for

The module labels has one function for each form:

steps/07-together-for-forms/src/labels.unacheckrununa
module labels

--- A shelf label for each SKU: a `together for` over a list, as the value of a `let`.
labels(skus: List[Text]) -> List[Text]
  ensures result.len == skus.len
=
  let made = together for sku in skus
    "label {sku}"
  made

--- The last day of each of the first `weeks` weeks of a sale: a `together for` over a range.
last_days(weeks: Int) -> List[Int]
  requires weeks >= 0
  ensures result.len == weeks
=
  together for week in 1..weeks
    week * 7

--- A body of several lines: its last line is the task's value.
sizes(skus: List[Text]) -> List[Text]
=
  together for sku in skus
    let size = sku.len
    let word = if size == 1 then "character" else "characters"
    "{sku}: {size} {word}"

--- A `together for` inside a `together for`: the label of each SKU of each order.
order_labels(orders: List[List[Text]]) -> List[List[Text]]
=
  together for order in orders
    labels(order)

pub main() -> Unit
  uses @console: Console[print]
=
  let skus = ["LAMP-01", "DESK-02", "RUG-07"]
  @console.print("{labels(skus)}")
  @console.print("{labels([])}")
  @console.print("{last_days(3)}")
  @console.print("{last_days(0)}")
  @console.print("{sizes(skus)}")
  let lamps = ["LAMP-01"]
  let desks = ["DESK-02", "DESK-05"]
  @console.print("{order_labels([lamps, desks])}")
  let edit shelf: List[Text] = []
  shelf = together for sku in desks
    "shelf {sku}"
  @console.print("{shelf}")

una run . prints:

Output
["label LAMP-01", "label DESK-02", "label RUG-07"]
[]
[7, 14, 21]
[]
["LAMP-01: 7 characters", "DESK-02: 7 characters", "RUG-07: 6 characters"]
[["label LAMP-01"], ["label DESK-02", "label DESK-05"]]
["shelf DESK-02", "shelf DESK-05"]

15.2.3.1 Over a list

together for sku in skus, then an indented body. sku is the element name, as the loop variable of a for loop: in each task, it stands for one element of skus. The body is the work of one task, and its last line is the task's value: here the text "label {sku}". The result is a List[Text], one label per SKU. labels([]) walks an empty list, starts no task, and gives an empty list.

15.2.3.2 Over a range

together for week in 1..weeks runs one task per whole number of the range, as a for loop over a range takes one turn per number (chapter 9). Both kinds of range work, .. with its end and ..< without. last_days(0) walks the empty range 1..0, starts no task, and gives an empty list.

15.2.3.3 A body of several lines

The body of sizes has three lines. The first two are let lines of the task's own, and the last line is the task's value. A name made in the body is the task's own: each task has its own size and its own word.

15.2.3.4 Where it stands: after let, as the last line, or in an assignment

together for gives a value, so it stands where a value goes:

15.2.3.5 One inside another

order_labels walks a list of orders, each a list of SKUs, and its body calls labels, which has a together for of its own. The result is a list of lists, one per order, each in the order of its SKUs. A together for may also stand directly in the body of another.

15.2.4 Counting the stock of every SKU

The forms together, with warehouses. stock_lines counts several SKUs at once, and each of its tasks calls total, which asks two warehouses at once:

steps/08-stock-of-each/src/stock.unacheckrununa
module stock

--- Why a warehouse gave no count.
kind StockError = | Offline(site: Text)

--- A warehouse's stock service: the units of a SKU on its shelves.
capability Warehouse
  op on_hand(sku: Text) -> Int
    fails StockError

--- A warehouse whose stock is held in a map: none of a SKU it does not stock.
handler shelves(stock: Map[Text, Int]) for Warehouse
  op on_hand(sku) = stock.get(key: sku).or_else(default: 0)

--- The units of `sku` in both warehouses, both asked at the same time.
total(sku: Text) -> Int
  uses @north: Warehouse[on_hand]
  uses @south: Warehouse[on_hand]
  fails StockError
=
  together
    let in_north = @north.on_hand(sku)
      if error pass
    let in_south = @south.on_hand(sku)
      if error pass
  in_north + in_south

--- One line per SKU, every SKU counted at the same time.
stock_lines(skus: List[Text]) -> List[Text]
  uses @north: Warehouse[on_hand]
  uses @south: Warehouse[on_hand]
  fails StockError
=
  together for sku in skus
    let units = total(sku)
      if error pass
    "{sku}: {units} units"

pub main() -> Unit
  uses @console: Console[print]
=
  let north = empty_map().with(key: "LAMP-01", value: 4).with(key: "DESK-02", value: 3)
  let south = empty_map().with(key: "LAMP-01", value: 2)
  let lines = stock_lines(["LAMP-01", "DESK-02", "CHAIR-09"]) with @north = shelves(north), @south = shelves(south)
    if error use ["a warehouse did not answer"]
  for line in lines
    @console.print(line)
  1. total, with a together of its own. Tasks inside tasks: total asks the two warehouses at the same time, and each task of stock_lines calls it. Three SKUs, two warehouses each: six questions, which may all be in progress at once.
  2. together for sku in skus. One task per SKU, as the last line of the body, so the list it builds is the function's result.
  3. let units = total(sku), then if error pass. A line of the body that can fail takes a clause, as in any block. A failure of total makes its task fail, and the task's failure makes stock_lines fail.
  4. "{sku}: {units} units". The last line, the task's value.
  5. with @north = shelves(north), @south = shelves(south). The bindings in tasks. Each task uses @north and @south, the bindings of the uses lines of stock_lines. main installs both handlers for the one call, and every task of that call sees them.

una run . prints:

Output
LAMP-01: 6 units
DESK-02: 3 units
CHAIR-09: 0 units

CHAIR-09 is in neither map, so both warehouses answer 0.

15.2.5 How together for behaves

15.2.5.1 The results come in the order of the list

The list together for gives has its results in the order of the elements, whatever order the tasks finish in. If the task for CHAIR-09 finishes first, its line is still the third. You never sort the results back into place.

15.2.5.2 One element, one task

The result has exactly as many elements as the list it walks, or as the range has numbers: one per task. An empty list or an empty range starts no task, and gives an empty list.

15.2.5.3 What the verifier knows: the length

The verifier knows that length too. labels promises ensures result.len == skus.len, and last_days promises ensures result.len == weeks, from requires weeks >= 0. una check . proves both from the together for alone (chapter 5). Each element has the type of the body's last line, with whatever that type promises.

15.2.5.4 It gives a value, so it ends a block or names one

A together for that is neither named by a let, nor assigned, nor the last line of its block would build a list and lose it. Here stock_lines gets a line after it:

src/stock.unadiff
--- a/src/stock.una
+++ b/src/stock.una
@@ -35,6 +35,7 @@
     let units = total(sku)
       if error pass
     "{sku}: {units} units"
+  ["no SKUs asked"]
 
 pub main() -> Unit
   uses @console: Console[print]
Diagnostic
[U0101] Error: a `together for` must be the last line of its block or the value of a `let` or of an assignment
    ╭─[ src/stock.una:34:3 ]
    │
 34 │   together for sku in skus
    │   ────┬───
    │       ╰───── a `together for` must be the last line of its block or the value of a `let` or of an assignment
    │
    │ Note: run `una explain U0101` for an explanation
────╯

The message says where a together for may stand: as the last line of its block, as the value of a let, or as the value of an assignment to a let edit name, as in main above. Name the list, or make it the last line.

15.2.5.5 It builds a list, not a total

A task cannot change a name declared outside it, so a together for cannot add up a running total as a for loop does. Build the list, then add it up after the block, with sum or fold (chapter 10). Section 15.3 says why.

15.2.6 A loop, map or together for

Which to use:

You want… Use
One result per element, each from a call that waits on a service together for
One result per element, from a short pure computation map (chapter 10), or together for
A running total, or a turn that reads what the turn before it left a for loop with let edit (chapter 9)
A few different pieces of work, each with its own name together with branches (section 15.1)
A step for each element that only prints a for loop: printing in order is what you want

In an executable, the tasks run on a pool of threads (The interpreter and an executable), and starting a task, and copying in what it reads, is work too. So together for pays off when each task waits for something, such as a service. For a short computation that waits for nothing, such as building a label, map reads more simply.

15.2.7 Check yourself: the order of the results

plan decides, for each SKU, whether to order more of it:

steps/10-restock/src/restock.unauna
module restock

--- What to do about each SKU: order more when fewer than 3 units are left.
plan(skus: List[Text], stock: Map[Text, Int]) -> List[Text]
=
  together for sku in skus
    let units = stock.get(key: sku).or_else(default: 0)
    if units < 3 then "order {sku}" else "{sku} ok"

pub main() -> Unit
  uses @console: Console[print]
=
  let stock = empty_map().with(key: "DESK-02", value: 1).with(key: "LAMP-01", value: 8)
  let skus = ["RUG-07", "LAMP-01", "DESK-02"]
  @console.print("{plan(skus, stock: stock)}")

Suppose the task for LAMP-01 finishes first. What does una run . print?

Show the answer
Output
["order RUG-07", "LAMP-01 ok", "order DESK-02"]

The results come in the order of skus, RUG-07, LAMP-01, DESK-02, whatever order the tasks finish in. RUG-07 is not in the map, so or_else gives 0, which is fewer than 3. DESK-02 has 1 unit left, and LAMP-01 has 8.

Next:15.3 What the result can depend on: failures and order