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

CMakeLists.txt

@@ -130,6 +130,6 @@ add_subdirectory(xo-imgui)
 # ----------------------------------------------------------------
 # documentation.  must follow add_subdirectory() for satellite projects
 
-xo_umbrella_doxygen_deps(xo_facet xo_alloc xo_alloc2 indentlog xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_interpreter xo_jit)
+xo_umbrella_doxygen_deps(xo_facet xo_alloc2 indentlog xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_interpreter xo_jit)
 xo_umbrella_doxygen_config()
 xo_umbrella_sphinx_config(index.rst docs/install.rst docs/glossary.rst)

conf.py

@@ -17,7 +17,7 @@ author = 'Roland Conybeare'
 extensions = [ "breathe",
                "sphinx.ext.mathjax",     # inline math
                "sphinx.ext.autodoc",     # generate info from docstrings
-               "sphinxcontrib.ditaa",    # diagrams-through-ascii-art
+#               "sphinxcontrib.ditaa",    # diagrams-through-ascii-art
                "sphinxcontrib.plantuml", # text -> uml diagrams
               ]
 

xo-alloc2/docs/AAllocator-reference.rst

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

xo-alloc2/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

xo-alloc2/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.

xo-alloc2/docs/index.rst

@@ -3,13 +3,17 @@
 xo-alloc2 documentation
 =======================
 
-xo-alloc2 is intended to provide fast vm-aware arena allocation.
+xo-alloc2 provides:
-Next-generation version of xo-alloc.
 
-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.
+Diagnostic features:
-* uses THP (Transparent Huge Pages) when available.
+
+* 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

xo-alloc2/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"

xo-gc/docs/ACollector-reference.rst

@@ -0,0 +1,41 @@
+.. _ACollector-reference:
+
+ACollector Reference
+====================
+
+Abstract interface facet for generational garbage collector.
+
+Context
+-------
+
+.. ditaa::
+    :--scale: 0.99
+
+    +--------------------------------------------------+-----------------+
+    |  IAllocIterator_DX1CollectorIterator             |                 |
+    |  IAllocator_DX1Collector                         |  RGCObject      |
+    |  ICollector_DX1Collector                         |  IGCObject_Xfer |
+    |  ICollector_Xfer                                 |  IGCObject_Any  |
+    |  ICollector_Any                                  |                 |
+    +--------------------------------------------------+-----------------+
+    +----------------------+--------------+------------+-----------------+
+    | DX1CollectorIterator | DX1Collector | ACollector |  AGCObject      |
+    |                      |              |            |                 |
+    +----------------------+--------------+------------+-----------------+
+    +--------------------------------------------------------------------+
+    |    CollectorConfig      generation      object_age     role        |
+    +--------------------------------------------------------------------+
+
+.. code-block:: cpp
+
+    #include <xo/gc/ACollector.hpp>
+
+Class
+-----
+
+.. doxygenclass:: xo::mm::ACollector
+
+Methods
+-------
+
+.. doxygengroup:: mm-collector-methods

xo-gc/docs/CMakeLists.txt

@@ -0,0 +1,17 @@
+# xo-gc/docs/CMakeLists.txt
+
+xo_doxygen_collect_deps()
+xo_docdir_doxygen_config()
+xo_docdir_sphinx_config(
+    index.rst
+#    glossary.rst
+#    implementation.rst
+#    ArenaConfig-reference.rst
+#    DArena-reference.rst
+    #install.rst
+    #introduction.rst
+    #implementation.rst
+)
+
+# see xo-reader/doc or xo-unit/doc for working examples
+# example.rst install.rst implementation.rst

xo-gc/docs/README

@@ -0,0 +1,70 @@
+build
+
+        +-----------------------------------------------+
+        | cmake                                         |
+        |   CMakeLists.txt                              |
+        |   $PREFIX/share/cmake/xo_macros/xo_cxx.cmake  |
+        +-----------------------------------------------+
+           |
+           |                                                  +----------------------+
+           +------------------------------------------------->| .build/docs/Doxyfile |
+           |                                                  +----------------------+
+           |                                                     |
+           |                                        /------------/
+           |                                        |
+           |                                        v
+           |     +---------------------------------------+    +-----------------+
+           +---->| doxygen                               |--->| .build/docs/dox |
+           |     |   $PREFIX/share/xo-macros/Doxyfile.in |    |   +- html/      |
+           |     +---------------------------------------+    |   +- xml/       |
+           |                                                  +-----------------+
+           |                                                     |
+           |                                        /------------/
+           |                                        |
+           |                                        v
+           |     +---------------------------------------+    +--------------------+
+           \---->| sphinx                                |--->| .build/docs/sphinx |
+                 |   +- conf.py                          |    |   +- html/         |
+                 |   +- _static/                         |    +--------------------+
+                 |   +- *.rst                            |
+                 +---------------------------------------+
+
+files
+
+   README            this file
+   CMakeLists.txt    build entry point
+   conf.py           sphinx config
+   _static           static files for sphinx
+
+map
+
+   index.rst
+   +- install.rst
+   +- examples.rst
+   +- unit-quantities.rst
+   +- classes.rst
+   +- glossary.rst
+   ...
+
+examples
+
+.. doxygenclass:: ${c++ class name}
+   :project:
+   :path:
+   :members:
+   :protected-members:
+   :private-members:
+   :undoc-members:
+   :member-groups:
+   :members-only:
+   :outline:
+   :no-link:
+   :allow-dot-graphs:
+
+.. doxygendefine:: ${c preprocessor define}
+
+.. doxygenconcept:: ${c++ concept definition}
+
+.. doxygenenum:: ${c++ enum definition}
+
+.. doxygenfunction:: ${c++ function name}

xo-gc/docs/implementation.rst

@@ -0,0 +1,42 @@
+.. _implementation:
+
+.. toctree::
+    :maxdepth: 2
+
+Components
+==========
+
+Library dependency tower for *xo-gc*
+
+.. ditaa::
+
+
+    +----------------+
+    |     xo_gc      |
+    +----------------+
+    |   xo_alloc2    |
+    +----------------+
+    |    xo_facet    |
+    +----------------+
+    |    xo_cmake    |
+    +----------------+
+
+Abstraction tower for *xo-gc* components:
+
+.. ditaa::
+    :--scale: 0.85
+
+    +--------------------------------------------------+-----------------+
+    |  IAllocIterator_DX1CollectorIterator             |                 |
+    |  IAllocator_DX1Collector                         |  RGCObject      |
+    |  ICollector_DX1Collector                         |  IGCObject_Xfer |
+    |  ICollector_Xfer                                 |  IGCObject_Any  |
+    |  ICollector_Any                                  |                 |
+    +--------------------------------------------------+-----------------+
+    +----------------------+--------------+------------+-----------------+
+    | DX1CollectorIterator | DX1Collector | ACollector |  AGCObject      |
+    |                      |              |            |                 |
+    +----------------------+--------------+------------+-----------------+
+    +--------------------------------------------------------------------+
+    |    CollectorConfig      generation      object_age     role        |
+    +--------------------------------------------------------------------+

xo-gc/docs/index.rst

@@ -0,0 +1,21 @@
+# xo-gc documentation mster file
+
+xo-gc documetation
+==================
+
+xo-gc provides a garbage collcetor
+with plugin architecture for collectable types.
+
+Features:
+
+* generational
+* compacting and copying
+* gc progress observable via callbacks
+
+.. toctree::
+    :maxdepth: 2
+    :caption: xo-gc contents
+
+    ACollector-reference.rst
+    genindex
+    search