From a51b4a86fc847e02f294b360a03d69797b8d7c18 Mon Sep 17 00:00:00 2001
From: Daisuke Aritomo <osyoyu@osyoyu.com>
Date: Fri, 9 May 2025 00:09:37 +0900
Subject: [PATCH] [DOC] ObjectSpace#each_object behavior in multi-Ractor mode

This behavior of ObjectSpace#each_object has been around since Ruby 3.0
when Ractors were first introduced, but was never documented and has
caused some amount of confusion:

https://bugs.ruby-lang.org/issues/17360
https://bugs.ruby-lang.org/issues/19387
https://bugs.ruby-lang.org/issues/21149
---
 gc.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/gc.c b/gc.c
index 179a85b200..418298a710 100644
--- a/gc.c
+++ b/gc.c
@@ -1545,6 +1545,17 @@ os_obj_of(VALUE of)
  *     2.2250738585072e-308
  *     Total count: 7
  *
+ *  When the process is in multi-Ractor mode (when <code>Ractor.new</code>
+ *  has been called within the process at least once), this method yields
+ *  Ractor-shareable objects only.
+ *
+ *     a = 12345678987654321 # shareable
+ *     b = [].freeze # shareable
+ *     c = {} # not shareable
+ *     ObjectSpace.each_object {|x| x } # yields a, b, and c
+ *     Ractor.new {} # enter multi-Ractor mode
+ *     ObjectSpace.each_object {|x| x } # does not yield c
+ *
  */
 
 static VALUE