ractor-sharing 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f667d77a73e96a72c9cbaa28e3d45b7511aa5d3ecafe79d23923c89918d634a6
-  data.tar.gz: 99ae5d37d366f37c0d81da184a5ff15abe681a56af5cf4383841e9acb4a091e2
+  metadata.gz: fdc8c45349210436be7413d61943f09d01e2a24cf74a2b460a5359f99f3523fb
+  data.tar.gz: be41113b5915e787e11e7a93d3f53ee56a264bfcb792f53bab865783aace9c98
 SHA512:
-  metadata.gz: ace4ea48c92eef46604b3743138609ff081325857138c1c581538aefb28a1636e993f0ce6a80c80796ad66beff047df648a829578767219476c970d233f58b3c
-  data.tar.gz: db8a6797917215ee087193ed345a75d7e619896a978e6a552ab7e2f85c19f017ccc33278b7e21acc452471b210247765629ef5420cfe34a9f7becc7686085a43
+  metadata.gz: d17a6abcabe3c2d2e0358189d5d3ff34700264096c0a8ac9f189523d79c02086edbe14dab7a54099dcb3441d15d18ffa0b8f47776d5363dd9714dc974da61715
+  data.tar.gz: 161edc3cd67b07f34d5e696370c83c5a2056306de4d60672391def61f0fa6f778d1c82fe76e7acba36b91a3875c73160b6ef1fb6b0b742669584ccc9e1b9b489

data/README.md

@@ -4,18 +4,21 @@ Ways for Ractors to share mutable state.
 
 Ractors keep their objects to themselves. What crosses between them is either
 frozen or copied, so there is nowhere to put a counter, a registry or a cache
-that several Ractors both read and change. Each class here is such a place.
+that multiple Ractors can both read and update. Each class here is such a place.
 
 What each one is, in a line:
 
 * **[`Ractor::TVar`](docs/tvar.md)** is a *transactional* variable. Read and
-  write any number of them inside one `Ractor.atomically` block, and everything
-  that block changed takes effect together or not at all. A block that loses a
-  race is rolled back and run again.
+  write as many of them as you like inside one `Ractor.atomically` block, and
+  all changes made by that block take effect together or not at all. A block
+  that loses a race is rolled back and run again.
 * **[`Ractor::LockVar`](docs/lockvar.md)** is a variable behind a *lock*. An
   update waits for its turn, and then its block runs exactly once.
 * **[`Ractor::LockHash`](docs/lockhash.md)** is a hash behind one lock. A
-  `synchronize` section is atomic across the keys of that hash, and only those.
+  `synchronize` section is atomic across the keys of that hash, and only that hash.
+* **[`Ractor::KeyLockHash`](docs/keylockhash.md)** is a hash with one lock per
+  key: the row lock to LockHash's table lock. Updates to unrelated keys run in
+  parallel, and nothing is atomic across two keys.
 * **[`Ractor::ActiveObject`](docs/active_object.md)** is an object that lives in
   a Ractor of its own. It never leaves; callers send it method calls, and the
   owner runs them one at a time.
@@ -23,14 +26,15 @@ What each one is, in a line:
   of its own. Callers send it blocks to run on it.
 
 **Start with `Ractor::TVar`.** It takes one variable or several, it cannot
-deadlock, and it is the quickest of these when a variable is fought over. Move
-off it only for a reason the others below name.
+deadlock, and it is the quickest of these under contention. Choose another
+abstraction only when one of the reasons below applies.
 
 | | reach for it when | read | write |
 |---|---|---:|---:|
 | [`Ractor::TVar`](docs/tvar.md)<br>`Ractor.atomically { a.value += 1 }` | always, unless a row below says otherwise. One variable or a dozen, with no lock order to get wrong | 68 ns | 351 ns |
 | [`Ractor::LockVar`](docs/lockvar.md)<br>`lv.update {\|v\| v + 1 }` | the block must run **exactly once**, because it logs, sends, or does anything else a retry would repeat | 74 ns | 352 ns |
-| [`Ractor::LockHash`](docs/lockhash.md)<br>`h.synchronize {\|h\| h[k] = v }` | the same, but the keys are not known in advance | 132 ns | 433 ns |
+| [`Ractor::LockHash`](docs/lockhash.md)<br>`h.synchronize {\|h\| h[k] = v }` | two or more keys must change together, or a snapshot must be consistent | 132 ns | 433 ns |
+| [`Ractor::KeyLockHash`](docs/keylockhash.md)<br>`m.update(k) {\|v\| v + 1 }` | the keys are independent: registries, caches, buckets, idempotency claims. Parallel across keys | 137 ns | 372 ns |
 | [`Ractor::ActiveObject`](docs/active_object.md)<br>`sync def add(k, v) = @db[k] = v` | the values will not be frozen, and the state deserves methods of its own | 2.3 µs | 2.8 µs |
 | [`Ractor::ActorHash`](docs/actor_hash.md)<br>`h.call {\|h\| h[:hits] += 1 }` | the same, and a plain hash is all the interface you need | 2.2 µs | 3.2 µs |
 
@@ -40,12 +44,13 @@ process ends; their write is the figure for a `sync` call, and drops to 1.6 µs
 and 1.9 µs when sent without waiting for the reply (`async def`, `async_call`).
 Contended, the order changes: see [Performance](#performance).
 
-The first three hold **shareable** values, so a change replaces a value rather
-than modifying it: `lv.update { it.merge(k => v).freeze }`. When your state is a
-mutable object you have no intention of freezing, such as a Hash you keep writing
-into or an object graph with methods over it, it cannot go in any of them. The last two
-are for exactly that: the object stays mutable and unshareable, in a Ractor of
-its own, and you send it the calls instead of the data.
+The first four hold **shareable** values -- made shareable for you on the way
+in, so no `.freeze` and no `Ractor.make_shareable` of your own -- and a change
+replaces a value rather than modifying it: `lv.update { it.merge(k => v) }`. When your state is a mutable
+object you intend to keep mutating, such as a Hash you keep writing into or an
+object graph with methods over it, storing it there would freeze it. The last
+two are for exactly that: the object stays mutable and unshareable, in a Ractor
+of its own, and you send it the calls instead of the data.
 
 ```ruby
 require "ractor/sharing"        # all of them
@@ -62,14 +67,47 @@ require "ractor/actor_hash"
 **The default: `TVar`.** One variable or a dozen, and the same code either way:
 whatever a transaction changes, the rest of the program sees all of it or none of
 it. There is no lock to take in the right order, so two transactions can never
-deadlock, and when a variable is genuinely fought over it is the quickest thing
+deadlock, and under genuine contention it is the quickest thing
 here, because losing a race and retrying beats parking a thread.
 
 ```ruby
-from, to = Ractor::TVar.new(100), Ractor::TVar.new(0)
-Ractor.atomically { from.value -= 10; to.value += 10 }
+class Service
+  def initialize
+    @mode   = Ractor::TVar.new(:maintenance)
+    @notice = Ractor::TVar.new("closed for maintenance")
+    Ractor.make_shareable(self)   # the TVars already are; this seals the shell
+  end
+
+  def open!  = Ractor.atomically { @mode.value = :open; @notice.value = "welcome!" }
+  def status = Ractor.atomically { [@mode.value, @notice.value] }   # one snapshot
+end
+
+SERVICE = Service.new             # shareable, so a constant every Ractor can use
+
+watchers = 4.times.map do
+  Ractor.new do
+    mixed = 0
+    10_000.times do
+      state, text = SERVICE.status
+      mixed += 1 if (state == :open) != (text == "welcome!")
+    end
+    mixed
+  end
+end
+
+SERVICE.open!
+
+watchers.sum(&:value) #=> 0
 ```
 
+Forty thousand snapshots taken across the flip, and not one of them caught the
+mode and the notice disagreeing. And look at the class: an ordinary one that
+makes itself shareable in its own `initialize`, so the instance lives in a
+constant and every Ractor just uses it -- the TVars are where the change
+lives. Its methods run in whichever Ractor calls them: no owner, no message,
+no round trip. That is the pattern to reach for before `ActiveObject` below,
+which exists for state that cannot be frozen at all.
+
 The one thing to hold on to: a transaction that loses a race is **rolled back and
 run again**, so its block has to be safe to run twice. Keep it to reading and
 writing TVars.
@@ -90,22 +128,91 @@ waiting for a turn beats retrying. One shareable value, and the
 block runs once by construction.
 
 ```ruby
-counter = Ractor::LockVar.new(0)
-4.times.map { Ractor.new(counter) {|c| 1000.times { c.increment } } }.each(&:join)
-counter.value #=> 4000
+lock = Ractor::LockVar.new(nil)
+
+claims = %w[ann ben cho dee].map do |name|
+  Ractor.new(lock, name) do |lv, me|
+    won = false
+    lv.update {|holder| holder || (won = true; me) }  # announce here: it runs once
+    won
+  end
+end
+
+claims.map(&:value).count(true) #=> 1
+```
+
+Four Ractors race to take the deploy lock; each block runs exactly once, so
+exactly one of them believes it won -- with a `TVar` the losing blocks would
+have run again, and a side effect in them with it.
+
+**Keys that change together: `LockHash`.** The everyday shape is a hash that
+holds an index into itself: a session store maps each token to its user *and*
+each user to their tokens, because "log out everywhere" needs the list. Login
+writes two keys; revocation deletes many. Each is one `synchronize`, because
+the gap is a security hole: revoked one by one, a racing request still
+authenticates with a not-yet-deleted token.
+
+```ruby
+sessions = Ractor::LockHash.new
+
+logins = %w[ann ben].flat_map do |user|
+  2.times.map do |device|
+    Ractor.new(sessions, user, "sid-#{user}-#{device}") do |s, u, sid|
+      s.synchronize {|h| h[sid] = u; h[u] = (h[u] || []) + [sid] }
+    end
+  end
+end
+logins.each(&:join)
+
+sessions.synchronize do |h|                    # ann logs out everywhere
+  (h["ann"] || []).each {|sid| h.delete(sid) }
+  h.delete("ann")
+end
+
+sessions["sid-ann-0"] #=> nil
+sessions["sid-ben-1"] #=> "ben"
 ```
 
-**The same, for a hash: `LockHash`.** A registry, a cache, a scoreboard each
-worker writes a row of, where the keys are not known in advance. Reads need no
-ceremony; writes go inside `synchronize`, and everything one section changes
-appears at once. Atomic across its own keys, and only those.
+Reads need no ceremony; writes go inside `synchronize`, and everything one
+section changes appears at once -- atomic across its own keys, and only that
+hash, with `to_h` a snapshot no write can tear.
+
+**Independent keys, in parallel: `KeyLockHash`.** A registry, a cache, a
+scoreboard where each worker owns its row: hashes whose keys never change
+together. There the whole-hash lock above is paying for atomicity nobody asked
+for, with unrelated clients waiting in one queue. `KeyLockHash` locks per key,
+and the everyday shape is a get-or-create cache:
 
 ```ruby
-board = Ractor::LockHash.new
-board.synchronize {|b| b[:worker_1] = 42 }
-board.to_h #=> {worker_1: 42}
+cache = Ractor::KeyLockHash.new
+
+readers = 4.times.map do
+  Ractor.new(cache) do |c|
+    renders = 0
+    render = ->(page) { renders += 1; "<p>page #{page}</p>" }   # the expensive part
+
+    100.times do |i|
+      page = i % 10
+      c.update("page-#{page}") {|html| html || render.(page) }
+    end
+    renders
+  end
+end
+
+readers.sum(&:value) #=> 10
 ```
 
+Four hundred fetches over ten pages, and the render ran exactly ten times.
+`update` holds that key's lock while the block runs, so simultaneous misses on
+one page wait for the first -- and waiting is correct here, because everyone
+waiting would have rendered the same page themselves: the system does the work
+once instead of eight times, and a miss on a *different* page never queues at
+all. (That is the one shape where a long block is the right trade; the rule
+and its price are in [the docs](docs/keylockhash.md).) A per-client tally is one
+`hits.increment(client)`, and check-and-claim is `update` with `:claimed` in
+it.
+
+
 **A mutable object: `ActiveObject`.** When freezing the state is not on the
 table, give the object a Ractor of its own. It never leaves; callers send method
 calls in, the owner runs them one at a time, and the object goes on being an
@@ -124,11 +231,21 @@ shareable value, one of the first three will cost you far less.
 ```ruby
 class People < Ractor::ActiveObject
   def initialize = @db = {}
-  async def add(name, age) = @db[name] = age
-  sync  def find(name) = @db[name]
+  async def add(name, age) = @db[name] = age   # fire and forget
+  sync  def find(name) = @db[name]             # a question: waits for the answer
 end
+
+people = People.new
+people.add("ada", 36)
+people.add("lin", 28)
+
+people.find("ada") #=> 36
+Ractor.new(people) {|p| p.find("lin") }.value #=> 28
 ```
 
+`People.new` returns a shareable proxy: hand it to any Ractor and the calls
+all funnel to the one owner, where `@db` stays an ordinary mutable Hash.
+
 **A hash whose values will not be frozen: `ActorHash`.** Same shape as
 `LockHash`, but the entries live in a Ractor of its own, so they can be anything
 and a block changes them in place over there. Reads are questions you ask;
@@ -136,16 +253,53 @@ changes are work you send, and you need not wait for them.
 
 ```ruby
 h = Ractor::ActorHash.new
-h.increment(:hits)
-h.async_call {|h| (h[:log] ||= []) << "a line" }
-h[:log]
+
+loggers = 3.times.map do |i|
+  Ractor.new(h, i) do |hash, id|
+    hash.increment(:hits)
+    hash.async_call(id) {|x, me| (x[:log] ||= []) << me }   # mutated in place, over there
+  end
+end
+loggers.each(&:join)
+
+h[:hits] #=> 3
+h.call {|x| x[:log].sort } #=> [0, 1, 2]
 ```
 
+The log is a plain mutable Array that never leaves the owner; the blocks go to
+it, not the other way around.
+
 Two signs you picked the wrong one. Reaching for two `LockVar`s at once is
 refused, with a message pointing here: that is the sign you wanted a `TVar`.
 Finding yourself freezing a copy of a collection on every update is the sign you
 wanted an `ActiveObject`.
 
+### In database terms
+
+If you think in database vocabulary, the first four unbundle what a database
+ships as one engine:
+
+| in a database | here |
+|---|---|
+| an MVCC read, taking no lock | `TVar#value` outside a transaction |
+| a serializable transaction, retried on conflict | `Ractor.atomically` |
+| a row lock | `KeyLockHash` -- sold separately: no transaction spans two of them |
+| a table lock | `LockHash#synchronize` |
+| the deadlock detector | not shipped: a second lock raises `Ractor::NestedLockError` at the door |
+
+Databases can default to row locks because a transaction manager acquires many
+of them and a deadlock detector cleans up when that cycles. There is no
+detector here, so the second lock is refused instead, and work that spans keys
+goes to the table lock or to the transactions.
+
+One thing no detector catches, there or here: taking too **few** locks. A
+deadlock is a cycle in who-waits-for-whom; locking one key, releasing it and
+then locking another produces no wait and no cycle, just an invariant quietly
+broken -- databases only catch that shape at serializable, because a declared
+transaction tells them what was supposed to be atomic. The declaration is the
+protection: keys that must agree go inside one `synchronize` or one
+`Ractor.atomically`, and no runtime is going to notice for you.
+
 
 ## Performance
 
@@ -160,6 +314,7 @@ operation, counted across all Ractors, on 16 cores.
 | `TVar#value` | 68 | **9** | 9 |
 | `LockVar#value` | 74 | 365 | 10 |
 | `LockHash#[]` | 132 | 489 | 23 |
+| `KeyLockHash#[]` | 137 | 478 | 18 |
 | `ActiveObject` sync method | 2300 | 1380 | 742 |
 | `ActorHash#[]` | 2179 | 1451 | 730 |
 | no sharing at all | 78 | n/a | 9 |
@@ -178,13 +333,14 @@ machine's limit.
 | `TVar` transaction | 351 | **509** | 108 |
 | `LockVar#update` | 352 | 1102 | **50** |
 | `LockHash#synchronize` | 433 | 1238 | 58 |
+| `KeyLockHash#update` | 372 | 1173 | 52 |
 | `ActiveObject` async method | 1555 | 839 | 179 |
 | `ActiveObject` sync method | 2789 | 1587 | 760 |
 | `ActorHash#async_call` | 1919 | 1032 | 219 |
 | `ActorHash#call` | 3166 | 1740 | 747 |
 | no sharing at all | 117 | n/a | 18 |
 
-**Fought over, nothing scales and `TVar` stays about 2× ahead**, because losing a
+**Under contention, nothing scales and `TVar` stays about 2× ahead**, because losing a
 race and running a short block again is cheaper than parking a thread and waking
 it, and a transaction that keeps losing backs off, about 100 ns per consecutive
 loss, spinning rather than sleeping, before running again. That cell is the
@@ -198,6 +354,12 @@ Ractor (16 on their own, sync against async above); on one shared object the
 serialisation at the owner leaves it under 2×, and from a single caller it is
 about 1.7×.
 
+Neither of these two conditions shows what `KeyLockHash` is for: on one shared
+key it is the same lock as everyone else, and separate maps share nothing. Its
+condition is **one shared map with a key per Ractor**, where the table lock
+pays for every neighbour and the key lock does not: 123 ns against `LockHash`'s
+1212 at four Ractors, 248 against 1312 at sixteen.
+
 The `no sharing at all` row is the machine's own ceiling: about 8× is as far as
 anything here scales. Called from the main Ractor rather than a worker, the two
 Ractor backed classes cost about 8.9 µs instead of 2.6, because that thread has a
@@ -211,8 +373,13 @@ that path rather than the class. It gets a table of its own:
 
 | | one Ractor (ns) | 16 on one object (ns) | 16 on their own (ns) |
 |---|---:|---:|---:|
-| `LockVar#increment` | 77 | 338 | **8** |
-| `TVar#increment` | 89 | **144** | 75 |
+| `LockVar#increment` | 80 | 348 | **9** |
+| `TVar#increment` | 76 | **159** | 75 |
+| `KeyLockHash#increment` | 144 | 518 | 16 |
+
+One hot counter belongs in a `LockVar` (or a `TVar`, contended); counters that
+spread over keys belong in the `KeyLockHash`, which pays the hash and the guard
+per call and scales across its keys like everything else it does.
 
 `benchmark/family.rb` produces all of these, sweeping 1, 2, 4, 8 and 16 Ractors
 over read, write and a 9:1 mix, under both conditions. Every worker reports ready
@@ -254,7 +421,8 @@ Ruby 4.0 or later (`Ractor::Port`, and Ractors that are worth using).
 rake            # compile both extensions and run every test
 ```
 
-Documentation for each class is in [docs/](docs/).
+Documentation for each class is in [docs/](docs/), and ten runnable,
+self-checking examples are in [examples/](examples/).
 
 ## License
 

data/docs/keylockhash.md

@@ -0,0 +1,141 @@
+# Ractor::KeyLockHash
+
+A hash with one lock per key. In database terms, the row lock to
+[`Ractor::LockHash`](lockhash.md)'s table lock:
+
+| | atomic unit | unrelated keys | two keys together |
+|---|---|---|---|
+| `LockHash` | the whole hash | wait for each other | atomic, its whole point |
+| `KeyLockHash` | one key | run in parallel | **never atomic** here |
+
+Reach for it when the keys are independent of one another and appear at
+runtime: token buckets per client, a get-or-create cache, idempotency keys,
+anything shaped "look up my key, change my key, never two at once".
+
+```ruby
+require "ractor/keylockhash"
+
+buckets = Ractor::KeyLockHash.new
+
+buckets[:quota] = 100                       # a plain write: no ceremony needed
+buckets.update(:quota) { |v| v - 1 }        # read-modify-write, atomic per key
+```
+
+`update` exists for one reason: computing the new value from the old one. It
+yields the current value (nil for a missing key) and stores what the block
+returns, all under one hold of that key's lock, and the block runs exactly
+once. Being told nil is being told you created the key, so put-if-absent needs
+nothing more:
+
+```ruby
+jobs = Ractor::KeyLockHash.new
+req_id = "order-1701"   # a bare String key is dup'd and frozen for you, like Hash's
+mine = false
+jobs.update(req_id) { |v| v ? v : (mine = true; :claimed) }
+mine #=> true
+jobs.update(req_id) { |v| v ? v : (mine = :again; :claimed) }
+mine #=> true
+```
+
+## API
+
+```ruby
+m = Ractor::KeyLockHash.new(initial = nil)
+
+m[key]                # read, under that key's lock
+m.fetch(key, default) # the usual default / block / KeyError; both run unlocked
+m.key?(key)
+m.keys / m.to_h       # a copy; consistent per key, NOT a whole-map snapshot
+m.inspect
+
+m[key] = value              # write, under that key's lock
+m.update(key) {|v| new_v }  # read-modify-write under one hold; v is nil if absent
+m.increment(key, by = 1)    # update with the block written for you; missing counts as 0
+m.delete(key)               # returns the old value, or nil
+```
+
+Values are **made shareable on the way in**, so neither `.freeze` nor
+`Ractor.make_shareable` is yours to write (deep-frozen in place; a value
+that cannot be raises `Ractor::IsolationError`). Keys must be shareable
+already, `ArgumentError` otherwise, with one courtesy borrowed from `Hash`
+itself: a bare String key is stored as a frozen copy, and yours stays yours.
+The map itself is frozen and shareable, so it can be passed to any Ractor.
+
+## One key at a time
+
+Touching any second lock inside `update` raises `Ractor::NestedLockError`,
+another key of the same map included: the shape "lock A, then grab B" is where
+deadlocks come from, and this class refuses it at the door. Two keys that must
+change together are [`Ractor::LockHash`](lockhash.md)'s job; several objects
+changing together are [`Ractor::TVar`](tvar.md)'s.
+
+For the same reason, `keys` and `to_h` are not a snapshot of the whole map at
+one moment: they visit the keys' locks one at a time. A consistent cross-key
+snapshot is again LockHash territory.
+
+## How it is built
+
+Lock striping: keys hash onto 64 shards, each a table behind a
+[lock of its own](lockvar.md#implementation-notes), so two keys occasionally
+share one. Databases would call the finer design a bucket **latch** plus a row
+**lock**; if shard collisions ever show up in a profile, that is the upgrade
+path, and the API would not change. One thing databases bundle with their row
+locks stays unbundled here: a transaction manager. They can let one
+transaction take many row locks because a deadlock detector cleans up the
+cycles; this class refuses the second lock at the door instead.
+
+A key's own `#hash` or `#eql?` that reaches back into the same map raises
+`NestedLockError` rather than deadlocking or being let in: the inner call may
+want a shard this thread does not hold.
+
+## Performance
+
+The number this class exists for, one **shared** map with a key per Ractor,
+updates only (median of three, ns per completed update across all Ractors):
+
+| Ractors | `KeyLockHash#update`, own key (ns) | `LockHash`, own key (ns) |
+|---:|---:|---:|
+| 1 | 451 | 476 |
+| 4 | **123** | 1212 |
+| 16 | **248** | 1312 |
+
+The table lock pays for every neighbour; the key lock does not. (Sixteen keys
+on 64 shards collide now and then, which is why 16 sits above 4.)
+
+Everywhere else it costs what `LockHash` costs: an uncontended update is
+372 ns, a read 137 ns, and sixteen Ractors fighting over one *single* key are
+one lock's queue again, 1173 ns per update. `increment` is 144 ns uncontended
+and 16 ns per op with a key per Ractor at sixteen -- same shape, block written
+for you. Measured on 16 cores, governor
+`performance`, ruby 4.1.0dev; `benchmark/family.rb` and its `ownkey`
+companion in the trials record produce these.
+
+## Keep the block short
+
+The family rule applies unchanged: the block holds that key's lock, so every
+other user of *that key* waits for it. Compute the new value and nothing more.
+
+The one deliberate exception is get-or-create caching, where holding the lock
+through the computation is the point -- it is what stops eight simultaneous
+misses computing eight times. The arithmetic is what justifies it: everyone
+waiting would have run the *identical* computation themselves, so each waits
+at most what it would have burned, and the system does the work once instead
+of eight times. That argument covers exactly this case and no other -- it is
+not licence for unrelated slow work under the lock -- and it assumes the
+computation reliably finishes: one render stuck on the network wedges its key,
+and, keys being striped over 64 shards, the occasional innocent neighbour.
+See [examples/15_cache_backend.rb](../examples/15_cache_backend.rb) for the
+trade priced and tested.
+
+## When something else fits better
+
+* Two keys that change together, or a consistent snapshot:
+  [`Ractor::LockHash`](lockhash.md).
+* One key so read-hot that even its own lock is a queue: put that value in a
+  [`Ractor::TVar`](tvar.md), whose reads take nothing.
+* Values you will not freeze: [`Ractor::ActorHash`](actor_hash.md).
+
+A worked cache backend, dog-pile protection included, is
+[examples/15_cache_backend.rb](../examples/15_cache_backend.rb).
+
+Part of [ractor-sharing](../README.md).

data/docs/lockhash.md

@@ -1,31 +1,44 @@
 # Ractor::LockHash
 
-A Hash that Ractors can share. Reads are allowed anywhere; every write goes
-through `synchronize`, and whatever one `synchronize` changes, other Ractors see
-all of it or none of it.
+A Hash that Ractors can share, for **keys that change together**. Reads are
+allowed anywhere; every write goes through `synchronize`, and whatever one
+`synchronize` changes, other Ractors see all of it or none of it.
 
 ```ruby
 require "ractor/lockhash"
 
-board = Ractor::LockHash.new
+sessions = Ractor::LockHash.new
+
+# login: the token and the user's index move together
+sessions.synchronize do |h|
+  h["sid-1"] = "ann"
+  h["ann"] = (h["ann"] || []) + ["sid-1"]
+end
 
-4.times.map do |i|
-  Ractor.new(board, i) do |b, id|
-    100.times {|n| b.synchronize {|x| x[id] = n } }
-  end
-end.each(&:join)
+# "log out everywhere": revoke every token AND the index, one section.
+# Revoked one by one, a racing request could still authenticate with a
+# not-yet-deleted token while the account believes it logged out.
+sessions.synchronize do |h|
+  (h["ann"] || []).each {|sid| h.delete(sid) }
+  h.delete("ann")
+end
 
-board.to_h.sort.to_h #=> {0 => 99, 1 => 99, 2 => 99, 3 => 99}   # whoever wrote first is first
+sessions.to_h #=> {}
 ```
 
+That is the shape this class is for: a hash that holds an index into itself,
+where a write is two keys or ten and a reader must never see them halfway.
+Keys that never change together do not need this lock, or its queue: they
+belong in [`Ractor::KeyLockHash`](keylockhash.md).
+
 ## Why not a LockVar holding a Hash
 
 You can put a frozen Hash in a [`Ractor::LockVar`](lockvar.md), but then changing
 one entry copies the whole thing:
 
 ```ruby
-lv = Ractor::LockVar.new({}.freeze)
-lv.update { it.merge(k: 1).freeze }   # O(n) per write
+lv = Ractor::LockVar.new({})
+lv.update { it.merge(k: 1) }   # O(n) per write
 ```
 
 `LockHash` keeps a real Hash and writes into it, so one entry costs one entry.
@@ -54,7 +67,12 @@ released is already stale, and inside a section `keys` says the same thing.
 that block **after** the lookup has released the lock, so a default that reads
 this hash again is fine.
 
-Keys and values must be **shareable**; `ArgumentError` otherwise. The LockHash
+Values are **made shareable on the way in**, so neither `.freeze` nor
+`Ractor.make_shareable` is yours to write (deep-frozen in place; a value
+that cannot be raises `Ractor::IsolationError`). Keys must be shareable
+already, `ArgumentError` otherwise, with one courtesy borrowed from `Hash`
+itself: a bare String key is stored as a frozen copy, and yours stays yours.
+The LockHash
 itself is frozen and shareable, so it can be passed to any Ractor. `keys` and
 `to_h` return plain mutable copies, yours to reshape; everything inside them is
 shareable already, so `Ractor.make_shareable(h.to_h)` is all it takes to hand
@@ -130,8 +148,9 @@ written; the lock is released, nothing more.
 
 One lock covers the whole hash, so **writes to unrelated keys wait for each
 other**, and a snapshot is O(n). A hash written to constantly is better modelled
-as one [`Ractor::LockVar`](lockvar.md) per key, which scales with the cores.
-That is open to you whenever you never need two keys to change together.
+as one lock per key -- [`Ractor::KeyLockHash`](keylockhash.md), the row lock to
+this class's table lock -- which scales with the cores. That is open to you
+whenever you never need two keys to change together.
 
 **Reads take the lock too, so they do not scale either.** Sixteen Ractors reading
 one shared LockHash cost 489 ns per read, against 23 ns when each has a hash of
@@ -150,4 +169,9 @@ The block holds the lock while it runs, so every other reader and writer of this
 hash waits for it. Change the entries and nothing else: no IO, no waiting on
 anything, no calling out to code that might.
 
+A worked example is a session store with "log out everywhere":
+[examples/16_session_store.rb](../examples/16_session_store.rb). The token and
+the per-user index live in one hash, and revoking them one by one would leave
+a gap where a logged-out token still authenticates.
+
 Part of [ractor-sharing](../README.md).