map

IntMap

IntMap 是以 int64 为键、按键有序、值大小固定的稀疏映射。它继承旧版 List 已经验证的整数键体系，但使用准确的容器名称，并复用新版拥有式 AVL 树和固定对象池。

启用与依赖

功能宏：

int_map 依赖 avl_tree，因此完整依赖链为：

公共头文件会拒绝缺失 XRT_FEATURE_AVL_TREE 的非法裁剪组合。

存储模型

每个条目只占用一个固定池槽：

• 键支持 INT64_MIN 到 INT64_MAX。
• 键可以为负数、跳号或极度稀疏，没有最大索引造成的连续空间浪费。
• 值直接内联在树节点中，没有逐值堆分配。
• 值地址在该键被删除、Clear 或 Unit 前保持稳定。
• 遍历顺序是整数键升序或降序，不是插入顺序。
• 查找、插入和删除的复杂度是 O(log n)。

IntMap 不内置线程归属、锁或 shared 模式。这个基础容器的同一实例不能被多线程并发修改；需要共享时，由调用方或后续同步容器层选择互斥锁、读写锁或任务归属模型。

tests/containers/test_container_external_sync.c 覆盖 IntMap 在外部 Mutex 下的多线程写入、最终键数和组合生命周期。

生命周期

SetDrop 只能在映射为空时调用，避免已有值的所有权合同在中途改变。

指针值便利接口

当映射以 sizeof(ptr) 初始化时，可使用：

SetPtr 用相同指针替换已有值时为无操作，不会调用释放器。在非 sizeof(ptr) 值映射上调用这些函数会报告 XERR_STATE。

有序查询

这些函数可选返回实际键。没有结果时返回空指针，并将键输出设为零。

完整范例

可编译范例位于 examples/containers/int_map/main.c。范例演示稀疏会话 ID、零初始化值槽和升序迭代。

与旧版 List 的取舍

保留：

• int64 全范围稀疏键。
• AVL 有序查找和升序遍历。
• 固定大小内联值槽。
• 指针值友好路径。
• 旧版百万级插入和千万级查找所覆盖的平衡树与池复用路径。

改进：

• 使用 IntMap 准确表达“整数到值”，不再占用惯例上的 List 名称。
• 外置迭代器支持多个并行迭代状态，不把状态藏在容器内。
• 增加降序遍历、上下界查询、只读查询、释放回调、Take 所有权移交、显式对齐和池页裁剪。
• 去掉容器内部 owner/shared 分支和锁对象，使基础容器的成本、依赖和线程合同更清晰。

旧版的百万插入和千万查找不放入每次单元回归，它们作为性能基准资产保留；日常回归使用更快的稳定地址、OOM、顺序和所有权边界测试。