Table of Contents

二进制格式——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 区 = 24B AddressInfo([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。