Home / Learn / 15 Concurrency and parallelism
15.4 Day-to-day: asking every warehouse at once
Page 5 of 9
15.4.1 What the program must do
A store keeps its stock in three warehouses, north, south and east. When an order comes in, the store needs to know, for each line, how many units of the SKU each warehouse holds, whether the three together hold enough, and whether the whole order can ship. The warehouses are services, and asking each one takes time, so the check should ask all three at once, and check all the lines of the order at once. When a warehouse does not answer, the check stops, and says which warehouse to try again.
The program is one module, availability. Its warehouses are handlers inside the program, so the whole check runs with no network, and its examples replace each warehouse with a fake.
15.4.2 The kinds and the warehouses
--- Why a warehouse gave no count.
pub kind StockError = | Offline(site: Text)
--- One line of an order: a SKU and how many units the customer wants.
pub kind OrderLine
sku: Text
quantity: Int
--- What each warehouse holds of one line's SKU.
pub kind Availability
sku: Text
wanted: Int
north: Int
south: Int
east: Int
--- A warehouse's stock service: the units of a SKU on its shelves.
pub 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.
pub 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.
pub handler offline(site: Text) for Warehouse
op on_hand(sku) = fail Offline(site)OrderLine is what the customer asks for. Availability is what the warehouses answer about one line: the SKU, the units wanted, and one field per warehouse. Warehouse is the stock service, with one operation that can fail with StockError. shelves answers from a map, as a real warehouse would answer from its stock list, and offline stands for a warehouse that does not answer, with the name of its site in the failure.
15.4.3 One line: three warehouses at once
--- What the three warehouses hold of a line's SKU, all three asked at the same time.
pub availability(line: OrderLine) -> Availability
uses @north: Warehouse[on_hand]
uses @south: Warehouse[on_hand]
uses @east: Warehouse[on_hand]
fails StockError
=
together
let north = @north.on_hand(line.sku)
if error pass
let south = @south.on_hand(line.sku)
if error pass
let east = @east.on_hand(line.sku)
if error pass
Availability(sku: line.sku, wanted: line.quantity, north: north, south: south, east: east)availability holds three warehouse bindings, @north, @south and @east, and asks all three in one together block, a branch each. Each branch passes its failure on: a count that misses a warehouse would be wrong, so any warehouse that does not answer fails the line. The record is built on the first line after the block, when the three counts are in.
15.4.4 An order: every line at once
--- Every line of an order, all the lines checked at the same time.
pub check_order(lines: List[OrderLine]) -> List[Availability]
uses @north: Warehouse[on_hand]
uses @south: Warehouse[on_hand]
uses @east: Warehouse[on_hand]
fails StockError
=
together for line in lines
availability(line)
if error passcheck_order runs one task per line of the order, and each task runs availability, which starts three tasks of its own. An order of two lines makes six questions, which may all be in progress at once. The list comes back in the order of the lines, and if any line fails, the whole order fails with the failure of the first line, in order, that fails.
15.4.5 The pure parts: what is held, and the report
--- The units of the line's SKU in the three warehouses together.
pub held(found: Availability) -> Int = found.north + found.south + found.east
--- Whether the three warehouses together hold enough units for the line.
pub can_ship(found: Availability) -> Bool = held(found) >= found.wanted
--- Whether every line of the order can ship.
pub ships_whole(found: List[Availability]) -> Bool = found.filter(keep: fn(line) -> not can_ship(line)).is_empty
--- One line of the report: the SKU, what each warehouse holds, and whether it ships.
pub report_line(found: Availability) -> Text
=
let counts = "{found.north} + {found.south} + {found.east} = {held(found)}"
let verdict = if can_ship(found) then "ships" else "short by {found.wanted - held(found)}"
"{found.sku}: {found.wanted} wanted, {counts} on hand, {verdict}"
--- What a person reads when a warehouse did not answer.
pub reason(failure: StockError) -> Text
=
when failure
is Offline(site) -> "the {site} warehouse did not answer; check again later"Everything else is pure: it uses no service and runs no task. held adds the three counts, can_ship compares them with what is wanted, and ships_whole keeps the lines that cannot ship and checks that there are none. report_line builds one line of the report, and reason turns a failure into a sentence. The concurrent part of the program stays small, in two functions, and everything it gives back is an ordinary value.
15.4.6 Printing the report
--- The stock of the north warehouse.
pub north_stock() -> Map[Text, Int] = empty_map().with(key: "LAMP-01", value: 4).with(key: "DESK-02", value: 1)
--- The stock of the south warehouse.
pub south_stock() -> Map[Text, Int] = empty_map().with(key: "LAMP-01", value: 2).with(key: "RUG-07", value: 3)
--- The stock of the east warehouse.
pub east_stock() -> Map[Text, Int] = empty_map().with(key: "DESK-02", value: 1).with(key: "RUG-07", value: 5)
--- Prints the report of one order, or why it could not be checked.
pub print_report(order: Text, outcome: Result[List[Availability], StockError]) -> Unit
uses @console: Console[print]
=
@console.print("Order {order}")
when outcome
is Ok(found) ->
for line in found
@console.print(" {report_line(line)}")
let whole = if ships_whole(found) then "the whole order ships" else "the order waits for stock"
@console.print(" {whole}")
is Err(failure) -> @console.print(" {reason(failure)}")
--- Checks two orders against the three warehouses, then the first again while one is offline.
pub main() -> Unit
uses @console: Console[print]
=
let lamps = [OrderLine(sku: "LAMP-01", quantity: 5), OrderLine(sku: "DESK-02", quantity: 2)]
let rugs = [OrderLine(sku: "RUG-07", quantity: 6), OrderLine(sku: "LAMP-01", quantity: 9)]
let first = attempt check_order(lamps) with @north = shelves(north_stock()), @south = shelves(south_stock()), @east = shelves(east_stock())
print_report("1042", outcome: first)
let second = attempt check_order(rugs) with @north = shelves(north_stock()), @south = shelves(south_stock()), @east = shelves(east_stock())
print_report("1043", outcome: second)
let retry = attempt check_order(lamps) with @north = shelves(north_stock()), @south = shelves(south_stock()), @east = offline("east")
print_report("1042, again", outcome: retry)The three *_stock functions give each warehouse's stock list. print_report takes the outcome of a check, a Result from attempt (chapter 7), and prints either the lines or the reason. It prints after the check has ended, with a plain for loop, so the lines are always in order. main checks two orders with all three warehouses, then the first order again with the east warehouse offline. Each check installs the three handlers for its one call, with with.
15.4.7 Running it
In the day-to-day directory:
una check .
una run .una run . prints:
Order 1042
LAMP-01: 5 wanted, 4 + 2 + 0 = 6 on hand, ships
DESK-02: 2 wanted, 1 + 0 + 1 = 2 on hand, ships
the whole order ships
Order 1043
RUG-07: 6 wanted, 0 + 3 + 5 = 8 on hand, ships
LAMP-01: 9 wanted, 4 + 2 + 0 = 6 on hand, short by 3
the order waits for stock
Order 1042, again
the east warehouse did not answer; check again laterOrder 1042 ships whole. Order 1043 holds a line that is short: 9 lamps wanted, 6 on hand. The third check fails at the east warehouse, so it prints the reason and no lines.
15.4.8 The whole program
module availability
-- Checks an order against the stock of three warehouses, asking all of them at once.
--- Why a warehouse gave no count.
pub kind StockError = | Offline(site: Text)
--- One line of an order: a SKU and how many units the customer wants.
pub kind OrderLine
sku: Text
quantity: Int
--- What each warehouse holds of one line's SKU.
pub kind Availability
sku: Text
wanted: Int
north: Int
south: Int
east: Int
--- A warehouse's stock service: the units of a SKU on its shelves.
pub 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.
pub 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.
pub handler offline(site: Text) for Warehouse
op on_hand(sku) = fail Offline(site)
--- What the three warehouses hold of a line's SKU, all three asked at the same time.
pub availability(line: OrderLine) -> Availability
uses @north: Warehouse[on_hand]
uses @south: Warehouse[on_hand]
uses @east: Warehouse[on_hand]
fails StockError
=
together
let north = @north.on_hand(line.sku)
if error pass
let south = @south.on_hand(line.sku)
if error pass
let east = @east.on_hand(line.sku)
if error pass
Availability(sku: line.sku, wanted: line.quantity, north: north, south: south, east: east)
--- Every line of an order, all the lines checked at the same time.
pub check_order(lines: List[OrderLine]) -> List[Availability]
uses @north: Warehouse[on_hand]
uses @south: Warehouse[on_hand]
uses @east: Warehouse[on_hand]
fails StockError
=
together for line in lines
availability(line)
if error pass
--- The units of the line's SKU in the three warehouses together.
pub held(found: Availability) -> Int = found.north + found.south + found.east
--- Whether the three warehouses together hold enough units for the line.
pub can_ship(found: Availability) -> Bool = held(found) >= found.wanted
--- Whether every line of the order can ship.
pub ships_whole(found: List[Availability]) -> Bool = found.filter(keep: fn(line) -> not can_ship(line)).is_empty
--- One line of the report: the SKU, what each warehouse holds, and whether it ships.
pub report_line(found: Availability) -> Text
=
let counts = "{found.north} + {found.south} + {found.east} = {held(found)}"
let verdict = if can_ship(found) then "ships" else "short by {found.wanted - held(found)}"
"{found.sku}: {found.wanted} wanted, {counts} on hand, {verdict}"
--- What a person reads when a warehouse did not answer.
pub reason(failure: StockError) -> Text
=
when failure
is Offline(site) -> "the {site} warehouse did not answer; check again later"
--- The stock of the north warehouse.
pub north_stock() -> Map[Text, Int] = empty_map().with(key: "LAMP-01", value: 4).with(key: "DESK-02", value: 1)
--- The stock of the south warehouse.
pub south_stock() -> Map[Text, Int] = empty_map().with(key: "LAMP-01", value: 2).with(key: "RUG-07", value: 3)
--- The stock of the east warehouse.
pub east_stock() -> Map[Text, Int] = empty_map().with(key: "DESK-02", value: 1).with(key: "RUG-07", value: 5)
--- Prints the report of one order, or why it could not be checked.
pub print_report(order: Text, outcome: Result[List[Availability], StockError]) -> Unit
uses @console: Console[print]
=
@console.print("Order {order}")
when outcome
is Ok(found) ->
for line in found
@console.print(" {report_line(line)}")
let whole = if ships_whole(found) then "the whole order ships" else "the order waits for stock"
@console.print(" {whole}")
is Err(failure) -> @console.print(" {reason(failure)}")
--- Checks two orders against the three warehouses, then the first again while one is offline.
pub main() -> Unit
uses @console: Console[print]
=
let lamps = [OrderLine(sku: "LAMP-01", quantity: 5), OrderLine(sku: "DESK-02", quantity: 2)]
let rugs = [OrderLine(sku: "RUG-07", quantity: 6), OrderLine(sku: "LAMP-01", quantity: 9)]
let first = attempt check_order(lamps) with @north = shelves(north_stock()), @south = shelves(south_stock()), @east = shelves(east_stock())
print_report("1042", outcome: first)
let second = attempt check_order(rugs) with @north = shelves(north_stock()), @south = shelves(south_stock()), @east = shelves(east_stock())
print_report("1043", outcome: second)
let retry = attempt check_order(lamps) with @north = shelves(north_stock()), @south = shelves(south_stock()), @east = offline("east")
print_report("1042, again", outcome: retry)
example "each warehouse's count goes into its own field"
given @north = shelves(north_stock())
given @south = shelves(south_stock())
given @east = shelves(east_stock())
do availability(OrderLine(sku: "LAMP-01", quantity: 5))
expect result == Availability(sku: "LAMP-01", wanted: 5, north: 4, south: 2, east: 0)
example "the lines come back in the order of the order"
given @north = shelves(north_stock())
given @south = shelves(south_stock())
given @east = shelves(east_stock())
do check_order([OrderLine(sku: "RUG-07", quantity: 1), OrderLine(sku: "DESK-02", quantity: 1)])
expect result.len == 2
expect result.first() == Some(Availability(sku: "RUG-07", wanted: 1, north: 0, south: 3, east: 5))
example "an empty order asks no warehouse"
given @north = shelves(north_stock())
given @south = shelves(south_stock())
given @east = shelves(east_stock())
do check_order([])
expect result == []
expect not performed @north.on_hand
example "a warehouse that does not answer fails the line"
given @north = shelves(north_stock())
given @south = shelves(south_stock())
given @east = offline("east")
do availability(OrderLine(sku: "LAMP-01", quantity: 5))
expect fails Offline
example "the warehouses before the one that fails are still asked"
given @north = shelves(north_stock())
given @south = offline("south")
given @east = shelves(east_stock())
do availability(OrderLine(sku: "LAMP-01", quantity: 5))
expect fails Offline
expect performed @north.on_hand
example "one line that cannot be checked fails the whole order"
given @north = shelves(north_stock())
given @south = offline("south")
given @east = shelves(east_stock())
do check_order([OrderLine(sku: "LAMP-01", quantity: 5), OrderLine(sku: "DESK-02", quantity: 2)])
expect fails Offline
example "a line short of stock says by how much"
do report_line(Availability(sku: "LAMP-01", wanted: 9, north: 4, south: 2, east: 0))
expect result == "LAMP-01: 9 wanted, 4 + 2 + 0 = 6 on hand, short by 3"
example "an order ships whole only when every line can ship"
do ships_whole([Availability(sku: "LAMP-01", wanted: 5, north: 4, south: 2, east: 0), Availability(sku: "RUG-07", wanted: 9, north: 0, south: 3, east: 5)])
expect not result
example "an empty order ships whole"
do ships_whole([])
expect result
example "the reason names the warehouse"
do reason(Offline("east"))
expect result == "the east warehouse did not answer; check again later"Next:15.5 Testing it