Home / Learn / 15 Concurrency and parallelism
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:
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:
LAMP-01: 6 unitsThe 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:
--- 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() -> Unittogether. The keyword, alone on its line, opens the block. The block is a statement: a step of the body, like aletline.let in_north = @north.on_hand(sku). Eachletline indented undertogetheris a branch, and its expression is a task. This task asks the north warehouse.if error pass. A branch keeps its handling clause, under it, as the sameletwould outside the block (chapter 7).let in_south = @south.on_hand(sku). The second branch, a second task. The two tasks start together.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:
LAMP-01: 6 unitsThat 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:
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:
two branches: 6
three branches: 4 + 2 + 0 = 6
a handler per branch: 6
a clause per branch: 615.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:
--- 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[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:
--- 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[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.
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
estimate: 4
total: -1In 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.