Table of Contents

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(值内联记录)

反模式

  1. 键当字符串直接拼用户输入不设上限——键长上限 4096 是配置契约;超长语义用值承载。
  2. 把记录地址当持久句柄跨 compaction 持有——地址是 revision 锚(CAS/监控用), 长期引用用键。
  3. CAS 高竞争当锁用——casGate 串行化;高竞争计数走 INCR 族。
  4. watch 消费方 break 后不 Dispose 迭代器——订阅生命周期由迭代器 Dispose 收口 (结构性安全,弃流即弃订阅)。
  5. 冷实例首写按热路径计时——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(两产品共享域语义)