/**
 * 日期: 2026-03-31
 * 作者: coffee
 * 描述: 基于 HTlsf 的引用计数内存管理模块
 *       单例模式，只需初始化一次
 *       支持引用计数、自动释放、外部内存拷贝转换
 */

#ifndef _H_MEM_H_
#define _H_MEM_H_


#include <stdint.h>
#include <stddef.h>


/**
 * @brief 初始化内存管理器（单例模式，只需调用一次）
 * @param buffer 外部缓冲区
 * @param size 缓冲区大小
 * @return 成功返回1, 失败返回0
 */
uint8_t HMemInit(void *buffer, size_t size);

/**
 * @brief 判断是否已初始化
 */
uint8_t HMemIsReady(void);

/**
 * @brief 分配内存
 * @param size 请求大小
 * @return 成功返回内存指针, 失败返回NULL
 */
void *HMemMalloc(size_t size);

/**
 * @brief 分配并清零内存
 * @param num 元素数量
 * @param size 每个元素大小
 * @return 成功返回内存指针, 失败返回NULL
 */
void *HMemCalloc(size_t num, size_t size);

/**
 * @brief 重新分配内存
 * @param ptr 原内存指针
 * @param size 新大小
 * @return 成功返回内存指针, 失败返回NULL (原内存保持不变)
 */
void *HMemRealloc(void *ptr, size_t size);

/**
 * @brief 释放内存 (引用计数为0时才真正释放)
 * @param ptr 内存指针
 * @return 成功返回1, 失败返回0
 */
uint8_t HMemFree(void *ptr);

/**
 * @brief 增加引用计数或拷贝外部内存
 * @param ptr 内存指针 (可以是外部内存)
 * @param size 如果是外部内存，指定要拷贝的大小；如果是 HMem 内存，此参数被忽略
 * @return
 *   - 如果是 HMem 分配的内存, 返回 ptr (引用计数+1)
 *   - 如果是外部内存, 返回新分配的内存指针 (内容已拷贝)
 *   - 内存不足返回 NULL
 */
void *HMemAddRef(void *ptr, size_t size);

/**
 * @brief 获取当前引用计数
 * @param ptr 内存指针
 * @return 引用计数, 如果不是 HMem 分配的返回 0
 */
uint32_t HMemGetRefCount(void *ptr);

/**
 * @brief 判断指针是否由 HMem 分配
 * @param ptr 内存指针
 * @return 是返回1, 否返回0
 */
uint8_t HMemIsManaged(void *ptr);

/**
 * @brief 获取可用内存大小
 */
size_t HMemGetFreeSize(void);

/**
 * @brief 获取已使用内存大小
 */
size_t HMemGetUsedSize(void);

/**
 * @brief 获取总容量
 */
size_t HMemGetCapacity(void);


#endif // _H_MEM_H_