Issue #21962 has been updated by Eregon (Benoit Daloze). This was discussed at the last dev meeting: https://github.com/ruby/dev-meeting-log/blob/master/2026/DevMeeting-2026-11-... I'm confused because IIRC twice matz agreed to the exact semantics proposed by this issue description (freeze all references, but never freeze modules & classes because that just breaks things), or with tiny tweaks. But somehow after that agreement somehow other things were discussed like `freeze_rec` and there was no clear conclusion at the dev meeting. `freeze_rec`/`freeze_elements` is I believe a separate proposal, and doesn't address many of the general use case (freezing an object graph/making objects immutable) or concrete use cases listed in https://bugs.ruby-lang.org/issues/21962#note-9. So I think we should let that be its own ticket, and not stand in the way of this one. Similarly the idea of a protocol was brought back, I think we already established at the RubyKaigi dev meeting this is too complex, slow, error-prone (easy to forget freezing ivars), and doesn't bring enough benefits. For cases which want "some objects frozen but not all" that's a use case outside `deep_freeze`, where manual freezing is required. About `T_DATA` objects after further thought I see no reason to treat them specially, I believe we should just freeze all references from there (as if using `ObjectSpace.reachable_objects_from`). We can optimize well-known builtin classes to use something more efficient. Finally a use case I care a lot about and I believe @headius too, see [here](https://bugs.ruby-lang.org/issues/21665#Proposal-Introduce-Objectdeep_freeze...), is we have seen people use `Ractor.make_shareable` to make an object graph / the value of a constant immutable, even though what they intended is unrelated to Ractor (for example, they want to make sure objects in a constant in a gem is never mutated, and it's safe to never recompute something depending on that). They use `Ractor.make_shareable` because that's in core, and there is no `deep_freeze` yet in core. But that's awkward for many reasons: * The intention is "freeze deeply"/"make immutable", yet `Ractor.make_shareable` has neither concept in its name * `Ractor.make_shareable` has different semantics, notably for Proc's, which are undesirable for deep freezing. * `Ractor.make_shareable` is very long, `A = [...].deep_freeze` is more idiomatic and natural. * `.deep_freeze` is still helpful for Ractor compatibility, as most objects graphs made immutable by `deep_freeze` will work just fine with Ractors. ---------------------------------------- Feature #21962: Add deep_freeze for recursive freezing https://bugs.ruby-lang.org/issues/21962#change-120180 * Author: Eregon (Benoit Daloze) * Status: Open ---------------------------------------- ### Motivation It is common to want some data structure to be immutable, e.g. to ensure it doesn't get mutated by multiple threads. See the first section of #21665 for a more detailed motivation, the summary is there is long-standing demand for it (back to #17145) for many reasons. One way/workaround to do this currently is `Ractor.make_shareable` but its name suggests a Ractor-specific purpose. The functionality of deeply freezing is separate from Ractor and it is generally useful. `Ractor.make_shareable` almost has the right semantics and has been used for years so this proposal largely follows its semantics rather than reinventing the wheel. The semantics also match the `ice_nine` gem, which further illustrates these semantics work well in practice and are expected. ### Examples It freezes deeply: ```ruby config = { db: { host: ENV["HOST"], ports: [5432] }, flags: [:a, :b] }.deep_freeze config.frozen? # => true config[:db].frozen? # => true config[:db][:host].frozen? # => true config[:db][:ports].frozen? # => true ``` Modules and classes are not frozen by `deep_freeze`: ```ruby String.deep_freeze String.frozen? # => false ``` It works for cyclic references: ```ruby a = [] a << a a.deep_freeze a.frozen? # => true ``` It calls `.freeze` on each object: ```ruby class Stats def initialize(samples) @samples = samples @mean = nil end def mean @mean ||= @samples.sum / @samples.size.to_f end def freeze mean super end end s = Stats.new([1.0, 2.0, 3.0]) s.deep_freeze s.mean # => 2.0, would raise FrozenError instead if overridden #freeze was not called ``` ### Background #21665 relaunched the discussion about `deep_freeze` and it was [discussed in a dev meeting](https://github.com/ruby/dev-meeting-log/blob/master/2025/DevMeeting-2025-11-...). @headius has said he won't have time to look at it soon. So I am proposing something concrete which hopefully can be approved as-is. ### Design * Proposed: `Kernel#deep_freeze`. Alternative: `Object.deep_freeze`. * `Kernel#deep_freeze` is consistent with `Kernel#freeze`. * `[a, b, c].deep_freeze` is nicer, more concise and more idiomatic than `Object.deep_freeze([a, b, c])`. * The proposal focuses on semantics; the exact method name and owner can be decided separately. * The return value is the receiver. * `deep_freeze` never freezes modules and classes and does not visit their internal references * Same as `Ractor.make_shareable` and `IceNine.deep_freeze` * No unexpected breakage because a class, its ancestors, their constants, etc all got frozen. * Very easy to explain in the documentation. * If people want to freeze classes/modules (rare case) they can with `.freeze` and have control and can decide whether to freeze the ancestors, constants, class variables, etc. * `deep_freeze` calls `freeze` and ensures every object is frozen * Same as `Ractor.make_shareable` and `IceNine.deep_freeze` * The already well-known hook to e.g. compute lazy caches eagerly, etc * We still check that `.freeze` did freeze the object, and raise a `RuntimeError` if not (same behavior and error message as `Ractor.make_shareable`). * Not a protocol of defining `deep_freeze` in many classes. * That does not work with circular references. * No need to invent a complex protocol when there is an existing working one (calling `.freeze`) which has proven to work well (by being used by `Ractor.make_shareable`). * Handling circular references by maintaining internally a set of visited objects to avoid walking circular references multiple times * As done in `obj_traverse_i` in `ractor.c`. * No expectation for calling `deep_freeze` repeatedly on the same object to be fast * An object flag wouldn't work for this, for the case that `freeze` raises an exception. * If some `freeze` method raises an exception, the exception is propagated. * Same as `Ractor.make_shareable` and `IceNine.deep_freeze` * Some objects visited before the exception may already be frozen, same as `Ractor.make_shareable` (unavoidable because we need to call `freeze` as we traverse the object graph). * `deep_freeze` does not stop at already-frozen objects, because they may still reference unfrozen objects. * No special treatment for shareable objects, they are frozen too. I think this addresses all the points mentioned in the [dev meeting discussion](https://github.com/ruby/dev-meeting-log/blob/master/2025/DevMeeting-2025-11-...) and in #21665 and in #17145. The traversal and freezing behavior closely follows `Ractor.make_shareable`, without introducing new semantics. ### Implementation The implementation in CRuby would be shared with `Ractor.make_shareable`, `ractor.c` already provides `rb_obj_traverse()` which is a great fit to implement this. From a high-level view the implementation works like this: `deep_freeze` recursively traverses the reachable object graph from the receiver. For each visited object: * If it is a `Class` or `Module`, it is not frozen and its internal references are not traversed. * Otherwise, Ruby calls `.freeze` on the object. * After calling `freeze`, Ruby verifies that the object is frozen. If it is not frozen, an exception is raised (same behavior and error message as `Ractor.make_shareable`). * The traversal keeps a visited set to avoid infinite recursion on cycles. ### Non-goals This proposal is focused on defining `deep_freeze` and nothing else: * This proposal does not define a new protocol requiring classes to implement custom recursive logic. * This proposal does not change `Ractor.make_shareable`. * This proposal does not freeze classes or modules. * This proposal does not attempt to define immutability as a broader language concept. ### Compatibility and risk * The proposal adds a new API and does not change existing `freeze` behavior. * It intentionally reuses existing `freeze` overrides on user objects. * It intentionally does not freeze classes/modules to avoid surprising breakage. * Its semantics are close to existing `Ractor.make_shareable`, reducing implementation risk. ### Relation to existing methods * `freeze`: freezes only the receiver (shallow). * `deep_freeze`: recursively freezes reachable objects. * `Ractor.make_shareable`: recursively freezes reachable objects except if they are already shareable. Special handling to make some objects shareable. -- https://bugs.ruby-lang.org/