roland/xo-alloc2
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

xo-alloc2: ++ documentation

Browse source
This commit is contained in:
Roland Conybeare 2025-12-24 01:29:57 -05:00
commit 0136044ba2
18 changed files with 474 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

67
docs/AAllocIterator-reference.rst Normal file
View file

@ -0,0 +1,67 @@
.. _AAllocIterator-reference:
AAllocIterator Reference
========================
Abstract interface facet for an alloc iterator.
Base class for runtime polymorphism over alloc-iterator implementations,
using faceted object model.
* runtime size consists of vtable pointer only.
* per FOMO principles, runtime state is stored separately.
Classes that inherit AAllocIterator will not add state.
Context
-------
.. ditaa::
:--scale: 0.99
+----------------------+-------------------------+-----------------------------------+
| RAllocator | RAllocIterator | IAllocator_DArena |
| | | IAllocIterator_DArenaIterator |
+----------------------+-------------------------+-----------------------------------+
| IAllocator_Xfer | IAllocIterator_Xfer | DArena |
| IAllocator_Any | IAllocIterator_Any | DArenaIterator |
| IAllocator_Impltype | IAllocIterator_Impltype | |
| | | |
+----------------------+-------------------------+-----------------------------------+
| AAllocator | AAllocIterator cBLU| ArenaConfig |
+----------------------+-------------------------+-----------------------------------+
+-----------------+----------------------------------------------+-------------------+
| | AllocInfo | |
| +----------------------------------------------+ |
| AllocError | AllocHeaderConfig | cmpresult |
| +----------------------------------------------+ |
| | AllocHeader | |
+-----------------+----------------------------------------------+-------------------+
Application code will likely use:
.. code-block:: cpp
#include <xo/alloc2/AllocIterator.hpp>
to get definitions for cooperating AllocIterator classes
:cpp:class:`xo::mm::AAllocIterator`,
:cpp:class:`xo::mm::IAllocIterator_Any`,
:cpp:class:`xo::mm::IAllocIterator_Xfer`,
:cpp:class:`xo::mm::RAllocator`
Instead, to get just :cpp:class:`xo::mm::AAllocIterator` definition:
.. code-block:: cpp
#include <xo/alloc2/AAllocIterator.hpp>
Class
-----
.. doxygenclass:: xo::mm::AAllocIterator
Methods
-------
.. doxygengroup:: mm-allociterator-methods

51
docs/ArenaConfig-reference.rst
View file

@ -11,25 +11,50 @@ Context
.. ditaa::
:--scale: 0.99
+--------------------------------+
| IAllocator_DArena |
+--------------------------------+
| IAllocator_Xfer |
+--------------------------------+
| IAllocator_ImplType |
+--------------+-----------------+
| | DArena |
| AAllocator +-----------------+
| | ArenaConfig cBLU|
+--------------+-----------------+
+----------------------+-------------------------+-----------------------------------+
| RAllocator | RAllocIterator | IAllocator_DArena |
| | | IAllocIterator_DArenaIterator |
+----------------------+-------------------------+-----------------------------------+
| IAllocator_Xfer | IAllocIterator_Xfer | DArena |
| IAllocator_Any | IAllocIterator_Any | DArenaIterator |
| IAllocator_Impltype | IAllocIterator_Impltype | |
| | | |
+----------------------+-------------------------+-----------------------------------+
| AAllocator | AAllocIterator | ArenaConfig cBLU|
+----------------------+-------------------------+-----------------------------------+
+-----------------+----------------------------------------------+-------------------+
| | AllocInfo | |
| +----------------------------------------------+ |
| AllocError | AllocHeaderConfig | cmpresult |
| +----------------------------------------------+ |
| | AllocHeader | |
+-----------------+----------------------------------------------+-------------------+
.. uml::
:caption: example arena config
:scale: 99%
:align: center
object cfg<<AreanConfig>>
cfg : name = "tmp"
cfg : size = 128MB
cfg : hugepage_z = 2MB
cfg : guard_z = 8
cfg : guard_byte = 0xfd
cfg : store_header_flag = true
cfg : header_size_mask = 0xffffffff
cfg : debug_flag = false
.. code-block:: cpp
#include <xo/alloc2/DArena.hpp>
#include <xo/alloc2/ArenaConfig.hpp>
Class
-----
.. doxygenclass:: xo::mm::ArenaConfig
.. doxygenclass:: mm-arenaconfig-instance-vars
Instance Variables
------------------
.. doxygengroup:: mm-arenaconfig-instance-vars

3
docs/CMakeLists.txt
View file

@ -8,9 +8,12 @@ xo_docdir_sphinx_config(
examples.rst
implementation.rst
AAllocator-reference.rst
IAllocator_Xfer-reference.rst
AAllocIterator-reference.rst
ArenaConfig-reference.rst
DArena-reference.rst
AllocInfo-reference.rst
cmpresult-reference.rst
#install.rst
#introduction.rst
#implementation.rst

7
docs/DArena-reference.rst
View file

@ -1,9 +1,9 @@
.. _DArena-reference:
DArena Reference
================
DArena
======
Native representation for arena allocator
Native arena allocator
Context
-------
@ -34,7 +34,6 @@ Context
#include <xo/alloc2/DArena.hpp>
Arena memory layout
~~~~~~~~~~~~~~~~~~~

55
docs/DArenaIterator-reference.rst Normal file
View file

@ -0,0 +1,55 @@
.. _DArenaIterator-reference:
DArenaIterator
==============
Iterator for allocs obtained from a :cpp:class:`DArena`.
Context
-------
.. ditaa::
:--scale: 0.99
+----------------------+-------------------------+-----------------------------------+
| RAllocator | RAllocIterator | IAllocator_DArena |
| | | IAllocIterator_DArenaIterator |
+----------------------+-------------------------+-----------------------------------+
| IAllocator_Xfer | IAllocIterator_Xfer | DArena |
| IAllocator_Any | IAllocIterator_Any +-----------------------------------+
| IAllocator_Impltype | IAllocIterator_Impltype | DArenaIterator |
| | | cBLU|
+----------------------+-------------------------+-----------------------------------+
| AAllocator | AAllocIterator | ArenaConfig |
+----------------------+-------------------------+-----------------------------------+
+-----------------+----------------------------------------------+-------------------+
| | AllocInfo | |
| +----------------------------------------------+ |
| AllocError | AllocHeaderConfig | cmpresult |
| +----------------------------------------------+ |
| | AllocHeader | |
+-----------------+----------------------------------------------+-------------------+
.. code-block:: cpp
#include <xo/alloc2/DArenaIterator.hpp>
Class
-----
.. doxygenclass:: xo::mm::DArenaIterator
Member Variables
----------------
.. doxygengroup:: mm-arenaiterator-instance-vars
Constructors
------------
.. doxygengroup:: mm-arenaiterator-ctors
Methods
-------
.. doxygengroup:: mm-arenaiterator-methods

73
docs/IAllocator_Xfer-reference.rst Normal file
View file

@ -0,0 +1,73 @@
.. _IAllocator_Xfer-reference:
IAllocator_Xfer
===============
IAllocator_Xfer provides a type-erased interface to a specific native allocator
implementation.
Context
-------
.. ditaa::
:--scale: 0.99
+----------------------+-------------------------+-----------------------------------+
| RAllocator | RAllocIterator | IAllocator_DArena |
| | | IAllocIterator_DArenaIterator |
+----------------------+-------------------------+-----------------------------------+
|cBLU IAllocator_Xfer | IAllocIterator_Xfer | DArena |
+----------------------+ IAllocIterator_Any | DArenaIterator |
| IAllocator_Any | IAllocIterator_Impltype | |
| IAllocator_Impltype | | |
+----------------------+-------------------------+-----------------------------------+
| AAllocator | AAllocIterator | ArenaConfig |
+----------------------+-------------------------+-----------------------------------+
+-----------------+----------------------------------------------+-------------------+
| | AllocInfo | |
| +----------------------------------------------+ |
| AllocError | AllocHeaderConfig | cmpresult |
| +----------------------------------------------+ |
| | AllocHeader | |
+-----------------+----------------------------------------------+-------------------+
Each method operates by downcasting its first argument to the known target
native interface type, and delegating to native interface method with the same name.
For example (paraphrasing):
.. code-block:: cpp
template <typename DRepr, typename IAllocator_DRepr>
bool IAllocator_Xfer<DRepr, IAllocator_DRepr>::contains(Copaque d,
const void * p) const ...
{
return IAllocator_DRepr::contains(*(DRepr*)(d), p);
};
Code for other methods follows the same pattern;
in fact expect to be able to generate class definition mechanically at some point.
Application code will not normally interact with :cpp:class:`IAllocator_Xfer`.
It will be used once for each specific allocator implementation
(e.g. with :cpp:class:`xo::mm::IAllocator_DArena`).
In any case, can include the transfer template with:
.. code-block:: cpp
#include <xo/alloc2/IAllocator_Xfer.hpp>
Class
-----
.. doxygenclass:: xo::mm::IAllocator_Xfer
Types
-----
.. doxygengroup:: mm-allocator-xfer-types
Methods
-------
.. doxygengroup:: mm-allocator-xfer-methods

55
docs/cmpresult-reference.rst Normal file
View file

@ -0,0 +1,55 @@
.. _cmpresult-reference:
cmpresult
=========
Represent the result of a partially ordered comparison
Context
-------
.. ditaa::
:--scale: 0.99
+----------------------+-------------------------+-----------------------------------+
| RAllocator | RAllocIterator | IAllocator_DArena |
| | | IAllocIterator_DArenaIterator |
+----------------------+-------------------------+-----------------------------------+
| IAllocator_Xfer | IAllocIterator_Xfer | DArena |
| IAllocator_Any | IAllocIterator_Any | DArenaIterator |
| IAllocator_Impltype | IAllocIterator_Impltype | |
| | | |
+----------------------+-------------------------+-----------------------------------+
| AAllocator | AAllocIterator | ArenaConfig |
+----------------------+-------------------------+-----------------------------------+
+-----------------+----------------------------------------------+-------------------+
| | AllocInfo | |
| +----------------------------------------------+ |
| AllocError | AllocHeaderConfig | cmpresult |
| +----------------------------------------------+ |
| | AllocHeader | cBLU |
+-----------------+----------------------------------------------+-------------------+
.. code-block:: cpp
#include <xo/alloc2/cmpresult.hpp>
Class
-----
.. doxygenclass:: xo::mm::cmpresult
Constructors
------------
.. doxgyengroup:: mm-cmpresult-ctors
Methods
-------
.. doxygengroup:: mm-cmpresult-methods
Member Variables
----------------
.. doxygengroup:: mm-cmpresult-instance-vars

17
docs/examples.rst
View file

@ -84,6 +84,17 @@ Given a successful allocation:
info.guard_lo(); // guard bytes preceding alloc
info.guard_hi(); // guard bytes following alloc
Can alternatively scan all live allocs in arena:
.. code-block:: cpp
for (AllocInfo info : arena) {
info.payload(); // allocated memory range
info.is_valid(); // true
info.guard_lo(); // guard bytes preceding alloc
info.guard_hi(); // guard bytes following alloc
}
Recycling memory
----------------
@ -102,8 +113,10 @@ Recycling memory
arena.allocated(); // 0k
arena.available(); // 8k
Memory released by @ref Darena::clear is still committed.
It's in use as far as operating system is concerned.
Memory recycled by :cpp:func:`DArena::clear()`
is available for reuse by application; it's still owned by arena.
We're just resetting the free pointer back to the beginning of arena
memory.
To release memory to the operating system, destroy arena:

4
docs/index.rst
View file

@ -24,9 +24,13 @@ Implemented using FOMO (faceted rust-like object model) from xo-facet
examples
implementation
AAllocator-reference
IAllocator_Xfer-reference
AAllocIterator-reference
ArenaConfig-reference
DArena-reference
DArenaIterator-reference
AllocInfo-reference
cmpresult-reference
glossary
genindex
search