Работа над дневником, запись 05.05.2026

ccpp/fxalloc/includes/FXAlloc.h

@@ -6,6 +6,10 @@
  * @brief Публичный интерфейс модуля-аллокатора fxalloc(includes/FXAlloc.h)
  * 
  * @details Language: C11 (ISO/IEC 9899:2011).
+ * Теоритический маскимальный размер блока `(1 << 32) - 25 = 4 294 967 271 байт`
+ * Первый вызов `fxalloc()`(без предварительного вызова `fxalloc_init()`) в потоке/процессе крайне медленный
+ * так как происходит инициализация пула, последующие вызовы будут работать с инициализированным
+ * пулом памяти.
  * Изначально аллокатор работает в следующем режиме:
  * `fxalloc → выделение блока через malloc() с добавлением метаданных`,
  * `fxfree → анализ метаданных с последующим вызовом free()`. Такое поведение
@@ -16,17 +20,19 @@
  * передачи данных по очередям между потоками без повторных выделений, функция `fxfree()`
  * из любого другого потока вернёт блок владельцу без накладных расходов на TLS, только
  * атомарная синхронизация.\
- * Изменение указателей `fxalloc` и `fxfree` строго запрещено! Без оперделения макроса
- * `_I_UNDERSTAND_THE_RISKS_AND_ASSUME_RESPONSIBILITY_` возникнет ошибка компиляции.\
+ * Изменение указателей `fxalloc` и `fxfree` строго запрещено!\
+ * Без оперделения макроса `_I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_` модуль
+ * не скомпилируется, возникнет ошибка компиляции, определение макроса = подписание конракта.\
  * По завершению работы потока/процесса в системах POSIX вся выделенная память
  * освобождается автоматически, в Windows необходимо вызвать `fxalloc_cleanup()`.
  * */
 #include <stdint.h>
-#include <threads.h>
 
 #ifdef _WIN32 // Windows
+    #include <Windows.h>
     #define thread_local __declspec(thread)
 #else // Linux
+    #include <threads.h>
     #define thread_local __thread
 #endif //_WIN32
 
@@ -37,7 +43,7 @@ extern "C" {
     /**
      * @brief Перечисление режимов работы аллокатора
      */
-    typedef enum {
+    typedef enum eFXAllocProfile {
         FXALLOC_SPEED,      ///< Максимальная производительность без статистики
         FXALLOC_SUMMARY,    ///< Поверхностная статистика
         FXALLOC_FULL        ///< Глубокий анализ расхода памяти
@@ -51,19 +57,17 @@ extern "C" {
      * @var +est_count: size_t - Предполагаемое количество блоков
      */
     typedef struct FXGrade {
-        /// Предполагаемый размер блока
-        const size_t est_size;
-        /// Предполагаемое количество блоков
-        const size_t est_count;
+        const size_t est_size;  ///< Предполагаемый размер блока
+        const size_t est_count; ///< Предполагаемое количество блоков
     } FXGrade;
 
     /**
     * @brief Переключает режимы работы алокатора
-    *    FXALLOC_SPEED,      ///< Максимальная производительность без статистики
-    *    FXALLOC_SUMMARY,    ///< Поверхностная статистика
-    *    FXALLOC_FULL        ///< Глубокий анализ расхода памяти
-    * @retval !0 при успешном переключении
-    * @retval 0 при ошибке(не вероятно)
+    *    `FXALLOC_SPEED` - Максимальная производительность без статистики
+    *    `FXALLOC_SUMMARY` - Поверхностная статистика
+    *    `FXALLOC_FULL` - Глубокий анализ расхода памяти
+    * @retval `1` при успешном переключении
+    * @retval `0` при ошибке(не вероятно)
     */
     int fxalloc_profile(eFXAllocProfile Profile);
 
@@ -72,9 +76,21 @@ extern "C" {
      * @param[in] Grades: const FXGrade* - Указатель на массив градаций
      * @param[in] ThreadName: const char* - Наименование потока, используется при профилировании
      * в следующем виде: `[thread_id] 'thread_name': blocks: total=1024 used=64...`.
-     * Если передан NULL - выводится только ID потока, т.е.: `[thread_id]: ...`
+     * Если передан `NULL` - выводится только ID потока, т.е.: `[thread_id]: ...`
      */
     int fxalloc_init(const FXGrade* Grades, const char* ThreadName);
+
+#ifndef _I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_
+    /**
+     * @brief Указатель на функцию выделения памяти
+     * @note Ни в коем разе не должен изменяться из вызывающего кода!!!
+     * @param[in] NBytes: size_t - Количество байт
+     * @retval `!0` - С адресом кратным размеру `sizeof(size_t)`. Указатель выровненный для любого типа данных
+     * @retval `NULL` - В случае единственно возможной ошибки `ENOMEM` результат сохранён в `errno`
+     * подробное описание `strerror(errno)`
+     */
+    extern thread_local void (*const fxalloc)(size_t NBytes);
+#else
     /**
      * @brief Указатель на функцию выделения памяти
      * @note Ни в коем разе не должен изменяться из вызывающего кода!!!
@@ -82,27 +98,30 @@ extern "C" {
      * @retval !0 - Кратный размеру(sizeof(size_t)) указатель выровненный для любого типа данных
      * @retval NULL - В случае единственно возможной ошибки ENOMEM результат сохранён в errno
      */
-#ifndef _I_UNDERSTAND_THE_RISKS_AND_ASSUME_RESPONSIBILITY_
-    extern thread_local void (*const fxalloc)(size_t NBytes);
-#else
     extern thread_local void (*fxalloc)(size_t NBytes);
 #endif
 
+#ifndef _I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_
     /**
      * @brief Указатель на функцию высвобождения памяти выделенной исключительно fxalloc
      * при использовании на любом другом указателе 100% неопределённое поведение
      * @note Ни в коем разе не должен изменяться из вызывающего кода!!!
-     * @param[in] _Ptr: void* - Указатель на блок памяти
+     * @param[in] Ptr: void* - Указатель на блок памяти
      */
-#ifndef _I_UNDERSTAND_THE_RISKS_AND_ASSUME_RESPONSIBILITY_
     extern thread_local void (*const fxfree)(void* Ptr);
 #else
+    /**
+     * @brief Указатель на функцию высвобождения памяти выделенной исключительно fxalloc
+     * при использовании на любом другом указателе 100% неопределённое поведение
+     * @note Ни в коем разе не должен изменяться из вызывающего кода!!!
+     * @param[in] Ptr: void* - Указатель на блок памяти
+     */
     extern thread_local void (*fxfree)(void* Ptr);
 #endif
 
     /**
-     * @brief Высвобождает ресурсы занятые потоком Вызывать непосредственно перед выходом,
-     * в противном случае UB или segfault
+     * @brief Высвобождает ресурсы занятые потоком. Вызывать непосредственно перед выходом
+     * из потока/процесса, в противном случае - `UB` или `segfault`
      */
     void fxalloc_cleanup();