日常使用与常见配方
分册导航: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 条时删除最老快照