includes/Core/e_memory.h - master - Zamar_Terrier/TigorEngine

includes/Core/e_memory.h
301 строка13 KB
Zamar_Terrier
Офигенное обновление движка
31 июл 2026, 21:03
31 июл 2026, 21:031682686
/**
 * @file e_memory.h
 * @brief Модуль управления памятью и динамическими структурами данных
 *
 * Этот модуль предоставляет функции для управления памятью, а также реализует
 * базовые динамические структуры данных: стек (Stack) и вектор (Vector).
 * Основные возможности:
 * - Управление выделением и освобождением памяти
 * - Работа со стеками (Stack) с поддержкой функций уничтожения элементов
 * - Работа с динамическими векторами (Vector)
 * - Отслеживание выделений памяти для отладки
 */

#ifndef E_MEMORY_H
#define E_MEMORY_H

#include "Variabels/engine_includes.h"

/**
 * @brief Инициализирует стек
 *
 * Создает новый стек с заданным именем для идентификации в отладке.
 *
 * @param name Имя стека для идентификации в отладочных целях
 * @return Указатель на инициализированный стек
 */
ChildStack *StackInit(char *name);

/**
 * @brief Создаёт элемент в стеке с функцией уничтожения
 *
 * Выделяет память для элемента заданного размера и добавляет его в стек.
 * При удалении элемента будет вызвана указанная функция уничтожения.
 *
 * @param header Указатель на заголовок стека
 * @param size Размер выделяемой памяти в байтах
 * @param destroyer Функция уничтожения, вызываемая при удалении элемента
 * @return Указатель на выделенную память элемента
 */
void *StackNewElementWD(ChildStack *header, uint32_t size, void(*destroyer)(void *));

/**
 * @brief Создаёт элемент в стеке без функции уничтожения
 *
 * Выделяет память для элемента заданного размера и добавляет его в стек.
 * При удалении элемента функция уничтожения не вызывается.
 *
 * @param header Указатель на заголовок стека
 * @param size Размер выделяемой памяти в байтах
 * @return Указатель на выделенную память элемента
 */
void *StackNewElement(ChildStack *header, uint32_t size);

/**
 * @brief Получает элемент стека по индексу
 *
 * Возвращает указатель на элемент стека по указанному индексу.
 *
 * @param header Указатель на заголовок стека
 * @param indx Индекс элемента (начиная с 0)
 * @return Указатель на элемент стека
 */
void *StackGetElement(ChildStack *header, uint32_t indx);

/**
 * @brief Получает количество элементов в стеке
 *
 * Возвращает текущее количество элементов в стеке.
 *
 * @param header Указатель на заголовок стека
 * @return Количество элементов в стеке
 */
uint32_t StackGetSize(ChildStack *header);

/**
 * @brief Удаляет элемент из стека
 *
 * Удаляет указанный элемент из стека и вызывает функцию удаления.
 *
 * @param header Указатель на заголовок стека
 * @param obj Указатель на удаляемый объект
 * @param deleter Функция удаления объекта
 * @return 0 при успешном удалении, код ошибки в противном случае
 */
int StackDeleteElement(ChildStack **header, void *obj, void(*deleter)(void *));

/**
 * @brief Очищает стек
 *
 * Удаляет все элементы из стека, вызывая функцию удаления для каждого.
 *
 * @param header Указатель на заголовок стека
 * @param deleter Функция удаления объектов
 * @param output Флаг вывода отладочной информации (0 - без вывода, 1 - с выводом)
 */
void StackClear(ChildStack *header, void(*deleter)(void *), int output);

/**
 * @brief Удаляет стек
 *
 * Удаляет заголовок стека и освобождает связанную память.
 *
 * @param header Указатель на заголовок стека
 */
void StackDelete(ChildStack *header);

/**
 * @brief Инициализирует вектор
 *
 * Создает новый вектор заданного размера элементов без функции уничтожения.
 *
 * @param vector Указатель на указатель вектора (будет инициализирован)
 * @param elem_size Размер одного элемента в байтах
 * @param name Имя вектора для идентификации в отладке
 */
void VectorInit(CustomVector **vector, uint32_t elem_size, const char *name);

/**
 * @brief Инициализирует вектор с функцией уничтожения
 *
 * Создает новый вектор заданного размера элементов с функцией уничтожения.
 *
 * @param vector Указатель на указатель вектора (будет инициализирован)
 * @param elem_size Размер одного элемента в байтах
 * @param name Имя вектора для идентификации в отладке
 * @param destroyer Функция уничтожения объектов
 */
void VectorInitWD(CustomVector **vector, uint32_t elem_size, const char *name, void(*destroyer)(void *));

/**
 * @brief Изменяет ёмкость вектора
 *
 * Изменяет выделенную память для вектора, сохраняя существующие элементы.
 *
 * @param vector Указатель на вектор
 * @param size Новая емкость вектора (количество элементов)
 */
void VectorResize(CustomVector *vector, uint32_t size);

/**
 * @brief Добавляет элемент в вектор
 *
 * Добавляет новый элемент в конец вектора, увеличивая его размер при необходимости.
 *
 * @param vector Указатель на вектор
 * @return Указатель на выделенную память нового элемента
 */
void *VectorAdd(CustomVector *vector);

/**
 * @brief Добавляет массив элементов в вектор
 *
 * Добавляет массив элементов в конец вектора.
 *
 * @param vector Указатель на вектор
 * @param size Количество элементов для добавления
 * @return Указатель на начало выделенной памяти для новых элементов
 */
void *VectorAddArray(CustomVector *vector, uint32_t size);

/**
 * @brief Копирует объект в вектор
 *
 * Копирует указанный объект в конец вектора.
 *
 * @param vector Указатель на вектор
 * @param obj Указатель на копируемый объект
 */
void VectorCopy(CustomVector *vector, void *obj);

/**
 * @brief Копирует массив в вектор
 *
 * Копирует массив объектов в конец вектора.
 *
 * @param vector Указатель на вектор
 * @param obj Указатель на копируемый массив
 * @param size Количество элементов для копирования
 */
void VectorCopyArray(CustomVector *vector, void *obj, uint32_t size);

/**
 * @brief Удаляет объект из вектора
 *
 * Удаляет указанный объект из вектора.
 *
 * @param vector Указатель на вектор
 * @param obj Указатель на удаляемый объект
 */
void VectorDelete(CustomVector *vector, void *obj);

/**
 * @brief Получает количество элементов в векторе
 *
 * Возвращает текущее количество элементов в векторе.
 *
 * @param vector Указатель на вектор
 * @return Количество элементов в векторе
 */
uint32_t VectorGetSize(CustomVector *vector);
uint32_t VectorGetCapacity(CustomVector *vector);
/**
 * @brief Получает данные вектора
 *
 * Возвращает указатель на внутренний буфер данных вектора.
 *
 * @param vector Указатель на вектор
 * @return Указатель на данные вектора
 */
void *VectorGetData(CustomVector *vector);

/**
 * @brief Очищает вектор
 *
 * Удаляет все элементы из вектора, но не освобождает память вектора.
 *
 * @param vector Указатель на вектор
 */
void VectorClear(CustomVector *vector);

/**
 * @brief Уничтожает вектор
 *
 * Освобождает всю память, выделенную для вектора.
 *
 * @param vector Указатель на вектор
 */
void VectorDestroy(CustomVector *vector);

/**
 * @brief Инициализирует систему управления памятью
 *
 * Инициализирует внутренние структуры системы управления памятью.
 * Должен вызываться до любых других функций выделения памяти.
 */
void InitMemory();

/**
 * @brief Выделяет блок памяти
 *
 * Выделяет блок памяти заданного размера.
 *
 * @param count Количество элементов
 * @param size Размер одного элемента в байтах
 * @return Указатель на выделенную память
 */
void *AllocateMemory(size_t count, int32_t size);

/**
 * @brief Выделяет блок памяти с именем
 *
 * Выделяет блок памяти с именем для идентификации в отладке.
 *
 * @param count Количество элементов
 * @param size Размер одного элемента в байтах
 * @param name Имя блока памяти для идентификации
 * @return Указатель на выделенную память
 */
void *AllocateMemoryN(size_t count, int32_t size, char *name);

/**
 * @brief Выделяет блок памяти с родительским указателем
 *
 * Выделяет блок памяти и устанавливает родительский указатель для иерархии.
 *
 * @param count Количество элементов
 * @param size Размер одного элемента в байтах
 * @param parent Родительский указатель для иерархии памяти
 * @return Указатель на выделенную память
 */
void *AllocateMemoryP(size_t count, int32_t size, void *parent);

/**
 * @brief Получает количество выделений памяти
 *
 * Возвращает текущее количество выделенных блоков памяти.
 * Используется для отслеживания утечек памяти.
 *
 * @return Количество выделенных блоков памяти
 */
uint32_t GetAllocatedMemoryCount();

/**
 * @brief Освобождает блок памяти
 *
 * Освобождает ранее выделенный блок памяти.
 *
 * @param data Указатель на блок памяти для освобождения
 * @return 0 при успешном освобождении, код ошибки в противном случае
 */
int FreeMemory(void *data);

/**
 * @brief Освобождает всю память
 *
 * Освобождает всю память, выделенную через систему управления памятью.
 * Используется для очистки перед завершением программы.
 */
void ClearAllAllocatedMemory();

#endif // E_MEMORY_H