Refactor reference iterator to use struct instead of tuple (#636)

While working on #635, I noticed that we were instantiating the reference iterator using tuples of `(id, kind)`. I think we can standardize on the approach we used for declarations with a `CDeclaration` struct to back this up.

If we end up needing to add more data to it, the changes to the FFI are minimized because we're not passing more tuple items. This PR creates `CReference` to be used across the FFI.

Author: vinistock

ext/rubydex/utils.c

@@ -57,12 +57,10 @@ VALUE rdxi_references_yield(VALUE args) {
     VALUE graph_obj = rb_ary_entry(args, 0);
     void *iter = (void *)(uintptr_t)NUM2ULL(rb_ary_entry(args, 1));
 
-    uint64_t id = 0;
-    ReferenceKind kind;
-
-    while (rdx_references_iter_next(iter, &id, &kind)) {
-        VALUE ref_class = rdxi_reference_class_for_kind(kind);
-        VALUE argv[] = {graph_obj, ULL2NUM(id)};
+    CReference cref;
+    while (rdx_references_iter_next(iter, &cref)) {
+        VALUE ref_class = rdxi_reference_class_for_kind(cref.kind);
+        VALUE argv[] = {graph_obj, ULL2NUM(cref.id)};
         VALUE obj = rb_class_new_instance(2, argv, ref_class);
         rb_yield(obj);
     }

rust/rubydex-sys/src/declaration_api.rs

@@ -7,7 +7,7 @@ use std::ptr;
 
 use crate::definition_api::{DefinitionsIter, rdx_definitions_iter_new_from_ids};
 use crate::graph_api::{GraphPointer, with_graph};
-use crate::reference_api::{ReferenceKind, ReferencesIter};
+use crate::reference_api::{CReference, ReferenceKind, ReferencesIter};
 use crate::utils;
 use rubydex::model::ids::{DeclarationId, StringId};
 
@@ -429,7 +429,11 @@ pub unsafe extern "C" fn rdx_declaration_references_iter_new(
             }
         };
 
-        let entries: Vec<_> = decl.references().iter().map(|ref_id| (**ref_id, kind)).collect();
+        let entries: Vec<_> = decl
+            .references()
+            .iter()
+            .map(|ref_id| CReference::new(**ref_id, kind))
+            .collect();
         ReferencesIter::new(entries.into_boxed_slice())
     })
 }

rust/rubydex-sys/src/graph_api.rs

@@ -2,7 +2,7 @@
 
 use crate::declaration_api::CDeclaration;
 use crate::declaration_api::DeclarationsIter;
-use crate::reference_api::{ReferenceKind, ReferencesIter};
+use crate::reference_api::{CReference, ReferenceKind, ReferencesIter};
 use crate::{name_api, utils};
 use libc::{c_char, c_void};
 use rubydex::indexing::LanguageId;
@@ -452,7 +452,7 @@ pub unsafe extern "C" fn rdx_graph_constant_references_iter_new(pointer: GraphPo
         let refs: Vec<_> = graph
             .constant_references()
             .keys()
-            .map(|id| (**id, ReferenceKind::Constant))
+            .map(|id| CReference::new(**id, ReferenceKind::Constant))
             .collect();
 
         ReferencesIter::new(refs.into_boxed_slice())
@@ -469,7 +469,7 @@ pub unsafe extern "C" fn rdx_graph_method_references_iter_new(pointer: GraphPoin
         let refs: Vec<_> = graph
             .method_references()
             .keys()
-            .map(|id| (**id, ReferenceKind::Method))
+            .map(|id| CReference::new(**id, ReferenceKind::Method))
             .collect();
 
         ReferencesIter::new(refs.into_boxed_slice())

rust/rubydex-sys/src/reference_api.rs

@@ -15,16 +15,29 @@ pub enum ReferenceKind {
     Method = 1,
 }
 
-/// Shared iterator over reference (id, kind) pairs
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+pub struct CReference {
+    id: u64,
+    kind: ReferenceKind,
+}
+
+impl CReference {
+    #[must_use]
+    pub fn new(id: u64, kind: ReferenceKind) -> Self {
+        Self { id, kind }
+    }
+}
+
 #[derive(Debug)]
 pub struct ReferencesIter {
-    pub entries: Box<[(u64, ReferenceKind)]>,
+    pub entries: Box<[CReference]>,
     pub index: usize,
 }
 
 impl ReferencesIter {
     #[must_use]
-    pub fn new(entries: Box<[(u64, ReferenceKind)]>) -> *mut ReferencesIter {
+    pub fn new(entries: Box<[CReference]>) -> *mut ReferencesIter {
         Box::into_raw(Box::new(ReferencesIter { entries, index: 0 }))
     }
 }
@@ -41,23 +54,15 @@ pub unsafe extern "C" fn rdx_references_iter_len(iter: *const ReferencesIter) ->
     unsafe { (&*iter).entries.len() }
 }
 
-/// Advances the iterator and writes the next entry into the provided out params.
+/// Advances the iterator and writes the next entry into `out_ref`.
 /// Returns `true` if an entry was written, or `false` if the iterator is exhausted or inputs are invalid.
 ///
 /// # Safety
 /// - `iter` must be a valid pointer previously returned by `ReferencesIter::new`.
-/// - `out_id` and `out_kind` must be valid, writable pointers.
-///
-/// # Panics
-/// - If the iterator is exhausted or inputs are invalid.
-/// - If the name, URI, start, or end pointers are invalid.
+/// - `out_ref` must be a valid, writable pointer.
 #[unsafe(no_mangle)]
-pub unsafe extern "C" fn rdx_references_iter_next(
-    iter: *mut ReferencesIter,
-    out_id: *mut u64,
-    out_kind: *mut ReferenceKind,
-) -> bool {
-    if iter.is_null() || out_id.is_null() || out_kind.is_null() {
+pub unsafe extern "C" fn rdx_references_iter_next(iter: *mut ReferencesIter, out_ref: *mut CReference) -> bool {
+    if iter.is_null() || out_ref.is_null() {
         return false;
     }
 
@@ -66,11 +71,10 @@ pub unsafe extern "C" fn rdx_references_iter_next(
         return false;
     }
 
-    let (id, kind) = it.entries[it.index];
+    let entry = it.entries[it.index];
     it.index += 1;
     unsafe {
-        *out_id = id;
-        *out_kind = kind;
+        *out_ref = entry;
     }
     true
 }