Работа над дневником

ccpp/fxalloc/includes/FXAlloc.h

@@ -1,47 +1,110 @@
 #pragma once
-
+/**
+ * @file neurox/ccpp/fxalloc/includes/FXAlloc.h
+ * @author felex67 (admin@felexdev.ru)
+ * @version 1.0.0 beta 
+ * @brief Публичный интерфейс модуля-аллокатора fxalloc(includes/FXAlloc.h)
+ * 
+ * @details Language: C11 (ISO/IEC 9899:2011).
+ * Изначально аллокатор работает в следующем режиме:
+ * `fxalloc → выделение блока через malloc() с добавлением метаданных`,
+ * `fxfree → анализ метаданных с последующим вызовом free()`. Такое поведение
+ * помогает сборать статистику для профилирования, которые могут быть получены
+ * переводом аллокатора в режим анализа(выполняется потоком-наблюдателем).
+ * При необходимости выделения отдельного пула для потока используйте `fxalloc_init()`,
+ * в глобальном пуле(НЕ TLS!!!) будет выделен блок памяти для этого потока, что даст возможность
+ * передачи данных по очередям между потоками без повторных выделений, функция `fxfree()`
+ * из любого другого потока вернёт блок владельцу без накладных расходов на TLS, только
+ * атомарная синхронизация.\
+ * Изменение указателей `fxalloc` и `fxfree` строго запрещено! Без оперделения макроса
+ * `_I_UNDERSTAND_THE_RISKS_AND_ASSUME_RESPONSIBILITY_` возникнет ошибка компиляции.\
+ * По завершению работы потока/процесса в системах POSIX вся выделенная память
+ * освобождается автоматически, в Windows необходимо вызвать `fxalloc_cleanup()`.
+ * */
 #include <stdint.h>
+#include <threads.h>
 
-#ifndef _WIN32
-    #include <sys/types.h>
+#ifdef _WIN32 // Windows
+    #define thread_local __declspec(thread)
+#else // Linux
+    #define thread_local __thread
 #endif //_WIN32
 
 #ifdef __cplusplus
 extern "C" {
 #endif //__cplusplus
 
-/**
- * @brief Структура преднастройки аллокатора задающая градации и количество блоков памяти
- * 
- * @property +est_size: size_t - Предполагаемый размер блока
- * @property +est_count: size_t - Предполагаемое количество блоков
- */
-typedef struct FXGrade {
-    /// Предполагаемый размер блока
-    const size_t est_size;
-    /// Предполагаемое количество блоков
-    const size_t est_count;
-} FXGrade;
+    /**
+     * @brief Перечисление режимов работы аллокатора
+     */
+    typedef enum {
+        FXALLOC_SPEED,      ///< Максимальная производительность без статистики
+        FXALLOC_SUMMARY,    ///< Поверхностная статистика
+        FXALLOC_FULL        ///< Глубокий анализ расхода памяти
+    }  eFXAllocProfile;
 
-/**
- * @brief Переменная для сохранения преднастроек пула памяти с ноль-терминантом
- * Определена в src/FXAlloc.c 
- */
-extern const FXGrade* grades;
+    /**
+     * @brief Структура преднастройки аллокатора задающая градации и количество блоков памяти.
+     * Массив должен быть отсортирован по возрастанию размера блока
+     * и заканчиваться элементом с `est_size = 0`
+     * @var +est_size: size_t - Предполагаемый размер блока
+     * @var +est_count: size_t - Предполагаемое количество блоков
+     */
+    typedef struct FXGrade {
+        /// Предполагаемый размер блока
+        const size_t est_size;
+        /// Предполагаемое количество блоков
+        const size_t est_count;
+    } FXGrade;
 
-/**
- * @brief Функция выделения памяти
- * @param[in] _NBytes: size_t - Количество байт
- * @retval !0 - Кратный size_t указатель выровненный для любого типа данных
- * @retval NULL - В случае единственно возможной ошибки EBADALLOC результат сохранён в errno
- */
-void* fxalloc(size_t _NBytes);
+    /**
+    * @brief Переключает режимы работы алокатора
+    *    FXALLOC_SPEED,      ///< Максимальная производительность без статистики
+    *    FXALLOC_SUMMARY,    ///< Поверхностная статистика
+    *    FXALLOC_FULL        ///< Глубокий анализ расхода памяти
+    * @retval !0 при успешном переключении
+    * @retval 0 при ошибке(не вероятно)
+    */
+    int fxalloc_profile(eFXAllocProfile Profile);
 
-/**
- * @brief Высвобождает память выделенную исключительно fxalloc
- * @param[in] _Ptr: void*
- */
-void fxfree(void* _Ptr);
+    /**
+     * @brief Инициализирует локальный пулл памяти исходя из заданных параметров блоков
+     * @param[in] Grades: const FXGrade* - Указатель на массив градаций
+     * @param[in] ThreadName: const char* - Наименование потока, используется при профилировании
+     * в следующем виде: `[thread_id] 'thread_name': blocks: total=1024 used=64...`.
+     * Если передан NULL - выводится только ID потока, т.е.: `[thread_id]: ...`
+     */
+    int fxalloc_init(const FXGrade* Grades, const char* ThreadName);
+    /**
+     * @brief Указатель на функцию выделения памяти
+     * @note Ни в коем разе не должен изменяться из вызывающего кода!!!
+     * @param[in] NBytes: size_t - Количество байт
+     * @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
+
+    /**
+     * @brief Указатель на функцию высвобождения памяти выделенной исключительно fxalloc
+     * при использовании на любом другом указателе 100% неопределённое поведение
+     * @note Ни в коем разе не должен изменяться из вызывающего кода!!!
+     * @param[in] _Ptr: void* - Указатель на блок памяти
+     */
+#ifndef _I_UNDERSTAND_THE_RISKS_AND_ASSUME_RESPONSIBILITY_
+    extern thread_local void (*const fxfree)(void* Ptr);
+#else
+    extern thread_local void (*fxfree)(void* Ptr);
+#endif
+
+    /**
+     * @brief Высвобождает ресурсы занятые потоком Вызывать непосредственно перед выходом,
+     * в противном случае UB или segfault
+     */
+    void fxalloc_cleanup();
 
 #ifdef __cplusplus
 }