Table of Contents

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 游标与全部遍历面的 统一保证口径见 扫描与游标契约。

反模式

  1. 把 HIncrBy 用于任意 HSet 值——HIncrBy 只支持 8B 小端 int64 值档,字符串值 fail-fast。
  2. 用 ZRange 当分页器高并发翻深页——排名区间是 O(k) 迭代;按分数窗口(ZRangeByScore)取数更廉。
  3. 拿 DomainMaxBytes 当精确配额——它是 envelope 逻辑字节口径的写侧守卫,非 Ring 物理占用。
  4. 导入冷档后开着 TTL 跑——导入记录 last-write = 导入时刻,冷档实例应配 DomainTtl = null。
  5. 跨实例直接做集合代数——算子是单实例跨域糖;跨实例请各自导出后在外部落 SAdd。
  6. 拿 uint.MaxValue 当业务域 id——备份流终结标记保留值,导出面拒绝。

想深入

  • 存储引擎与 Ring:src/KernLab.Tier.Runtime/docs/(storage-engine、ring 使用指南)
  • 一致性模型与 Session 2PC:src/KernLab.Tier.Products/docs/product-consistency.md