xo-alloc: doc improvements

docs/install.rst

@@ -24,7 +24,7 @@ Install
 One-step Install
 ----------------
 
-Install along with the reset of *XO* from `xo-umbrella2 source`_
+Install along with the rest of *XO* from `xo-umbrella2 source`_
 
 .. _xo-umbrella2 source: https://github.com/rconybea/xo-umbrella2
 

include/xo/alloc/ArenaAlloc.hpp

@@ -11,16 +11,41 @@
 namespace xo {
     namespace gc {
         /** @class ArenaAlloc
-         *  @brief Bump allocator with fixed capacity
+         *  @brief Bump allocator with fixed capacity with dynamic virtual memory commitment.
          *
          *  @text
          *
-         *    <-----allocated----> <--------free------->
+         *    allocation order:
-         *    XXXXXXXXXXXXXXXXXXXX______________________
+         *    ----------------------->
-         *    ^                   ^                     ^
+         *
-         *    lo                  free                  hi
+         *    <----------------- .size() ------------------>
-         *                                              limit
+         *    <----------------- .committed() --------------->
+         *
+         *    <-------allocated------><--------free-------->  <---uncommitted---->
+         *    XXXXXXXXXXXXXXXXXXXXXXXX______________________  ....................
+         *    ^       ^               ^                     ^                     ^
+         *    lo      checkpoint   free                 limit                    hi
+         *
+         *                            +- .alloc() ->
+         *                                                  +-- .expand() -->
+         *   >        < .before_checkpoint()
+         *           >                < .after_checkpoint()
+         *
          *  @endtext
+         *
+         *  Design Notes:
+         *  - non-copyable, non-moveable
+         *  - always heap-allocated
+         *  - @ref lo_ <= @ref checkpoint_ <= @ref free_ <= @ref limit_ <= @ref hi_
+         *  - memory obtained from mmap(), not heap
+         *  - memory addresses are stable. Expand storage by committing VM pages.
+         *  - @ref lo_ is aligned on VM page size (guaranteed by mmap())
+         *  - @ref lo_ + @ref committed_z_ <= @ref hi_
+         *  - @ref limit_ <= @ref lO_ + @ref committed_z_
+         *  - @ref committed_z_ is always a multiple of VM page size
+         *  - @ref limit_ is not guaranteed to be aligned with VM page size.
+         *  - @ref expand increases @ref limit_ and @ref committed_z_ as needed.
+         *
          **/
         class ArenaAlloc : public IAlloc {
         public:
@@ -57,11 +82,14 @@ namespace xo {
             /** Reset to empty state; provision at least @p need_z bytes of (committed) space **/
             void reset(std::size_t need_z);
 
+            /** gc support: If used for storing xo::Object instances, scan allocated memory
+             *  to populate @p *p_dest.
+             **/
             void capture_object_statistics(capture_phase phase,
                                            ObjectStatistics * p_dest) const;
 
             /** expand available (i.e. committed) space to size at least @p z
-             *  In practice will round up to a multiple of @ref page_z_
+             *  In practice will round up to a multiple of @ref page_z_.
              **/
             bool expand(std::size_t z);
 
@@ -98,7 +126,7 @@ namespace xo {
             /** optional instance name, for diagnostics **/
             std::string name_;
 
-            /** size of a VM page **/
+            /** size of a VM page (from getpagesize()) **/
             std::size_t page_z_;
 
             /** allocator owns memory in range [@ref lo_, @ref hi_) **/

include/xo/alloc/Forwarding.hpp

@@ -1,28 +0,0 @@
-/* Forwarding.hpp
- *
- * author: Roland Conybeare, Jul 2025
- */
-
-#pragma once
-
-#include "Object.hpp"
-
-namespace xo {
-    namespace gc {
-        class Forwarding : public Object {
-        public:
-            Forwarding() = default;
-
-            // inherited from Object..
-#ifdef NOT_USING
-            virtual bool _is_forwarded() const override final { return true; }
-#endif
-            virtual Object * _destination() override final { return destination_.ptr(); }
-
-        private:
-            gp<Object> destination_;
-        };
-    } /*namespace gc*/
-} /*namespace xo*/
-
-/* end Forwarding.hpp */

include/xo/alloc/Forwarding1.hpp

@@ -7,6 +7,16 @@
 
 namespace xo {
     namespace obj {
+        /** @class Forwarding1
+         *  @brief forwarding pointer for garbage collector.
+         *
+         *  Used internally by garbage collector (see @ref GC).
+         *  During evacuate phase overwrite from-space objects in-place
+         *  with an instance of this class.
+         *
+         *  This class suitable only for singly-inheriting objects,
+         *  i.e. those that have exactly one vtable.
+         **/
         class Forwarding1 : public Object {
         public:
             explicit Forwarding1(gp<Object> dest);
@@ -17,11 +27,11 @@ namespace xo {
             virtual bool        _is_forwarded() const final override { return true; }
             virtual Object *    _offset_destination(Object * src) const final override;
             virtual Object *    _destination() final override;
-            /** never called on Forwarding1 **/
+            /** required by Object i/face, but never called on Forwarding1 **/
             virtual std::size_t _shallow_size() const final override;
-            /** never called on Forwarding1 **/
+            /** required by Object i/face, but never called on Forwarding1 **/
             virtual Object *    _shallow_copy() const final override;
-            /** never called on Forwarding1 **/
+            /** required by Object i/face, but never called on Forwarding1 **/
             virtual std::size_t _forward_children() final override;
 
         private:

include/xo/alloc/Object.hpp

@@ -75,8 +75,8 @@ namespace xo {
      *  for a type appear directly in that type's vtable, and at specific locations.
      *  This implies one level of indirection when GC traverses an instance.
      *
-     *  Would be feasible to relax the must-inherit-from-Object constraint,
+     *  Would be feasible to relax the must-inherit-from-Object constraint
-     *  but cost would be an extra layer of indirection
+     *  by having GC use its own wrapper, at cost of an extra layer of indirection
      **/
     class Object {
     public: