Table of Contents

日常使用与常见配方

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

3. 日常使用(IFileSystem 平面)

TierVolume 实现完整 IFileSystem——与内存/本地/网络文件系统同构,全部 API 见 src/KernLab.Tier.Core/IO/IFileSystem.cs 与 IFileHandle.cs。要点:

3.1 命名空间

fs.CreateDirectory("docs");                     // mkdir -p(幂等 + 耐久)
fs.DeleteDirectory("docs");                     // 仅限空(非空抛 DirectoryNotEmpty)
fs.MoveDirectory("a", "b");                     // 实例内元数据事务原子(不依赖 OS rename)
fs.CreateFile("docs/f.bin", preallocateSize: 1 << 30, extra: someExtra);  // 显式创建 + 预分配 + FileExtra
fs.Delete("docs/f.bin");                        // 耐久删除(打开句柄在档拒删——SharingViolation)
fs.Move("a/x", "b/x", overwrite: false);        // 内建父目录刷盘(DurableRename)
var info = fs.Stat("docs/f.bin");               // 单条目完整信息
foreach (var e in fs.EnumerateEntries("docs", "*", recursive: true)) { }
  • FileExtra:≤1536B 侧车数据(xattr 同构)——CreateFile(extra:) 建、Stat 读、IFileHandle.SetFileExtra/ReadFileExtra/WriteFileExtra 增改。

3.2 数据面(IFileHandle)

using var h = fs.Open("docs/f.bin", new FileOpenOptions
{
    Access = AccessMode.ReadWrite,
    Mode = FileOpenMode.OpenOrCreate,       // OpenExisting / CreateNew / Truncate / Append
    Sharing = FileSharing.ReadWrite,
    PreallocateSize = 1 << 30,              // open 即幂等预分配(unwritten 区间——读零)
    Hints = FileOpenHints.None,             // 两档模型见 §4
});

h.Write(offset, data);                      // pwrite 语义(越 EOF 零洞扩展)
var got = h.Read(offset, buf);              // pread 语义(EOF 处短读)
var pos = h.Append(chunk);                  // 原子预留追加——多线程同句柄无覆写,返回写入偏移
h.WriteVector(offset, sources);             // writev
h.Flush();                                  // fsync 语义(排干 + 日志提交——持久化屏障)

3.3 空间管理(稀疏与预分配——区间三态)

h.SetLength(100L << 30);                    // 纯逻辑扩展——零物理分配(稀疏)
h.Preallocate();                            // 幂等预分配(重放 open 语义)
h.PunchHole(offset, length);                // 物理回收区间(文件大小不变、区间读零)——字节粒度契约:对齐中段物理回收,非对齐边缘写零(可观测等价,不报对齐错)
h.CollapseRange(offset, length);            // 塌缩(后续数据前移,文件缩短)——全平台
h.InsertRange(offset, length);              // 插入零洞(后续数据后移)——全平台

h.Length;            // 逻辑长度(含洞)
h.AllocatedSize;     // 物理占用(PunchHole 后 < Length)
h.EnumerateAllocatedRangesDetailed();       // 区间 + unwritten 状态(物理占用真相)

容量判据 = 物理块数:100G 逻辑文件在 10G 卷上成立,只要 written 数据装得下。

3.4 其他能力

h.CopyRange(dest, srcOff, dstOff, len);     // 文件系统内高效拷贝
h.CloneRange(dest);                         // 整文件克隆(回退 CopyRange)
h.Lock(off, len, FileLockMode.Exclusive);   // 进程内逻辑范围锁(单实例下即完备)
h.TryLock(off, len, mode);
h.Unlock(off, len);

using var view = h.Map(offset, length, AccessMode.ReadWrite);  // MMF 直映射(文件载体;
                                                              // 单连续区间文件零拷贝;碎片文件自动物化)
h.Advise(FileAdvise.Sequential);            // 纯流式读档(见 §4.3)

3.5 卷几何(精确)

var v = fs.Volume;    // FreeSpace / TotalSpace 精确(superblock + 位图推导,非估算)
fs.VolumeUuid;        // 卷 UUID(诊断)

12. 常见配方

配方 A:追加日志型工作负载(引擎段文件同构)

using var h = fs.Open("wal/seg-001", new FileOpenOptions
{
    Access = AccessMode.ReadWrite, Mode = FileOpenMode.OpenOrCreate,
    Sharing = FileSharing.ReadWrite, PreallocateSize = 512L << 20,   // 预分配消分配税
});
// 追加走 Append(原子预留);落盘节奏按需:FlushData(批)/ Flush(提交点)/ WriteThrough(逐写)

配方 B:大文件扫描分析(只读吞吐优先)

using var h = fs.Open("datasets/big", new FileOpenOptions
{
    Access = AccessMode.Read, Mode = FileOpenMode.OpenExisting,
    Hints = FileOpenHints.NoBuffering,          // 直达档——O_DIRECT 读通道,扫描不冲刷内存
});
h.Advise(FileAdvise.Sequential);                 // 纯流式:无页机制、无预取交互

配方 C:备份到 S3 再恢复

using var store = S3ObjectStore.Create(/* s3 options */);
using var remote = RemoteFileSystem.OpenOrCreate(store);   // 桥构造动词见 network-file-system.md §1
RootSpaceImage.Transfer(volumeFs, remote);       // 结构化管线(TCA1 + Zstd 压缩)
// 灾备:Transfer(remote, TierVolumeFs.New(TierVolumeCarrier.File("/restore.tier"), ...))

配方 D:在线扩容不打断服务

fs.AddCarrier(TierVolumeCarrier.Device("/dev/sdb1"));   // 新块立即可用;成员表事务原子持久

配方 E:每日增量备份链(快照基点 + 增量重放)

var snap = volumeFs.CreateSnapshot($"daily-{DateTime.UtcNow:yyyyMMdd}");
File.Copy("/data/vol.tier", $"/backup/base-{snap.Name}.tier");      // 首日:dd 全量基座
using var delta = File.Create($"/backup/delta-{snap.Name}.bin");
volumeFs.ExportDelta(delta, snap.CaptureLsn);                       // 次日起:基点=上次末端,链路增量
// 副本侧 base + 逐段 ApplyDelta 收敛;保留超 16 条时删除最老快照