In Ruby, what makes an object Ractor-shareable, and how do Ractor.make_shareable and the shareable_constant_value comment fix a constant Ractors cannot read?

## The problem: a constant a worker cannot read Suppose the image-hash workers share a table of thresholds: ```ruby THRESHOLDS = { sharp: [0.8, 0.9], blurry: [0.1, 0.3] } r = Ractor.new { THRESHOLDS[:sharp].first } r.value # raises Ractor::RemoteError, cause: Ractor::IsolationError ``` The main Ractor can read `THRESHOLDS`, but a non-main Ractor may read a constant only if it refers to a **shareable** object, and this Hash is mutable. The error message says it can not access non-shareable objects in constant `Object::THRESHOLDS` by non-main Ractor. ## What shareable means `Ractor.shareable?(obj)` answers the question. An object is shareable when any number of Ractors can use it at once without risk: - **Always shareable:** Integers, Floats, Rationals, Complex numbers, Symbols, `nil`, `true`, `false`. - **Shareable by nature:** `Class` and `Module` objects and `Ractor` objects. - **Shareable when deeply frozen:** a String, Array, Hash, Struct or ordinary object is shareable only if it is frozen **and** every object it refers to (elements, keys, values, instance variables) is shareable too. ```ruby Ractor.shareable?("gray".freeze) # => true Ractor.shareable?(["gray".freeze, [1]].freeze) # => false, [1] is mutable Ractor.shareable?({ mode: :fast }.freeze) # => true ``` The trap is that `freeze` is shallow: freezing the outer Hash does not freeze the arrays inside it. ## Ractor.make_shareable `Ractor.make_shareable(obj, copy: false)` walks the object graph and makes it shareable: | Call | Original object | Returns | |---|---|---| | `Ractor.make_shareable(obj)` | frozen in place, together with everything it references | the same object | | `Ractor.make_shareable(obj, copy: true)` | left unchanged and still mutable | a deep-frozen copy | Parts that are already shareable are skipped. If something in the graph cannot be made shareable, for example an object whose class comes from a C extension that does not support it, the call raises `Ractor::Error`. Because the default mode freezes in place, calling it on an object that other code still mutates will break that code with `FrozenError`; `copy: true` avoids that at the cost of a copy. ```ruby THRESHOLDS = Ractor.make_shareable( { sharp: [0.8, 0.9], blurry: [0.1, 0.3] } ) Ractor.new { THRESHOLDS[:sharp].first }.value # => 0.8 ``` ## The shareable_constant_value magic comment Wrapping every constant is noisy, so Ruby provides a magic comment, `# shareable_constant_value:`, with four modes: 1. **`none`** (the default): no special treatment. 2. **`literal`**: a constant assigned a literal (and the literals nested in it) is deep-frozen; any other value must already be shareable, or Ruby raises `Ractor::IsolationError` ("cannot assign unshareable object to X"). 3. **`experimental_everything`**: every value assigned to a constant goes through `Ractor.make_shareable`, which can deep-freeze objects that belong to someone else, such as a gem's constant. 4. **`experimental_copy`**: every value is deep-copied and then made shareable, leaving the source alone. ```ruby # shareable_constant_value: literal THRESHOLDS = { sharp: [0.8, 0.9], blurry: [0.1, 0.3] } # deep-frozen CACHE = Object.new # raises Ractor::IsolationError at assignment ``` The directive applies to constants that follow it in the current scope and can appear more than once in a file. `Module#const_set` is not affected by it. ## Diagnosing it in practice When a Ractor fails, the caller sees `Ractor::RemoteError`; the useful information is in its `cause`: 1. Rescue `Ractor::RemoteError` around `value` or `join` and print `e.cause.class` and `e.cause.message`. 2. If the cause is `Ractor::IsolationError` and the message names a constant, check that constant with `Ractor.shareable?` in the main Ractor. 3. Walk its contents: the culprit is usually one nested mutable String, Array or Hash, or an object with a mutable instance variable. ## Choosing a fix - Prefer **`literal` mode** in files that define lookup tables for Ractor code: it freezes what should be frozen and fails loudly on anything else. - Use **`make_shareable`** for values built at runtime, and **`copy: true`** when the original must stay mutable. - If a constant holds a truly mutable cache, freezing it is the wrong fix: give each Ractor its own copy, or keep the cache in one Ractor and ask it over a port.