Home / Learn / 15 Concurrency and parallelism

Release v0.4.0Edition 0.2

15.1 Running work at the same time: together

Page 2 of 9

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

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 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 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 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 does; here Warehouse names the capability, and the handler is shelves:

steps/01-one-after-another/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, 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:

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

src/stock.unadiff
--- 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).
  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:

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

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:

steps/03-together-forms/src/forms.unacheckrununa
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:

Output
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 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, 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:

src/forms.unadiff
--- 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
Diagnostic
[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:

src/forms.unadiff
--- 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
Diagnostic
[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 shows each one. To build a list of results, use together for (section 15.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).

15.1.6 together or plain let lines

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)

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.

steps/06-estimate/src/estimate.unauna
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?

Show the answer
Output
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.

Next:15.2 Building a list at the same time: together for