ractor-sharing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88fa8b206f015cc52f9fb975060cd60ad960b4156a9b827aeb553a31ae34cf39
+  data.tar.gz: 00adc02e6a7c43bb44ec0c1b701bd3d8b6b1681df54cb3a4163a0b981a087da6
+SHA512:
+  metadata.gz: '0156339ebc1d6924032c142bd106036a9852c5564d01d25e4e198e7b5e11fc006bcfbdcfabe0ec3b26cb925acaa8c102f3690b7f05d5098d4cdf4b318967ee5b'
+  data.tar.gz: 7cdc6b398b61e1c202653116d6faad460f84a248d0867dde5905f27e6aee288278f91a3d16f0c4444316a4396105ade08a9562b7a8a064d6f627580ddc8e80cc

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koichi Sasada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,261 @@
+# ractor-sharing
+
+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.
+
+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.
+* **[`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.
+* **[`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.
+* **[`Ractor::ActorHash`](docs/actor_hash.md)** is a hash that lives in a Ractor
+  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.
+
+| | 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::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 |
+
+One uncontended operation from a single Ractor on 16 cores, replacing a frozen
+record. The two at the bottom also start a Ractor apiece, which runs until the
+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.
+
+```ruby
+require "ractor/sharing"        # all of them
+
+require "ractor/tvar"           # or one at a time
+require "ractor/lockvar"
+require "ractor/lockhash"
+require "ractor/active_object"
+require "ractor/actor_hash"
+```
+
+## Which one
+
+**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
+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 }
+```
+
+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.
+
+That retry is also what contention costs it. With sixteen Ractors on one variable
+a minimal block runs about 1.8 times per completed update, which is cheap enough
+that `TVar` is still the quickest thing here. The factor climbs with the length
+of the block, though: a few microseconds of work in there and it runs closer to
+five times, and most of the machine is doing work that gets thrown away. A
+variable that is both hot and not trivial to update is the case for `LockVar`
+below, which waits its turn and runs the block once.
+
+Everything below is a reason to leave `TVar` behind.
+
+**When the block must run exactly once: `LockVar`.** If the block has a side
+effect a retry would repeat, such as writing a line or sending a message, then
+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
+```
+
+**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.
+
+```ruby
+board = Ractor::LockHash.new
+board.synchronize {|b| b[:worker_1] = 42 }
+board.to_h #=> {worker_1: 42}
+```
+
+**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
+ordinary mutable Ruby object.
+
+Know what that costs. Each instance **starts a Ractor**, which lives until the
+process ends, since there is no way to stop one, so this is for a handful of
+long-lived objects, not for many small ones. And every call from another Ractor
+is a message round trip: a `sync` call is about **2.6 µs** from a worker Ractor,
+against **0.35 µs** for an uncontended `LockVar#update` on the same machine. An
+`async` call does not wait for the reply and costs about **1.6 µs**. Calls
+to one object are also serialized through its owner, so the object is a
+throughput limit as well as a home for the state. If your state does fit in a
+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]
+end
+```
+
+**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;
+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]
+```
+
+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`.
+
+
+## Performance
+
+The workload is one shared record, a frozen `{status:, seq:}`: a **read** takes it
+out, a **write** puts a new frozen one in its place. Nanoseconds for one
+operation, counted across all Ractors, on 16 cores.
+
+### Reading
+
+| | one Ractor (ns) | 16 on one object (ns) | 16 on their own (ns) |
+|---|---:|---:|---:|
+| `TVar#value` | 68 | **9** | 9 |
+| `LockVar#value` | 74 | 365 | 10 |
+| `LockHash#[]` | 132 | 489 | 23 |
+| `ActiveObject` sync method | 2300 | 1380 | 742 |
+| `ActorHash#[]` | 2179 | 1451 | 730 |
+| no sharing at all | 78 | n/a | 9 |
+
+**Reads of a shared object scale on `TVar` and do not on the two locks.** A
+`TVar` read outside a transaction takes nothing, so sixteen Ractors reading one
+`TVar` cost the same as sixteen reading their own. `LockVar#value` and
+`LockHash#[]` take the lock, so those sixteen readers stand in a queue: 365 ns
+against 9. Give each Ractor its own object and every one of them scales to the
+machine's limit.
+
+### Writing
+
+| | one Ractor (ns) | 16 on one object (ns) | 16 on their own (ns) |
+|---|---:|---:|---:|
+| `TVar` transaction | 351 | **509** | 108 |
+| `LockVar#update` | 352 | 1102 | **50** |
+| `LockHash#synchronize` | 433 | 1238 | 58 |
+| `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
+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
+volatile one: between sweeps it lands anywhere from 500 to 870 ns, so its row is
+the median of seven runs where every other cell is the median of three.
+**Spread out, the locks scale as far as the machine does and `TVar` does not**:
+7.0× for `LockVar` against 3.3×, because every committing transaction takes one
+process wide lock to allocate its version number. **Not waiting for the reply is
+worth 3× to 4× when the objects are spread out** on the two classes that keep a
+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×.
+
+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
+native thread to itself and waking it is a syscall.
+
+### Not increment
+
+`TVar#increment` and `LockVar#increment` each take a fast path that adds two
+Fixnums without running any Ruby, so a benchmark built on `increment` measures
+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 |
+
+`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
+before the clock starts, and every run is checked afterwards against the number
+of writes that went in, so a lost update cannot report itself as a fast run.
+These numbers are from ruby 4.1.0dev (master 69b49ac7ae) on 16 cores with the CPU
+governor fixed at `performance`.
+
+**Each cell is the median of three runs** (`REPS=3`), and how much to trust a
+small difference depends on the row. Between two independent sweeps the
+`TVar`, `LockVar` and `LockHash` cells moved by 0% to 10%, so their comparisons
+hold. The two async rows moved by 12% to 23%, which is why the claim above is 3×
+to 4× and not a figure with a decimal in it.
+
+## What is not here
+
+These classes hold state. They are not a way for Ractors to wait for each other.
+
+A Ractor waits in one place, `Ractor::Port#receive`, and that is the design, not
+an accident. Waiting for another Ractor to produce something, hand work over or
+reach a point is a conversation between them, and it is held in messages. So
+there is no queue here that several Ractors take work from, no barrier, no
+semaphore: those would be a second place to wait, and a rendezvous dressed up as
+a data structure.
+
+The one wait they make you do is for a lock, and even that is a `receive`: a
+thread that cannot take a lock parks on a `Ractor::Port` of its own until the
+holder sends it a wakeup. (Inside the extensions there are native mutexes, held
+for a few instructions and never across Ruby code, and `ActiveObject` waits on
+`Ractor.select` while its owner starts. Neither is a place your program waits.)
+
+## Requirements
+
+Ruby 4.0 or later (`Ractor::Port`, and Ractors that are worth using).
+
+## Development
+
+```
+rake            # compile both extensions and run every test
+```
+
+Documentation for each class is in [docs/](docs/).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/docs/active_object.md

@@ -0,0 +1,211 @@
+# Ractor::ActiveObject
+
+`Ractor::ActiveObject` runs the [Active Object pattern](https://en.wikipedia.org/wiki/Active_object)
+on Ractors: each instance's state is owned by a dedicated *owner Ractor*, and
+method calls from any other Ractor are forwarded to it and executed there one
+at a time. The model is "move the request to the data owner", not "move the
+data to the computation".
+
+From the user's point of view it is an ordinary Ruby class whose public
+interface is *published* with `sync` / `async` / `future`.
+
+```ruby
+require "ractor/active_object"
+
+class People < Ractor::ActiveObject
+  def initialize
+    @db = {}
+  end
+
+  async def add(name, age)   # fire-and-forget
+    @db[name] = age
+  end
+
+  sync def find(name)        # wait for the result
+    @db[name]
+  end
+
+  future def load_all         # returns a Future immediately
+    @db.dup
+  end
+end
+
+PEOPLE = People.new          # proxy is shareable: usable from any Ractor
+PEOPLE.add("ko1", 46)
+
+Ractor.new do
+  p PEOPLE.find("ko1")       # => 46
+  f = PEOPLE.load_all
+  p f.value                  # => {"ko1" => 46}
+end.join
+```
+
+Requires Ruby 4.0 or later (`Ractor::Port`).
+
+## What it costs
+
+Each instance starts a Ractor of its own, and that Ractor runs until the process
+ends: there is no shutdown. Creating active objects in a loop leaks them.
+
+Every `sync` call from another Ractor is a message round trip, about **2.6 µs**
+measured on 16 cores, where the same update on an uncontended
+`Ractor::LockVar` is **0.35 µs**. From the main Ractor rather than a worker it is
+**8.9 µs**, because that thread has a native thread to itself and waking it is a
+syscall. Calls to one object run one at a time on its owner, so a single hot
+object caps how fast callers get through it.
+
+**An `async` method is the one to reach for when nothing needs the answer**, since
+the round trip is most of the cost: sixteen Ractors with an object each get
+through `async` calls at **0.18 µs**, against 0.76 µs for the same method declared
+`sync`. Reads have to be `sync`, because the answer is the point.
+
+None of that applies to calls made *inside* the owner: those are plain Ruby
+calls. And if the state you are guarding fits in a shareable value,
+[`Ractor::LockVar`](lockvar.md) or [`Ractor::TVar`](tvar.md) will be much
+cheaper.
+
+## Invocation policies
+
+| modifier | explicit form          | caller waits? | returns              | exception                     |
+|----------|------------------------|---------------|----------------------|-------------------------------|
+| `sync`   | `obj.sync_send(m, …)`  | yes           | the method's result  | re-raised in the caller       |
+| `async`  | `obj.async_send(m, …)` | no            | `nil`                | `#on_async_exception` (owner) |
+| `future` | `obj.future_send(m, …)`| no            | `Future`             | raised by `Future#value`      |
+
+* `sync`, `async` and `future` are class-level DSL methods that take method
+  names, so they compose like `private`: `async def foo…`, `async :foo, :bar`,
+  `sync attr_reader :size`. Declaring a method *publishes* it on the proxy,
+  regardless of its visibility in the class.
+* **`Foo.new` returns a proxy (an instance of `Foo::Proxy`), not a `Foo`.**
+  The proxy has exactly the published methods plus `inspect` and `sync_send` / `async_send`
+  / `future_send`, `owner`, `owner?`, `active_object_class`. Undeclared methods
+  raise `NoMethodError` on the proxy; `*_send` can still reach them, like
+  `__send__`.
+* `*_send` always overrides the declared policy.
+* `Klass.invocation_policy(:name)` returns `:sync` / `:async` / `:future`
+  (or `nil` if not published); `Klass.proxy_class` is the proxy class.
+
+### Calls on the owner Ractor
+
+Inside the owner Ractor the object is a plain `Foo` instance (the *servant*):
+calls between its methods are ordinary Ruby calls, with no mailbox and no policy;
+`async` methods run immediately and return their real value. A proxy used
+inside its own owner Ractor (e.g. through a constant) also calls the servant
+directly. `owner?` tells you which side you are on; `owner` is the owner
+Ractor. A method that returns `self` hands the caller the proxy.
+
+### Ordering
+
+Requests from one thread are executed in the order they were sent, one at a
+time per object. A `sync` call therefore works as a barrier after `async`
+calls:
+
+```ruby
+class Cache < Ractor::ActiveObject
+  def initialize = @c = {}
+  async def set(k, v) = @c[k] = v
+  sync  def nop = nil
+end
+cache = Cache.new
+
+cache.set(:x, 1)        # async
+cache.sync_send(:nop)   # everything above has been applied
+```
+
+### Arguments and results
+
+Arguments and results cross Ractors with the normal `Ractor#send` semantics
+(copy, or share by reference if shareable). Values that cannot be sent raise
+`TypeError` at the caller (arguments) or come back as
+`Ractor::ActiveObject::Error` (results / exceptions), so a caller never hangs.
+Exceptions keep the owner-side backtrace, followed by the caller's frames.
+
+Blocks cannot be passed to remote invocations (`ArgumentError`); they work for
+calls made on the owner Ractor.
+
+`sync` calls take their reply port from a Ractor-local pool
+(`Ractor[:__ao_reply_ports__]`, an Array), so steady-state calls allocate no
+port. A port is owned exclusively by one caller while in use, so concurrent
+threads of a Ractor never see each other's replies; the pool grows to the
+number of concurrent callers. A port whose wait was interrupted (e.g. by
+`Timeout`) is discarded, never reused. `future` calls always get a fresh port.
+
+A caller waits on its reply port alone (`Port#receive`), not on
+`Ractor.select(reply, owner)`: watching the owner as well costs ≈4 % of a
+2.5 µs `sync` call. The owner is not expected to die, since its request loop
+rescues `Exception`, and if it does go down with a request in flight it
+answers that caller with an `ActiveObject::Error` from an `ensure`, while any
+later send fails fast with `Ractor::ClosedError` → `ActiveObject::Error`.
+
+The gap this leaves is a caller whose request was still queued when the owner
+died: it stays blocked in `receive`. Waking it would need either the
+per-call `Ractor.select`, or `Ractor#monitor` on the reply port, but
+`monitor` delivers a bare `:exited` that does not say which Ractor exited, so
+reply ports would have to be pooled per owner, and that bookkeeping costs the
+same ≈4 %. (`Port#close` is not an option: it cannot be called from another
+Ractor, and even from the owning Ractor it does not wake a thread already
+blocked in `receive`.) Both were measured and rejected.
+
+### Futures
+
+```ruby
+class Slow < Ractor::ActiveObject
+  future def compute(x) = x * 2
+end
+obj = Slow.new
+
+f = obj.future_send(:compute, 1)
+f.value       # waits; returns the result or raises the method's exception
+f.wait        # waits; returns self, never raises
+f.resolved?   # true once the result has been observed by #value / #wait
+f.rejected?
+```
+
+A `Future` can be consumed only in the Ractor that created it (its reply port
+belongs to that Ractor). Threads inside that Ractor may share it.
+
+### Async errors
+
+An exception raised by an `async` invocation is passed to
+`on_async_exception(exception, method_name)` on the owner. The default
+implementation prints a warning; override it to supervise:
+
+```ruby
+class Worker < Ractor::ActiveObject
+  def initialize = @failures = []
+  sync def failures = @failures.map(&:first)
+
+  def on_async_exception(e, name)
+    @failures << [name, e]
+  end
+end
+```
+
+### Lifecycle
+
+`Klass.new(*args, **kwargs)` starts the owner Ractor, runs `initialize` there
+(exceptions propagate to the caller) and returns a frozen, shareable proxy.
+The owner Ractor serves requests until the process exits. If it terminates
+for another reason, the in-flight call and every later call raise
+`Ractor::ActiveObject::Error`; requests already queued behind it, whose
+callers are blocked on their reply ports, are the one case that can hang.
+
+## Implementation notes and limitations
+
+* `Foo::Proxy` is created when `Foo` is defined (`Foo < Bar` gives
+  `Foo::Proxy < Bar::Proxy`, so published methods are inherited). Declaring a
+  method defines a forwarding method on the proxy class. A subclass that
+  overrides a published method keeps the parent's policy unless it declares
+  the method again.
+* The servant is untouched: no wrappers, `super` and private calls work as in
+  any Ruby class.
+* Subclasses must be defined in the main Ractor (class definition needs to
+  store class-level state, which non-main Ractors cannot do).
+* `proxy.is_a?(Foo)` is false; use `proxy.active_object_class` or
+  `Foo.proxy_class === proxy`.
+* `Future#ready?` (non-blocking check) is not provided: `Ractor::Port` has no
+  non-blocking receive.
+* Ruby prints "Ractor API is experimental" on the first `Ractor.new`; silence
+  it with `Warning[:experimental] = false` if you want.
+
+Part of [ractor-sharing](../README.md).

data/docs/actor_hash.md

@@ -0,0 +1,144 @@
+# Ractor::ActorHash
+
+A Hash kept by a Ractor of its own. Reading it is a question you ask; every
+change is work you send, and the work runs where the Hash is.
+
+```ruby
+require "ractor/actor_hash"
+
+h = Ractor::ActorHash.new
+h.async_call {|h| h[:hits] = (h[:hits] || 0) + 1 }   # send it and carry on
+h[:hits]                                             # ask
+```
+
+## Why not LockHash
+
+[`Ractor::LockHash`](lockhash.md) can only hold **shareable** values, so every
+change replaces a value with a frozen new one. Here the entries never leave the
+owner except as copies, so they can be anything, and a block changes them in
+place over there:
+
+```ruby
+h.async_call {|h| (h[:log] ||= []) << "a line" }   # a value it goes on appending to
+```
+
+The price is the owner: one Ractor per ActorHash, running until the process
+ends, and about **2.2 µs** for a round trip, where a LockHash operation is a few
+hundred **ns**. Reach for this one when the state genuinely will not be frozen;
+otherwise LockHash is far cheaper.
+
+A write that does not need an answer should be `async_call` or `set` rather than
+`call`: not waiting for the reply is worth about 3× on sixteen Ractors with a
+hash each (219 ns against 747) and under 2× on sixteen sharing one (1032 ns
+against 1740). Reads pay the full round trip regardless, since a read is the
+answer.
+
+## API
+
+```ruby
+h = Ractor::ActorHash.new(initial = nil)
+
+h[key]                 # read; an unshareable value comes back as a copy
+h.fetch(key)           # KeyError when missing; also fetch(key, default) and fetch(key) { }
+h.key?(key)
+h.keys / h.to_h        # a copy of the whole thing
+h.inspect
+
+h.set(key, value)                 # send a write; returns nil
+h.increment(key, by = 1)          # send an add; returns nil
+
+h.async_call  {|h, *args| ... }   # send it, do not wait; returns nil
+h.call        {|h, *args| ... }   # send it and wait; returns what the block returned
+h.future_call {|h, *args| ... }   # send it, get a Future straight away
+
+h.sync_send(:name, *args)         # the same three, by method name
+h.async_send(:name, *args)
+h.future_send(:name, *args)
+h.active_object_class             # Ractor::ActorHash
+```
+
+There is no `size` and no `empty?`, for the reason
+[`LockHash`](lockhash.md) has none: a count is stale by the time it reaches you.
+
+**What comes back is subject to the ordinary Ractor rules**, not always a copy: a
+shareable value crosses by reference, an unshareable but copyable one is copied,
+and one that cannot be moved or copied raises
+`Ractor::ActiveObject::Error`. The practical point stands, which is that mutating
+what you got back does not reach the owner's hash.
+
+There is no `h[key] = value`. A change is a message you send, and an assignment
+does not look like one; more to the point, having it invites the two round trips
+with a gap in the middle:
+
+```ruby
+h[:n] = h[:n] + 1              # not available, and it was a lost update
+h.increment(:n)                # one message, and you do not wait for it
+```
+
+`set` and `increment` are not shorthand for the block forms. **Their arguments
+travel as arguments**, so they are not held to what an isolated block may capture:
+
+```ruby
+key = :a
+key = :b                             # a local assigned more than once
+h.async_call {|h| h[key] = 1 }       # => Ractor::IsolationError
+h.set(key, 1)                        # fine
+```
+
+For anything else, such as deleting, clearing, or changing a value in place, send
+a block.
+
+`async` and `future` mean what they mean for
+[`Ractor::ActiveObject`](active_object.md), which this is built on: an exception
+in an `async_call` reaches `#on_async_exception` on the owner, and one in a
+`future_call` is raised by `Future#value`. Calls from one Ractor arrive in
+order, and the owner runs them one at a time, so an `async_call` has landed by
+the time the next call is answered.
+
+Prefer `async_call`. A change you do not need an answer to costs you nothing to
+send, where waiting costs the round trip.
+
+### What comes back is a copy
+
+```ruby
+h.async_call {|h| h[:list] = [1] }
+got = h[:list]
+got << 2          # changes the copy, not the Hash
+h[:list]          #=> [1]
+```
+
+That is the same bargain ETS makes, and it is what lets the values be mutable at
+all. To change one, change it where it lives.
+
+The block is handed the **real Hash**, not a copy and not a proxy, so every Hash
+method is there. It cannot escape either, since the block runs on the owner and
+anything returned is copied on the way back.
+
+### The block is isolated
+
+It crosses to another Ractor, so `Ractor.shareable_proc` has to accept it: it may
+read outer variables that are **never reassigned** anywhere in their scope, and
+everything else has to be passed as an argument.
+
+```ruby
+h.set(:total, 0)
+n = 10
+h.async_call {|h| h[:total] += n }         # fine: n is never reassigned
+h.async_call(10) {|h, n| h[:total] += n }  # always fine
+```
+
+"Never reassigned" is judged from the whole enclosing scope: one later assignment
+to `n` makes every block that reads it impossible to isolate.
+
+## Where it sits
+
+| | shareable values, no Ractor | any values, a Ractor of its own |
+|---|---|---|
+| one value | [`LockVar`](lockvar.md) | |
+| a hash | [`LockHash`](lockhash.md) | **`ActorHash`** |
+| your own class | | [`ActiveObject`](active_object.md) |
+
+`ActorHash` is an `ActiveObject` with the interface already chosen, and is built
+on one. Use `ActiveObject` directly when the state deserves methods of its own.
+
+Part of [ractor-sharing](../README.md).