Table of Contents

载体与格式化

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

2. 载体与格式化

2.1 两种载体

TierVolumeCarrier.File("/data/vol.tier")        // 文件载体:容量声明内按需增长,稀疏友好
TierVolumeCarrier.Device("/dev/nvme0n1p3")     // 设备载体:固定几何(Linux;O_DIRECT 强制)
TierVolumeCarrier.Device("/dev/C:")            // 设备载体(Windows 卷 → \.\C:;CreateFile share=0 + FSCTL_LOCK_VOLUME)
TierVolumeCarrier.Device("/dev/PhysicalDrive1")// 设备载体(Windows 物理盘 → \.\PhysicalDrive1;独占句柄排他)
  • 文件载体创建伴生锁文件 <path>.lock(跨进程互斥);
  • 设备载体(Linux)用 flock 互斥;容量/扇区经 BLKGETSIZE64/BLKSSZGET ioctl 探测;
  • 设备载体(Windows,2026-08-26 补齐):virtual:///dev/C:(卷)/ virtual:///dev/PhysicalDriveN(物理盘)—— CreateFile share=0 独占 + 卷锁定(FSCTL_LOCK_VOLUME,物理盘无卷锁语义);NO_BUFFERING 直 IO + WRITE_THROUGH 写穿档(IS-03 同机制);扇区经 GetDiskFreeSpace 探测(物理盘失败默认 512)。 须管理员权限;卷被挂载占用时先手动卸载(不自动卸卷——危险)。快照挂载(只读)共享读开口不锁卷。

2.2 格式化

public static TierVolumeFs New(TierVolumeCarrier carrier, TierVolumeFormatOptions? options = null, ILogger? logger = null)   // Format 已终态改名 New(零过渡)
选项 默认 说明
QuotaBytes -1 空间根硬上限(一词制):正数 = 供给(位图按此预留——物理级执法);-1 = 按需自动扩容(文件载体:初始 64MiB、分配接近界即倍增位图重定位,直到磁盘物理满;设备载体 = 设备大小)
Label null 卷标签(≤32B UTF-8——New 写入 superblock;Open 断言不符即抛)
BlockSize 4096 内部块大小;2 的幂,[512, 1MiB]
JournalReserveBytes 8 MiB 日志物理预留(0 = 不预留——此后该卷永不开日志)
Preallocation Metadata 载体预分配方式轴(IS-02/IS-04 统一词汇):Metadata = 现行稀疏(SetLength 只改元数据,簇随写分配);Full = 载体物理占位(不标记稀疏 + 创建时物化全部空间——一次性成本部署方承担,换运行时零分配抖动;无特权 Windows / Linux 无 fallocate 时转零写物化,全失败 fail-fast)
CarrierWriteThrough false 载体句柄写穿档(IS-03):载体以 FILE_FLAG_WRITE_THROUGH/O_SYNC 打开——每写完成即达稳定存储;journal 提交免独立 fsync(写穿完成即单屏障),Flush 对已写穿数据短路。与句柄级 FileOpenHints.WriteThrough(逐写 journal 提交)正交
  • 显式语义:对已格式化载体 New 抛 IOError.AlreadyExists(防毁卷脚枪;格式化前还会探测别卷成员头);

自动扩容(QuotaBytes = -1 的文件载体):初始 64MiB 小界;分配触及界(空间耗尽/碎片化两触发点)时 位图重定位 + superblock 原子翻转倍增(64M→128M→…,Open 配额收紧则目标 = min(倍增, 配额界)),直到磁盘 物理满(ENOSPC → DiskFull 语义)。崩溃两侧自洽:翻转前崩溃 = 旧界旧位图完好;翻转后 = 新位图已先落盘。 日志语义不切割(翻转保留日志字段原值;追加式扩容下既有记录块号稳定)。多载体卷(AddCarrier 后)退出自动 扩容——容量管理转显式。

  • 格式化完成即 clean、日志就绪(JournalReserveBytes > 0 时)。

2.3 打开

public static TierVolumeFs Open(TierVolumeCarrier carrier, TierVolumeOpenOptions? options = null, ILogger? logger = null)
public static TierVolumeFs Open(TierVolumeCarrier?[] carriers, TierVolumeOpenOptions? options = null, ILogger? logger = null)
选项 默认 说明
Access(基类三态) ReadWrite Read = 只读打开(写意图抛 IOError.ReadOnlyVolume);ReadWrite = 缺省;Write = 纯摄入——虚拟卷无此概念,Open 即拒
PageCacheBytes 64 MiB 自管页缓存预算;0 = 禁用读缓存(纯直达形态——大扫描不占内存)
AllowDegraded false 多载体卷允许成员缺失(null 占位)——只读降级形态
SnapshotName null 非空 = 以该快照只读挂载卷(必须与 Access = Read 组合)——见 §7.2
Preallocation Metadata 载体预分配方式轴——须与格式化档一致:Full 档跳过载体稀疏标记(避免把 full 载体静默降回稀疏语义)
CarrierWriteThrough false 载体句柄写穿档——须与格式化档一致

打开路径自动完成:唯一性检查 → superblock 采纳(CRC/版本)→ 日志重放(dirty 卷)→ 可达性对账 → 恢复可写。断电后直接 Open 即可,无需修复工具。

  • 版本高于支持上限 → IOError.Unsupported(绝不静默猜测);
  • 多载体:成员清单须全量按序(成员 0 = 主载体);UUID/索引不匹配拒开;缺失成员未 AllowDegraded 拒开。

2.4 关闭(重要)

fs.Dispose();   // clean 关闭:提交 + 置 clean 位 + 轮写 + 释放锁
  • 正常关闭 = 走 clean 协议(下次打开跳过恢复遍历,快路径);
  • 进程直接退出/崩溃 = dirty 残留——不丢已提交数据,下次打开走日志重放 + 孤儿回收后恢复可写;
  • 崩溃语义(fsync 语义窗口):Flush() 前的写允许丢失,Flush() 后的完整存活。

8. 维护门闩(静默快照前置)

using (fs.EnterMaintenance("backup", MaintenanceScope.WriteOperations, ct))
{
    // 此期间:写操作抛 IOError.UnderMaintenance,读放行
    // 在途写已收敛(进入时阻塞等待归零)
}
  • 责任划分:fs 层门闩挡得住句柄操作,挡不住你自己的后台任务——调用方先自行收敛业务侧写入,再 Enter;
  • AllOperations 档读写全拒(还原目标卷用);
  • 管线 QuietSource = true 时自动包夹(见 §6)。