ractor-sharing 0.1.0

data/docs/lockhash.md

@@ -0,0 +1,150 @@
+# 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.
+
+```ruby
+require "ractor/lockhash"
+
+board = Ractor::LockHash.new
+
+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)
+
+board.to_h.sort.to_h #=> {0 => 99, 1 => 99, 2 => 99, 3 => 99}   # whoever wrote first is first
+```
+
+## 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
+```
+
+`LockHash` keeps a real Hash and writes into it, so one entry costs one entry.
+
+## API
+
+```ruby
+h = Ractor::LockHash.new(initial = nil)
+
+h[key]                # read
+h.fetch(key, default) # read, with the usual default / block / KeyError
+h.key?(key)
+h.keys / h.to_h       # a frozen, shareable snapshot of the whole hash
+h.inspect
+
+h.synchronize {|h| ... }   # the only place writes are allowed; yields the LockHash
+h[key] = value             #   inside synchronize
+h.delete(key)              #   inside synchronize
+h.clear                    #   inside synchronize
+```
+
+There is no `size` and no `empty?`. A count handed back after the lock is
+released is already stale, and inside a section `keys` says the same thing.
+
+`fetch` prefers its block to an explicit default, as `Hash#fetch` does, and runs
+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
+itself is frozen and shareable, so it can be passed to any Ractor.
+
+### Writes only inside `synchronize`
+
+```ruby
+h = Ractor::LockHash.new
+h[:a] = 1
+# => NoMethodError: '[]=' is only allowed inside Ractor::LockHash#synchronize
+```
+
+It is a `NoMethodError` for the same reason calling a private method is: the
+method is there, but not callable from where you are.
+
+Every write being inside a block is what makes reading an entry and writing it
+back one step rather than two:
+
+```ruby
+# WRONG: refused, and it was a lost update anyway
+h[:hits] = h[:hits] + 1
+```
+
+```ruby
+h = Ractor::LockHash.new(hits: 0)
+h.synchronize {|h| h[:hits] = h[:hits] + 1 }   # right
+```
+
+The block is handed the LockHash, **never the Hash inside it**, so no reference
+to the state can escape and be written to later, or from another Ractor.
+
+### The two idioms
+
+Almost everything a shared hash gets used for is one of these, and both are one
+`synchronize`:
+
+```ruby
+h = Ractor::LockHash.new
+k = :key
+
+h.synchronize {|h| h[k] ||= 42 }                 # memoize: computed once, by one caller
+h.synchronize {|h| h[:n] = (h[:n] || 0) + 1 }    # count: read and write in one step
+```
+
+There is no `compute` or `fetch_or_store` here. One lock covers the whole hash,
+so a dedicated method for one key would run at exactly the same speed as the
+block above, and only spend a name. Such methods start to mean something when a
+lock can be taken per key, and this one is not. See below.
+
+### What one `synchronize` gives you
+
+Everything it changes becomes visible together. A reader calling `[]` or `to_h`
+waits for a section in flight rather than looking inside one:
+
+```ruby
+board = Ractor::LockHash.new
+i = 1
+board.synchronize {|b| b[:x] = i; b[:y] = i }   # a reader never sees x != y
+```
+
+That is atomicity **across the keys of this hash**. Across separate objects it is
+not: taking a *different* LockHash, or a LockVar, from inside a `synchronize`
+raises `Ractor::NestedLockError`, because that is where lock-order deadlocks come
+from. Several objects that must change together are [`Ractor::TVar`](tvar.md)'s
+job. Nesting `synchronize` on the *same* hash is allowed, so a section may call a
+method that takes one again.
+
+There is no rollback either. A block that raises keeps whatever it had already
+written; the lock is released, nothing more.
+
+## The cost of that atomicity
+
+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.
+
+**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
+its own; a [`Ractor::TVar`](tvar.md) read costs 9 ns whether it is shared or not,
+because it takes no lock. One exclusive lock covers the whole hash, so a reader cannot be let in beside a
+writer the way a TVar's single slot can. If your load is read heavy
+and the hash is shared, that is the number that will decide it.
+
+Acquisition is not FIFO: a thread may barge ahead of waiters, so readers hammering
+a hash in a tight loop can starve a writer. Keep sections short, and give busy
+reader loops something else to do between reads.
+
+## Keep the block short
+
+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.
+
+Part of [ractor-sharing](../README.md).

data/docs/lockvar.md

@@ -0,0 +1,280 @@
+# Ractor::LockVar
+
+**One** variable that Ractors can share. It holds one shareable object; 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.
+
+```ruby
+require "ractor/lockvar"
+
+counter = Ractor::LockVar.new(0)
+
+rs = 4.times.map do
+  Ractor.new(counter) do |c|
+    1000.times { c.update {|n| n + 1 } }
+  end
+end
+rs.each(&:join)
+
+p counter.value #=> 4000
+```
+
+## API
+
+```ruby
+lv = Ractor::LockVar.new(initial = nil)
+
+lv.value               # read, under the lock -- a snapshot, never an input to update
+lv.update {|v| new_v } # replace the value, under the lock; returns new_v
+lv.increment(n = 1)    # add n under the lock, as update {|v| v + n } would
+lv.inspect
+```
+
+`inspect` does not take the lock, so it never blocks and never raises: call it
+from a debugger, from inside another update, from anywhere. The value it shows
+may be one update out of date, which for a display is the right trade.
+
+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
+
+A LockVar holds one **shareable** object, and so does everything you store into
+it. Anything else raises `ArgumentError`:
+
+```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
+```
+
+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
+`lv.value[k] = v`.
+
+A rejected value leaves the variable as it was.
+
+### Reads and updates
+
+Both take the lock, so an update's **whole block** is atomic as far as readers
+are concerned, not just its final store. That is what an update block needs when
+it makes anything else observable:
+
+```ruby
+lv = Ractor::LockVar.new(0)
+lv.update {|v| $last = v; v + 1 }   # every reader sees lv.value > $last
+```
+
+Blind assignment is `lv.update { x }` (the block just ignores the old value).
+There is no `value=`: an unlocked write would silently discard a concurrent
+`update` that had already read the old value.
+
+Note that the block's result *is* the new value, so a block that forgets to
+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.
+
+## Read-modify-write belongs inside the block
+
+Any new value computed from the current one has to be computed inside `update`,
+from the value the block is given. Reading outside and writing inside is broken:
+another update lands in between, and yours discards it. Counting is only the
+smallest example. The same goes for appending to a frozen array, merging into a
+frozen hash, clamping, toggling, anything that reads before it writes.
+
+```ruby
+# WRONG
+v = lv.value
+lv.update { v + 1 }
+
+h = lv.value
+lv.update { h.merge(key => 1).freeze }
+```
+
+```ruby
+# RIGHT
+lv = Ractor::LockVar.new(0)
+lv.update { it + 1 }
+
+h = Ractor::LockVar.new({}.freeze)
+h.update { it.merge(key: 1).freeze }
+```
+
+Four Ractors incrementing 500 times each:
+
+```
+wrong: 829 / 2000   (1171 updates lost)
+right: 2000 / 2000
+```
+
+`value` is for looking: a snapshot, true when it was taken and possibly stale by
+the time you use it. **Never feed it back into `update`.**
+
+Nothing in the library can catch this for you, so the warning is the whole
+defence.
+
+## One variable, and how that differs from TVar
+
+The unit here is a single variable. That is the whole distinction between this
+and its neighbour, not optimistic versus pessimistic, which is only how each one
+happens to be built.
+
+| | `Ractor::LockVar` | [`Ractor::TVar`](tvar.md) |
+|---|---|---|
+| synchronizes | one variable | several variables together |
+| written as | `lv.update {\|v\| ... }` | `Ractor.atomically { ... }` |
+| on conflict | waits its turn | rolls back and runs the block again |
+| the block runs | exactly once | as many times as it takes |
+| so the block may | have side effects | only compute |
+| lock ordering | refused: one variable at a time | not a question |
+
+A transaction only starts to mean something once there is a second variable, so
+for one variable there is nothing to express beyond a read-modify-write, which
+is why reading and updating are all there is to it.
+
+The row that decides most cases is the rollback. A `TVar` transaction that loses
+a race is discarded and run again, so its block has to be safe to run twice:
+anything it did that was not a `TVar` write has already happened and will happen
+again. A `LockVar` update waits for its turn instead, and then runs once.
+
+```ruby
+$log = []
+lv = Ractor::LockVar.new(0)
+lv.update {|v| $log << v; v + 1 }   # logs exactly once
+```
+
+Touching another LockVar from inside an update is refused:
+
+```ruby
+a = Ractor::LockVar.new(1)
+b = Ractor::LockVar.new(2)
+a.update {|v| b.value }
+# => Ractor::NestedLockError:
+#    already inside another Ractor::LockVar;
+#    use Ractor::TVar to change several of them together
+```
+
+Lock ordering is where locking goes wrong, and refusing the first nesting turns a
+rare production deadlock into a deterministic error. Reaching for a second
+variable is the sign that you wanted a transaction: `Ractor::TVar` logs reads and
+writes and retries on conflict, so it needs no lock order at all.
+
+No LockVar can be touched from inside an update, its own included. The block is
+handed the value it needs, and a nested update's write would be discarded by the
+outer block's result anyway. The holder is tracked per **thread**.
+
+## Keep the block short
+
+The block holds the lock while it runs, so everything else waiting on this
+variable waits for it. Compute the new value and nothing more: no IO, no waiting
+on anything, no calling out to code that might. This is not a `LockVar`
+restriction so much as the rule for any critical section, and `TVar` wants the
+same thing for its own reason: a transaction is validated against the version it
+read when it started, so a long block is a long window for somebody else to
+invalidate it.
+
+## Performance
+
+The workload is one shared value, a frozen `{status:, seq:}` record: a **read**
+takes it out, an **update** puts a new frozen one in its place. Numbers are **ns
+per completed operation across all Ractors**, so one that halves when the Ractors
+double means it scaled. Measured on 16 cores with the CPU governor fixed at
+`performance`, on ruby 4.1.0dev; `benchmark/family.rb` runs the same comparison
+and checks after every run that no update was lost. Each cell is the median of
+three runs, and these cells moved by 0% to 10% between independent sweeps.
+
+### Reading
+
+```ruby
+n.times.map {|i| Ractor.new(vars[i]) {|v| K.times { v.value } } }.each(&:join)
+```
+
+| Ractors | shared `LockVar#value` (ns) | shared `TVar#value` (ns) | own `LockVar#value` (ns) | own `TVar#value` (ns) |
+|---:|---:|---:|---:|---:|
+| 1 | 77 | 74 | 74 | 68 |
+| 2 | 115 | 43 | 47 | 42 |
+| 4 | 297 | 23 | 23 | 32 |
+| 8 | 347 | 17 | 12 | 10 |
+| 16 | 365 | 9 | 10 | 9 |
+
+**A shared `LockVar` does not scale for reading, and this is the number to know
+before choosing it.** `#value` takes the lock, so sixteen Ractors reading one
+variable stand in a queue and the read costs 365 ns instead of 10. `TVar#value`
+outside a transaction takes nothing, so it reads the same whether the variable is
+shared or not. Give each Ractor a variable of its own and both scale to the
+machine's limit.
+
+What the lock buys is the guarantee in *Reads and updates* above: a reader waits
+for an update in flight, so an update block is atomic to readers and not just its
+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 }
+```
+
+| Ractors | shared `LockVar#update` (ns) | shared `TVar` `atomically` (ns) | own `LockVar#update` (ns) | own `TVar` `atomically` (ns) |
+|---:|---:|---:|---:|---:|
+| 1 | 359 | 358 | 352 | 351 |
+| 2 | 823 | 366 | 209 | 204 |
+| 4 | 1014 | 384 | 106 | 132 |
+| 8 | 1017 | 462 | 56 | 99 |
+| 16 | 1102 | 509 | 50 | 108 |
+
+**Fought over, 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
+again. The shared-16 `TVar` cell is the volatile one, landing anywhere from 500
+to 870 ns between sweeps; it is quoted as the median of seven runs.
+
+**Spread out, `LockVar` scales and `TVar` does not**: 352 ns down to 50 is 7.0×,
+against 3.3× for `TVar`. Every committing transaction takes one process wide lock
+to allocate the next version number, whichever variable it touched, and that lock
+is the ceiling.
+
+**Do not choose `LockVar` for speed on a contended variable.** How much any of
+this matters depends on how often your variable is actually contended and how
+much of your load is reads, which are properties of your program rather than of
+either class, so measure yours. What `LockVar` gives you regardless is that the
+block runs once.
+
+### Not increment
+
+`LockVar#increment` and `TVar#increment` each take a fast path that adds two
+Fixnums without running any Ruby, so they are not a measurement of either class:
+77 ns and 89 ns for one Ractor on its own variable, 338 ns and 144 ns for
+sixteen on one.
+
+## Implementation notes
+
+* The lock state is protected by a native mutex that is held for a few
+  instructions only and **never across Ruby code**, so a waiter can never keep
+  another Ractor from reaching a GC safepoint.
+* A thread that has to wait parks on a `Ractor::Port` of its own rather than on a
+  condition variable. `Port#receive` goes through the VM scheduler, so the wait
+  **rides the M:N scheduler** (enabled by default on non-main Ractors) and stays
+  interruptible: `Thread#kill` on a waiter works and leaves the lock untouched.
+* An uncontended `update` touches the native mutex only: no Port is created and
+  no message is sent.
+* `update` and `value` are written in C so that no interrupt can be delivered
+  between taking the lock and arming the `ensure` that releases it. (With the
+  block form written in Ruby, a `Thread#kill` landing in that window stranded the
+  lock forever; it reproduced within a couple of iterations.)
+* Only the first waiter is woken, and waiters stay queued until they wake by
+  themselves, so a wakeup lost to an interrupt is retried by the next release; a
+  waiter that leaves without taking the lock passes the wakeup on. A waiter whose
+  Ractor has ended has a closed port, so the wakeup is skipped and the next
+  waiter is tried instead.
+* Acquisition is **not FIFO**: a thread may barge ahead of queued waiters.
+* `inspect` never takes the lock, so it neither blocks nor raises.
+
+Part of [ractor-sharing](../README.md).

data/docs/tvar.md

@@ -0,0 +1,124 @@
+# Ractor::TVar
+
+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
+not at all.
+
+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)
+
+Ractor.atomically do
+  config.value  = config.value.merge(mode: :running).freeze
+  version.value = "v2".freeze             # 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 }
+```
+
+Where two variables have to agree, that is the whole point:
+
+```ruby
+from = Ractor::TVar.new(100)
+to   = Ractor::TVar.new(0)
+
+Ractor.atomically do
+  from.value -= 10
+  to.value   += 10        # no one ever sees the money in neither account
+end
+```
+
+Nothing is locked while the block runs. Each transaction reads a consistent
+snapshot and, at the end, commits only if nothing it read has changed since;
+otherwise it is **rolled back and run again**. So a block may run more than once,
+and must be safe to: keep it to reading and writing TVars, with no side effects
+and no waiting.
+
+```ruby
+tv = Ractor::TVar.new(0)
+rs = 4.times.map { Ractor.new(tv) {|t| 10_000.times { Ractor.atomically { t.value += 1 } } } }
+rs.each(&:join)
+tv.value #=> 40000
+```
+
+## API
+
+```ruby
+tv = Ractor::TVar.new(initial = nil)   # any shareable object
+
+Ractor.atomically { ... }   # everything inside is one transaction
+
+tv.value             # read; inside a transaction or out
+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.
+
+**A write needs a transaction.** `tv.value = v` on its own raises
+`Ractor::TransactionError`, "can not set without transaction". There is no
+one-off write, because a write on its own is where a lost update comes from:
+
+```ruby
+Ractor.atomically { tv.value = tv.value + 1 }   # right
+tv.increment                                    # right, and shorter
+```
+
+A read outside a transaction is allowed, and returns the value as it stands.
+`increment` is allowed too: outside a transaction it does the whole add in one
+step, under the variable's own lock when both sides are Fixnums, and as a one-off
+transaction otherwise.
+
+`Ractor::TransactionError` is raised for a transaction that cannot proceed;
+`Ractor::RetryTransaction` is what a rollback is made of.
+
+## When something else fits better
+
+* One variable, or a block that must not run twice:
+  [`Ractor::LockVar`](lockvar.md), which waits its turn instead of retrying.
+* State you do not want to freeze, a mutable object updated in place:
+  [`Ractor::ActorHash`](actor_hash.md) or [`Ractor::ActiveObject`](active_object.md).
+
+## Scaling
+
+**Reads outside a transaction cost nothing and scale.** Sixteen Ractors reading
+one shared TVar cost 9 ns per read, the same as sixteen reading their own, where
+the pessimistic [`Ractor::LockVar`](lockvar.md) costs 365 ns for the same thing
+because its read takes the lock. If your load is read heavy and the state is
+shared, this is the reason to be here.
+
+A read outside a transaction is a read of one slot. It is not a snapshot across
+several: two TVars that have to agree must be read inside one
+`Ractor.atomically`, the same way they are written.
+
+**Commits do not run in parallel.** Every committing transaction takes one
+process wide lock to allocate its version number, whichever variables it touched.
+Sixteen Ractors updating sixteen *unrelated* TVars get about 3.3× the throughput of
+one, where sixteen LockVars get 7.0×. On an update as small as `increment` there
+is no gain left at all: sixteen Ractors on sixteen TVars get no more throughput
+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*
+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
+off**, spinning about 100 ns per consecutive loss before running again, which
+trims the work thrown away in a storm and costs an occasionally contended write
+nothing measurable. That contended figure is the volatile one, landing anywhere
+from 500 to 870 ns between sweeps. The full tables are in
+[the README](../README.md#performance).
+
+Part of [ractor-sharing](../README.md).

data/ext/ractor/lock/extconf.rb

@@ -0,0 +1,2 @@
+require 'mkmf'
+create_makefile('ractor/lock')