xo-alloc + xo-allocutil: refactor to shrink dep surface area

include/xo/allocutil/IObject.hpp

@@ -0,0 +1,97 @@
+/** @file IObject.hpp
+ *
+ *  @author Roland Conybeare, Nov 2025
+ **/
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace xo {
+    namespace gc { class IAlloc; }
+
+    /** @class IObject
+     *  @brief Base interface for GC interaction
+     *
+     *  Classes that can be collected inherit this api
+     *  indirectly via xo::Object (see xo/alloc/Object.hpp)
+     **/
+    class IObject {
+    public:
+        /** true iff this object represents a forwarding pointer.
+         *  Forwarding pointers are exclusively created by the garbage collector;
+         *  forwarding pointers (and only forwarding pointers) return true here.
+         **/
+        virtual bool _is_forwarded() const { return false; }
+
+        /** offset for uncommon situation where pointer address is offset from object
+         *  base address
+         **/
+        virtual IObject * _offset_destination(IObject * src) const { return src; };
+
+        /** replace this object with a forwarding pointer referring to @p dest.
+         **/
+        virtual void _forward_to(IObject * dest) = 0;
+
+        /** if this object represents a forwarding pointer, return its new location.
+         *  forwarding pointers belong to the garbage collector implementation.
+         *  (if you have to ask -- no, your class is not a forwarding pointer)
+         *  all other objects return nullptr here.
+         **/
+        virtual IObject * _destination() { return nullptr; }
+
+        /** return amount of storage (including padding) consumed by this object,
+         *  excluding immediate Object-pointer children
+         **/
+        virtual std::size_t _shallow_size() const = 0;
+
+        /** if subject is allocated by GC:
+         *  - create copy C in to-space
+         *  - destination C will be nursery|tenured depending on location of this.
+         *  else
+         *  - return this to disengage from GC
+         *
+         *  Require: @ref mm is an instance of @ref gc::GC
+         **/
+        virtual IObject * _shallow_copy(gc::IAlloc * gc) const = 0;
+
+        /** update child pointers that refer to forwarding pointers,
+         *  replacing them with the correct destination.
+         *  See @ref Object::deep_move
+         *
+         *  this   gray object, located in to-space.
+         *  fwd1   forwarding objects.
+         *         Located in from-space. Invalid at end of GC cycle.
+         *  p1,p2  source pointers.
+         *  D1,D2  already-forwarded objects. located in to-space.
+         *
+         *  before:
+         *    this       fwd1
+         *    +----+     +-+
+         *    | p1 ----->|x|-------> D1
+         *    |    |     +-+
+         *    |    |
+         *    | p2 ----------------> D2
+         *    +----+
+         *
+         *  after:
+         *    this
+         *    +----+
+         *    | p1 ----------------> D1
+         *    |    |
+         *    |    |
+         *    | p2 ----------------> D2
+         *    +----+
+         *
+         *  this is now white
+         *
+         *  @return shallow size of *this.  Must exactly match the amount of memory in to-space
+         *  allocated by @ref _shallow_move
+         *
+         **/
+        virtual std::size_t _forward_children(gc::IAlloc * gc) = 0;
+    };
+}
+
+/* end IObject.hpp */