From 3bd5fe699fdbd2fde70074e2dbab6195f25ec824 Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Tue, 23 Dec 2025 01:20:11 -0500 Subject: [PATCH] xo-alloc2: ++ docs + scaffold xo-gc docs --- CMakeLists.txt | 2 +- conf.py | 2 +- xo-alloc2/docs/AAllocator-reference.rst | 5 ++ xo-alloc2/docs/CMakeLists.txt | 1 + xo-alloc2/docs/examples.rst | 40 ++++++++++++++ xo-alloc2/docs/index.rst | 15 ++++-- xo-alloc2/utest/arena.test.cpp | 1 - xo-gc/docs/ACollector-reference.rst | 41 +++++++++++++++ xo-gc/docs/CMakeLists.txt | 17 ++++++ xo-gc/docs/README | 70 +++++++++++++++++++++++++ xo-gc/docs/implementation.rst | 42 +++++++++++++++ xo-gc/docs/index.rst | 21 ++++++++ 12 files changed, 249 insertions(+), 8 deletions(-) create mode 100644 xo-alloc2/docs/examples.rst create mode 100644 xo-gc/docs/ACollector-reference.rst create mode 100644 xo-gc/docs/CMakeLists.txt create mode 100644 xo-gc/docs/README create mode 100644 xo-gc/docs/implementation.rst create mode 100644 xo-gc/docs/index.rst diff --git a/CMakeLists.txt b/CMakeLists.txt index 5c358c65..bef04e3b 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/conf.py b/conf.py index 2cafc981..bda2bbda 100644 --- a/conf.py +++ b/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 ] diff --git a/xo-alloc2/docs/AAllocator-reference.rst b/xo-alloc2/docs/AAllocator-reference.rst index 4bb0150f..7ae4ea8d 100644 --- a/xo-alloc2/docs/AAllocator-reference.rst +++ b/xo-alloc2/docs/AAllocator-reference.rst @@ -56,6 +56,11 @@ Class .. doxygenclass:: xo::mm::AAllocator +Types +----- + +.. doxygengroup:: mm-allocator-type-traits + Methods ------- diff --git a/xo-alloc2/docs/CMakeLists.txt b/xo-alloc2/docs/CMakeLists.txt index 55ceed69..aefd71f3 100644 --- a/xo-alloc2/docs/CMakeLists.txt +++ b/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 diff --git a/xo-alloc2/docs/examples.rst b/xo-alloc2/docs/examples.rst new file mode 100644 index 00000000..a60bebd6 --- /dev/null +++ b/xo-alloc2/docs/examples.rst @@ -0,0 +1,40 @@ +.. _examples: + +.. toctree + :maxdepth: 2 + +Examples +======== + +Arena allocation +----------------- + +.. code-block:: cpp + + #include + + 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. diff --git a/xo-alloc2/docs/index.rst b/xo-alloc2/docs/index.rst index 5c666a37..ac8a802d 100644 --- a/xo-alloc2/docs/index.rst +++ b/xo-alloc2/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 diff --git a/xo-alloc2/utest/arena.test.cpp b/xo-alloc2/utest/arena.test.cpp index 6826dd3f..823e2051 100644 --- a/xo-alloc2/utest/arena.test.cpp +++ b/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" diff --git a/xo-gc/docs/ACollector-reference.rst b/xo-gc/docs/ACollector-reference.rst new file mode 100644 index 00000000..bc858c18 --- /dev/null +++ b/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 + +Class +----- + +.. doxygenclass:: xo::mm::ACollector + +Methods +------- + +.. doxygengroup:: mm-collector-methods diff --git a/xo-gc/docs/CMakeLists.txt b/xo-gc/docs/CMakeLists.txt new file mode 100644 index 00000000..34052860 --- /dev/null +++ b/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 diff --git a/xo-gc/docs/README b/xo-gc/docs/README new file mode 100644 index 00000000..2fab6399 --- /dev/null +++ b/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} diff --git a/xo-gc/docs/implementation.rst b/xo-gc/docs/implementation.rst new file mode 100644 index 00000000..e3434c0c --- /dev/null +++ b/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 | + +--------------------------------------------------------------------+ diff --git a/xo-gc/docs/index.rst b/xo-gc/docs/index.rst new file mode 100644 index 00000000..c973002a --- /dev/null +++ b/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