虚拟文件系统使用指南(TierVolumeFs · virtual://——KernLab.Tier.Core.IO.TierVolume)
状态:正式文档(自包含——不依赖设计/开发过程文档) 读者:消费
KernLab.Tier.CoreIO 层的应用/引擎开发者 同级: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. 规范与禁区
- 一卷一实例,无侧门:一切载体字节访问(含备份导出)必须经实例——直接
dd一个活卷属于违规(锁是 advisory 拦不住外部写者;设备载体 O_DIRECT 下有一致性风险); - 句柄必须 Dispose:
IFileHandle持有共享登记;泄漏句柄会挡住 Delete/维护收敛; - 不要绕过
TierVolumeFs类型表面:盘上格式细节全部内嵌私有——partial 拆分是内部组织,不是扩展点; - 写放大自知:碎片文件
Map会物化(全文件重写);CollapseRange/InsertRange是 memmove 语义; - 容量声明与扩容两态自知:
QuotaBytes=-1的文件载体走自动扩容(§2.2——倍增位图重定位直到物理满); 显式配额 / 多载体 / 设备载体下容量定死,跨上限一律AddCarrier(纯加法)。
想深入
- 盘上字节格式(superblock/位图/journal/delta 的精确布局——互操作解析): binary-format-spec.md §2.11
- 跨层持久化稳定性(崩溃窗口谱系与分工):persistence-architecture.md
分册导航:virtual-file-system.md | virtual-carrier.md | virtual-usage.md | virtual-operations.md | 载体与格式化 | 日常使用与常见配方 | 多载体/管线/快照