二进制格式——Ring 族(BlittableRing / VarKeyRing / Overflow / RingMeta)
分册:总览与通用约定 | Log 族 | Ring 族 | 段元组/索引/快照 | TierVolume | 产品格式 | 网络线格式
2.5 Ring 记录帧(BlittableRing record,40B)
Ring = 产品数据真源(Kv/TimeSeries/Blob 共用),记录直接裸写在引擎页内存(无页帧包裹)。
[BlittableRingHeader 40B][key: sizeof(TKey) B][value: 8B..N B][padding 8 对齐]
0 40
[Magic 4][Ver 2][Flags 2][PayloadLength 4][PadLen 2][PreviousAddress 16][Reserved 4][Crc32C 4]
0 4 6 8 12 16 32 36
| 偏移 | 宽度 | 字段 | 含义 |
|---|---|---|---|
| 0 | 4 | MagicValue | 0x44485242 "BRHD" |
| 4 | 2 | Version | 0x0200(v2 泛型改版——KeyLength 字段退役,key 长度 = sizeof(TKey) 类型事实) |
| 6 | 2 | Flags | 含 0x13 = CRC32C(0x03)|PAYLOAD_4B(0x10);状态位 bits8-11:0x0100=VALID /0x0200=TOMBSTONE /0x0400=SEALED /0x0800=INNEWVERSION;0x2000=VALUE_OVERFLOW |
| 8 | 4 | PayloadLength | = KeySize + ValueLength(数据记录)或 blockSize(meta 记录) |
| 12 | 2 | PaddingLength | 8 对齐补零 |
| 16 | 16 | PreviousAddress | 版本链前驱(8B 对齐) |
| 32 | 4 | Reserved | 恒 0(写零防 CRC 脏字节) |
| 36 | 4 | Crc32C | in-Header,覆盖 [0, 40+PayloadLength),Crc 区置零 |
- key 以原始 blittable 字节直写(
Unsafe.WriteUnaligned);value 紧随;溢出记录 value 区 = 24BAddressInfo([0] LogicalAddress 16B+[16] long Size)。 - 空位判定 =
Magic==0(从未写入槽)。 - Ring 7 水位 CAS128(内存态):7 个 16B 槽经
NativeAtomic128原子单调推进——槽序Begin/FlushedUntil/ReadOnly/SafeReadOnly/Head/SafeHead/ClosedUntil;盘上持久化的是 2.7 的子集。
源码:Structures/Ring/BlittableRing.Header.cs:19-48、BlittableRing.Codec.cs、RingBase.Watermarks.cs。
2.5b VarKeyRing 记录帧(变长键环——VRHD)
变长键形态(Products/VarKv 底座,VarKeyRing : RingBase)——header 复用 BlittableRing 40B
v2 结构(Magic 0x44485256 "VRHD"),差异全在记录体:变长 prologue 代替定长 key 槽。
记录体:[KeyHash 8B(XxHash64)][KeyLen 2B LE][KeyBytes][Payload]——prologue 10B 为
设计取舍(变长记录 frame 是布局生成契约的当前边界,非逃逸;四要素登记见架构册)。
判等闭环 = 哈希命中 → KeyHash 比对 → 键字节精确比对(终判)——正确性永不依赖 hash。
键长上限锚 meta(VarKeyRingSettings.KeyLengthCap,缺省 4096;超限构造期 fail-fast)。
专用 codec VarKeyRing.Codec.cs;"VRHD" 与 BlittableRing "BRHD" 魔数互斥——换代语义防误读。
源码:Structures/Ring/VarKeyRing.cs、VarKeyRing.Codec.cs、RecordMagic.cs(VRHD@58)。
2.6 OverflowRecord(18B)
WiscKey value-log 溢出帧(大值分块写)。
[Magic 4][Ver 2][Flags 2][PayloadLength 4][PadLen 2][Crc32C 4][value][padding 4 对齐]
0 4 6 8 12 14
CRC32C 覆盖 [0,14)(Crc 区外)+ value + padding。版本 0x0100。
源码:Structures/Ring/Contracts/OverflowRecordHeader.cs:14-28。
2.7 RingMeta 水位块(12B + 132B + 4B)
Header 与 LogMeta 同构(Magic 0x44484D52 "RMHD"、Version 0x0100、Flags 0x4F——同款 ValidEquals 强校验)。Payload 132B:
| 偏移 | 宽度 | 字段 |
|---|---|---|
| 0 | 16 | BeginAddress |
| 16 | 16 | FlushedUntilAddress |
| 32 | 16 | SafeReadOnlyAddress |
| 48 | 16 | ReadOnlyAddress |
| 64 | 16 | TailAddress |
| 80 | 8 | LastCommittedSeq |
| 88 | 8 | LastPreparedSeq |
| 96 | 16 | OverflowTailAddress |
| 112 | 4 | KeySize(打开时与实例 sizeof(TKey) 校验) |
| 116 | 16 | CommittedTailAddress(2PC Abort 回退点) |
HeadAddress/SafeHeadAddress/ClosedUntilAddress 不落盘(恢复从 BeginAddress 重建)。CRC32C 尾部 footer。
源码:Structures/Ring/Contracts/RingMetaHeader.cs、RingMetaPayload.cs:18-46。