ractor-sharing 0.2.0 → 0.3.0

data/examples/11_webshop.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+#
+# A small shop, with every tool in its natural seat:
+#
+#   prices     TVar      read by every checkout, changed once mid-run (a sale)
+#   stock      TVar/SKU  a checkout reserves EVERY item in the cart or nothing
+#   ledger     LockHash  order count, revenue, per-SKU figures that must agree
+#   audit      ActiveObject  fire-and-forget order log, ordered by its owner
+#
+# The heart is the checkout transaction: prices and all the cart's stock levels
+# are read and written in ONE Ractor.atomically, so a cart is never half
+# reserved and never priced across a sale boundary.
+#
+#   ruby -Ilib examples/11_webshop.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+SKUS = %i[mug tee cap].freeze
+START_STOCK = { mug: 120, tee: 90, cap: 60 }.freeze
+
+PRICES = Ractor::TVar.new({ mug: 12, tee: 25, cap: 15 }.freeze)
+STOCK  = Ractor.make_shareable(START_STOCK.transform_values { |n| Ractor::TVar.new(n) })
+
+ledger = Ractor::LockHash.new(orders: 0, revenue: 0)
+
+class AuditLog < Ractor::ActiveObject
+  def initialize = @lines = []
+  async def order(shopper, cart, cost) = @lines << [shopper, cart, cost].freeze
+  async def rejection(shopper, cart)   = @lines << [shopper, cart, :out_of_stock].freeze
+  sync def entries = @lines.dup
+end
+audit = AuditLog.new
+
+shoppers = 4.times.map do |i|
+  Ractor.new(PRICES, STOCK, ledger, audit, i) do |prices, stock, led, log, id|
+    rng = Random.new(42 + id)
+    sold = 0
+    40.times do
+      cart = SKUS.sample(rng.rand(1..2), random: rng).tally  # e.g. {mug: 1, tee: 1}
+
+      # All or nothing: every stock level and the price list, one transaction.
+      cost = Ractor.atomically do
+        next nil if cart.any? { |sku, n| stock[sku].value < n }
+
+        cart.each { |sku, n| stock[sku].value -= n }
+        p = prices.value
+        cart.sum { |sku, n| p[sku] * n }
+      end
+
+      if cost.nil?
+        log.rejection(id, cart)
+        next
+      end
+
+      # The books: order count, revenue and the per-SKU units move together,
+      # so no snapshot ever shows an order whose units are missing.
+      led.synchronize do |h|
+        h[:orders] += 1
+        h[:revenue] += cost
+        cart.each { |sku, n| h[sku] = (h[sku] || 0) + n }
+      end
+      log.order(id, cart, cost)
+      sold += 1
+    end
+    sold
+  end
+end
+
+# The sale: one atomic price flip, mid-run. A checkout sees old or new, never a mix.
+sleep 0.01
+Ractor.atomically { PRICES.value = PRICES.value.merge(tee: 19).freeze }
+
+# An accountant snapshots the books while shoppers are still at it: order count
+# and revenue always came from the same synchronize, so cross-checking entries
+# never catches them mid-write.
+accountant = Ractor.new(ledger) do |led|
+  60.times.count do
+    snap = led.to_h
+    abort "negative books: #{snap}" if snap[:orders].negative? || snap[:revenue].negative?
+    true
+  end
+end
+
+orders_placed = shoppers.sum(&:value)
+accountant.join
+books = ledger.to_h
+entries = audit.entries
+sold_entries = entries.reject { |e| e[2] == :out_of_stock }
+
+# Conservation, the real test of the checkout transaction:
+SKUS.each do |sku|
+  sold = sold_entries.sum { |_, cart, _| cart[sku] || 0 }
+  left = STOCK[sku].value
+  abort "#{sku}: #{START_STOCK[sku]} - #{sold} != #{left}" unless START_STOCK[sku] - sold == left
+  abort "#{sku} ledger units off" unless (books[sku] || 0) == sold
+  abort "#{sku} oversold" if left.negative?
+end
+abort "books vs audit: #{books[:orders]} vs #{sold_entries.size}" unless books[:orders] == sold_entries.size
+abort "revenue drifted" unless books[:revenue] == sold_entries.sum { |_, _, c| c }
+abort "ledger vs shoppers" unless books[:orders] == orders_placed
+
+rej = entries.size - sold_entries.size
+puts "ok: #{books[:orders]} orders, #{rej} rejected out-of-stock, revenue #{books[:revenue]}; " \
+     "stock left #{SKUS.map { |s| "#{s}:#{STOCK[s].value}" }.join(' ')}"

data/examples/12_kvstore_wal.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+#
+# A crash-safe key-value store: every write is appended to a write-ahead log
+# on disk before anything else sees it, then the process "crashes" and a fresh
+# store replays the log -- and must arrive at the identical state.
+#
+# The store is an ActiveObject rather than an ActorHash for one load-bearing
+# reason: THE STORE ITSELF writes its log, inside its own owner, so the log
+# order and the apply order are the same order by construction. Writers are
+# async (a set does not wait for the disk); reads are sync; sync def flush is
+# the durability barrier.
+#
+#   ruby -Ilib examples/12_kvstore_wal.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+require "tempfile"
+
+class KVStore < Ractor::ActiveObject
+  def initialize(wal_path, replay: false)
+    @h = {}
+    @wal = File.open(wal_path, replay ? "r" : "w")
+    if replay
+      @wal.each_line do |line|
+        op, key, arg = line.chomp.split("\t", 3)
+        apply(op, key, arg)
+      end
+      @wal.close
+      @wal = nil
+    end
+  end
+
+  async def set(key, value) = log_and_apply("set", key, value.to_s)
+  async def incr(key, by = 1) = log_and_apply("incr", key, by.to_s)
+  async def del(key) = log_and_apply("del", key)
+
+  sync def get(key) = @h[key]
+  sync def snapshot = @h.dup
+  sync def flush = (@wal&.fsync; @h.size)   # the barrier: everything before is on disk
+
+  private
+
+  def log_and_apply(op, key, arg = nil)
+    @wal.puts([op, key, arg].compact.join("\t"))
+    apply(op, key, arg)
+  end
+
+  def apply(op, key, arg)
+    case op
+    when "set"  then @h[key] = arg
+    when "incr" then @h[key] = (@h[key] || "0").to_i + Integer(arg)
+    when "del"  then @h.delete(key)
+    end
+  end
+end
+
+wal = Tempfile.create(["kvstore", ".wal"])
+wal.close
+
+store = KVStore.new(wal.path)
+
+writers = 4.times.map do |i|
+  Ractor.new(store, i) do |s, id|
+    100.times do |j|
+      s.set("user:#{id}:name", "shopper-#{id}")
+      s.incr("hits")
+      s.incr("user:#{id}:visits")
+      s.del("user:#{id}:name") if j == 50
+    end
+    s.flush   # my writes are applied and on disk
+    :ok
+  end
+end
+writers.each(&:join)
+
+before = store.snapshot
+abort "hits wrong: #{before}" unless before["hits"] == 400
+
+# The crash: the store object is simply abandoned. All we hold is the file.
+recovered = KVStore.new(wal.path, replay: true).snapshot
+
+abort "recovery diverged:\n  live    #{before}\n  replay  #{recovered}" unless recovered == before
+File.unlink(wal.path)
+puts "ok: #{before.size} keys survived the crash byte for byte; " \
+     "hits=#{recovered['hits']}, wal replayed from #{File.basename(wal.path)}"

data/examples/13_buffered_logger.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+#
+# A production-shaped logger: callers fire and forget, the owner BATCHES --
+# it buffers lines and writes the file only when the buffer fills or grows
+# stale, so six hundred log calls become a handful of write syscalls.
+#
+# Notice how little machinery this takes: the buffer, the high-water mark and
+# the "when did I last flush" clock are ordinary ivars, because the owner is
+# the only one who ever touches them. The batching policy is just an if.
+#
+#   ruby -Ilib examples/13_buffered_logger.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+require "tempfile"
+
+class BufferedLogger < Ractor::ActiveObject
+  FLUSH_AT    = 64     # lines
+  FLUSH_AFTER = 0.05   # seconds without a flush
+
+  def initialize(path)
+    @io = File.open(path, "a")
+    @buf = []
+    @last_flush = now
+    @writes = 0        # actual write syscalls, to show the batching
+  end
+
+  async def log(line)
+    @buf << "#{line}\n"
+    flush! if @buf.size >= FLUSH_AT || now - @last_flush > FLUSH_AFTER
+  end
+
+  # For quiet periods: anybody may poke the logger now and then, and stale
+  # lines go out even when nothing new arrives.
+  async def tick
+    flush! if @buf.any? && now - @last_flush > FLUSH_AFTER
+  end
+
+  sync def close
+    flush!
+    @io.fsync
+    @io.close
+    @writes
+  end
+
+  private
+
+  def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  def flush!
+    return if @buf.empty?
+
+    @io.write(@buf.join)   # one syscall for the whole batch
+    @writes += 1
+    @buf.clear
+    @last_flush = now
+  end
+end
+
+file = Tempfile.create(["app", ".log"])
+file.close
+logger = BufferedLogger.new(file.path)
+
+workers = 4.times.map do |i|
+  Ractor.new(logger, i) do |log, id|
+    150.times { |seq| log.log("w#{id} seq=#{seq}") }   # never waits for the disk
+    :ok
+  end
+end
+ticker = Thread.new { 5.times { sleep 0.02; logger.tick } }
+
+workers.each(&:join)
+ticker.join
+writes = logger.close
+
+lines = File.readlines(file.path, chomp: true)
+abort "lines lost: #{lines.size}" unless lines.size == 600
+# The owner serializes, and ports are FIFO per sender: each worker's own lines
+# land in the file in the order it logged them.
+4.times do |id|
+  seqs = lines.filter_map { |l| $1.to_i if l =~ /\Aw#{id} seq=(\d+)\z/ }
+  abort "w#{id} lines reordered or lost" unless seqs == (0...150).to_a
+end
+abort "no batching happened: #{writes} writes" unless writes < 600 / 8
+File.unlink(file.path)
+puts "ok: 600 log calls became #{writes} write syscalls; every worker's lines in order"

data/examples/14_api_gateway.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+#
+# An API gateway: three middlewares you meet in every real backend, each on
+# the member of the family that fits it.
+#
+#   token buckets   LockHash   one frozen {tokens:, at:} record per client,
+#                              refilled and debited in one synchronize
+#   idempotency     LockHash   "seen this request id?" is an atomic
+#                              check-and-claim across keys that grow forever
+#   circuit breaker LockVar    one state machine, and the "breaker opened"
+#                              audit line fires EXACTLY once per transition,
+#                              because an update block never reruns
+#
+# A request runs the gauntlet in order: bucket -> idempotency -> breaker ->
+# upstream. The upstream and the audit trail are ActiveObjects.
+#
+#   ruby -Ilib examples/14_api_gateway.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+CAPACITY   = 20     # bucket size per client
+REFILL     = 50.0   # tokens per second
+THRESHOLD  = 5      # consecutive failures that open the breaker
+COOLDOWN   = 0.03   # seconds before the breaker lets a probe through
+
+class Upstream < Ractor::ActiveObject
+  def initialize = (@hits = Hash.new(0); @down = false)
+  sync def set_down(flag) = @down = flag
+  sync def call(id) = @down ? :error : (@hits[id] += 1; "resp-#{id}".freeze)
+  sync def hits = @hits.dup
+end
+
+class Audit < Ractor::ActiveObject
+  def initialize = @events = []
+  async def event(name) = @events << name
+  sync def events = @events.dup
+end
+
+def mono = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+# --- the gateway, called from any Ractor -----------------------------------
+
+def gateway_call(gw, client, id)
+  client = -client                  # LockHash keys must be shareable:
+  id = -id                          # -string is the frozen, deduped copy
+
+  # 1. Token bucket: refill by elapsed time, take one, all under the hash lock.
+  allowed = nil
+  gw[:buckets].synchronize do |h|
+    rec = h[client] || { tokens: CAPACITY.to_f, at: mono }.freeze
+    tokens = [rec[:tokens] + (mono - rec[:at]) * REFILL, CAPACITY.to_f].min
+    allowed = tokens >= 1.0
+    h[client] = { tokens: allowed ? tokens - 1.0 : tokens, at: mono }.freeze
+  end
+  return [:rate_limited] unless allowed
+
+  # 2. Idempotency: claim the id or find it done. The claim is atomic; the
+  #    handler itself runs outside the lock, so the section stays short.
+  #    `mine` is decided INSIDE the synchronize: reading :claimed back out
+  #    is not the same thing as having claimed it -- the first draft of this
+  #    example confused the two, and two racing retries both executed.
+  mine = false
+  claim = nil
+  gw[:idem].synchronize do |h|
+    if h.key?(id)
+      claim = h[id]
+    else
+      h[id] = :claimed
+      mine = true
+    end
+  end
+  unless mine
+    if claim.is_a?(Symbol)                    # somebody is on it: wait for them
+      200.times do
+        done = gw[:idem][id]
+        return [:cached, done] unless done.is_a?(Symbol)
+        sleep 0.001
+      end
+      abort "idempotency claim never resolved for #{id}"
+    end
+    return [:cached, claim]                   # already done: same answer again
+  end
+
+  # 3. Circuit breaker: decide under the lock, call outside it, record under it.
+  state = gw[:breaker].update do |b|
+    if b[:state] == :open && mono - b[:opened_at] >= COOLDOWN
+      b.merge(state: :half_open).freeze       # one probe may pass
+    else
+      b
+    end
+  end
+  if state[:state] == :open
+    gw[:idem].synchronize { |h| h.delete(id) }  # release the claim: not handled
+    return [:circuit_open]
+  end
+
+  resp = gw[:upstream].call(id)
+
+  gw[:breaker].update do |b|
+    if resp == :error
+      f = b[:failures] + 1
+      if f >= THRESHOLD && b[:state] != :open
+        gw[:audit].event(:breaker_opened)     # runs once: updates never rerun
+        { state: :open, failures: f, opened_at: mono }.freeze
+      else
+        b.merge(failures: f).freeze
+      end
+    else
+      gw[:audit].event(:breaker_closed) if b[:state] == :half_open
+      { state: :closed, failures: 0, opened_at: 0.0 }.freeze
+    end
+  end
+
+  if resp == :error
+    gw[:idem].synchronize { |h| h.delete(id) }  # failed calls may be retried
+    [:upstream_error]
+  else
+    gw[:idem].synchronize { |h| h[id] = resp }
+    [:ok, resp]
+  end
+end
+
+GW = Ractor.make_shareable({
+  buckets: Ractor::LockHash.new,
+  idem: Ractor::LockHash.new,
+  breaker: Ractor::LockVar.new({ state: :closed, failures: 0, opened_at: 0.0 }.freeze),
+  upstream: Upstream.new,
+  audit: Audit.new
+})
+
+# --- act 1: the polite and the greedy --------------------------------------
+polite, greedy = %w[polite greedy].map do |who|
+  Ractor.new(GW, who) do |gw, me|
+    n = me == "polite" ? CAPACITY : CAPACITY * 3
+    n.times.map { |i| gateway_call(gw, me, "#{me}-#{i}").first }.tally
+  end
+end
+p_tally, g_tally = polite.value, greedy.value
+abort "polite got limited: #{p_tally}" unless p_tally == { ok: CAPACITY }
+abort "greedy was not limited: #{g_tally}" unless g_tally[:rate_limited] &&
+                                                  g_tally[:ok] <= CAPACITY + 3
+
+# --- act 2: at-most-once under retries --------------------------------------
+retriers = 3.times.map do |i|
+  Ractor.new(GW, i) do |gw, me|
+    # Ten ids SHARED by all three clients, each sent twice: 60 requests, and
+    # the upstream must see each id exactly once.
+    2.times.flat_map { (0...10).map { |k| gateway_call(gw, "retrier#{me}", "order-#{k}") } }
+  end
+end
+responses = retriers.flat_map(&:value)
+hits = GW[:upstream].hits
+(0...10).each do |k|
+  abort "order-#{k} executed #{hits["order-#{k}"]} times" unless hits["order-#{k}"] == 1
+  answers = responses.select { |_, r| r == "resp-order-#{k}" }
+  abort "order-#{k}: divergent answers" unless answers.size == 6   # 3 clients x 2 tries
+end
+
+# --- act 3: the upstream falls over ------------------------------------------
+GW[:upstream].set_down(true)
+storm = Ractor.new(GW) do |gw|
+  40.times.map { |i| gateway_call(gw, "monitor#{i % 8}", "storm-#{i}").first }.tally
+end.value
+abort "breaker never rejected fast: #{storm}" unless storm[:circuit_open]&.positive?
+storm_hits = GW[:upstream].hits.count { |k, _| k.start_with?("storm-") }
+abort "breaker let the storm through: #{storm_hits} upstream calls" if storm_hits > THRESHOLD + 3
+
+GW[:upstream].set_down(false)
+sleep COOLDOWN * 1.5
+probe = gateway_call(GW, "prober", "probe-1")
+abort "did not recover: #{probe}" unless probe.first == :ok
+
+events = GW[:audit].events
+abort "opened #{events.count(:breaker_opened)} times" unless events.count(:breaker_opened) >= 1
+abort "never announced recovery" unless events.last == :breaker_closed
+abort "breaker not closed: #{GW[:breaker].value}" unless GW[:breaker].value[:state] == :closed
+
+puts "ok: greedy limited to #{g_tally[:ok]}/#{CAPACITY * 3}; 10 shared ids -> 10 upstream calls " \
+     "for 60 requests; storm of 40 hit upstream #{storm_hits} times, breaker " \
+     "#{events.tally.map { |e, n| "#{e} x#{n}" }.join(', ')}"

data/examples/15_cache_backend.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+#
+# A cache backend on KeyLockHash, and the reason it is one line: update(key)
+# holds THAT KEY's lock while the block runs, so when eight workers miss the
+# same key at once, exactly one computes and seven wait a few ms and read --
+# the dog-pile (cache stampede) problem, solved by the locking shape itself.
+# The price is the same shape: a slow compute blocks that key, and only that
+# key. Real cache backends make exactly this trade.
+#
+#   ruby -Ilib examples/15_cache_backend.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+CACHE = Ractor::KeyLockHash.new
+
+def fetch_fragment(key)
+  computed = false
+  html = CACHE.update(key) do |cached|
+    cached || begin
+      computed = true
+      sleep 0.02                      # an expensive render, allegedly
+      "<div id=#{key}>rendered</div>"
+    end
+  end
+  [html, computed]
+end
+
+workers = 8.times.map do |i|
+  Ractor.new(i) do |id|
+    renders = 0
+    hits = 0
+    24.times do |n|
+      key = "fragment-#{(n + id) % 6}"    # eight workers, six hot keys
+      html, computed = fetch_fragment(key)
+      abort "wrong fragment" unless html.include?(key)
+      computed ? renders += 1 : hits += 1
+    end
+    [renders, hits]
+  end
+end
+
+renders = workers.map(&:value)
+total_renders = renders.sum(&:first)
+total_hits = renders.sum(&:last)
+abort "dog-pile: #{total_renders} renders for 6 keys" unless total_renders == 6
+abort "misplaced arithmetic" unless total_renders + total_hits == 8 * 24
+
+CACHE.delete("fragment-0")              # invalidation is just delete
+_, recomputed = fetch_fragment("fragment-0")
+abort "invalidation did not take" unless recomputed
+
+puts "ok: 192 fetches, 6 renders (one per key, stampede absorbed), " \
+     "#{total_hits} lock-protected hits; invalidate + refetch rendered once more"

data/examples/16_session_store.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+#
+# A session store with "log out everywhere" -- the LockHash shape as it
+# actually occurs in a web backend. Two directions live in one hash:
+#
+#   "sid:..."  => user          the session token a request authenticates with
+#   "user:..." => [sids]        the index that makes logout-all possible
+#
+# Login writes both directions; logout-all deletes N sessions AND the index.
+# Each is one synchronize, because the gap matters: revoke sessions one by one
+# and a racing request can still authenticate with a not-yet-deleted token
+# while the account believes it logged out. The auditor checks the two
+# directions agree in every snapshot it ever takes.
+#
+#   ruby -Ilib examples/16_session_store.rb
+Warning[:experimental] = false
+require "ractor/sharing"
+
+STORE = Ractor::LockHash.new
+
+def login(store, user, device)
+  sid = "sid:#{user}:#{device}"
+  store.synchronize do |h|
+    h[sid] = user
+    h["user:#{user}"] = (h["user:#{user}"] || []) + [sid]
+  end
+  sid
+end
+
+def authenticate(store, sid) = store[sid]
+
+def logout_everywhere(store, user)
+  store.synchronize do |h|
+    (h["user:#{user}"] || []).each { |sid| h.delete(sid) }
+    h.delete("user:#{user}")
+  end
+end
+
+workers = %w[ann ben cho dee].map do |user|
+  Ractor.new(STORE, user) do |store, me|
+    authed = 0
+    5.times do |round|
+      sids = 4.times.map { |d| login(store, me, "device#{round}-#{d}") }
+      sids.each { |sid| authed += 1 if authenticate(store, sid) == me }
+      logout_everywhere(store, me)
+      abort "a token survived logout-all" if sids.any? { |sid| authenticate(store, sid) }
+    end
+    authed
+  end
+end
+
+# The auditor never catches the store between the two directions: every session
+# it sees is listed in its user's index, and every listed session exists.
+auditor = Ractor.new(STORE) do |store|
+  400.times.count do
+    snap = store.to_h
+    snap.each do |k, v|
+      next unless k.start_with?("sid:")
+      abort "session #{k} not in its index" unless (snap["user:#{v}"] || []).include?(k)
+    end
+    snap.each do |k, sids|
+      next unless k.start_with?("user:")
+      sids.each { |sid| abort "index lists a dead session #{sid}" unless snap.key?(sid) }
+    end
+    true
+  end
+end
+
+audits = auditor.value
+authed = workers.sum(&:value)
+abort "sessions leaked: #{STORE.to_h}" unless STORE.to_h.empty?
+abort "logins failed to authenticate" unless authed == 4 * 5 * 4
+puts "ok: #{authed} authentications, 20 logout-everywheres, store empty at the end; " \
+     "#{audits} audits and the two directions never disagreed"

data/examples/README.md

@@ -0,0 +1,35 @@
+# Examples
+
+Each file runs on its own and checks its own result: it prints one `ok:` line
+or aborts. From a checkout:
+
+```
+ruby -Ilib examples/01_bank_transfer.rb
+```
+
+| file | class | the situation |
+|---|---|---|
+| [01_bank_transfer.rb](01_bank_transfer.rb) | `TVar` | money moves between accounts; an auditor never catches the total wrong |
+| [02_seat_booking.rb](02_seat_booking.rb) | `TVar` | booking adjacent seat pairs; the with-locks version of this deadlocks |
+| [03_feature_flags.rb](03_feature_flags.rb) | `TVar` | read-mostly config: flags read constantly, flipped rarely, no lock on the read |
+| [04_progress.rb](04_progress.rb) | `LockVar` | workers count up, the main Ractor peeks whenever it redraws |
+| [05_exactly_once.rb](05_exactly_once.rb) | `LockVar` | the side effect that a TVar retry would repeat, counted both ways |
+| [06_metrics_board.rb](06_metrics_board.rb) | `LockHash` | per-endpoint records and a global total that agree in every snapshot |
+| [07_word_count.rb](07_word_count.rb) | `ActorHash` | map-reduce whose reduce side mutates tallies in place |
+| [08_lru_cache.rb](08_lru_cache.rb) | `ActiveObject` | an LRU cache: a Hash plus an eviction order nobody wants to freeze |
+| [09_audit_log.rb](09_audit_log.rb) | `ActiveObject` | fire-and-forget logging with `async`, strictly ordered by the owner |
+| [10_price_quotes.rb](10_price_quotes.rb) | `ActiveObject` | fan out `future` calls, gather the answers later |
+
+Two of them are small applications rather than single tricks:
+
+| file | classes | the application |
+|---|---|---|
+| [11_webshop.rb](11_webshop.rb) | `TVar` + `LockHash` + `ActiveObject` | a shop: carts reserved all-or-nothing, a mid-run sale, books that always balance, an audit log |
+| [12_kvstore_wal.rb](12_kvstore_wal.rb) | `ActiveObject` | a crash-safe KV store: write-ahead log on disk, crash, replay, identical state |
+| [13_buffered_logger.rb](13_buffered_logger.rb) | `ActiveObject` | a batching file logger: buffer, high-water mark and flush clock are just ivars |
+| [14_api_gateway.rb](14_api_gateway.rb) | `LockHash` + `LockVar` + `ActiveObject` | an API gateway: token buckets, idempotency keys, a circuit breaker that announces each transition exactly once |
+| [15_cache_backend.rb](15_cache_backend.rb) | `KeyLockHash` | a cache backend: get-or-create per key, dog-piles absorbed by the key lock itself |
+| [16_session_store.rb](16_session_store.rb) | `LockHash` | a session store with "log out everywhere": token and index move together, or a revoked token still authenticates |
+
+The [test suite](../test/examples_test.rb) runs every one of them, so they
+cannot rot.