xo-alloc2: ++ docs + scaffold xo-gc docs

docs/AAllocator-reference.rst

@@ -56,6 +56,11 @@ Class
 
 .. doxygenclass:: xo::mm::AAllocator
 
+Types
+-----
+
+.. doxygengroup:: mm-allocator-type-traits
+
 Methods
 -------
 

docs/CMakeLists.txt

@@ -6,6 +6,7 @@ xo_docdir_sphinx_config(
     index.rst
     glossary.rst
     implementation.rst
+    AAllocator-reference.rst
     ArenaConfig-reference.rst
     DArena-reference.rst
     #install.rst

docs/examples.rst

@@ -0,0 +1,40 @@
+.. _examples:
+
+.. toctree
+    :maxdepth: 2
+
+Examples
+========
+
+Arena allocation
+-----------------
+
+.. code-block:: cpp
+
+    #include <xo/alloc2/arena/DArena.hpp>
+
+    using namespace xo::mm;
+    using namespace std;
+
+
+Create an arena:
+
+.. code-block:: cpp
+
+    // create arena, size 64k
+    DArena arena = DArena::map(ArenaConfig { .size_ = 64*1024; });
+
+    cout << arena.lo() << ".." << arena.hi();
+
+This determines a VM memory address range.
+Actually address range is rounded up to a whole number of VM pages.
+Size here is a hard maximum. It cannot be changed for this arena instance.
+
+.. code-block:: cpp
+
+    arena.reserved(); // 64k
+    arena.committed(); // 0k
+    arena.available(); // 0k
+
+Although we know the address range for arena, it doesn't own any physical
+memory yet.

docs/index.rst

@@ -3,13 +3,17 @@
 xo-alloc2 documentation
 =======================
 
-xo-alloc2 is intended to provide fast vm-aware arena allocation.
-Next-generation version of xo-alloc.
+xo-alloc2 provides:
 
-Features:
+* Fast vm-aware arena allocation.
+* Allocates uncommitted virtual memory, and commits on demand.
+* When available, uses THP (Transparent Huge Pages) to mitigate pagetable pressure.
+* Optional GC support, with per-alloc header.
 
-* allocates uncommitted virtual memory, and commits on demand.
-* uses THP (Transparent Huge Pages) when available.
+Diagnostic features:
+
+* with alloc headers: forward iterators over individual allocations
+* configurable guard memory between allocations.
 
 Implemented using FOMO (faceted rust-like object model) from xo-facet
 
@@ -17,6 +21,7 @@ Implemented using FOMO (faceted rust-like object model) from xo-facet
     :maxdepth: 2
     :caption: xo-alloc2 contents
 
+    examples
     implementation
     AAllocator-reference
     ArenaConfig-reference

utest/arena.test.cpp

@@ -4,7 +4,6 @@
  **/
 
 #include "xo/alloc2/Allocator.hpp"
-//#include "xo/alloc2/IAllocator_Any.hpp"
 #include "xo/alloc2/alloc/IAllocator_Xfer.hpp"
 //#include "xo/alloc2/DArena.hpp"
 #include "xo/alloc2/arena/IAllocator_DArena.hpp"