.. _allocator_file:

********************
C Allocator Overview
********************

Memory allocation in C++ typically involves direct use of the ``new``,
and ``free`` operators. While flexible, these can incur performance
overhead, lead to fragmentation, and increase the risk of memory leaks or
dangling pointers in large applications.

The *Allocator module* in this library provides lightweight and efficient
allocation utilities implemented in pure C and declared in
``allocator.hpp``.  The only dpendency this module has within the CSalt 
library is the ``error.hpp`` file, making it suitable ifor integration 
into larger systems.

Build-time configuration flags modify behavior depending on needs:

* ``STATIC_ONLY`` — Disables all heap allocation. Only stack or static
  memory supplied by the application is permitted.

These features make the allocator suitable for environments requiring strict
determinism and safety analysis, such as embedded and real-time systems or projects 
that require compliance to MISRA C++ standards.

.. _memory_type_enum:

Enums and Data Structures 
=========================
The ``csalt++`` library uses the following enum to help 
indicate if the allocator is utilyzing statically allocated memory from 
the stack or dynamically allocated memory from the heap.

.. code-block:: c++

   enum MemType {
      ALLOC_INVALID = 0,
      STATIC = 1,
      DYNAMIC = 2
   };

.. _allocator_overview:

Allocator Overview 
==================

    .. doxygenclass:: cslt::Allocator
       :members:
       :protected-members:
       :undoc-members:
       :private-members:

.. _heap_overview:

Heap Overview 
=============

    .. doxygenclass:: cslt::HeapAllocator
       :members:

.. _arena_overview:

Arena Overview 
==============

    .. doxygenclass:: cslt::ArenaAllocator
       :members:

ArenaDeleter
------------

An ``ArenaAllocator`` class can have it memory manually freed or be passed 
between scopes.  However, if the user does not manually free the memory, it 
will be automatically freed after it leaves its originating scope.

The ``ArenaDeleter`` struct is a data structure used to destroy Arena memory 
after it goes out of scope.  While this is a publically available struct, the 
struct is automatically invoked via a ``UniquePtr`` when an ``ArenaAllocator``
is initialized, and the user does not need to interact with it.

    .. doxygenstruct:: cslt::ArenaDeleter
       :members:

.. _pool_overview:

Pool Overview 
=============

    .. doxygenclass:: cslt::PoolAllocator
       :members:

Pool Deleter 
------------

A ``PoolAllocator`` class can have it memory manually freed or be passed 
between scopes.  However, if the user does not manually free the memory, it 
will be automatically freed after it leaves its originating scope.

The ``PoolDeleter`` struct is a data structure used to destroy Arena memory 
after it goes out of scope.  While this is a publically available struct, the 
struct is automatically invoked via a ``UniquePtr`` when a ``PoolAllocator``
is initialized, and the user does not need to interact with it.

    .. doxygenstruct:: cslt::PoolDeleter
       :members:

.. _freelist_overview:

Free List Overview 
==================

    .. doxygenclass:: cslt::FreeListAllocator
       :members:

FreeListDeleter
---------------

An ``FreeListAllocator`` class can have it memory manually freed or be passed 
between scopes.  However, if the user does not manually free the memory, it 
will be automatically freed after it leaves its originating scope.

The ``FreeListDeleter`` struct is a data structure used to destroy Arena memory 
after it goes out of scope.  While this is a publically available struct, the 
struct is automatically invoked via a ``UniquePtr`` when an ``FreeListAllocator``
is initialized, and the user does not need to interact with it.

    .. doxygenstruct:: cslt::FreeListDeleter
       :members:

.. _buddy_overview:

Buddy Overview 
==============

    .. doxygenclass:: cslt::BuddyAllocator
       :members:

BuddyDeleter
------------

An ``BuddyAllocator`` class can have it memory manually freed or be passed 
between scopes.  However, if the user does not manually free the memory, it 
will be automatically freed after it leaves its originating scope.

The ``BuddyDeleter`` struct is a data structure used to destroy Arena memory 
after it goes out of scope.  While this is a publically available struct, the 
struct is automatically invoked via a ``UniquePtr`` when an ``BuddyAllocator``
is initialized, and the user does not need to interact with it.

    .. doxygenstruct:: cslt::BuddyDeleter
       :members:

.. _slab_overview:

Slab Overview 
=============

    .. doxygenclass:: cslt::SlabAllocator
       :members:

SlabDeleter
-----------

An ``SlabAllocator`` class can have it memory manually freed or be passed 
between scopes.  However, if the user does not manually free the memory, it 
will be automatically freed after it leaves its originating scope.

The ``SlabDeleter`` struct is a data structure used to destroy Arena memory 
after it goes out of scope.  While this is a publically available struct, the 
struct is automatically invoked via a ``UniquePtr`` when an ``SlabAllocator``
is initialized, and the user does not need to interact with it.

    .. doxygenstruct:: cslt::SlabDeleter
       :members: