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

xo-alloc2: ++ documentation + threshold size for THP feature

Browse source
This commit is contained in:
Roland Conybeare 2025-12-23 21:06:38 -05:00
commit 289751d3fd
18 changed files with 642 additions and 192 deletions
Download patch file Download diff file Expand all files Collapse all files

159
docs/implementation.rst
View file

@ -1,7 +1,7 @@
.. _implementation:
Components
==========
Implementation
==============
Library dependency tower for *xo-alloc2*
@ -15,36 +15,147 @@ Library dependency tower for *xo-alloc2*
| xo_cmake |
+-----------------+
Abstraction tower for *xo-alloc2* components
Abstraction tower for *xo-alloc2* components (simplified)
.. ditaa::
:--scale: 0.99
+--------------------------------+
| IAllocator_DArena |
+--------------------------------+
| IAllocator_Xfer |
| IAllocator_Any |
+--------------+-----------------+
| | DArena |
| AAllocator +-----------------+
| | ArenaConfig |
+--------------+-----------------+
+----------------+-----------------+-------------------+
| | | DArena |
| Allocator | AllocIterator | DArenaIterator |
| | +-------------------+
| | | ArenaConfig |
+----------------+-----------------+-------------------+
| auxiliary types |
+------------------------------------------------------+
.. list-table:: Descriptions
Abstraction tower for *xo-alloc2* components (detailed)
.. 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 | |
+-----------------+----------------------------------------------+-------------------+
.. list-table:: Polymorphic Allocator
:header-rows: 1
:widths: 20 90
* - Component
* - Class
- Description
* - ``AAllocator``
- allocator facet (abstract interface)
* - ``DArena``
- arena representation
* - ``IAllocator_ImplType<D>``
- lookup implementation for allocator A
with representation D.
- Abstract allocator interface for runtime polymorphism
* - ``IAllocator_Any``
- Stub allocator interface for uninitialized variant
* - ``IAllocator_Xfer<D>``
- transfer interface. downcast to native state.
* - ``IAllocator_DArena``
- allocator implementation for ``DArena``
- Allocator interface template for representation ``D``
* - ``IAllocator_Impltype<D>``
- Lookup allocator interface for representation ``D``
* - ``RAllocator<O>``
- Provide allocator methods for FOMO object ``O``
.. list-table:: Polymorphich Alloc Iterator
:header-rows: 1
:widths: 20 90
* - Class
- Description
* - ``AAllocIterator``
- Abstract interface for iteration over allocs
* - ``IAllocIterator_Any``
- Stub alloc-iterator interface for uninitialized variant
* - ``IAllocIterator_Xfer<D>``
- Alloc-iterator interface template for representation ``D``
* - ``IAllocIterator_Impltype<D>``
- Lookup alloc-iterator interface for representation ``D``
* - ``RAllocIterator<D>``
- Provide alloc-iterator methods for FOMO object ``O``.
.. list-table:: Native Arena Allocator
:header-rows: 1
:widths: 20 90
* - Class
- Description
* - ``ArenaConfig``
- Configuration for a ``DArena`` instance
* - ``DArena``
- VM-aware arena allocator
* - ``DArenaIterator``
- Iterator over ``DArena`` allocations
* - ``IAlllocator_DArena``
- Adapt a ``DArena`` to facet ``AAllocator``
* - ``IAllocIterator_DArenaAllocator``
- Adapt a ``DArenaIterator`` to facet ``AAllocIterator``
.. list-table:: Auxiliary/Support Types
:header-rows: 1
:widths: 20 90
* - Class
- Description
* - ``AllocError``
- Return type for an alloc request, with error details.
* - ``AllocInfo``
- An opaque allocation. Value of an alloc-iterator.
* - ``AllocHeaderConfig``
- Per-allocator configuration of alloc headers
* - ``AllocHeader``
- Per-allocation header (8 bytes)
* - ``cmpresult``
- Result of alloc-iterator comparison
Example Object Diagram
.. uml::
:caption: representation for an arena allocator
:scale: 99%
:align: center
object rarena1<<RAllocator>>
rarena1 : iface = vtable1
rarena1 : data = darena1
object vtable1<<IAllocator_DArena_vtable>>
vtable1 : alloc()
object darena1<<DArena>>
darena1 : config
darena1 : lo
darena1 : hi
darena1 : free
darena1 : limit
darena1 : last_error
rarena1 o-- vtable1
rarena1 o-- darena1
Remarks:
* When we know the allocator representation at compile time (``DArena`` here),
then we also know the interface (``IAllocator_DArena``).
Devirtualization is easy since interface methods are all final.
* Size of a FOMO object is two pointers; it's natural to create such objects
on the fly and pass them by value.
When storing an allocator in another data structure, we only need to use
the RAllocator stack if we want runtime polymorphism for the stored allocator.
Otherwise can store a ``DArena`` instance.