slot_map

裁剪与依赖

启用 XRT_FEATURE_SLOT_MAP 时必须同时启用 XRT_FEATURE_ARRAY。只需要连续指针 序列时，应裁掉本模块并使用 ptr_array。

适用边界

适合：

• 连接、session、worker 和任务对象的稳定句柄；
• 对象移除后复用槽位，但不能让旧句柄误命中新对象；
• 需要 O(1) 插入、查询、替换和删除的本地对象表。

不适合：

• 需要按连续索引排序、批量插入或压缩删除的序列，使用 ptr_array；
• 需要自动管理对象生命周期的所有权容器；
• 多执行流无锁并发访问。共享时由调用方提供外部同步。

稳定契约

• xslot 的零值永远无效；句柄包含 32 位零基索引和 32 位非零代际。
• 插入和替换拒绝 NULL，因此 Get 返回 NULL 可以无歧义地表示句柄无效。
• 删除槽时推进代际。复用同一索引会得到不同句柄，旧句柄永久失效。
• 单个槽的代际耗尽后会永久退役，不回绕到旧代际，因此不会产生 ABA 命中。
• 空闲槽由链表以 O(1) 复用；普通删除优先复用最近释放的槽。
• Clear 使全部活动句柄失效、保留容量，并从最低索引开始重建空闲链。
• 槽表没有 Trim。释放尾部槽后再次创建同索引会丢失代际历史，破坏旧句柄

永久失效的保证；需要回收全部存储时使用 Unit 或 Destroy。

• 槽表只借用指针，不释放对象。Remove 可取回原指针，便于调用方完成析构。
• 分配失败时，已有句柄、值、数量、槽跨度、容量和结构版本保持不变。
• Reserve 和 Set 不改变结构版本；Insert、Remove 和非空 Clear 会使

已开始的迭代器失效。

迭代

迭代按零基槽索引递增，跳过空闲和退役槽。IterNext 返回非空对象指针， pSlot 可选；遍历结束返回 NULL 且不设置新错误。

开始迭代后执行 Insert、Remove 或非空 Clear，下一次 IterNext 返回 NULL 并设置 XERR_STATE。Set 和 Reserve 不改变槽结构，允许继续迭代。

示例

同一索引稍后被复用时，新句柄的代际不同，旧 Handle 仍会被拒绝。