Table of Contents

虚拟文件系统使用指南(TierVolumeFs · virtual://——KernLab.Tier.Core.IO.TierVolume)

状态:正式文档(自包含——不依赖设计/开发过程文档) 读者:消费 KernLab.Tier.Core IO 层的应用/引擎开发者 同级:io.md(IO 总指南)· perf/io-performance.md(性能)


0. 一句话

虚拟文件系统(第四类文件系统 · TierVolume 格式实现):一个自描述的单工件(.tier 文件或 Linux/Windows 块设备),既是活卷又是存档。 你得到一个 TierVolumeFs 对象,它实现完整的 IFileSystem——命名空间、数据面、FileExtra、崩溃一致性全部内建,跨平台(Linux/macOS/Windows 的文件载体 + Linux 与 Windows 设备载体),零 BCL File/Directory 依赖。

using var fs = TierVolumeFs.New(TierVolumeCarrier.File("/data/vol.tier"),
    new TierVolumeFormatOptions { QuotaBytes = 10L << 30 });           // New 即格式化;QuotaBytes 缺省 -1 = 按需自动扩容

fs.CreateDirectory("docs");                                            // 父目录须先建——OpenOrCreate 只建文件不建目录
using var h = fs.Open("docs/hello.txt", new FileOpenOptions
{
    Access = AccessMode.ReadWrite,
    Mode = FileOpenMode.OpenOrCreate,
    Sharing = FileSharing.ReadWrite,
});
h.Write(0, "hello, virtual medium"u8);
h.Flush();

1. 核心模型(30 秒版)

概念 事实
载体 .tier 文件 或 Linux 块设备/裸分区——一份逻辑布局,两种物理形态
自持一致性 崩溃一致性不委托 OS——superblock 双份轮写 + 循环日志(WAL)+ 可达性对账,断电后 Open 即恢复
一卷一实例 进程内登记(卷 UUID)+ 跨进程锁(文件载体伴生 .lock / 设备 flock)——第二个实例打开同卷立即 SharingViolation
统一块空间 条目/区间/FileExtra/数据同源分配——没有"文件数上限"这种台阶,满了只因空间
区间三态 洞(读零)/ unwritten(预分配,读零)/ written——Length 与 AllocatedSize 是两个事实
自管页缓存 顶替 OS page cache 的位置:命中 = memcpy;另有直达档(NoBuffering)绕过
实例即文件系统 导出/导入/迁移全部经 IFileSystem 接口平面(管线 + dd 快道),无侧门

4. 两档 IO 模型与调优

4.1 缓冲档(默认)与直达档

档 打开方式 路径 适用
缓冲 Hints = None 自管页缓存:命中 ~100ns memcpy / miss 载体读 + 自动预读 随机读、重读、小写(写回 + 后台 flusher)
直达 Hints = NoBuffering 绕过自管缓存:载体直读/直写(文件载体走 O_DIRECT 读通道;对齐规范内建) 大顺序扫描、备份、透写

两档语义同构(与本地文件系统的两档对称)——直达档对齐由实现吸收(弹跳窗/合并读),未对齐缓冲也可用;一致性规范内建(直达写失效对应缓存页 / 直达读前排干重叠脏页)。

4.2 自管页缓存参数

  • 预算:TierVolumeOpenOptions.PageCacheBytes(默认 64 MiB);
  • 预算内行为:插入序 FIFO 逐出(命中不挪位——按首次装入序逐出;非访问序 LRU,随机热点负载的命中 策略取舍见下)、写回脏页(flusher 阈值 max(1MB, 预算/8) 唤醒)、整块 run 写绕(write-around,不污染缓存);
  • 0 预算 = 纯直达形态:扫描型负载不想吃内存时用。

4.3 Advise 与预读

  • Advise(FileAdvise.Sequential):纯流式读档——一次排干该文件自管脏页后全程载体直读(无页机制开销、无预取交互;OS 缓存自然服务重复扫描);
  • 不带 Advise 的顺序读:自动预读器(连续读启发式,内核 readahead 同构——专用线程 + 有界队列背压);
  • Advise(WillNeed/DontNeed/Random):语义提示(no-op 安全)。

4.4 WriteThrough / FlushData

// 打开时 Hints = FileOpenHints.WriteThrough:逐写日志提交——O_SYNC 语义,崩溃窗口归零(最重档)
h.Flush();       // 全量:排干 + 日志提交(fsync 形态)
h.FlushData();   // 数据面:排干 + 载体屏障(fdatasync 形态——不含日志记录;FlushDataOnly 能力位)
fs.FlushRoot();  // 目录级收口(净卷 = 纯屏障,纳秒级)

崩溃窗口谱系(默认档):后台 flusher 50ms 轮询 / 75% 日志占用触发检查点 → FlushData → Flush(单屏障日志提交)→ WriteThrough(零窗口)。


9. 能力位(Capabilities)

TierVolume 置位(对照 Disk 全对齐 + 6 增强):

Sparse(内部恒真)· RandomWrite · EmptyDirectories · DurableRename · AtomicDirectoryMove(增强:实例内元数据事务,不依赖 OS)· ExclusiveLock(增强:内建)· RangeLock(增强:进程内逻辑锁)· RangeShift(增强:全平台)· ContiguousCapture · MaintenanceGate · CopyRange · VectorIO · DirectIO · Advise · WriteThrough · FlushDataOnly · Mmap(文件载体;设备诚实不置位)。卷几何精确(superblock+位图推导)经 fs.Volume 读面提供——是读面非能力位。

消费方按能力位决策,不要按文件系统硬编码——这是四类文件系统平权的机械保证。


10. 错误码速查

IOError 场景 处置
SharingViolation 第二实例开同卷 / 删除打开中的文件 / 载体被外部持有 检查另一实例;先关句柄
AlreadyExists New 到已格式化载体 / CreateFile 已存在 显式语义,幂等由调用方组合
ReadOnlyVolume 只读/降级卷上的写意图 与权限问题分离——修复 = 全量成员重开
UnderMaintenance 维护租约生效中被 scope 拒的操作 等租约解除
DiskFull 物理块耗尽(含 Transfer 预检) 因空间不因条目——扩容(加载体)或删除
AlignmentError CollapseRange/InsertRange 未按 AllocationUnit 对齐(PunchHole 为字节粒度契约——非对齐边缘写零,不报对齐错) 对齐到 Volume.AllocationUnit
Unsupported 版本高于支持上限 / 未置位能力位 前向双门——绝不静默
NotFound 多载体成员缺失且未 AllowDegraded 全量清单或降级打开

11. 规范与禁区

  1. 一卷一实例,无侧门:一切载体字节访问(含备份导出)必须经实例——直接 dd 一个活卷属于违规(锁是 advisory 拦不住外部写者;设备载体 O_DIRECT 下有一致性风险);
  2. 句柄必须 Dispose:IFileHandle 持有共享登记;泄漏句柄会挡住 Delete/维护收敛;
  3. 不要绕过 TierVolumeFs 类型表面:盘上格式细节全部内嵌私有——partial 拆分是内部组织,不是扩展点;
  4. 写放大自知:碎片文件 Map 会物化(全文件重写);CollapseRange/InsertRange 是 memmove 语义;
  5. 容量声明与扩容两态自知:QuotaBytes=-1 的文件载体走自动扩容(§2.2——倍增位图重定位直到物理满); 显式配额 / 多载体 / 设备载体下容量定死,跨上限一律 AddCarrier(纯加法)。

想深入


分册导航:virtual-file-system.md | virtual-carrier.md | virtual-usage.md | virtual-operations.md | 载体与格式化 | 日常使用与常见配方 | 多载体/管线/快照