Table of Contents

存储地址与引擎契约(Storage/)

LogicalAddress(16B 逻辑地址)

readonly struct:[SegId 4B][Extension 4B(ABA 防护)][Offset 8B]——地址即身份: 判等/哈希/排序只比较地址本身,不回源数据。

  • 双哨兵语义(最高频误用点):
    • Empty = (0,0,0)——seg0 的起点,是合法地址,不是"没有值";
    • Invalid = (-1,-1,-1)——**"无值/未初始化/越界"**哨兵;
    • 判空一律 IsValid(SegId >= 0 && Offset >= 0)——addr != Empty 是错误写法 (把合法起点当成了无值)。新 API 的无值表示必须用 Invalid 并先核对既有哨兵约定。
  • 段表算术教义:地址推进/回退/跨段一律走 AdvanceAddress/RetreatAddress/GetDistance 段表算术——禁手工拆字段 ±(Hollow 占位连续;三禁:只推不减=死循环、break=跨 Hollow 提前停、替换须核对循环分支语义)。
  • 边界规范形:exact-fill 停驻 (segId, GrowthLimit)——(seg+1, 0) 哨兵形态已废除; 区间写法半开 [start, end)。
  • 排序 = 段主序(SegId 优先,Offset 次之)——与 SortedDictionary 键元组序同构; C# ValueTuple 无 </>=(CS0019),用领域比较运算符直比。

IStorageEngine(引擎契约)

继承 IStorageInfo(纯信息视图:定位/配置/路径解析)+ ILifecycle<EngineRecoveryHints> (观测:IsReady/RecoveryState/WaitForReady*)——子系统只依赖 IStorageInfo,不与 IO 耦合。

  • 启动不在接口面:Initialize 已消除——启动统一经 StorageEngineBuilder.Start/StartAsync 一步到位;恢复 hints 经 Start(hints) 传入,段生长上限/分段开关是构造期配置。
  • IO 面:AppendAsync(顺序追加,返回起始逻辑地址)/ WriteAsync(原地覆写)/ ReadAsync / Flush(同步三重载:全量/至 upTo/Range)/ Truncate / 回收压缩族(StartReclaim / StartCompact / StartRangeCompact)。
  • 动态水位:AllocatedTail(分配尾,含攒批窗口)与提交尾分离——分配尾 ≠ 可见尾。

恢复与枚举

  • EngineRecoveryHints(committedTailHint, allocatedTailHint)——只携带双尾修正 (可空 = 不修正);生命周期参数(段生长上限/分段开关)构造期传入,不经此类型。 构造 = 配置,启动 = 双尾。
  • RecoveryState/RecoveryPhase/RecoveryProgress 见生命周期契约。
  • ReadDirection(Forward/Backward 顺序读向)、ISequentialReader(顺序读游标—— 推进不减 remaining 的"防御推进"禁令见 log.md)、SnapshotMode(流式/段式快照形态)、 CompactResult/CompactStatus(回收终态:Committed+sparse / Committed / Wasted / Aborted ——ReclaimRollback→MarkAbort 语义勿改回)。
  • MagicLocation:Magic 粗定位(恢复扫盘 MagicLocator 的契约形态)。

反模式

  1. 用 Empty 表示"无值"——把 seg0 合法起点当哨兵;无值用 Invalid + IsValid 判定。
  2. 手工拆 SegId/Offset 做地址算术——跨段/Hollow 场景必错;统一走段表算术 API。
  3. 子系统依赖 IStorageEngine 拿信息——只该依赖 IStorageInfo(避免与 IO 耦合)。
  4. EngineRecoveryHints 塞生命周期配置——构造期参数混进启动修正,配置/启动两轴混淆。

源码:Storage/(LogicalAddress / IStorageEngine / IStorageInfo / EngineRecoveryHints / ReadDirection / ISequentialReader / SnapshotMode / CompactResult / CompactStatus / MagicLocation)。