Struct: keep direct reference to IMEMO/fields when space allows

It's not rare for structs to have additional ivars, hence are one
of the most common, if not the most common type in the `gen_fields_tbl`.

This can cause Ractor contention, but even in single ractor mode
means having to do a hash lookup to access the ivars, and increase
GC work.

Instead, unless the struct is perfectly right sized, we can store
a reference to the associated IMEMO/fields object right after the
last struct member.

```
compare-ruby: ruby 3.5.0dev (2025-08-06T12:50:36Z struct-ivar-fields-2 9a30d141a1) +PRISM [arm64-darwin24]
built-ruby: ruby 3.5.0dev (2025-08-06T12:57:59Z struct-ivar-fields-2 2ff3ec237f) +PRISM [arm64-darwin24]
warming up.....

|                      |compare-ruby|built-ruby|
|:---------------------|-----------:|---------:|
|member_reader         |    590.317k|  579.246k|
|                      |       1.02x|         -|
|member_writer         |    543.963k|  527.104k|
|                      |       1.03x|         -|
|member_reader_method  |    213.540k|  213.004k|
|                      |       1.00x|         -|
|member_writer_method  |    192.657k|  191.491k|
|                      |       1.01x|         -|
|ivar_reader           |    403.993k|  569.915k|
|                      |           -|     1.41x|
```

Co-Authored-By: Étienne Barrié <etienne.barrie@gmail.com>

Author: byroot

benchmark/struct_accessor.yml

@@ -1,5 +1,12 @@
 prelude: |
   C = Struct.new(:x) do
+    def initialize(...)
+      super
+      @ivar = 42
+    end
+
+    attr_accessor :ivar
+
     class_eval <<-END
       def r
         #{'x;'*256}
@@ -15,11 +22,16 @@ prelude: |
         m = method(:x=)
         #{'m.call(nil);'*256}
       end
+      def r_ivar
+        #{'ivar;'*256}
+      end
     END
   end
+  C.new(nil) # ensure common shape is known
   obj = C.new(nil)
 benchmark:
   member_reader: "obj.r"
   member_writer: "obj.w"
   member_reader_method: "obj.rm"
   member_writer_method: "obj.wm"
+  ivar_reader: "obj.r_ivar"

depend

@@ -6065,6 +6065,7 @@ hash.$(OBJEXT): $(top_srcdir)/internal/set_table.h
 hash.$(OBJEXT): $(top_srcdir)/internal/st.h
 hash.$(OBJEXT): $(top_srcdir)/internal/static_assert.h
 hash.$(OBJEXT): $(top_srcdir)/internal/string.h
+hash.$(OBJEXT): $(top_srcdir)/internal/struct.h
 hash.$(OBJEXT): $(top_srcdir)/internal/symbol.h
 hash.$(OBJEXT): $(top_srcdir)/internal/thread.h
 hash.$(OBJEXT): $(top_srcdir)/internal/time.h
@@ -6288,6 +6289,7 @@ hash.$(OBJEXT): {$(VPATH)}symbol.h
 hash.$(OBJEXT): {$(VPATH)}thread_$(THREAD_MODEL).h
 hash.$(OBJEXT): {$(VPATH)}thread_native.h
 hash.$(OBJEXT): {$(VPATH)}util.h
+hash.$(OBJEXT): {$(VPATH)}variable.h
 hash.$(OBJEXT): {$(VPATH)}vm_core.h
 hash.$(OBJEXT): {$(VPATH)}vm_debug.h
 hash.$(OBJEXT): {$(VPATH)}vm_opts.h
@@ -12926,6 +12928,7 @@ range.$(OBJEXT): $(top_srcdir)/internal/enumerator.h
 range.$(OBJEXT): $(top_srcdir)/internal/error.h
 range.$(OBJEXT): $(top_srcdir)/internal/fixnum.h
 range.$(OBJEXT): $(top_srcdir)/internal/gc.h
+range.$(OBJEXT): $(top_srcdir)/internal/imemo.h
 range.$(OBJEXT): $(top_srcdir)/internal/numeric.h
 range.$(OBJEXT): $(top_srcdir)/internal/range.h
 range.$(OBJEXT): $(top_srcdir)/internal/serial.h
@@ -12948,6 +12951,7 @@ range.$(OBJEXT): {$(VPATH)}config.h
 range.$(OBJEXT): {$(VPATH)}defines.h
 range.$(OBJEXT): {$(VPATH)}encoding.h
 range.$(OBJEXT): {$(VPATH)}id.h
+range.$(OBJEXT): {$(VPATH)}id_table.h
 range.$(OBJEXT): {$(VPATH)}intern.h
 range.$(OBJEXT): {$(VPATH)}internal.h
 range.$(OBJEXT): {$(VPATH)}internal/abi.h
@@ -15580,6 +15584,7 @@ shape.$(OBJEXT): $(top_srcdir)/internal/serial.h
 shape.$(OBJEXT): $(top_srcdir)/internal/set_table.h
 shape.$(OBJEXT): $(top_srcdir)/internal/static_assert.h
 shape.$(OBJEXT): $(top_srcdir)/internal/string.h
+shape.$(OBJEXT): $(top_srcdir)/internal/struct.h
 shape.$(OBJEXT): $(top_srcdir)/internal/symbol.h
 shape.$(OBJEXT): $(top_srcdir)/internal/variable.h
 shape.$(OBJEXT): $(top_srcdir)/internal/vm.h
@@ -16569,6 +16574,7 @@ string.$(OBJEXT): $(top_srcdir)/internal/serial.h
 string.$(OBJEXT): $(top_srcdir)/internal/set_table.h
 string.$(OBJEXT): $(top_srcdir)/internal/static_assert.h
 string.$(OBJEXT): $(top_srcdir)/internal/string.h
+string.$(OBJEXT): $(top_srcdir)/internal/struct.h
 string.$(OBJEXT): $(top_srcdir)/internal/transcode.h
 string.$(OBJEXT): $(top_srcdir)/internal/variable.h
 string.$(OBJEXT): $(top_srcdir)/internal/vm.h
@@ -16766,6 +16772,7 @@ string.$(OBJEXT): {$(VPATH)}thread.h
 string.$(OBJEXT): {$(VPATH)}thread_$(THREAD_MODEL).h
 string.$(OBJEXT): {$(VPATH)}thread_native.h
 string.$(OBJEXT): {$(VPATH)}util.h
+string.$(OBJEXT): {$(VPATH)}variable.h
 string.$(OBJEXT): {$(VPATH)}vm_core.h
 string.$(OBJEXT): {$(VPATH)}vm_debug.h
 string.$(OBJEXT): {$(VPATH)}vm_opts.h
@@ -18103,6 +18110,7 @@ variable.$(OBJEXT): $(top_srcdir)/internal/serial.h
 variable.$(OBJEXT): $(top_srcdir)/internal/set_table.h
 variable.$(OBJEXT): $(top_srcdir)/internal/static_assert.h
 variable.$(OBJEXT): $(top_srcdir)/internal/string.h
+variable.$(OBJEXT): $(top_srcdir)/internal/struct.h
 variable.$(OBJEXT): $(top_srcdir)/internal/symbol.h
 variable.$(OBJEXT): $(top_srcdir)/internal/thread.h
 variable.$(OBJEXT): $(top_srcdir)/internal/variable.h

gc.c

@@ -3260,6 +3260,10 @@ rb_gc_mark_children(void *objspace, VALUE obj)
             gc_mark_internal(ptr[i]);
         }
 
+        if (!FL_TEST_RAW(obj, RSTRUCT_GEN_FIELDS)) {
+            gc_mark_internal(RSTRUCT_FIELDS_OBJ(obj));
+        }
+
         break;
       }
 
@@ -4188,6 +4192,15 @@ rb_gc_update_object_references(void *objspace, VALUE obj)
             for (i = 0; i < len; i++) {
                 UPDATE_IF_MOVED(objspace, ptr[i]);
             }
+
+            if (RSTRUCT_EMBED_LEN(obj)) {
+                if (!FL_TEST_RAW(obj, RSTRUCT_GEN_FIELDS)) {
+                    UPDATE_IF_MOVED(objspace, ptr[len]);
+                }
+            }
+            else {
+                UPDATE_IF_MOVED(objspace, RSTRUCT(obj)->as.heap.fields_obj);
+            }
         }
         break;
       default:

internal/struct.h

@@ -11,10 +11,23 @@
 #include "ruby/internal/stdbool.h"     /* for bool */
 #include "ruby/ruby.h"          /* for struct RBasic */
 
+/* Flags of RStruct
+ *
+ * 1-7: RSTRUCT_EMBED_LEN
+ *          If non-zero, the struct is embedded (its contents follow the
+ *          header, rather than being on a separately allocated buffer) and
+ *          these bits are the length of the Struct.
+ * 8:   RSTRUCT_GEN_FIELDS
+ *          The struct is embedded and has no space left to store the
+ *          IMEMO/fields reference. Any ivar this struct may have will be in
+ *          the generic_fields_tbl. This flag doesn't imply the struct has
+ *          ivars.
+ */
 enum {
     RSTRUCT_EMBED_LEN_MASK = RUBY_FL_USER7 | RUBY_FL_USER6 | RUBY_FL_USER5 | RUBY_FL_USER4 |
                                  RUBY_FL_USER3 | RUBY_FL_USER2 | RUBY_FL_USER1,
     RSTRUCT_EMBED_LEN_SHIFT = (RUBY_FL_USHIFT+1),
+    RSTRUCT_GEN_FIELDS = RUBY_FL_USER8,
 };
 
 struct RStruct {
@@ -23,6 +36,7 @@ struct RStruct {
         struct {
             long len;
             const VALUE *ptr;
+            VALUE fields_obj;
         } heap;
         /* This is a length 1 array because:
          *   1. GCC has a bug that does not optimize C flexible array members
@@ -116,4 +130,31 @@ RSTRUCT_GET(VALUE st, long k)
     return RSTRUCT_CONST_PTR(st)[k];
 }
 
+static inline VALUE
+RSTRUCT_FIELDS_OBJ(VALUE st)
+{
+    const long embed_len = RSTRUCT_EMBED_LEN(st);
+    VALUE fields_obj;
+    if (embed_len) {
+        RUBY_ASSERT(!FL_TEST_RAW(st, RSTRUCT_GEN_FIELDS));
+        fields_obj = RSTRUCT_GET(st, embed_len);
+    }
+    else {
+        fields_obj = RSTRUCT(st)->as.heap.fields_obj;
+    }
+    return fields_obj;
+}
+
+static inline void
+RSTRUCT_SET_FIELDS_OBJ(VALUE st, VALUE fields_obj)
+{
+    const long embed_len = RSTRUCT_EMBED_LEN(st);
+    if (embed_len) {
+        RUBY_ASSERT(!FL_TEST_RAW(st, RSTRUCT_GEN_FIELDS));
+        RSTRUCT_SET(st, embed_len, fields_obj);
+    }
+    else {
+        RB_OBJ_WRITE(st, &RSTRUCT(st)->as.heap.fields_obj, fields_obj);
+    }
+}
 #endif /* INTERNAL_STRUCT_H */

struct.c

@@ -811,13 +811,22 @@ struct_alloc(VALUE klass)
 {
     long n = num_members(klass);
     size_t embedded_size = offsetof(struct RStruct, as.ary) + (sizeof(VALUE) * n);
+    if (RCLASS_MAX_IV_COUNT(klass) > 0) {
+        embedded_size += sizeof(VALUE);
+    }
+
     VALUE flags = T_STRUCT | (RGENGC_WB_PROTECTED_STRUCT ? FL_WB_PROTECTED : 0);
 
     if (n > 0 && rb_gc_size_allocatable_p(embedded_size)) {
         flags |= n << RSTRUCT_EMBED_LEN_SHIFT;
 
         NEWOBJ_OF(st, struct RStruct, klass, flags, embedded_size, 0);
-
+        if (RCLASS_MAX_IV_COUNT(klass) == 0 && embedded_size == rb_gc_obj_slot_size((VALUE)st)) {
+            FL_SET_RAW((VALUE)st, RSTRUCT_GEN_FIELDS);
+        }
+        else {
+            RSTRUCT_SET_FIELDS_OBJ((VALUE)st, 0);
+        }
         rb_mem_clear((VALUE *)st->as.ary, n);
 
         return (VALUE)st;

test/ruby/test_object_id.rb

@@ -252,3 +252,52 @@ def initialize
     end;
   end
 end
+
+class TestObjectIdStruct < TestObjectId
+  EmbeddedStruct = Struct.new(:embedded_field)
+
+  def setup
+    @obj = EmbeddedStruct.new
+  end
+end
+
+class TestObjectIdStructGenIvar < TestObjectId
+  GenIvarStruct = Struct.new(:a, :b, :c)
+
+  def setup
+    @obj = GenIvarStruct.new
+  end
+end
+
+class TestObjectIdStructNotEmbed < TestObjectId
+  MANY_IVS = 80
+
+  StructNotEmbed = Struct.new(*MANY_IVS.times.map { |i| :"field_#{i}" })
+
+  def setup
+    @obj = StructNotEmbed.new
+  end
+end
+
+class TestObjectIdStructTooComplex < TestObjectId
+  StructTooComplex = Struct.new(:a) do
+    def initialize
+      @too_complex_obj_id_test = 1
+    end
+  end
+
+  def setup
+    if defined?(RubyVM::Shape::SHAPE_MAX_VARIATIONS)
+      assert_equal 8, RubyVM::Shape::SHAPE_MAX_VARIATIONS
+    end
+    8.times do |i|
+      StructTooComplex.new.instance_variable_set("@TestObjectIdStructTooComplex#{i}", 1)
+    end
+    @obj = StructTooComplex.new
+    @obj.instance_variable_set("@a#{rand(10_000)}", 1)
+
+    if defined?(RubyVM::Shape)
+      assert_predicate(RubyVM::Shape.of(@obj), :too_complex?)
+    end
+  end
+end

test/ruby/test_ractor.rb

@@ -99,6 +99,24 @@ class TestClass
     RUBY
   end
 
+  def test_struct_instance_variables
+    assert_ractor(<<~'RUBY')
+      StructIvar = Struct.new(:member) do
+        def initialize(*)
+          super
+          @ivar = "ivar"
+        end
+        attr_reader :ivar
+      end
+      obj = StructIvar.new("member")
+      obj_copy = Ractor.new { Ractor.receive }.send(obj).value
+      assert_equal obj.ivar, obj_copy.ivar
+      refute_same obj.ivar, obj_copy.ivar
+      assert_equal obj.member, obj_copy.member
+      refute_same obj.member, obj_copy.member
+    RUBY
+  end
+
   def test_fork_raise_isolation_error
     assert_ractor(<<~'RUBY')
       ractor = Ractor.new do