работа над документацией

includes/FXAlloc.h

@@ -4,48 +4,55 @@
  * @author felex67 (admin@felexdev.ru)
  * @version 1.0.0 dev-in-progress
  * 
- * @brief Публичный интерфейс модуля аллокатора-профилировщика
+ * @brief Публичный интерфейс модуля аллокатора-профилировщика для серверных очередей/пакетов
  * 
  * @details Language: C11 (ISO/IEC 9899:2011).
  * 
- * Теоретический маскимальный размер блока `(1 << 32) - 25 = 4 294 967 271 байт`
+ * SRP + KISS + YAGNI + HLP(High Level Performance)
+ *
+ * @note Поддерживаемые компиляторы:
+ * - MSVC: Версия >= 1930(VisualStudio 22+)
+ * - GCC: Версия >= 5.0
+ * - CLang: Любая
  * 
- * При первом вызове `fxalloc()` до `fxalloc_init()` в глобальной облачти будет
- * проинициализирован пул с градациями 
+ * @warning Изменять указатели `(*fxalloc)()/(*fxfree)()` строго запрещено!!!
+ * @note Для увеличения производительности необходимо заключение контракта: определение
+ * макроса `_I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_`. Без определения
+ * этого макроса модуль вынужден работать через прокси-функции что влечёт за собой
+ * снижение производительности(увеличение ~25 тактов на вызов `fxalloc/fxfree`).
+ *
+ * @note Режим `__FXALLOC_TURBO` работает только при неконстантных `fxalloc/fxfree`.
+ * В этом режиме недоступен глубокий анализ использования памяти. Особенности:
+ *  - Метаданные для каждого блока уменьшаются до 16-ти байт.
+ *  - Все блоки выравниваются по адресам кратным 16.
+ *  - Все LIFO Грейдов выравниваются по L1(кэш процессора первого уровня). Настроить можно
+ *    изменив `FXALLOC_LIFO_HEAD_ALIGN` на соответствующее Вашей архитектуре значение
  * 
- * Первый вызов `fxalloc()`(без предварительного вызова `fxalloc_init()`) в
+ * @note Первый вызов `fxalloc()`(без предварительного вызова `fxalloc_init()`) в
  * потоке/процессе крайне медленный так как происходит инициализация пула,
- * последующие вызовы будут работать с инициализированным пулом памяти.
+ * для потока/процесса, последующие вызовы будут работать с инициализированным пулом памяти.
+ * Для преднастройки пула потока используйте функцию `fxalloc_init()`.
  * 
- * Изначально аллокатор работает в следующем режиме:
- *     `fxalloc` → выделение блока через `malloc()` с добавлением метаданных,
- *     `fxfree` → анализ метаданных с последующим вызовом `free()`.
- * Такое поведение помогает сборать статистику для профилирования, которые могут
- * быть получены переводом аллокатора в режим анализа(выполняется потоком-наблюдателем).
+ * @note Теоретический максимальный размер блока `(1U << 32) - 25` → 4'294'967'271 байт.
+ * Рекомендуемый размер блока не более 64 КиБ.
  * 
- * При необходимости выделения отдельного пула для потока используйте `fxalloc_init()`,
- * в глобальном пуле(НЕ TLS!!!) будет выделен блок памяти для этого потока, что даст возможность
- * передачи данных по очередям между потоками без повторных выделений, функция `fxfree()`
- * из любого другого потока вернёт блок владельцу без накладных расходов на TLS, только
- * атомарная синхронизация.\
+ * Алгоритмы использования:
+ * 1. `void* ptr = fxalloc(N) → работаем с ptr → fxfree(ptr) → fxalloc_cleanup()`
+ *  - `fxalloc` → При первом вызове инициализирует пул в глобальной области с настройками
+ *                по умолчанию для данного потока, вызывает `malloc`, устанавливает метаданные.
+ *  - Работа с указателем: Можно передавать в любой поток.
+ *  - `fxfree` → анализ метаданных с последующим возвратом блока потоку-владельцу без
+ *               вызова `free()`, блок остаётся в пуле.
+ *  - `fxalloc_cleanup()` → Запускает процесс очищения памяти занятой потоком.
+ * 2. `fxalloc_init(grades, threadName, FXSEARCH_...) → работаем → fxalloc_cleanup()`
+ *  - `fxalloc_init` → Инициализирует пул в глобальной области для данного потока с
+ *                     переданными настройками: FXGrade*, ThreadName, eXFAllocSearchType.
+ *  - `fxalloc_cleanup()` → Запускает процесс очищения памяти занятой потоком.
+ * Такое поведение помогает собрать статистику для профилирования. Данные об использовании
+ * памяти могут быть получены переводом аллокатора в режим анализа(выполняется потоком-наблюдателем).
  * 
- * Изменение указателей `fxalloc` и `fxfree` строго запрещено!!!\
  * 
- * Зачем нужен макрос `_I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_`:
- * В случае когда макрос определён модульне может изменять `(*fxalloc)()/(*fxfree)()` напрямую
- * и вынужден работать через прокси-функцию, что добавляет +-25 такстов к каждому вызову
- * пользователем `(*fxaloc)()/(*fxfree)()`, т.к. оба указывают на прокси-функции. При
- * рпределении макроса необходимость в проксировании отсутствует, т.к. модуль может менять
- * `(*fxaloc)()/(*fxfree)()` напрямую. Однако даже при определении макроса пользователь никогда
- * ни в коем случае не должен изменять эти указатели!!!
- * Определение макроса `_I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_` равно
- * подписанию контракта. Если в дальнейшем код пользователя изменит любой из этих указателей
- * вся вина лежит исключительно на нём!
- * 
- * По завершению работы потока/процесса в системах POSIX вся выделенная память
- * освобождается автоматически, в Windows необходимо вызвать `fxalloc_cleanup()`.
- * 
- * Подробное описание процесса разработки интерфейса и аллокатора вцелом можно найти в файле:
+ * Подробное описание процесса разработки интерфейса и аллокатора в целом можно найти в файле:
  * `neurox/ccpp/fxalloc/DIARY.md`
  * */
 
@@ -84,7 +91,7 @@ extern "C" {
     }  eFXAllocProfile;
 
     /**
-     * @brief Задаёт шаг градаций по-умолчанию используемый в изначальной версии
+     * @brief Задаёт шаг градаций по умолчанию используемый в изначальной версии
      * `fxalloc()`. Градации будут заполнены для блоков с шагом в
      * `1 << FXALLOC_DEFAULT_GRADE_STEP_SHIFT` до размера 65 535 байт(~1024 грейда),
      * все блоки будут сохраняться в LIFO каждого грейда до конца работы потока.
@@ -95,7 +102,7 @@ extern "C" {
      * @details Если установить данный параметр  0 будет недоступен режим полного
      * профилирования, статистика будет содержать только `malloced = N times`,
      * `average_size = N bytes`, `min = N bytes` и `max = N bytes`.
-     * В случае по-умолчанию можно будет получить более подробную информацию по
+     * В случае по умолчанию можно будет получить более подробную информацию по
      * каждому грейду и использованию памяти в нём. Не рекомендуется снижать параметр,
      * т.к. это напрямую повлияет на размер метаданных пула.
      */
@@ -192,13 +199,33 @@ extern "C" {
      */
     extern TLS void (*fxfree)(void* Ptr);
 #endif
-
     /**
      * @brief Высвобождает ресурсы занятые потоком. Вызывать непосредственно перед выходом
      * из потока/процесса, в противном случае - `UB` или `segfault`
      */
     void fxalloc_cleanup();
 
+    /**
+     * @brief Структурная единица отчёта
+     * 
+     */
+    typedef struct FXAllocGradeStat {
+        uint32_t block_size;        ///< Размер блока(грейд)
+        uint32_t blocks_total;      ///< Всего блоков
+        uint32_t blocks_prealloced; ///< Преаллоцировано блоков
+        uint32_t blocks_malloced;   ///< Блоков выделенных дополнительно
+        uint32_t blocks_used;       ///< Блоков используется
+        uint32_t data_min;          ///< Минимальный размер данных
+        uint32_t data_max;          ///< Максимальный размер данных
+        uint32_t data_avg;          ///< Средняя арифметическая `(data_1 + ... + data_N) / total` bytes
+    } FXAllocGradeStat;
+
+    typedef struct FXAllocStatistics {
+        const char* thread_name;    ///<
+        FXAllocGradeStat* profile;  ///<
+        size_t thread_id;           ///<
+        size_t ngrades;             ///<
+    } FXAllocStatistics;
 #ifdef __cplusplus
 }
 #endif //__cplusplus