TierHash / TierZSet / TierSet——集合结构家族使用指南
KernLab.Tier 的域级集合三件套:TierHash(field → value 哈希表)、TierZSet(score 有序集)、 TierSet(去重集合)。语义与业界 Hash/Set/ZSet 结构逐动词对齐(哈希字段读写 / 有序集范围查询 / 去重集合),底层 = Ring×HashIndex×BTree 组合特化(tc-tier-collections-spec),单实例多命名域共享页池与索引,域是一等公民。
什么时候用
| 需求 | 用什么 |
|---|---|
| field → value 映射(对象属性/配置/计数器) | TierHash |
| 按分数排序的成员集(排行榜/延迟队列/优先级) | TierZSet |
| 去重成员集(标签/黑白名单/已见集合) | TierSet |
| 队列语义(FIFO/消费组) | TierQueue(不是 TierList) |
| 时间序列 | TierTimeSeries |
三件套都是 dense-only 内核:单实例承载任意多个命名域,共享 Ring 页池/索引树/域账文件; 域按需惰性注册,域 0 是两参 API 的默认落点。
快速上手
using KernLab.Tier.Core.IO;
using KernLab.Tier.Products.Collections;
// TierHash
var fs = TierFs.New("local:///data/collections");
await using var hash = await new TierHashBuilder(fs, new HashOptions { HashName = "gw.attrs" })
.WithWorkerScheduler(IsolatedTaskScheduler.Shared)
.StartAsync();
bool isNew = await hash.HSetAsync(0, "user:42:name"u8.ToArray(), "alice"u8.ToArray(), ct);
ReadOnlyMemory<byte>? value = await hash.HGetAsync(0, "user:42:name"u8.ToArray(), ct);
long n = await hash.HIncrByAsync(0, "user:42:hits"u8.ToArray(), 1, ct); // 不存在从 0 起算
// TierZSet——延迟队列消费面
await using var zset = await new TierZSetBuilder(fs, new ZSetOptions { ZSetName = "gw.delay" })
.WithWorkerScheduler(IsolatedTaskScheduler.Shared)
.StartAsync();
await zset.ZAddAsync(0, DateTimeOffset.UtcNow.AddMinutes(5).ToUnixTimeSeconds(), payload, ct);
(byte[] Member, double Score)? due = await zset.ZPopMinAsync(0, ct); // 原子取最小
// TierSet + 集合代数
await using var set = await new TierSetBuilder(fs, new SetOptions { SetName = "gw.tags" })
.WithWorkerScheduler(IsolatedTaskScheduler.Shared)
.StartAsync();
await set.SAddAsync(0, new ReadOnlyMemory<byte>[] { "vip"u8.ToArray() }, ct);
var both = await TierSetAlgebra.IntersectAsync(set, 1, 2); // 跨域交集
await set.SAddAsync(9, both.Select(m => (ReadOnlyMemory<byte>)m).ToArray(), ct); // 结果落域由调用方承接
概念
域(domain)
域 = 一个 uint 实例 id(uint.MaxValue 为备份流终结标记保留值)。写入时惰性注册,首次写即建账。
TruncateDomainAsync(domain) 整域回收;TTL 过期的粒度也是整域(key 级 TTL 语义)。
两参 API 落域 0,与命名域同位平等。
数据真相源与索引
所有写入都是 Ring append-only record(envelope 自述完整域/成员/值字节)+ 索引同步插入。 点查索引是判重/覆盖判定的真相源;TierZSet 另有 score 有序 BTree((域, score 全序编码, member 哈希))。 崩溃后恢复 = 域账载入 → 索引重放(墓碑感知、最新写胜出)→ Ring 重放事实权威化域账(spec §7 三步)。
分数全序编码
ZSet 的 double 分数经 IEEE754 符号位翻转编码后进键,树序 = 数值序。-0.0 归一为 +0.0;
NaN 一律 fail-fast;±Inf 合法(与业界有序集分数语义一致)。
字节占用口径
域账的 BytesOccupied = envelope 逻辑字节(固定头 + field/member + value),非 Ring 物理开销;
DomainMaxBytes 守卫与统计同口径。
写入语义
| 动词 | 语义 |
|---|---|
HSetAsync |
覆盖旧值;返回是否新增(覆盖 = false) |
HIncrByAsync |
不存在字段从 0 起算;值档 = 8B 小端 int64(非 8B 既有值/溢出 fail-fast) |
ZAddAsync |
覆盖 = 更新 score(GT/LT/NX 条件选项 + CH 计数口径);返回新增数 0/1 |
ZIncrByAsync |
不存在成员 = 新增(delta 即初值);结果 NaN fail-fast |
ZPopMin/ZPopMax |
原子取极值并移除(空域返回 null) |
SAddAsync |
幂等——已存在成员 no-op;返回实际新增数 |
HDelAsync/ZRemAsync/SRemAsync |
返回实际删除数(不存在不计) |
写操作全程单闸串行(读无锁);写入返回 = 内存可见,落盘由 FlushAsync 决定。
范围与有序查询(TierZSet)
ZRangeAsync(start, stop):排名区间双闭,负数自尾部数(-1 = 最高分),出界钳制; 同分成员按 member 字节序(字典序)稳定交付。ZRevRangeAsync:降序位序(TryGetMax + TryGetPrev 反向步进)。ZRangeByScoreAsync(min, max):分数双闭区间;ZCountAsync同界计数。- ZRANGEBYSCORE 开区间 GT/LT 边界选项后置(spec 定案⑥)——LIMIT 与 ZRANK/ZREVRANK 已实现(min/max 恒双闭)。
集合代数(TierSet)
IReadOnlyList<byte[]> both = await TierSetAlgebra.IntersectAsync(set, 1, 2, ct);
IReadOnlyList<byte[]> all = await TierSetAlgebra.UnionAsync(set, new uint[] { 1, 2, 3 }, ct);
IReadOnlyList<byte[]> diff = await TierSetAlgebra.DiffAsync(set, 1, 2, ct); // A − B
结果不落域——落目标域由调用方 SAddAsync 承接(SINTERSTORE 系落点选项后置)。
成员按原始字节判等;交付序 = 首入参域的 Ring 地址序。
TTL 与容量
| 选项 | 含义 | 缺省 |
|---|---|---|
DomainTtl |
整域过期(now − lastWrite > TTL → 整域消失) | null = 不淘汰 |
DomainMaxBytes |
单域 envelope 字节上限,超限写侧 fail-fast | null = 不限 |
RetentionScanInterval |
TTL 扫描间隔 + 脏域账持久节拍 | 1 分钟 |
DomainCapacity |
域数护栏(0 = 不限) | 2²⁰ |
per-field/per-member TTL(字段级过期)为非目标。
崩溃恢复与备份
- 恢复全自动:
StartAsync内完成域账载入 + 索引重放 + 对账;已删除不复活、整域回收不回魂、 域账计数以重放事实权威化。 - 冷备份(自描述流,CRC32C 全程校验):
var fs = File.Create("attrs.thb1");
await TierHashBackup.ExportAsync(hash, fs, ct);
fs.Position = 0;
var result = await TierHashBackup.ImportAsync(target, fs, ct); // 幂等重放
TierHash = THB1、TierZSet = TZB1、TierSet = TSE2。导入 = 逐批重放(幂等),
last-write = 导入时刻;尾部损坏已导入前缀不回滚(流式非原子契约)。
文件布局
| 实例名 | 文件 |
|---|---|
{name}(Hash) |
{name}.hash.ring / {name}.hash.index / {name}.hash.water |
{name}(ZSet) |
{name}.zset.ring / {name}.zset.index / {name}.zset.ordidx / {name}.zset.water |
{name}(Set) |
{name}.set.ring / {name}.set.index / {name}.set.water |
订阅(Watch——域级变更流)
三件各自提供 Watch(domain, from, ct) 域级变更流(订阅契约 1.6 泵形态——历史补扫 + 实时直通缝合):
await using var enumerator = hash.Watch(domain: 0).GetAsyncEnumerator();
while (await enumerator.MoveNextAsync())
{
var ev = enumerator.Current; // (Domain, Identity 字节, Kind, Address[, Score])
// Kind = Put(HSet/HIncrBy/HSetNx;ZSet 另携 Score)或 Delete(HDEL/SREM/ZREM/ZPop)
}
- 游标:
ev.Address即续传游标(Ring 地址序);断连/重开凭已见最大地址Watch(domain, from)续传 (开区间(from, ...]——无重无漏)。 - 值不进事件:事件 = 变更通知非数据面——值经点查(
HGetAsync/ZScoreAsync)自理。 - 断连:慢订阅者事件通道写满即断连(
CollectionWatchDisconnectedException,WatchChannelCapacity可调)——写路径不被反压;流干净结束 = 实例已关闭(不得重订);订阅级取消 =OperationCanceledException。 - 设计边界:域回收(
TruncateDomainAsync/TTL 过期)= 物理治理非数据变更,不发事件 (与 TierKv 回收强删同界);历史段 Delete 事件身份为空字节(Ring 墓碑零载荷——实时段身份完整), 断连窗口横跨删除的消费方凭域级对账自理。
Redis 命令对照(parity 面速查)
逐命令对照(✅ 实现 / ⊘ 排除含四要素理由——排除项的重开条件随排除行标注):
| Tier 面 | Redis 同位命令 | 排除(四要素见审计表) |
|---|---|---|
| TierHash | HSET/HGET/HDEL/HINCRBY/HEXISTS/HLEN/HGETALL/HMGET/HSETNX/HEXISTS/域 TTL/HSCAN | HINCRBYFLOAT(值档分叉)、HKEYS/HVALS/HSTRLEN/HRANDFIELD(HGETALL 组合/随机语义) |
| TierSet | SADD/SREM/SISMEMBER/SMISMEMBER/SCARD/SMEMBERS/SSCAN/域 TTL | SINTER/SUNION/SDIFF+STORE/SMOVE(跨键=hub 事务/扇出面)、SPOP/SRANDMEMBER(随机语义) |
| TierZSet | ZADD(GT/LT/NX/CH)/ZINCRBY/ZREM/ZSCORE/ZMSCORE/ZCOUNT/ZCARD/ZRANGE/ZREVRANGE/ZRANGEBYSCORE(LIMIT)/ZREMRANGEBYSCORE/ZREMRANGEBYRANK/ZRANK/ZREVRANK/ZPOPMIN/ZPOPMAX/ZSCAN/域 TTL | ZREVRANGEBYSCORE(按 score 降序区间——随需求排期)、ZRANGEBYLEX 族(D9 双排序维)、ZRANDMEMBER(D8) |
副本档(TierXxxReplica)读面透传同表;写面经组提案全组一致。三族 SCAN 游标与全部遍历面的 统一保证口径见 扫描与游标契约。
反模式
- 把 HIncrBy 用于任意 HSet 值——HIncrBy 只支持 8B 小端 int64 值档,字符串值 fail-fast。
- 用 ZRange 当分页器高并发翻深页——排名区间是 O(k) 迭代;按分数窗口(ZRangeByScore)取数更廉。
- 拿
DomainMaxBytes当精确配额——它是 envelope 逻辑字节口径的写侧守卫,非 Ring 物理占用。 - 导入冷档后开着 TTL 跑——导入记录 last-write = 导入时刻,冷档实例应配
DomainTtl = null。 - 跨实例直接做集合代数——算子是单实例跨域糖;跨实例请各自导出后在外部落 SAdd。
- 拿
uint.MaxValue当业务域 id——备份流终结标记保留值,导出面拒绝。
想深入
- 存储引擎与 Ring:
src/KernLab.Tier.Runtime/docs/(storage-engine、ring 使用指南) - 一致性模型与 Session 2PC:
src/KernLab.Tier.Products/docs/product-consistency.md