feat(stable-api): add RARRAY_AREF and RARRAY_ASET with write barrier

Implements #671

- Add rarray_aref() and rarray_aset() to StableApiDefinition trait
- Implement for Ruby 2.7, 3.0, 3.1, 3.2, 3.3, 3.4, 4.0
- RARRAY_ASET uses rb_gc_writebarrier for GC correctness
- Add C fallback in compiled.c
- Add FFI wrappers in compiled.rs
- Add public RARRAY_AREF and RARRAY_ASET macros
- Add comprehensive parity tests
- Add show-asm entries for assembly analysis

Depends on write barrier implementation from batch3.

Author: ianks

crates/rb-sys-tests/src/stable_api_test.rs

@@ -185,6 +185,166 @@ parity_test!(
     }
 );
 
+#[rb_sys_test_helpers::ruby_test]
+fn test_rarray_aref_basic() {
+    let ary = unsafe { rb_sys::rb_ary_new_capa(3) };
+    unsafe {
+        rb_sys::rb_ary_push(
+            ary,
+            rb_sys::rb_str_new_cstr("hello\0".as_ptr() as *const i8),
+        );
+        rb_sys::rb_ary_push(
+            ary,
+            rb_sys::rb_str_new_cstr("world\0".as_ptr() as *const i8),
+        );
+    }
+    let idx = 0;
+
+    assert_ne!(stable_api::get_default().version(), (0, 0));
+
+    let rust_result = unsafe { stable_api::get_default().rarray_aref(ary, idx) };
+    let compiled_c_result = unsafe { stable_api::get_compiled().rarray_aref(ary, idx) };
+
+    assert_eq!(
+        compiled_c_result, rust_result,
+        "compiled_c was {:?}, rust was {:?}",
+        compiled_c_result, rust_result
+    );
+}
+
+#[rb_sys_test_helpers::ruby_test]
+fn test_rarray_aref_second_element() {
+    let ary = unsafe { rb_sys::rb_ary_new_capa(3) };
+    unsafe {
+        rb_sys::rb_ary_push(
+            ary,
+            rb_sys::rb_str_new_cstr("hello\0".as_ptr() as *const i8),
+        );
+        rb_sys::rb_ary_push(
+            ary,
+            rb_sys::rb_str_new_cstr("world\0".as_ptr() as *const i8),
+        );
+    }
+    let idx = 1;
+
+    assert_ne!(stable_api::get_default().version(), (0, 0));
+
+    let rust_result = unsafe { stable_api::get_default().rarray_aref(ary, idx) };
+    let compiled_c_result = unsafe { stable_api::get_compiled().rarray_aref(ary, idx) };
+
+    assert_eq!(
+        compiled_c_result, rust_result,
+        "compiled_c was {:?}, rust was {:?}",
+        compiled_c_result, rust_result
+    );
+}
+
+#[rb_sys_test_helpers::ruby_test]
+fn test_rarray_aref_evaled() {
+    let ary = ruby_eval!("[1, 2, 3]");
+    let idx = 1;
+
+    assert_ne!(stable_api::get_default().version(), (0, 0));
+
+    let rust_result = unsafe { stable_api::get_default().rarray_aref(ary, idx) };
+    let compiled_c_result = unsafe { stable_api::get_compiled().rarray_aref(ary, idx) };
+
+    assert_eq!(
+        compiled_c_result, rust_result,
+        "compiled_c was {:?}, rust was {:?}",
+        compiled_c_result, rust_result
+    );
+}
+
+#[rb_sys_test_helpers::ruby_test]
+fn test_rarray_aset_basic() {
+    let ary = unsafe { rb_sys::rb_ary_new_capa(3) };
+    unsafe {
+        rb_sys::rb_ary_push(ary, rb_sys::Qnil as rb_sys::VALUE);
+    }
+    let val = unsafe { rb_sys::rb_str_new_cstr("test\0".as_ptr() as *const i8) };
+    let idx = 0;
+
+    assert_ne!(stable_api::get_default().version(), (0, 0));
+
+    unsafe { stable_api::get_default().rarray_aset(ary, idx, val) };
+    let rust_result = unsafe { stable_api::get_default().rarray_aref(ary, idx) };
+
+    // Reset for C test
+    let ary2 = unsafe { rb_sys::rb_ary_new_capa(3) };
+    unsafe {
+        rb_sys::rb_ary_push(ary2, rb_sys::Qnil as rb_sys::VALUE);
+    }
+    unsafe { stable_api::get_compiled().rarray_aset(ary2, idx, val) };
+    let compiled_c_result = unsafe { stable_api::get_compiled().rarray_aref(ary2, idx) };
+
+    assert_eq!(
+        compiled_c_result, rust_result,
+        "compiled_c was {:?}, rust was {:?}",
+        compiled_c_result, rust_result
+    );
+}
+
+#[rb_sys_test_helpers::ruby_test]
+fn test_rarray_aset_replace() {
+    let ary = unsafe { rb_sys::rb_ary_new_capa(3) };
+    unsafe {
+        rb_sys::rb_ary_push(ary, rb_sys::rb_str_new_cstr("old\0".as_ptr() as *const i8));
+        rb_sys::rb_ary_push(
+            ary,
+            rb_sys::rb_str_new_cstr("value\0".as_ptr() as *const i8),
+        );
+    }
+    let val = unsafe { rb_sys::rb_str_new_cstr("new\0".as_ptr() as *const i8) };
+    let idx = 0;
+
+    assert_ne!(stable_api::get_default().version(), (0, 0));
+
+    unsafe { stable_api::get_default().rarray_aset(ary, idx, val) };
+    let rust_result = unsafe { stable_api::get_default().rarray_aref(ary, idx) };
+
+    // Reset for C test
+    let ary2 = unsafe { rb_sys::rb_ary_new_capa(3) };
+    unsafe {
+        rb_sys::rb_ary_push(ary2, rb_sys::rb_str_new_cstr("old\0".as_ptr() as *const i8));
+        rb_sys::rb_ary_push(
+            ary2,
+            rb_sys::rb_str_new_cstr("value\0".as_ptr() as *const i8),
+        );
+    }
+    unsafe { stable_api::get_compiled().rarray_aset(ary2, idx, val) };
+    let compiled_c_result = unsafe { stable_api::get_compiled().rarray_aref(ary2, idx) };
+
+    assert_eq!(
+        compiled_c_result, rust_result,
+        "compiled_c was {:?}, rust was {:?}",
+        compiled_c_result, rust_result
+    );
+}
+
+#[rb_sys_test_helpers::ruby_test]
+fn test_rarray_aset_evaled() {
+    let ary = ruby_eval!("[1, 2, 3]");
+    let val = ruby_eval!("42");
+    let idx = 1;
+
+    assert_ne!(stable_api::get_default().version(), (0, 0));
+
+    unsafe { stable_api::get_default().rarray_aset(ary, idx, val) };
+    let rust_result = unsafe { stable_api::get_default().rarray_aref(ary, idx) };
+
+    // Reset for C test
+    let ary2 = ruby_eval!("[1, 2, 3]");
+    unsafe { stable_api::get_compiled().rarray_aset(ary2, idx, val) };
+    let compiled_c_result = unsafe { stable_api::get_compiled().rarray_aref(ary2, idx) };
+
+    assert_eq!(
+        compiled_c_result, rust_result,
+        "compiled_c was {:?}, rust was {:?}",
+        compiled_c_result, rust_result
+    );
+}
+
 parity_test!(
     name: test_rbasic_class_of_array,
     func: rbasic_class,

crates/rb-sys/src/macros.rs

@@ -112,6 +112,38 @@ pub unsafe fn RARRAY_LEN(obj: VALUE) -> c_long {
     api().rarray_len(obj)
 }
 
+/// Read array element at index (akin to `RARRAY_AREF`).
+///
+/// ### Safety
+///
+/// This function is unsafe because it dereferences a raw pointer in order to
+/// access internal Ruby memory.
+///
+/// - @param[in]  obj  An object of ::RArray.
+/// - @param[in]  idx  Index within the array (must be within bounds: 0..RARRAY_LEN(obj)).
+/// - @return     The element at the given index.
+#[inline(always)]
+pub unsafe fn RARRAY_AREF(obj: VALUE, idx: isize) -> VALUE {
+    api().rarray_aref(obj.into(), idx)
+}
+
+/// Write array element at index (akin to `RARRAY_ASET`).
+///
+/// This function includes the GC write barrier for correctness.
+///
+/// ### Safety
+///
+/// This function is unsafe because it dereferences a raw pointer in order to
+/// access internal Ruby memory.
+///
+/// - @param[in]  obj  An object of ::RArray.
+/// - @param[in]  idx  Index within the array (must be within bounds: 0..RARRAY_LEN(obj)).
+/// - @param[in]  val  The value to set at the given index.
+#[inline(always)]
+pub unsafe fn RARRAY_ASET(obj: VALUE, idx: isize, val: VALUE) {
+    api().rarray_aset(obj.into(), idx, val)
+}
+
 /// Get the length of a Ruby string.
 ///
 /// ### Safety

crates/rb-sys/src/stable_api.rs

@@ -58,6 +58,24 @@ pub trait StableApiDefinition {
     /// is valid.
     unsafe fn rarray_const_ptr(&self, obj: VALUE) -> *const VALUE;
 
+    /// Get element from array by index (akin to `RARRAY_AREF`).
+    ///
+    /// # Safety
+    /// This function is unsafe because it dereferences a raw pointer to get
+    /// access to underlying Ruby data. The caller must ensure that the pointer
+    /// is valid and that the index is within bounds.
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE;
+
+    /// Set element in array by index (akin to `RARRAY_ASET`).
+    ///
+    /// Includes GC write barrier for safety.
+    ///
+    /// # Safety
+    /// This function is unsafe because it dereferences a raw pointer to get
+    /// access to underlying Ruby data. The caller must ensure that the pointer
+    /// is valid and that the index is within bounds.
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE);
+
     /// Get the class from a VALUE which contains an RBasic struct.
     ///
     /// `VALUE` is a valid pointer to a non-immediate object.

crates/rb-sys/src/stable_api/compiled.c

@@ -41,6 +41,18 @@ impl_rarray_const_ptr(VALUE obj)
   return RARRAY_CONST_PTR(obj);
 }
 
+VALUE
+impl_rarray_aref(VALUE obj, long idx)
+{
+  return RARRAY_AREF(obj, idx);
+}
+
+void
+impl_rarray_aset(VALUE obj, long idx, VALUE val)
+{
+  RARRAY_ASET(obj, idx, val);
+}
+
 VALUE
 impl_rbasic_class(VALUE obj)
 {

crates/rb-sys/src/stable_api/compiled.rs

@@ -21,6 +21,12 @@ extern "C" {
     #[link_name = "impl_rarray_const_ptr"]
     fn impl_rarray_const_ptr(ary: VALUE) -> *const VALUE;
 
+    #[link_name = "impl_rarray_aref"]
+    fn impl_rarray_aref(ary: VALUE, idx: c_long) -> VALUE;
+
+    #[link_name = "impl_rarray_aset"]
+    fn impl_rarray_aset(ary: VALUE, idx: c_long, val: VALUE);
+
     #[link_name = "impl_rbasic_class"]
     fn impl_rbasic_class(obj: VALUE) -> VALUE;
 
@@ -159,6 +165,16 @@ impl StableApiDefinition for Definition {
         impl_rarray_const_ptr(obj)
     }
 
+    #[inline]
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE {
+        impl_rarray_aref(obj, idx as c_long)
+    }
+
+    #[inline]
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE) {
+        impl_rarray_aset(obj, idx as c_long, val)
+    }
+
     #[inline]
     unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>> {
         NonNull::<VALUE>::new(impl_rbasic_class(obj) as _)

crates/rb-sys/src/stable_api/ruby_2_7.rs

@@ -95,6 +95,17 @@ impl StableApiDefinition for Definition {
         ptr
     }
 
+    #[inline]
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE {
+        *self.rarray_const_ptr(obj).offset(idx)
+    }
+
+    #[inline]
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE) {
+        let ptr = self.rarray_const_ptr(obj).cast_mut().offset(idx);
+        self.rb_obj_write(obj, ptr, val);
+    }
+
     #[inline]
     unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>> {
         let rbasic = obj as *const crate::RBasic;

crates/rb-sys/src/stable_api/ruby_3_0.rs

@@ -103,6 +103,17 @@ impl StableApiDefinition for Definition {
         }
     }
 
+    #[inline]
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE {
+        *self.rarray_const_ptr(obj).offset(idx)
+    }
+
+    #[inline]
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE) {
+        let ptr = self.rarray_const_ptr(obj).cast_mut().offset(idx);
+        self.rb_obj_write(obj, ptr, val);
+    }
+
     #[inline]
     unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>> {
         let rbasic = obj as *const crate::RBasic;

crates/rb-sys/src/stable_api/ruby_3_1.rs

@@ -96,6 +96,17 @@ impl StableApiDefinition for Definition {
         ret
     }
 
+    #[inline]
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE {
+        *self.rarray_const_ptr(obj).offset(idx)
+    }
+
+    #[inline]
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE) {
+        let ptr = self.rarray_const_ptr(obj).cast_mut().offset(idx);
+        self.rb_obj_write(obj, ptr, val);
+    }
+
     #[inline]
     unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>> {
         let rbasic = obj as *const crate::RBasic;

crates/rb-sys/src/stable_api/ruby_3_2.rs

@@ -90,6 +90,17 @@ impl StableApiDefinition for Definition {
         ptr
     }
 
+    #[inline]
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE {
+        *self.rarray_const_ptr(obj).offset(idx)
+    }
+
+    #[inline]
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE) {
+        let ptr = self.rarray_const_ptr(obj).cast_mut().offset(idx);
+        self.rb_obj_write(obj, ptr, val);
+    }
+
     #[inline]
     unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>> {
         let rbasic = obj as *const crate::RBasic;

crates/rb-sys/src/stable_api/ruby_3_3.rs

@@ -82,6 +82,17 @@ impl StableApiDefinition for Definition {
         ptr
     }
 
+    #[inline]
+    unsafe fn rarray_aref(&self, obj: VALUE, idx: isize) -> VALUE {
+        *self.rarray_const_ptr(obj).offset(idx)
+    }
+
+    #[inline]
+    unsafe fn rarray_aset(&self, obj: VALUE, idx: isize, val: VALUE) {
+        let ptr = self.rarray_const_ptr(obj).cast_mut().offset(idx);
+        self.rb_obj_write(obj, ptr, val);
+    }
+
     #[inline]
     unsafe fn rbasic_class(&self, obj: VALUE) -> Option<NonNull<VALUE>> {
         let rbasic = obj as *const crate::RBasic;