---
title: "15.1 Running work at the same time: together"
url: https://una-lang.org/en/learn/concurrency/running-work-at-the-same-time-together/
release: v0.4.0
edition: "0.2"
---

# 15.1 Running work at the same time: together

## 15.1.1 What concurrent work is

Think of finding out how many lamps three warehouses hold, by phone. You can call the north warehouse, wait for the answer, then call the south one, then the east one. Or three clerks can each call one warehouse, at the same moment, while you wait until all three come back. The second way can take as long as the slowest call, not as long as all three together.

Work that runs this way is **concurrent**: several pieces of it are in progress at the same time, instead of one after another. Each piece is a **task**: a part of the program that runs on its own and ends with a result. In Una, a `together` block starts its tasks, waits until every one of them has ended, and then gives their results to the code that comes after it. No task outlives the block that started it. Running tasks this way, always inside a block that waits for them all, is called **structured concurrency**.

A word you will meet next to this one is **parallel**: two tasks run in parallel when the computer really runs them at the same instant, on two of its processor cores. Concurrency is the broader idea: the tasks are in progress at the same time, whether the computer runs them at the same instant or switches between them. Una lets you say that work may run concurrently; how much of it runs in parallel is the computer's business ([The interpreter and an executable](https://una-lang.org/en/learn/concurrency/what-the-result-can-depend-on-failures-and-order/#the-interpreter-and-an-executable)).

## 15.1.2 Why a program waits on several services at once

Most of the time a program spends waiting is not spent computing. It is spent waiting for answers: from a warehouse's stock service, a payment service, a database. In [chapter 12](https://una-lang.org/en/learn/capabilities/your-own-capabilities-and-handlers/#s12-3) such a service is a capability, and each call of one of its operations waits until the service answers. Over a network, an answer can take a tenth of a second or more.

A program that asks two warehouses, one after the other, waits twice. Each step of a body runs to its end before the next one starts, as [chapter 1](https://una-lang.org/en/learn/hello/the-main-function/#s1-3) says, so the second question is not even sent until the first answer has come back. The two questions do not depend on each other, so nothing is gained by that order. With `together`, the program can send both and wait once, for the slower of the two.

Only the waiting can change. The result stays what it was, and this chapter shows that the result cannot change: the program computes the same totals, the same failures and the same report, whether the questions are asked one after another or at the same time.

## 15.1.3 How to write `together`

Each example of this chapter is a package of its own, a step, as [chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains. The first step asks two warehouses for the units of one SKU, one after the other. `Warehouse` is a capability with one operation, `on_hand`, which can fail with `StockError` when a warehouse does not answer, and `shelves` is a handler that answers from a map, as the handler `warehouse` of [chapter 12](https://una-lang.org/en/learn/capabilities/your-own-capabilities-and-handlers/#s12-3) does; here `Warehouse` names the capability, and the handler is `shelves`:

```una include="steps/01-one-after-another/src/stock.una" title="steps/01-one-after-another/src/stock.una" verified="check, run"
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, asked one after the other.
total(sku: Text) -> Int
  uses @north: Warehouse[on_hand]
  uses @south: Warehouse[on_hand]
  fails StockError
=
  let in_north = @north.on_hand(sku)
    if error pass
  let in_south = @south.on_hand(sku)
    if error pass
  in_north + in_south

pub main() -> Unit
  uses @console: Console[print]
=
  let north = empty_map().with(key: "LAMP-01", value: 4)
  let south = empty_map().with(key: "LAMP-01", value: 2)
  let units = total("LAMP-01") with @north = shelves(north), @south = shelves(south)
    if error use 0
  @console.print("LAMP-01: {units} units")
```

`una run .` prints:

```text include="steps/01-one-after-another/expected/output.txt"
LAMP-01: 6 units
```

The two `let` lines of `total` run in order: first the north warehouse is asked, and only when it has answered, the south one. To ask both at the same time, put the two `let` lines under `together`:

:::steps
```diff include="steps/01-one-after-another..steps/02-together:src/stock.una" title="src/stock.una"
--- a/src/stock.una
+++ b/src/stock.una
@@ -12,16 +12,17 @@
 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, asked one after the other.
+--- 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
 =
-  let in_north = @north.on_hand(sku)
-    if error pass
-  let in_south = @south.on_hand(sku)
-    if error pass
+  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
 
 pub main() -> Unit
```

1. **`together`.** The keyword, alone on its line, opens the block. The block is a statement: a step of the body, like a `let` line.
2. **`let in_north = @north.on_hand(sku)`.** Each `let` line indented under `together` is a **branch**, and its expression is a task. This task asks the north warehouse.
3. **`if error pass`.** A branch keeps its handling clause, under it, as the same `let` would outside the block ([chapter 7](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3)).
4. **`let in_south = @south.on_hand(sku)`.** The second branch, a second task. The two tasks start together.
5. **`in_north + in_south`.** The first line after the block. It runs only when both tasks have ended, and both names are bound by then.
:::

`una run .` prints the same line as before:

```text include="steps/02-together/expected/output.txt"
LAMP-01: 6 units
```

That is the point of the change: the result is the same, and only the waiting can differ. Under `una run`, the tasks still run one after another, so this step takes no less time; the waiting shrinks in an executable that asks real services ([The interpreter and an executable](https://una-lang.org/en/learn/concurrency/what-the-result-can-depend-on-failures-and-order/#the-interpreter-and-an-executable)).

## 15.1.4 The forms of `together`

The module `forms` has one function for each way of writing a branch, and a `main` that calls them:

```una include="steps/03-together-forms/src/forms.una" title="steps/03-together-forms/src/forms.una" verified="check, run"
module forms

--- 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)

--- A warehouse that does not answer.
handler offline(site: Text) for Warehouse
  op on_hand(sku) = fail Offline(site)

--- Two branches: the units of `sku` in two warehouses.
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

--- Three branches: the units of `sku` in three warehouses, as a text.
three_sites(sku: Text) -> Text
  uses @north: Warehouse[on_hand]
  uses @south: Warehouse[on_hand]
  uses @east: 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
    let in_east = @east.on_hand(sku)
      if error pass
  "{in_north} + {in_south} + {in_east} = {in_north + in_south + in_east}"

--- The units of `sku` in the one warehouse a caller hands over.
units_of(sku: Text) -> Int
  uses @warehouse: Warehouse[on_hand]
  fails StockError
=
  @warehouse.on_hand(sku)
    if error pass

--- A branch that installs its own handler: each store's stock comes from its own map.
two_stores(sku: Text, harbor: Map[Text, Int], market: Map[Text, Int]) -> Int
  fails StockError
=
  together
    let at_harbor = units_of(sku) with @warehouse = shelves(harbor)
      if error pass
    let at_market = units_of(sku) with @warehouse = shelves(market)
      if error pass
  at_harbor + at_market

--- Branches that handle their own failure: a warehouse that does not answer counts as none.
estimate(sku: Text) -> Int
  uses @north: Warehouse[on_hand]
  uses @south: Warehouse[on_hand]
=
  together
    let in_north = @north.on_hand(sku)
      if error use 0
    let in_south = @south.on_hand(sku)
      if error use 0
  in_north + in_south

pub main() -> Unit
  uses @console: Console[print]
=
  let north = empty_map().with(key: "LAMP-01", value: 4)
  let south = empty_map().with(key: "LAMP-01", value: 2)
  let east = empty_map().with(key: "DESK-02", value: 3)
  let units = total("LAMP-01") with @north = shelves(north), @south = shelves(south)
    if error use 0
  @console.print("two branches: {units}")
  let line = three_sites("LAMP-01") with @north = shelves(north), @south = shelves(south), @east = shelves(east)
    if error use "no count"
  @console.print("three branches: {line}")
  let stores = two_stores("LAMP-01", harbor: north, market: south)
    if error use 0
  @console.print("a handler per branch: {stores}")
  let rough = estimate("LAMP-01") with @north = shelves(north), @south = shelves(south)
  @console.print("a clause per branch: {rough}")
```

`una run .` prints:

```text include="steps/03-together-forms/expected/output.txt"
two branches: 6
three branches: 4 + 2 + 0 = 6
a handler per branch: 6
a clause per branch: 6
```

### 15.1.4.1 Two branches

`total` is the smallest `together`: two branches, each one call of an operation. A `together` block always has at least two branches.

### 15.1.4.2 Three branches or more

`three_sites` asks three warehouses, `@north`, `@south` and `@east`, at once. A block may have as many branches as you need, each on its own `let` line, and they all may run at the same time. After the block, the three names are bound, and the last line puts them in a text.

### 15.1.4.3 A branch that installs a handler: `with`

`two_stores` has no warehouse bindings of its own. Each branch calls `units_of` with a handler installed for that one call, `with @warehouse = shelves(harbor)` and `with @warehouse = shelves(market)`, as [chapter 12](https://una-lang.org/en/learn/capabilities/passing-authority-with-rebinding-and-narrowing/#s12-4) shows. Each task gets its own installation, so the two tasks ask two different warehouses through the same function.

### 15.1.4.4 A branch that handles its own failure

`estimate` handles each failure in its branch, with `if error use 0`: a warehouse that does not answer counts as none. A branch takes any clause of [chapter 7](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3), and the clause applies to that branch alone. Since every failure is handled, `estimate` itself cannot fail, and its header has no `fails`.

### 15.1.4.5 What a branch may hold

The expression of a branch is any expression a `let` takes: a call of an operation, a call of your own function, an arithmetic expression, a text. Usually it is a call that waits for something, since that is what is worth running at the same time. A branch may also call a function that has its own `together` inside: tasks may hold tasks.

## 15.1.5 How `together` behaves

### 15.1.5.1 A branch sees what came before the block, not its siblings

The expression of a branch sees every name bound before the block: the parameters, and the `let` lines above `together`. It does not see the names of the other branches, its **siblings**, since they are computed at the same time and do not exist yet. Here a third branch tries to add the other two:

```diff include="steps/03-together-forms..steps/04-sibling:src/forms.una" title="src/forms.una"
--- a/src/forms.una
+++ b/src/forms.una
@@ -27,7 +27,8 @@
       if error pass
     let in_south = @south.on_hand(sku)
       if error pass
-  in_north + in_south
+    let both = in_north + in_south
+  both
 
 --- Three branches: the units of `sku` in three warehouses, as a text.
 three_sites(sku: Text) -> Text
```

```text include="steps/04-sibling/expected/rendered.txt"
[U1001] Error: cannot find name `in_north` in this module, its imports or the prelude
    ╭─[ src/forms.una:30:16 ]
    │
 30 │     let both = in_north + in_south
    │                ────┬───
    │                    ╰───── cannot find name `in_north` in this module, its imports or the prelude
    │
    │ Note: run `una explain U1001` for an explanation
────╯
[U1001] Error: cannot find name `in_south` in this module, its imports or the prelude
    ╭─[ src/forms.una:30:27 ]
    │
 30 │     let both = in_north + in_south
    │                           ────┬───
    │                               ╰───── cannot find name `in_south` in this module, its imports or the prelude
    │
    │ Note: run `una explain U1001` for an explanation
────╯
```

The message is the one for a name that does not exist at all, U1001, once for each sibling the branch reads. The marks point at the two names. Inside the block, `in_north` and `in_south` do not exist yet; after the block, they do. The repair is the one `total` already uses: compute the sum on the first line after the block.

### 15.1.5.2 At least two branches, and only `let` lines

A block of one branch would run one task while the function waits for it, which is what a plain `let` already does. So Una refuses it:

```diff include="steps/03-together-forms..steps/05-one-branch:src/forms.una" title="src/forms.una"
--- a/src/forms.una
+++ b/src/forms.una
@@ -25,9 +25,7 @@
   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
+  in_north
 
 --- Three branches: the units of `sku` in three warehouses, as a text.
 three_sites(sku: Text) -> Text
```

```text include="steps/05-one-branch/expected/rendered.txt"
[U2024] Error: `together` needs at least two `let` branches; with one, write a plain `let`
    ╭─[ src/forms.una:25:3 ]
    │
 25 │   together
    │   ────┬───
    │       ╰───── `together` needs at least two `let` branches; with one, write a plain `let`
    │
    │ Note: run `una explain U2024` for an explanation
────╯
```

The message gives the repair: with one task, write a plain `let`. The same code, U2024, reports a block that holds a line other than a `let`, such as a call standing on its own: every line under `together` is a branch, and a branch is a `let` line. A step that needs several lines goes into a function, and the branch calls it.

### 15.1.5.3 After the block, the names come in order

When every task has ended, the names of the branches are bound in the order of the branches, as consecutive `let` lines would bind them. Each name has the type its `let` would give it outside the block, and the verifier knows about it what it would know after that `let`.

### 15.1.5.4 The block ends when every task has ended

The line after the block runs only when all its tasks have ended. A task cannot keep running after its block, and it cannot be handed to other code to finish later: a branch gives a value, not a task.

### 15.1.5.5 `together` is a step, not a value

`together` with branches is a statement: it binds names and gives no value of its own. So it cannot stand after `let`, and it cannot be the last line of a body, the line that gives the function's result. Both are U0101, and [Common mistakes](https://una-lang.org/en/learn/concurrency/common-mistakes/#s15-6) shows each one. To build a list of results, use `together for` ([section 15.2](https://una-lang.org/en/learn/concurrency/building-a-list-at-the-same-time-together-for/#s15-2)).

### 15.1.5.6 Edition `0.2` and later

`together` is a keyword from edition `0.2` on, the edition of every package in this book. In a package of edition `0.1`, it is a reserved word ([chapter 19](https://una-lang.org/en/learn/editions/)).

## 15.1.6 `together` or plain `let` lines

:::decide
**Which to use:**

| You want… | Use |
| --- | --- |
| Two or more calls that wait on services and do not need each other's answers | `together`, one branch per call |
| A call that needs the result of an earlier one | plain `let` lines, in order |
| One call | a plain `let` |
| A failure of one service to fail the whole step | `if error pass` on that branch |
| A failure of one service to count as a default | `if error use` on that branch |
| One result for each element of a list | `together for` ([section 15.2](https://una-lang.org/en/learn/concurrency/building-a-list-at-the-same-time-together-for/#s15-2)) |
:::

## 15.1.7 Check yourself: a warehouse that does not answer

This step asks two warehouses twice, once with `estimate` and once with `total`. The north warehouse holds 4 lamps, and the south one does not answer: `offline` is a handler whose operation always fails with `Offline`.

```una include="steps/06-estimate/src/estimate.una" title="steps/06-estimate/src/estimate.una"
module estimate

--- 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)

--- A warehouse that does not answer.
handler offline(site: Text) for Warehouse
  op on_hand(sku) = fail Offline(site)

--- The units of `sku` in two warehouses: a warehouse that does not answer counts as none.
estimate(sku: Text) -> Int
  uses @north: Warehouse[on_hand]
  uses @south: Warehouse[on_hand]
=
  together
    let in_north = @north.on_hand(sku)
      if error use 0
    let in_south = @south.on_hand(sku)
      if error use 0
  in_north + in_south

--- The units of `sku` in two warehouses: a warehouse that does not answer fails the count.
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

pub main() -> Unit
  uses @console: Console[print]
=
  let north = empty_map().with(key: "LAMP-01", value: 4)
  let rough = estimate("LAMP-01") with @north = shelves(north), @south = offline("south")
  @console.print("estimate: {rough}")
  let exact = total("LAMP-01") with @north = shelves(north), @south = offline("south")
    if error use -1
  @console.print("total: {exact}")
```

What does `una run .` print?

:::answer Show the answer
```text include="steps/06-estimate/expected/output.txt"
estimate: 4
total: -1
```

In `estimate`, each branch handles its own failure, so the south branch gives 0 and the block ends normally: 4 + 0. In `total`, the south branch passes its failure on, so the block fails, `total` fails with it, and the clause of `main`, `if error use -1`, gives -1. Running the branches at the same time changes neither answer.
:::
