/**
 * @file strpool.h
 * @brief 字符串池实现
 * 
 * 提供字符串驻留（String Interning）功能，保证相同字符串的唯一性存储
 */

#ifndef __SMCC_STRPOOL_H__
#define __SMCC_STRPOOL_H__

#include <lib/core.h>
#include <lib/rt/rt_alloc.h>
#include <lib/utils/ds/hashtable.h>

/**
 * @struct strpool_t
 * @brief 字符串池上下文
 * 
 * 组合哈希表和专用内存分配器实现的高效字符串存储池
 */
typedef struct strpool {
    hash_table_t ht;       /**< 哈希表用于快速查找已存储字符串 */
    long_alloc_t stralloc; /**< 长块分配器优化小字符串内存管理 */
} strpool_t;

/**
 * @brief 初始化字符串池
 * @param pool 字符串池实例指针
 * 
 * @warning 使用前需确保 hashtable 的 hash_func 和 key_cmp 已正确设置
 */
void init_strpool(strpool_t* pool);

/**
 * @brief 驻留字符串到池中
 * @param pool 字符串池实例指针
 * @param str 要驻留的 C 字符串
 * @return 池中唯一字符串的持久指针
 * 
 * @note 返回值生命周期与字符串池一致
 * @note 重复插入相同字符串会返回已有指针
 */
const char* strpool_intern(strpool_t* pool, const char* str);

/**
 * @brief 销毁字符串池
 * @param pool 字符串池实例指针
 * 
 * @warning 销毁后已获取的字符串指针将失效
 * @note 会自动释放所有驻留字符串内存
 */
void strpool_destroy(strpool_t* pool);

#endif // __SMCC_STRPOOL_H__