#pragma once /** * @file fxalloc/includes/FXAlloc.h * @author felex67 (admin@felexdev.ru) * @version 1.0.0 dev-in-progress * * @brief Публичный интерфейс модуля аллокатора-профилировщика для серверных очередей/пакетов * * @details Language: C11 (ISO/IEC 9899:2011). * * SRP + KISS + YAGNI + HLP(High Level Performance) * * @note Поддерживаемые компиляторы: * - MSVC: Версия >= 1930(VisualStudio 22+) * - GCC: Версия >= 5.0 * - CLang: Любая * * @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` на соответствующее Вашей архитектуре значение * * @note Первый вызов `fxalloc()`(без предварительного вызова `fxalloc_init()`) в * потоке/процессе крайне медленный так как происходит инициализация пула, * для потока/процесса, последующие вызовы будут работать с инициализированным пулом памяти. * Для преднастройки пула потока используйте функцию `fxalloc_init()`. * * @note Теоретический максимальный размер блока `(1U << 32) - 25` → 4'294'967'271 байт. * Рекомендуемый размер блока не более 64 КиБ. * * Алгоритмы использования: * 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()` → Запускает процесс очищения памяти занятой потоком. * Такое поведение помогает собрать статистику для профилирования. Данные об использовании * памяти могут быть получены переводом аллокатора в режим анализа(выполняется потоком-наблюдателем). * * * Подробное описание процесса разработки интерфейса и аллокатора в целом можно найти в файле: * `neurox/ccpp/fxalloc/DIARY.md` * */ #ifdef __cplusplus extern "C" { #endif //__cplusplus #include #if (defined(__GNUC__) && (__GNUC__ >= 5)) || defined(__clang__) #include #include #define TLS __thread typedef pthread_mutex_t fxsync_t; typedef pthread_t thread_id_t; #elif defined(_MSC_VER) && _MSC_VER >= 1930 #include #include #define TLS __declspec(thread) typedef HANDLE fxsync_t; typedef HANDLE thread_id_t; #else #error "Unsupported compiler. Only Clang, GCC >=5.0 and MSVC VS 2022+ support _Atomic in C11" #endif /** * @brief Перечисление режимов работы аллокатора */ typedef enum eFXAllocProfile { FXALLOC_SPEED, ///< Максимальная производительность без статистики FXALLOC_SUMMARY, ///< Поверхностная статистика FXALLOC_FULL, ///< Глубокий анализ расхода памяти FXALLOC_GETPROFILE, ///< Используется для получения текущего профиля } eFXAllocProfile; /** * @brief Задаёт шаг градаций по умолчанию используемый в изначальной версии * `fxalloc()`. Градации будут заполнены для блоков с шагом в * `1 << FXALLOC_DEFAULT_GRADE_STEP_SHIFT` до размера 65 535 байт(~1024 грейда), * все блоки будут сохраняться в LIFO каждого грейда до конца работы потока. * Такой режим предусмотрен для профилирования. * @note Изменение шага напрямую влияет на количество грейдов и размер метаданных * при увеличении на 1(7): шаг грейда - 128 байт, размер пула - 512 грейдов и т.д. * при уменьшении на 1(5): шаг грейда - 32 байта, размер пула - 2048 грейдов и т.д. * @details Если установить данный параметр 0 будет недоступен режим полного * профилирования, статистика будет содержать только `malloced = N times`, * `average_size = N bytes`, `min = N bytes` и `max = N bytes`. * В случае по умолчанию можно будет получить более подробную информацию по * каждому грейду и использованию памяти в нём. Не рекомендуется снижать параметр, * т.к. это напрямую повлияет на размер метаданных пула. */ typedef enum eFXAllocConfig { FXALLOC_GRADE_STEP_SHIFT = 6,///< left bit shifts (1 << 6) = 64 - hf FXALLOC_LIFO_HEAD_ALIGN = 64,///< Задаёт выравнивание LIFO по L1 cache } eFXAllocConfig; /** * @brief Варианты настройки алгоритма поиска грейдов для данного потока * В случае если первой в потоке вызывается функция `fxalloc` режим автоматически * устанавливается в сдвиговый, т.к. Инициализируется пул согласно * `FXALLOC_GRADE_STEP_SHIFT` в своём алгоритме функции сдвигового поиска опираются * именно на это значение. * В противном случае(первый вызов - `fxalloc_init`) вы можете сами задать тип поиска. * Рекомендации под задачу: * * Высокая вариативность - оставить градации по умолчанию откалибровав `FXALLOC_GRADE_STEP_SHIFT` * * Низкая вариативность(очереди) - линейный поиск * * Средняя вариативность(запросы и т.д.) - бираный поиск */ typedef enum eXFAllocSearchType { FXSEARCH_AUTO, ///< Выберется Бинарный/линейный в зависимости от длины массива градаций(>= 7) FXSEARCH_LINEAR, ///< Линейный поиск FXSEARCH_BINARY, ///< Бинарный поиск FXSEARCH_SHIFTED, ///< Поиск сдвигом вправо(`idx = (NBytes - 1) >> FXALLOC_GRADE_STEP_SHIFT;`) } eXFAllocSearchType; /** * @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 Переключает режимы работы алокатора * `FXALLOC_SPEED` - Максимальная производительность без статистики * `FXALLOC_SUMMARY` - Поверхностная статистика * `FXALLOC_FULL` - Глубокий анализ расхода памяти * @retval `1` при успешном переключении * @retval `0` при ошибке(не вероятно) */ int fxalloc_profile(eFXAllocProfile Profile); /** * @brief Инициализирует локальный пулл памяти исходя из заданных параметров блоков * @param[in] Grades: const FXGrade* - Указатель на массив градаций * @param[in] ThreadName: const char* - Наименование потока, используется при профилировании * @param[in] SearchType: eXFAllocSearchType - Тип поиска по градациям * в следующем виде: `[thread_id] 'thread_name': blocks: total=1024 used=64...`. * Если передан `NULL` - выводится только ID потока, т.е.: `[thread_id]: ...` */ int fxalloc_init(const FXGrade* Grades, const char* ThreadName, eXFAllocSearchType SearchType); #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 TLS void (*const fxalloc)(size_t NBytes); #else /** * @brief Указатель на функцию выделения памяти * @note Ни в коем разе не должен изменяться из вызывающего кода!!! * @param[in] NBytes: size_t - Количество байт * @retval !0 - Кратный размеру(sizeof(size_t)) указатель выровненный для любого типа данных * @retval NULL - В случае единственно возможной ошибки ENOMEM результат сохранён в errno */ extern TLS void (*fxalloc)(size_t NBytes); #endif #ifndef _I_UNDERSTAND_THAT_I_SHOULD_NEVER_CHANGE_THESE_POINTERS_ /** * @brief Указатель на функцию высвобождения памяти выделенной исключительно fxalloc * при использовании на любом другом указателе 100% неопределённое поведение * @note Ни в коем разе не должен изменяться из вызывающего кода!!! * @param[in] Ptr: void* - Указатель на блок памяти */ extern TLS void (*const fxfree)(void* Ptr); #else /** * @brief Указатель на функцию высвобождения памяти выделенной исключительно fxalloc * при использовании на любом другом указателе 100% неопределённое поведение * @note Ни в коем разе не должен изменяться из вызывающего кода!!! * @param[in] Ptr: void* - Указатель на блок памяти */ 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