ractor-sharing 0.2.0 → 0.3.0

data/docs/lockvar.md

@@ -1,6 +1,7 @@
 # Ractor::LockVar
 
-**One** variable that Ractors can share. It holds one shareable object; any
+**One** variable that Ractors can share. It holds one shareable object (made
+shareable on the way in); any
 Ractor can read it, and any Ractor can replace what is in it, one at a time.
 Several variables that have to change together are `Ractor::TVar`'s job, and a
 whole hash of them is [`Ractor::LockHash`](lockhash.md)'s.
@@ -8,16 +9,16 @@ whole hash of them is [`Ractor::LockHash`](lockhash.md)'s.
 ```ruby
 require "ractor/lockvar"
 
-counter = Ractor::LockVar.new(0)
+roster = Ractor::LockVar.new([])
 
-rs = 4.times.map do
-  Ractor.new(counter) do |c|
-    1000.times { c.update {|n| n + 1 } }
+rs = %w[ann ben cho dee].map do |name|
+  Ractor.new(roster, name) do |r, me|
+    r.update {|team| team + [me] }   # read-modify-write, one at a time
   end
 end
 rs.each(&:join)
 
-p counter.value #=> 4000
+p roster.value.sort #=> ["ann", "ben", "cho", "dee"]
 ```
 
 ## API
@@ -39,22 +40,24 @@ A variable, not a lock: there is no lock, unlock, or owner query. `value` and
 `update` are the whole of it, and `increment` is there because a counter is what
 a shared variable most often is.
 
-### The value must be shareable
+### The value is made shareable
 
-A LockVar holds one **shareable** object, and so does everything you store into
-it. Anything else raises `ArgumentError`:
+A LockVar holds one **shareable** object, and the store sees to it: a value
+that already is shareable passes through untouched, anything else is
+deep-frozen **in place**. No `.freeze` and no `Ractor.make_shareable` of your
+own, and the object you handed
+over comes out frozen -- hand over things you are done mutating (storing
+`STDOUT` would freeze `STDOUT`). A value that cannot be made shareable raises
+`Ractor::IsolationError`.
 
 ```ruby
-Ractor::LockVar.new({})            # => ArgumentError: only shareable object are allowed
-lv.update { [1, 2] }               # => ArgumentError
-lv.update { [1, 2].freeze }        # fine
-lv.update { {a: 1}.freeze }        # fine
+lv = Ractor::LockVar.new({})       # fine; the hash is frozen in place
+lv.update { [1, 2] }               # fine; frozen on the way in
 ```
 
-That is what makes a LockVar safe to hand to any Ractor: it is frozen and
-shareable itself, and the value inside it is too, so nothing reachable through it
-can be mutated behind the lock's back. It also means an update replaces the value
-rather than modifying it: `lv.update { it.merge(k => v).freeze }`, not
+Shareable means nothing reachable through the LockVar can be mutated behind
+the lock's back. It also means an update replaces the value rather than
+modifying it: `lv.update { it.merge(k => v) }`, not
 `lv.value[k] = v`.
 
 A rejected value leaves the variable as it was.
@@ -79,7 +82,7 @@ return it clears the variable: `lv.update {|v| puts v }` stores `nil`.
 
 `increment` is there because adding to a number is the most common update of all;
 it is the block form with the block written for you, and behaves the same way in
-every respect, including refusing to store a sum that is not shareable.
+every respect, including making the sum shareable on the way in.
 
 ## Read-modify-write belongs inside the block
 
@@ -95,7 +98,7 @@ v = lv.value
 lv.update { v + 1 }
 
 h = lv.value
-lv.update { h.merge(key => 1).freeze }
+lv.update { h.merge(key => 1) }
 ```
 
 ```ruby
@@ -103,8 +106,8 @@ lv.update { h.merge(key => 1).freeze }
 lv = Ractor::LockVar.new(0)
 lv.update { it + 1 }
 
-h = Ractor::LockVar.new({}.freeze)
-h.update { it.merge(key: 1).freeze }
+h = Ractor::LockVar.new({})
+h.update { it.merge(key: 1) }
 ```
 
 Four Ractors incrementing 500 times each:
@@ -218,7 +221,7 @@ final store. If your load is read heavy and shared, that guarantee is expensive.
 ### Updating
 
 ```ruby
-v.update {|rec| { status: rec[:status], seq: rec[:seq] + 1 }.freeze }
+v.update {|rec| { status: rec[:status], seq: rec[:seq] + 1 } }
 ```
 
 | Ractors | shared `LockVar#update` (ns) | shared `TVar` `atomically` (ns) | own `LockVar#update` (ns) | own `TVar` `atomically` (ns) |
@@ -229,7 +232,7 @@ v.update {|rec| { status: rec[:status], seq: rec[:seq] + 1 }.freeze }
 | 8 | 1017 | 462 | 56 | 99 |
 | 16 | 1102 | 509 | 50 | 108 |
 
-**Fought over, neither scales and `TVar` stays about 2× ahead**, because the
+**Under contention, neither scales and `TVar` stays about 2× ahead**, because the
 loser of a race retries a short block where `LockVar` parks the thread and wakes
 it through a port, which costs more than the block did; and a transaction that
 keeps losing backs off, a 100 ns spin per consecutive loss, before running

data/docs/tvar.md

@@ -3,7 +3,7 @@
 A variable Ractors can share, and the one to reach for first.
 [Software transactional memory](https://en.wikipedia.org/wiki/Software_transactional_memory)
 for Ractors and Threads: read and write as many TVars as you like inside
-`Ractor.atomically`, and everything that block changes takes effect together or
+`Ractor.atomically`, and all changes made by that block take effect together or
 not at all.
 
 A TVar holds any shareable object, not only a number:
@@ -11,20 +11,20 @@ A TVar holds any shareable object, not only a number:
 ```ruby
 require "ractor/tvar"
 
-config  = Ractor::TVar.new({ mode: :idle }.freeze)
-version = Ractor::TVar.new("v1".freeze)
+config  = Ractor::TVar.new(mode: :idle)
+version = Ractor::TVar.new("v1")
 
 Ractor.atomically do
-  config.value  = config.value.merge(mode: :running).freeze
-  version.value = "v2".freeze             # nobody sees v1 running, or v2 idle
+  config.value  = config.value.merge(mode: :running)
+  version.value = "v2"                    # nobody sees v1 running, or v2 idle
 end
 ```
 
 One variable is a transaction with one variable in it, and reads the same way:
 
 ```ruby
-seen = Ractor::TVar.new([].freeze)
-Ractor.atomically { seen.value = (seen.value + [:x]).freeze }
+seen = Ractor::TVar.new([])
+Ractor.atomically { seen.value = seen.value + [:x] }
 ```
 
 Where two variables have to agree, that is the whole point:
@@ -55,7 +55,7 @@ tv.value #=> 40000
 ## API
 
 ```ruby
-tv = Ractor::TVar.new(initial = nil)   # any shareable object
+tv = Ractor::TVar.new(initial = nil)   # anything; made shareable on the way in
 
 Ractor.atomically { ... }   # everything inside is one transaction
 
@@ -64,7 +64,13 @@ tv.value = v         # write; only inside a transaction
 tv.increment(n = 1)  # add in one step; inside or out, for values that answer to +
 ```
 
-Values must be shareable; `ArgumentError` otherwise.
+Values are **made shareable on the way in**: one that already is passes
+through untouched, anything else is deep-frozen **in place** -- storing a value
+here means sharing it, so neither `.freeze` nor `Ractor.make_shareable` is
+yours to write, and the object you
+handed over comes out frozen. Hand over things you are done mutating: storing
+`STDOUT` would freeze `STDOUT`. A value that cannot be made shareable raises
+`Ractor::IsolationError`.
 
 **A write needs a transaction.** `tv.value = v` on its own raises
 `Ractor::TransactionError`, "can not set without transaction". There is no
@@ -90,6 +96,43 @@ transaction otherwise.
 * State you do not want to freeze, a mutable object updated in place:
   [`Ractor::ActorHash`](actor_hash.md) or [`Ractor::ActiveObject`](active_object.md).
 
+## A shareable class with TVar slots
+
+A TVar is frozen and shareable; only the value inside it moves. So a class
+whose mutable state lives in TVars can make its own instances shareable, and a
+shareable instance crosses to any Ractor **by reference**, methods included --
+or simply lives in a constant that every Ractor uses:
+
+```ruby
+class Account
+  def initialize(balance)
+    @balance = Ractor::TVar.new(balance)
+    @history = Ractor::TVar.new([])
+    Ractor.make_shareable(self)   # fails loudly if an ivar could not travel
+  end
+
+  def deposit(amount)
+    Ractor.atomically do
+      @balance.value += amount
+      @history.value += [amount]
+    end
+  end
+
+  def balance = @balance.value
+end
+
+acc = Account.new(100)
+Ractor.new(acc) { |a| a.deposit(25) }.join
+acc.balance #=> 125
+```
+
+The methods run in whichever Ractor calls them -- there is no owner and no
+message round trip -- and the transactions they declare are the whole
+synchronization. This is the pattern to exhaust before reaching for
+[`Ractor::ActiveObject`](active_object.md): an active object earns its Ractor
+and its ~2.5 µs per call when the state genuinely cannot be frozen, not when a
+few slots of it change.
+
 ## Scaling
 
 **Reads outside a transaction cost nothing and scale.** Sixteen Ractors reading
@@ -111,7 +154,7 @@ than one does (both about 80 ns, inside the noise), because the commit is then
 all of the work. Transaction
 bodies do run in parallel; it is the commit that does not.
 
-**Fought over, retrying beats waiting.** Sixteen Ractors updating the *same*
+**Under contention, retrying beats waiting.** Sixteen Ractors updating the *same*
 variable cost about 509 ns per completed update against 1102 for a LockVar,
 because the loser of a race runs a short block again rather than parking a
 thread and waking it. A transaction that loses twice in a row also **backs

data/examples/01_bank_transfer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+#
+# The classic STM example, because nothing shows "all or none" better: money
+# moves between accounts, and no observer ever sees it in neither.
+#
+#   ruby -Ilib examples/01_bank_transfer.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+accounts = { alice: Ractor::TVar.new(300), bob: Ractor::TVar.new(300), carol: Ractor::TVar.new(300) }
+Ractor.make_shareable(accounts)
+TOTAL = 900
+
+# Three tellers shuffle money along a ring. Each transfer is one transaction:
+# both balances change together or not at all.
+tellers = accounts.keys.zip(accounts.keys.rotate).map do |from, to|
+  Ractor.new(accounts[from], accounts[to]) do |a, b|
+    500.times do
+      Ractor.atomically do
+        amount = a.value >= 5 ? 5 : a.value
+        a.value -= amount
+        b.value += amount
+      end
+    end
+    :ok
+  end
+end
+
+# The auditor reads all three inside one transaction, so it sees a consistent
+# snapshot: the total must be exact in every single read, mid-shuffle included.
+auditor = Ractor.new(accounts) do |acc|
+  1_000.times.count do
+    total = Ractor.atomically { acc.each_value.sum(&:value) }
+    abort "audit failed: saw #{total}" unless total == TOTAL
+    true
+  end
+end
+
+audits = auditor.value
+tellers.each(&:join)
+final = accounts.transform_values(&:value)
+abort "money leaked: #{final}" unless final.values.sum == TOTAL
+puts "ok: #{audits} audits mid-shuffle, every one saw exactly #{TOTAL}; final #{final}"

data/examples/02_seat_booking.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+#
+# Booking two adjacent seats. With one lock per seat this is the textbook
+# deadlock: two buyers taking overlapping pairs in opposite order wait on each
+# other forever. With TVars there is no lock order to get wrong: the loser of a
+# race is rolled back and simply looks again.
+#
+#   ruby -Ilib examples/02_seat_booking.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+SEATS = Ractor.make_shareable(Array.new(10) { Ractor::TVar.new(:free) })
+
+buyers = %i[ann ben cho dee].map do |name|
+  Ractor.new(SEATS, name) do |seats, me|
+    # One transaction: find the first adjacent free pair and take both.
+    # Everybody scans in a different direction on purpose -- the opposite-order
+    # access that would deadlock locks is just contention here.
+    Ractor.atomically do
+      range = (0...seats.size - 1)
+      range = range.to_a.reverse if %i[ben dee].include?(me)
+      i = range.find { |j| seats[j].value == :free && seats[j + 1].value == :free }
+      next nil if i.nil?
+
+      seats[i].value = me
+      seats[i + 1].value = me
+      i
+    end
+  end
+end
+
+got = buyers.map(&:value)
+taken = SEATS.map(&:value)
+abort "somebody got no pair: #{taken}" if got.any?(&:nil?)
+got.each do |i|
+  a, b = taken[i], taken[i + 1]
+  abort "pair at #{i} torn: #{taken}" unless a == b && a != :free
+end
+abort "double booking: #{taken}" unless taken.tally.values.all? { |n| n <= 2 }
+puts "ok: #{taken.each_slice(2).map { |s| s.map { |v| v == :free ? '__' : v[0, 2] }.join }.join(' | ')}"

data/examples/03_feature_flags.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+#
+# A read-mostly config: flags read on every request by every worker, flipped
+# once in a blue moon. This is where TVar shines -- a read outside a
+# transaction takes no lock at all, so sixteen readers of one shared TVar pay
+# the same as sixteen readers of their own (about 9 ns on our bench machine).
+#
+#   ruby -Ilib examples/03_feature_flags.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+FLAGS = Ractor::TVar.new({ new_ui: false, beta_search: false }.freeze)
+
+workers = 4.times.map do
+  Ractor.new(FLAGS) do |flags|
+    reads = 0
+    reads += 1 until flags.value[:new_ui]      # serve requests on the old UI
+    reads += 1 until flags.value[:beta_search] # then wait for the next rollout
+    reads
+  end
+end
+
+sleep 0.05  # let them serve a while on the old flags
+Ractor.atomically { FLAGS.value = FLAGS.value.merge(new_ui: true).freeze }
+sleep 0.05
+Ractor.atomically { FLAGS.value = FLAGS.value.merge(beta_search: true).freeze }
+
+reads = workers.sum(&:value)
+abort "a worker never saw the rollout" if reads.zero?
+puts "ok: 4 workers made #{reads} flag reads across two rollouts, no locks anywhere"

data/examples/04_progress.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+#
+# A shared progress counter: workers add what they finished, the main Ractor
+# reads it whenever it feels like drawing the bar. increment is atomic, value
+# is just a peek -- nobody coordinates with anybody.
+#
+#   ruby -Ilib examples/04_progress.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+TOTAL = 4 * 200
+done = Ractor::LockVar.new(0)
+
+workers = 4.times.map do
+  Ractor.new(done) do |d|
+    200.times do
+      # pretend to move some bytes
+      d.increment
+    end
+    :ok
+  end
+end
+
+bars = []
+until (n = done.value) == TOTAL
+  bars << "[#{'#' * (n * 20 / TOTAL)}#{'.' * (20 - n * 20 / TOTAL)}]"
+  # the reader sleeps; the writers never wait for it
+  sleep 0.001
+end
+workers.each(&:join)
+
+abort "lost updates: #{done.value}" unless done.value == TOTAL
+puts "ok: #{bars.size} redraw(s) while counting to #{TOTAL}, e.g. #{bars[bars.size / 2]}"

data/examples/05_exactly_once.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+#
+# Why LockVar exists when TVar is usually faster: a TVar transaction that loses
+# a race RUNS ITS BLOCK AGAIN, so a side effect inside it repeats. A LockVar
+# update waits its turn and runs the block exactly once. Here both race to be
+# "the one who announces", and we count how often each block actually ran.
+#
+#   ruby -Ilib examples/05_exactly_once.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+N = 8
+tv = Ractor::TVar.new(0)
+lv = Ractor::LockVar.new(0)
+
+# Each Ractor counts its own block executions in plain locals. (Not in another
+# LockVar: touching one lock from inside another is refused, by design.)
+rs = N.times.map do
+  Ractor.new(tv, lv) do |t, l|
+    tv_runs = lv_runs = 0
+    250.times do
+      Ractor.atomically { tv_runs += 1; t.value += 1 }  # side effect in a transaction: may rerun
+      l.update { |v| lv_runs += 1; v + 1 }              # side effect under the lock: runs once
+    end
+    [tv_runs, lv_runs]
+  end
+end
+counts = rs.map(&:value)
+tv_runs = counts.sum(&:first)
+lv_runs = counts.sum(&:last)
+
+updates = N * 250
+abort "TVar lost updates" unless tv.value == updates
+abort "LockVar lost updates" unless lv.value == updates
+abort "a LockVar block ran #{lv_runs} times for #{updates} updates" unless lv_runs == updates
+extra = tv_runs - updates
+puts "ok: #{updates} updates each. LockVar blocks ran exactly #{lv_runs}; " \
+     "TVar blocks ran #{tv_runs} (#{extra} rerun#{'s' if extra != 1} -- keep side effects out of transactions)"

data/examples/06_metrics_board.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+#
+# Request metrics: a per-endpoint record AND a global total that must agree.
+# Two keys changing together is exactly what LockHash's synchronize gives you,
+# and to_h is a snapshot taken under the same lock -- so every report balances,
+# even taken mid-flight from another Ractor.
+#
+#   ruby -Ilib examples/06_metrics_board.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+board = Ractor::LockHash.new(total: 0)
+ENDPOINTS = %w[/home /search /cart].freeze
+
+workers = 4.times.map do
+  Ractor.new(board) do |b|
+    300.times do |i|
+      ep = ENDPOINTS[i % ENDPOINTS.size]
+      ms = 5 + i % 20
+      b.synchronize do |h|
+        rec = h[ep] || { count: 0, total_ms: 0, worst_ms: 0 }.freeze
+        h[ep] = { count: rec[:count] + 1, total_ms: rec[:total_ms] + ms,
+                  worst_ms: [rec[:worst_ms], ms].max }.freeze
+        h[:total] = h[:total] + 1   # the cross-key part: total moves with the record
+      end
+    end
+    :ok
+  end
+end
+
+# The reporter never catches the books unbalanced: per-endpoint counts must sum
+# to :total in every snapshot, because both changed under one synchronize.
+reporter = Ractor.new(board) do |b|
+  200.times.count do
+    snap = b.to_h
+    sum = snap.reject { |k, _| k == :total }.values.sum { |r| r[:count] }
+    abort "unbalanced snapshot: #{sum} recorded but total says #{snap[:total]}" unless sum == snap[:total]
+    true
+  end
+end
+
+snapshots = reporter.value
+workers.each(&:join)
+final = board.to_h
+abort "final books off" unless final[:total] == 1200
+puts "ok: #{snapshots} mid-flight snapshots all balanced; " +
+     final.reject { |k, _| k == :total }.map { |ep, r| "#{ep} avg #{r[:total_ms] / r[:count]}ms" }.join(", ")

data/examples/07_word_count.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+#
+# Map-reduce with a mutable reduce side: workers count their chunk locally,
+# then send the merge to the ActorHash as work. The tallies live unfrozen in
+# the owner Ractor and are bumped in place -- no freezing a Hash per update,
+# which is what the lock family would have demanded.
+#
+#   ruby -Ilib examples/07_word_count.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+TEXT = ("the quick brown fox jumps over the lazy dog " * 50 +
+        "sator arepo tenet opera rotas " * 30).freeze
+CHUNKS = TEXT.scan(/(?:\S+\s*){1,40}/).map(&:freeze).freeze
+
+tally = Ractor::ActorHash.new
+
+workers = 4.times.map do |i|
+  Ractor.new(tally, CHUNKS, i) do |t, chunks, offset|
+    chunks.each_with_index do |chunk, j|
+      next unless j % 4 == offset
+
+      counts = chunk.split.tally
+      # Fire and forget: the block runs on the owner, against the real hash.
+      t.async_call(counts) { |h, c| c.each { |w, n| h[w] = (h[w] || 0) + n } }
+    end
+    t[:the]   # one sync read = my merges have all landed (per-sender FIFO)
+    :ok
+  end
+end
+workers.each(&:join)
+
+expected = TEXT.split.tally
+got = tally.to_h
+abort "tallies differ" unless got == expected
+puts "ok: #{got.values.sum} words, #{got.size} distinct; 'the' => #{got['the']}, 'tenet' => #{got['tenet']}"

data/examples/08_lru_cache.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+#
+# An LRU cache is a Hash plus an eviction order, mutated on every hit -- state
+# you have no intention of freezing. Give it a Ractor of its own: callers see
+# ordinary methods, the owner runs them one at a time, and the object graph
+# never leaves home.
+#
+#   ruby -Ilib examples/08_lru_cache.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+class LRUCache < Ractor::ActiveObject
+  def initialize(capacity)
+    @capacity = capacity
+    @h = {}          # key => value
+    @order = []      # least recently used first
+    @hits = @misses = 0
+  end
+
+  sync def get(key)
+    if @h.key?(key)
+      @hits += 1
+      @order.delete(key)
+      @order << key
+      @h[key]
+    else
+      @misses += 1
+      nil
+    end
+  end
+
+  sync def put(key, value)
+    @order.delete(key)
+    @order << key
+    @h[key] = value
+    @h.delete(@order.shift) while @h.size > @capacity
+    value
+  end
+
+  sync def stats = { size: @h.size, hits: @hits, misses: @misses }.freeze
+end
+
+cache = LRUCache.new(8)
+
+rs = 4.times.map do
+  Ractor.new(cache) do |c|
+    200.times do |i|
+      key = "item-#{(i * 7) % 20}"
+      c.get(key) or c.put(key, "value of #{key}")
+    end
+    :ok
+  end
+end
+rs.each(&:join)
+
+s = cache.stats
+abort "capacity breached: #{s}" if s[:size] > 8
+abort "nothing happened: #{s}" unless s[:hits] + s[:misses] == 800
+puts "ok: #{s[:size]}/8 slots, #{s[:hits]} hits, #{s[:misses]} misses across 4 Ractors"

data/examples/09_audit_log.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+#
+# A fire-and-forget audit log: workers must not wait for the log to be written,
+# so the method is async -- the call costs a send, not a round trip (about 5x
+# cheaper on our bench machine). Reads are sync, because the answer is the point.
+#
+#   ruby -Ilib examples/09_audit_log.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+class AuditLog < Ractor::ActiveObject
+  def initialize = @lines = []
+  async def record(who, what) = @lines << "#{@lines.size}: #{who} #{what}"
+  sync def size = @lines.size
+  sync def tail(n) = @lines.last(n).dup
+end
+
+log = AuditLog.new
+
+workers = %w[ann ben cho dee].map do |name|
+  Ractor.new(log, name) do |l, me|
+    150.times { |i| l.record(me, "step #{i}") }  # never waits
+    l.size                                       # one sync call = my records landed
+    :ok
+  end
+end
+workers.each(&:join)
+
+abort "records lost: #{log.size}" unless log.size == 600
+abort "sequence torn" unless log.tail(600).each_with_index.all? { |line, i| line.start_with?("#{i}:") }
+puts "ok: 600 records, strictly ordered by the owner; tail: #{log.tail(1).first.inspect}"

data/examples/10_price_quotes.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+#
+# Fan out, then gather: ask several slow services for quotes as futures, do
+# other work, and only then sit down to wait. Each future is a ticket for an
+# answer that is being computed while you are not looking.
+#
+#   ruby -Ilib examples/10_price_quotes.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+class PriceService < Ractor::ActiveObject
+  def initialize(vendor, base)
+    @vendor = vendor
+    @base = base
+  end
+
+  future def quote(item)
+    sleep 0.05  # the network, allegedly
+    { vendor: @vendor, item: item, price: @base + item.sum % 17 }.freeze
+  end
+end
+
+services = { "acme" => 100, "moma" => 90, "zenith" => 95 }.map { |v, base| PriceService.new(v, base) }
+
+t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+futures = services.map { |s| s.quote("garden gnome") }   # all three are working now
+elapsed_to_fire = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+quotes = futures.map(&:value)                            # now we wait
+elapsed_total = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+
+best = quotes.min_by { |q| q[:price] }
+abort "missing quotes: #{quotes}" unless quotes.size == 3 && quotes.all? { |q| q[:price].positive? }
+abort "firing the futures blocked" if elapsed_to_fire > 0.04
+puts format("ok: 3 quotes in %.0f ms (three 50 ms sleeps, overlapped); best: %s at %d",
+            elapsed_total * 1000, best[:vendor], best[:price])