From b794f225b2bc2edd7c45f3cd0de2e9c8d6bafb9e Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Mon, 6 Apr 2026 23:18:45 -0400
Subject: [PATCH] refactor: xo-gc: + GCObjectVisitor.generation_of()

Concession to narrow MutationLogStore to only use GCObjectVisitor
instead of assuming X1Collector.
---
 idl/GCObjectVisitor.json5                     | 25 ++++++++++++++-----
 include/xo/alloc2/Generation.hpp              |  3 ++-
 include/xo/alloc2/gc/AGCObjectVisitor.hpp     |  6 +++++
 include/xo/alloc2/gc/IGCObjectVisitor_Any.hpp |  1 +
 .../xo/alloc2/gc/IGCObjectVisitor_Xfer.hpp    |  5 ++++
 include/xo/alloc2/gc/RGCObjectVisitor.hpp     |  3 +++
 6 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/idl/GCObjectVisitor.json5 b/idl/GCObjectVisitor.json5
index e029417e..201623bd 100644
--- a/idl/GCObjectVisitor.json5
+++ b/idl/GCObjectVisitor.json5
@@ -4,11 +4,9 @@
     output_hpp_dir: "include/xo/alloc2",
     output_impl_subdir: "gc",
     includes: [
+        "<xo/alloc2/Generation.hpp>",
+        "<xo/alloc2/role.hpp>",
         "<xo/arena/AllocInfo.hpp>",
-//        "<xo/alloc2/Allocator.hpp>",
-//        "<xo/alloc2/Collector.hpp>",
-//        "<cstdint>",
-//        "<cstddef>",
     ],
     // extra includes in GCObject.hpp, if any
     user_hpp_includes: [
@@ -38,7 +36,7 @@
 //        },
     ],
     const_methods: [
-        // AllocInfo alloc_info(void * gco);
+        // AllocInfo alloc_info(void * gco) const noexcept;
         {
             name: "alloc_info",
             doc: [
@@ -53,7 +51,22 @@
             noexcept: false,
             attributes: [],
         },
-        // Generation generation_of(...);
+        // Generation generation_of(role r, const void * addr) const noexcept;
+        {
+            name: "generation_of",
+            doc: [
+                "generation to which pointer @p addr belongs, given role @p r;",
+                "sentinel if @p addr is not owned by collector",
+            ],
+            return_type: "Generation",
+            args: [
+                {type: "role", name: "r"},
+                {type: "const void *", name: "addr"},
+            ],
+            const: true,
+            noexcept: true,
+            attributes: [],
+        },
     ],
     nonconst_methods: [
         // void alloc_copy(void * src)
diff --git a/include/xo/alloc2/Generation.hpp b/include/xo/alloc2/Generation.hpp
index 2c83485b..a311c606 100644
--- a/include/xo/alloc2/Generation.hpp
+++ b/include/xo/alloc2/Generation.hpp
@@ -16,7 +16,8 @@ namespace xo {
         /** @class generation
          *  @brief type-safe generation number
          **/
-        struct Generation {
+        class Generation {
+        public:
             using value_type = std::uint32_t;
 
             constexpr Generation() = default;
diff --git a/include/xo/alloc2/gc/AGCObjectVisitor.hpp b/include/xo/alloc2/gc/AGCObjectVisitor.hpp
index 71603d1a..df5d1f47 100644
--- a/include/xo/alloc2/gc/AGCObjectVisitor.hpp
+++ b/include/xo/alloc2/gc/AGCObjectVisitor.hpp
@@ -14,6 +14,8 @@
 #pragma once
 
 // includes (via {facet_includes})
+#include <xo/alloc2/Generation.hpp>
+#include <xo/alloc2/role.hpp>
 #include <xo/arena/AllocInfo.hpp>
 #include <xo/facet/obj.hpp>
 #include <xo/facet/facet_implementation.hpp>
@@ -22,6 +24,7 @@
 // see GCObject.hpp, also in xo-alloc2/
 namespace xo { namespace mm { class AGCObject; }}
 namespace xo { namespace mm { class AllocInfo; }}
+namespace xo { namespace mm { class Generation; }}
 
 namespace xo {
 namespace mm {
@@ -58,6 +61,9 @@ public:
     /** allocation metadata for gc-aware data at address @p gco.
 @p gco must be the result of a call to collector's alloc() function **/
     virtual AllocInfo alloc_info(Copaque data, void * addr)  const = 0;
+    /** generation to which pointer @p addr belongs, given role @p r;
+sentinel if @p addr is not owned by collector **/
+    virtual Generation generation_of(Copaque data, role r, const void * addr)  const  noexcept = 0;
 
     // nonconst methods
     /** allocate copy of source object at address @p src.
diff --git a/include/xo/alloc2/gc/IGCObjectVisitor_Any.hpp b/include/xo/alloc2/gc/IGCObjectVisitor_Any.hpp
index 5e48ef43..7cb7f6d9 100644
--- a/include/xo/alloc2/gc/IGCObjectVisitor_Any.hpp
+++ b/include/xo/alloc2/gc/IGCObjectVisitor_Any.hpp
@@ -59,6 +59,7 @@ namespace mm {
 
         // const methods
         [[noreturn]] AllocInfo alloc_info(Copaque, void *)  const override { _fatal(); }
+        [[noreturn]] Generation generation_of(Copaque, role, const void *)  const  noexcept override { _fatal(); }
 
         // nonconst methods
         [[noreturn]] void * alloc_copy(Opaque, std::byte *)  const override;
diff --git a/include/xo/alloc2/gc/IGCObjectVisitor_Xfer.hpp b/include/xo/alloc2/gc/IGCObjectVisitor_Xfer.hpp
index 8daaee44..c457c557 100644
--- a/include/xo/alloc2/gc/IGCObjectVisitor_Xfer.hpp
+++ b/include/xo/alloc2/gc/IGCObjectVisitor_Xfer.hpp
@@ -13,6 +13,8 @@
 
 #pragma once
 
+#include <xo/alloc2/Generation.hpp>
+#include <xo/alloc2/role.hpp>
 #include <xo/arena/AllocInfo.hpp>
 
 namespace xo {
@@ -46,6 +48,9 @@ namespace mm {
         AllocInfo alloc_info(Copaque data, void * addr)  const override {
             return I::alloc_info(_dcast(data), addr);
         }
+        Generation generation_of(Copaque data, role r, const void * addr)  const  noexcept override {
+            return I::generation_of(_dcast(data), r, addr);
+        }
 
         // non-const methods
         void * alloc_copy(Opaque data, std::byte * src)  const override {
diff --git a/include/xo/alloc2/gc/RGCObjectVisitor.hpp b/include/xo/alloc2/gc/RGCObjectVisitor.hpp
index 461790a8..bba6756c 100644
--- a/include/xo/alloc2/gc/RGCObjectVisitor.hpp
+++ b/include/xo/alloc2/gc/RGCObjectVisitor.hpp
@@ -91,6 +91,9 @@ public:
     AllocInfo alloc_info(void * addr)  const {
         return O::iface()->alloc_info(O::data(), addr);
     }
+    Generation generation_of(role r, const void * addr)  const  noexcept {
+        return O::iface()->generation_of(O::data(), r, addr);
+    }
 
     // non-const methods (still const in router!)
     void * alloc_copy(std::byte * src)  {