perf(stable-api): inline rhash_size for MRI stable versions

ianks · ianks · commit 59d517579664 · 2026-04-23T08:28:59.000-04:00
Read RHash AR-table size directly from RBasic.flags (one mask+shift) and
ST-table size from st_table.num_entries (one deref), replacing the
rb_hash_size dylib call. Handles the 3.3+ layout change where st_table
is embedded at sizeof(RHash) rather than behind a pointer.

Rust: 4 instructions  C (RHASH_SIZE): 3 instructions
diff --git a/crates/rb-sys-tests/src/stable_api_test.rs b/crates/rb-sys-tests/src/stable_api_test.rs
@@ -1667,7 +1667,28 @@ parity_test!(
     func: rhash_size,
     data_factory: {
         ruby_eval!("{}")
-    }
+    },
+    expected: 0
+);
+
+parity_test!(
+    name: test_rhash_size_ar_mode,
+    func: rhash_size,
+    data_factory: {
+        // Small hash — typically uses AR table (up to 8 entries)
+        ruby_eval!("{a: 1, b: 2}")
+    },
+    expected: 2
+);
+
+parity_test!(
+    name: test_rhash_size_st_mode,
+    func: rhash_size,
+    data_factory: {
+        // Large hash — forces ST table (> 8 entries)
+        ruby_eval!("(1..20).each_with_object({}) { |i, h| h[i] = i }")
+    },
+    expected: 20
 );
 
 #[rb_sys_test_helpers::ruby_test]
@@ -1685,7 +1706,17 @@ parity_test!(
     func: rhash_empty_p,
     data_factory: {
         ruby_eval!("{}")
-    }
+    },
+    expected: true
+);
+
+parity_test!(
+    name: test_rhash_empty_p_nonempty,
+    func: rhash_empty_p,
+    data_factory: {
+        ruby_eval!("{a: 1}")
+    },
+    expected: false
 );
 
 #[rb_sys_test_helpers::ruby_test]
diff --git a/crates/rb-sys/src/stable_api/ruby_2_7.rs b/crates/rb-sys/src/stable_api/ruby_2_7.rs
@@ -536,21 +536,49 @@ impl StableApiDefinition for Definition {
         unsafe { crate::rb_float_new(val) }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_size(&self, obj: VALUE) -> usize {
-        // Call rb_hash_size which returns a fixnum VALUE
-        let size_val = crate::rb_hash_size(obj);
-        // Convert fixnum to usize
-        if self.fixnum_p(size_val) {
-            // FIX2LONG: shift right by 1 to get the actual value
-            (size_val >> 1) as usize
+        // Ruby 2.7 RHash layout:
+        //   struct RHash { RBasic basic; union { st_table *st; ar_table *ar; } as; VALUE ifnone; };
+        //
+        // AR mode (RUBY_FL_USER3 not set): size is packed in
+        //   RBasic.flags bits [USER4..USER7] >> 16 (= FL_USHIFT+4).
+        // ST mode (RUBY_FL_USER3 set): dereference the st_table pointer in
+        //   RHash.as and read st_table.num_entries directly.
+        //
+        // SAFETY: caller guarantees obj is a valid T_HASH VALUE.
+        #[repr(C)]
+        struct RHashPre33 {
+            basic: crate::RBasic,
+            st: *mut crate::st_table, // union { st_table *st; ar_table *ar; } — same size
+            ifnone: VALUE,
+        }
+
+        let rhash = obj as *const RHashPre33;
+        let flags = (*rhash).basic.flags;
+
+        // RHASH_ST_TABLE_FLAG = FL_USER3 = 32768
+        let st_flag = crate::ruby_fl_type::RUBY_FL_USER3 as VALUE;
+        if (flags & st_flag) == 0 {
+            // AR mode: size encoded in bits [USER4..USER7].
+            // RHASH_AR_TABLE_SIZE_MASK = FL_USER4|FL_USER5|FL_USER6|FL_USER7 = 0x000F_0000
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16
+            let mask: VALUE = (crate::ruby_fl_type::RUBY_FL_USER4 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER5 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER6 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER7 as VALUE);
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16 (stable across all Ruby versions)
+            let shift = 16u32;
+            ((flags & mask) >> shift) as usize
         } else {
-            // Fallback for large hashes (shouldn't normally happen)
-            crate::rb_num2ulong(size_val) as usize
+            // ST mode: dereference the st_table pointer and read num_entries.
+            // SAFETY: the st pointer is valid when RHASH_ST_TABLE_FLAG is set.
+            let st = (*rhash).st;
+            (*st).num_entries as usize
         }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool {
         self.rhash_size(obj) == 0
     }
diff --git a/crates/rb-sys/src/stable_api/ruby_3_0.rs b/crates/rb-sys/src/stable_api/ruby_3_0.rs
@@ -539,21 +539,49 @@ impl StableApiDefinition for Definition {
         unsafe { crate::rb_float_new(val) }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_size(&self, obj: VALUE) -> usize {
-        // Call rb_hash_size which returns a fixnum VALUE
-        let size_val = crate::rb_hash_size(obj);
-        // Convert fixnum to usize
-        if self.fixnum_p(size_val) {
-            // FIX2LONG: shift right by 1 to get the actual value
-            (size_val >> 1) as usize
+        // Ruby 3.0 RHash layout (pre-3.3):
+        //   struct RHash { RBasic basic; union { st_table *st; ar_table *ar; } as; VALUE ifnone; };
+        //
+        // AR mode (RUBY_FL_USER3 not set): size is packed in
+        //   RBasic.flags bits [USER4..USER7] >> 16 (= FL_USHIFT+4).
+        // ST mode (RUBY_FL_USER3 set): dereference the st_table pointer in
+        //   RHash.as and read st_table.num_entries directly.
+        //
+        // SAFETY: caller guarantees obj is a valid T_HASH VALUE.
+        #[repr(C)]
+        struct RHashPre33 {
+            basic: crate::RBasic,
+            st: *mut crate::st_table, // union { st_table *st; ar_table *ar; } — same size
+            ifnone: VALUE,
+        }
+
+        let rhash = obj as *const RHashPre33;
+        let flags = (*rhash).basic.flags;
+
+        // RHASH_ST_TABLE_FLAG = FL_USER3 = 32768
+        let st_flag = crate::ruby_fl_type::RUBY_FL_USER3 as VALUE;
+        if (flags & st_flag) == 0 {
+            // AR mode: size encoded in bits [USER4..USER7].
+            // RHASH_AR_TABLE_SIZE_MASK = FL_USER4|FL_USER5|FL_USER6|FL_USER7 = 0x000F_0000
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16
+            let mask: VALUE = (crate::ruby_fl_type::RUBY_FL_USER4 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER5 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER6 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER7 as VALUE);
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16 (stable across all Ruby versions)
+            let shift = 16u32;
+            ((flags & mask) >> shift) as usize
         } else {
-            // Fallback for large hashes (shouldn't normally happen)
-            crate::rb_num2ulong(size_val) as usize
+            // ST mode: dereference the st_table pointer and read num_entries.
+            // SAFETY: the st pointer is valid when RHASH_ST_TABLE_FLAG is set.
+            let st = (*rhash).st;
+            (*st).num_entries as usize
         }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool {
         self.rhash_size(obj) == 0
     }
diff --git a/crates/rb-sys/src/stable_api/ruby_3_1.rs b/crates/rb-sys/src/stable_api/ruby_3_1.rs
@@ -532,21 +532,49 @@ impl StableApiDefinition for Definition {
         unsafe { crate::rb_float_new(val) }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_size(&self, obj: VALUE) -> usize {
-        // Call rb_hash_size which returns a fixnum VALUE
-        let size_val = crate::rb_hash_size(obj);
-        // Convert fixnum to usize
-        if self.fixnum_p(size_val) {
-            // FIX2LONG: shift right by 1 to get the actual value
-            (size_val >> 1) as usize
+        // Ruby 3.1 RHash layout (pre-3.3):
+        //   struct RHash { RBasic basic; union { st_table *st; ar_table *ar; } as; VALUE ifnone; };
+        //
+        // AR mode (RUBY_FL_USER3 not set): size is packed in
+        //   RBasic.flags bits [USER4..USER7] >> 16 (= FL_USHIFT+4).
+        // ST mode (RUBY_FL_USER3 set): dereference the st_table pointer in
+        //   RHash.as and read st_table.num_entries directly.
+        //
+        // SAFETY: caller guarantees obj is a valid T_HASH VALUE.
+        #[repr(C)]
+        struct RHashPre33 {
+            basic: crate::RBasic,
+            st: *mut crate::st_table, // union { st_table *st; ar_table *ar; } — same size
+            ifnone: VALUE,
+        }
+
+        let rhash = obj as *const RHashPre33;
+        let flags = (*rhash).basic.flags;
+
+        // RHASH_ST_TABLE_FLAG = FL_USER3 = 32768
+        let st_flag = crate::ruby_fl_type::RUBY_FL_USER3 as VALUE;
+        if (flags & st_flag) == 0 {
+            // AR mode: size encoded in bits [USER4..USER7].
+            // RHASH_AR_TABLE_SIZE_MASK = FL_USER4|FL_USER5|FL_USER6|FL_USER7 = 0x000F_0000
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16
+            let mask: VALUE = (crate::ruby_fl_type::RUBY_FL_USER4 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER5 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER6 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER7 as VALUE);
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16 (stable across all Ruby versions)
+            let shift = 16u32;
+            ((flags & mask) >> shift) as usize
         } else {
-            // Fallback for large hashes (shouldn't normally happen)
-            crate::rb_num2ulong(size_val) as usize
+            // ST mode: dereference the st_table pointer and read num_entries.
+            // SAFETY: the st pointer is valid when RHASH_ST_TABLE_FLAG is set.
+            let st = (*rhash).st;
+            (*st).num_entries as usize
         }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool {
         self.rhash_size(obj) == 0
     }
diff --git a/crates/rb-sys/src/stable_api/ruby_3_2.rs b/crates/rb-sys/src/stable_api/ruby_3_2.rs
@@ -530,21 +530,49 @@ impl StableApiDefinition for Definition {
         unsafe { crate::rb_float_new(val) }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_size(&self, obj: VALUE) -> usize {
-        // Call rb_hash_size which returns a fixnum VALUE
-        let size_val = crate::rb_hash_size(obj);
-        // Convert fixnum to usize
-        if self.fixnum_p(size_val) {
-            // FIX2LONG: shift right by 1 to get the actual value
-            (size_val >> 1) as usize
+        // Ruby 3.2 RHash layout (pre-3.3):
+        //   struct RHash { RBasic basic; union { st_table *st; ar_table *ar; } as; VALUE ifnone; };
+        //
+        // AR mode (RUBY_FL_USER3 not set): size is packed in
+        //   RBasic.flags bits [USER4..USER7] >> 16 (= FL_USHIFT+4).
+        // ST mode (RUBY_FL_USER3 set): dereference the st_table pointer in
+        //   RHash.as and read st_table.num_entries directly.
+        //
+        // SAFETY: caller guarantees obj is a valid T_HASH VALUE.
+        #[repr(C)]
+        struct RHashPre33 {
+            basic: crate::RBasic,
+            st: *mut crate::st_table, // union { st_table *st; ar_table *ar; } — same size
+            ifnone: VALUE,
+        }
+
+        let rhash = obj as *const RHashPre33;
+        let flags = (*rhash).basic.flags;
+
+        // RHASH_ST_TABLE_FLAG = FL_USER3 = 32768
+        let st_flag = crate::ruby_fl_type::RUBY_FL_USER3 as VALUE;
+        if (flags & st_flag) == 0 {
+            // AR mode: size encoded in bits [USER4..USER7].
+            // RHASH_AR_TABLE_SIZE_MASK = FL_USER4|FL_USER5|FL_USER6|FL_USER7 = 0x000F_0000
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16
+            let mask: VALUE = (crate::ruby_fl_type::RUBY_FL_USER4 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER5 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER6 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER7 as VALUE);
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16 (stable across all Ruby versions)
+            let shift = 16u32;
+            ((flags & mask) >> shift) as usize
         } else {
-            // Fallback for large hashes (shouldn't normally happen)
-            crate::rb_num2ulong(size_val) as usize
+            // ST mode: dereference the st_table pointer and read num_entries.
+            // SAFETY: the st pointer is valid when RHASH_ST_TABLE_FLAG is set.
+            let st = (*rhash).st;
+            (*st).num_entries as usize
         }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool {
         self.rhash_size(obj) == 0
     }
diff --git a/crates/rb-sys/src/stable_api/ruby_3_3.rs b/crates/rb-sys/src/stable_api/ruby_3_3.rs
@@ -542,21 +542,49 @@ impl StableApiDefinition for Definition {
         unsafe { crate::rb_float_new(val) }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_size(&self, obj: VALUE) -> usize {
-        // Call rb_hash_size which returns a fixnum VALUE
-        let size_val = crate::rb_hash_size(obj);
-        // Convert fixnum to usize
-        if self.fixnum_p(size_val) {
-            // FIX2LONG: shift right by 1 to get the actual value
-            (size_val >> 1) as usize
+        // Ruby 3.3 RHash layout (3.3+):
+        //   struct RHash { RBasic basic; VALUE ifnone; };
+        //   // st_table embedded at sizeof(RHash) = 24 bytes from obj when in ST mode.
+        //
+        // AR mode (RUBY_FL_USER3 not set): size is packed in
+        //   RBasic.flags bits [USER4..USER7] >> 16 (= FL_USHIFT+4).
+        // ST mode (RUBY_FL_USER3 set): the st_table is embedded immediately after
+        //   the RHash struct in memory at offset sizeof(RHash) = 24 bytes.
+        //
+        // SAFETY: caller guarantees obj is a valid T_HASH VALUE.
+        #[repr(C)]
+        struct RHash33 {
+            basic: crate::RBasic,
+            ifnone: VALUE,
+        }
+
+        let rbasic = obj as *const crate::RBasic;
+        let flags = (*rbasic).flags;
+
+        // RHASH_ST_TABLE_FLAG = FL_USER3 = 32768
+        let st_flag = crate::ruby_fl_type::RUBY_FL_USER3 as VALUE;
+        if (flags & st_flag) == 0 {
+            // AR mode: size encoded in bits [USER4..USER7].
+            // RHASH_AR_TABLE_SIZE_MASK = FL_USER4|FL_USER5|FL_USER6|FL_USER7 = 0x000F_0000
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16
+            let mask: VALUE = (crate::ruby_fl_type::RUBY_FL_USER4 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER5 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER6 as VALUE)
+                | (crate::ruby_fl_type::RUBY_FL_USER7 as VALUE);
+            // RHASH_AR_TABLE_SIZE_SHIFT = FL_USHIFT + 4 = 12 + 4 = 16 (stable across all Ruby versions)
+            let shift = 16u32;
+            ((flags & mask) >> shift) as usize
         } else {
-            // Fallback for large hashes (shouldn't normally happen)
-            crate::rb_num2ulong(size_val) as usize
+            // ST mode: the st_table is embedded at sizeof(RHash) past obj.
+            // SAFETY: the embedded st_table is valid when RHASH_ST_TABLE_FLAG is set.
+            let st_ptr = (obj as usize + core::mem::size_of::<RHash33>()) as *const crate::st_table;
+            (*st_ptr).num_entries as usize
         }
     }
 
-    #[inline]
+    #[inline(always)]
     unsafe fn rhash_empty_p(&self, obj: VALUE) -> bool {
         self.rhash_size(obj) == 0
     }
diff --git a/crates/rb-sys/src/stable_api/ruby_3_4.rs b/crates/rb-sys/src/stable_api/ruby_3_4.rs
diff --git a/crates/rb-sys/src/stable_api/ruby_4_0.rs b/crates/rb-sys/src/stable_api/ruby_4_0.rs
diff --git a/script/show-asm b/script/show-asm
