TierVarKv 使用指南(变长键 KV)
★ 值面 = 原始字节(
byte[]直存直取,无类型化 overlay——「Var」指键形态变长, 与值类型化无关;类型化值面走泛型 TierKv + [KvStore] 生成器)。 记录面 =VarKeyRing([KeyHash 8B][KeyLen 2B][KeyBytes][Payload] 盘上几何,ring-varkey 设计稿)。 产品命名空间 =KernLab.Tier.Products.VarKv(与Products.Kv产品级平级)。
定位(是什么 / 不是什么)
是什么:变长键 KV 产品——byte[] 键(≤4096 字节,D2 拍板 etcd 同位)、字节序全序语义、
LWW 覆写 + 值版/地址版 CAS + 每键 TTL(惰性读删 + sweep 三件套)+ INCR 族 + 原子批 +
前缀扫描 + watch 订阅流 + 备份件(TVB1,TTL 维度保真)。与泛型 TierKv
(定长键)并列一等公民(无主次、无迁移方向——消费方按键型选择)。
不是什么:不做类型化值面(自转字节);范围扫描(ScanByRange)挂账 ring-varkey D5 排序族独立设计稿(前缀扫描已覆盖有序面主需求);会话域(VarKvSession)与 checkpoint 归 wave-2(VarKv 写语义 = 写即持久,无 commit policy 轴)。
快速开始
using KernLab.Tier.Core;
using KernLab.Tier.Products.VarKv;
await using var kv = await new TierVarKvBuilder(
TierFs.New("memory:"), // 介质即配置:memory:/local:///路径/virtual://
TierVarKvOptions.Default.WithKvName("sessions")).StartAsync();
var addr = await kv.PutAsync("user:42:session"u8.ToArray(), Encoding.UTF8.GetBytes("active"));
var value = await kv.TryGetAsync("user:42:session"u8.ToArray()); // null = 未命中/过期
// TTL(过期惰性读删 + sweep 三件套:内置循环 + Options 间隔可关 + ForceExpirySweepAsync 手动口)
await kv.PutAsync(key, value, TimeSpan.FromMinutes(30));
var ttl = await kv.TryGetTimeToLiveAsync(key);
await kv.PersistAsync(key); // 移除过期点(值不变)
// CAS 双形态(值版 NX 语义 / 地址版 LogicalAddress 锚——Put 返回地址即期望锚闭环)
var swapped = await kv.CompareAndSwapAsync(key, expectedValue: null, newValue);
var cas = await kv.CompareAndSwapByAddressAsync(key, addr, newValue);
// INCR 族(单闸 RMW:0 起算/非 8B 值 fail-fast/RMW 不动既有 TTL)
var n = await kv.IncrByAsync(counterKey, 1);
// 原子批(casGate 域全或无:整批落盘 + 整批可见)
var addresses = await kv.CommitBatchAsync(
new[] { new VarKvBatchOperation(k1, v1, IsDelete: false) });
// 前缀扫描(键字节序产出——存活条目流)
await foreach (var (key, value) in kv.ScanByPrefixAsync("user:42:"u8.ToArray()))
Console.WriteLine($"{Encoding.UTF8.GetString(key)} = {value.Length}B");
// watch 订阅(前缀过滤 + 历史补扫 + 实时通道——hub 水位去重;泵形态统一归 PW5)
await foreach (var ev in kv.Watch("user:42:"u8.ToArray()))
Console.WriteLine($"{ev.Kind} @{ev.Address}");
装配(TierKv 同构三段式)
| 部件 | 职责 |
|---|---|
TierVarKvBuilder |
显式装配路(缺省工厂 + With* 覆盖)——StartAsync() 一步到位 |
TierVarKvAssembly |
Options→Settings 翻译面(ring/点索引 Settings + 缺省工厂) |
TierVarKvOptions |
配置轴(ring 几何/点索引容量/sweep 间隔/watch 容量/调度器/时钟缝) |
生命周期 = LifecycleBase 正典(Initialize → 恢复 → WaitForReadyAsync):
ring 先行,恢复核心启动点索引窗口重放 + 有序索引全量重放重建(派生重放教义——
索引是可重建派生结构,任何索引重建不丢数据);过期 sweep 循环为内建 worker
(恢复完成后启动,Dispose 统一收口)。
核心语义
| 语义 | 契约 |
|---|---|
| 写(Put 覆写) | append-only 追加 + 双索引换绑——同键重复写 = 最新胜出,返回记录地址(revision 锚);写即持久(FlushUntilTail) |
| 键长 | ≤4096 字节(超限 ArgumentOutOfRangeException——配置期早暴露) |
| 删除 | 墓碑(重放安全);不存在键也落墓碑记录并发布 Delete 事件,返回 false(返回值幂等——存储/watch 面有副作用) |
| TTL | 过期惰性读删(读命中判帧内过期戳)+ sweep 到期墓碑化(Delete 同构事件——过期即变更) |
| CAS | 值版:期望值匹配才写;expectedValue = null 抢「不存在」位(NX);地址版:Invalid = 期望不存在;casGate 内串行化(CAS×CAS 恰一成功) |
| INCR | 既有值非 8B int64 / checked 溢出 fail-fast;RMW 沿用原过期点 |
| 原子批 | casGate 域全或无——批内整批追加 + 单次落盘 + 整批可见 |
| 前缀扫描 | 键字节序、存活过滤;空前缀 = 全量 |
| watch | 订阅点前写必达(历史补扫)+ 实时不重(hub 水位去重);独立泵生命周期归 PW5 统一 |
| 判等闭环 | 索引 tag/哈希命中 → 记录 KeyHash → 键字节精确比对(终判)——正确性永不依赖 hash 单独判定 |
| 大值 | 启用 RingOverflowPolicy = Enabled 后超阈值自动 WiscKey 分离(值落溢出引擎,记录存指针)——调用方无感;缺省 Disabled(值内联记录) |
反模式
- 键当字符串直接拼用户输入不设上限——键长上限 4096 是配置契约;超长语义用值承载。
- 把记录地址当持久句柄跨 compaction 持有——地址是 revision 锚(CAS/监控用), 长期引用用键。
- CAS 高竞争当锁用——casGate 串行化;高竞争计数走 INCR 族。
- watch 消费方 break 后不 Dispose 迭代器——订阅生命周期由迭代器 Dispose 收口 (结构性安全,弃流即弃订阅)。
- 冷实例首写按热路径计时——mem 介质首写含首段创建 ~几十 ms(一次性固有成本); 短 TTL 写入在装配后先预热再挂表。
集群模式
实例交 VarKvStateMachine(Products.Net)装配——每副本一本地实例、apply 唯一写者;
副本门面 TierVarKvReplica 已交付(AddRaftBytesKvAsync 返回类型;协议域号 0x61 族,
命名/登记随 PW3 集中成文)。装配入口:
hub.AddRaftBytesKvAsync(...)。
备份
TierVarKvBackup.ExportAsync/ImportAsync(TVB1 统一流格式——契约 1.7):
流头 magic + 记录([KeyLength][Key][ExpiryTicks][ValueLength][Value])+ 终结标记 +
Footer(记录数/CRC32C)。TTL 维度保真——过期点原样落流,导入按原过期点恢复
(备份不把 TTL 抹平成永生;已过期条目不导出不复活)。
性能
- 双形态同负载基线(变长 vs 定长对照——dual-form-kv-baseline): 变长形态写/点查/前缀扫描全套落档,VarKeyRing 记录面即首个变长基线。
- 消费选型:键可映射定长(int/long/Guid)→ 泛型 TierKv(零键 prologue 开销);真变长 (用户输入/复合路径)→ TierVarKv。
深入
- 通用 KV 语义(会话/事务/检查点):tierkv.md(两产品共享域语义)