pi_block_device
pi_block_device 是面向 B+ 树、Hash 表等上层写时复制数据结构的异步块存储 crate。它提供公共 trait/API,并实现基于文件系统和追加日志的 FileBlockStore。项目仍处于 0.1 阶段,不承诺公共 API 的兼容稳定性。
项目状态
当前版本为 0.1.0,MSRV 为 Rust 1.85,使用 Rust 2024 edition。已实现初始化与恢复、单写者事务、普通块与大块分配/写入、根和名称绑定、持久提交、固定快照、块读取、段枚举、批量逻辑释放、durable 后物理文件退休,以及后台日志轮转和完整检查点维护。
- crates.io:
pi_block_device = "0.1.0" - API 文档:https://docs.rs/pi_block_device
- MSRV:Rust 1.85
- 许可证:MIT
已实现功能
- 缺失路径或严格空目录的 durable 初始化,以及已有设备的日志恢复和重启孤儿清理。
- 15 种普通槽位:4、6、8、12、16、24、32、48、64、96、128、192、256、384、512 KiB;超过 512 KiB 使用独立大块文件。
- 每个 store 同时一个写事务;多读者和固定快照不受后续提交影响。
alloc->write_batch-> 根/名称/释放变更 ->commit的写时复制提交协议。release_blocks对普通块和大块即时分类,先验证完整批次,再原子更新事务 candidate;最终根仍引用释放块时,commit返回InvalidWriteInput。- 普通块释放清理存活位图,但不回退
frontier、不复用旧空洞;空 Sealed 段移除,空 Active 段替换为新版本空 Active 段。 - durable 发布后,已移除段文件和大块文件进入进程内退休队列。标准线程 worker 接收提交、snapshot drop 和
ReadBufdrop 通知,并以 10/25/50/100 ms 有限退避重试 unlink;NotFound视为完成,其他失败保留队列项。 - snapshot 以固定
State的路径引用保护文件;返回的ReadBuf以精确物理路径 lease 保护文件。保护解除后 worker 才删除退休文件,物理删除把文件占用归还给操作系统。 - Active 普通块的拥有型读取,以及 Sealed 普通块和大块的只读映射读取。
- 不确定提交结果的安全围栏,以及重新打开时的恢复和孤儿清理。
- 活动日志达到 4 MiB 后,由标准线程后台合并轮转建议。worker 取得单写者门禁后捕获最新已提交状态,轮转并把完整 checkpoint 作为新 Active 的首条记录 durable 写入,再释放门禁并归档旧结构;归档失败保持 Ready 并自动重试。
当前限制
- 指标尚未实现:
FileBlockStore::metrics返回零值占位,available_bytes为None。 - 整理和释放候选由上层选择;本 crate 不主动遍历引用图或决定何时 GC。
- 块内引用由上层维护;提交只检查最终根集合是否直接包含已释放块,不能发现块内容中的引用。
- 日志压缩、数据压缩、加密和数据 checksum 尚未实现;文件后端的压缩、加密和 checksum 能力标志均为
false。 - 默认文件后端使用同步
std::fsI/O 核心;异步方法可能阻塞调用线程。异步运行时中的延迟敏感调用应放入其阻塞任务设施。 - 普通块读取返回完整槽位,短输入的尾部会补零;大块读取返回原始逻辑长度。
- 释放普通块不会让后续分配复用
frontier之前的旧空洞;不要把逻辑释放描述为块地址空间可复用。只有退休物理文件成功删除后,相关文件占用才归还给操作系统。 - 退休队列只存在于进程内;若进程在 unlink 前退出,重新打开会把最终状态未引用的 regular file 当作孤儿删除。
- 一个
SegmentId只能交回创建它的同一 store 实例、同一快照。 CommitStatusUnknown表示提交可能已生效,不能按“失败回滚”处理,也不能直接重放同一逻辑操作;它会实际围栏 store。- store 进入
RecoveryRequired围栏后,新的read、open_snapshot和begin_write会被拒绝。围栏前取得的旧 snapshot 仍可查询固定元数据,围栏前已返回的旧ReadBuf仍有效;旧 snapshot 不能绕过围栏发起新的块读取。 - 恢复会截断 Active 段的冗余完整槽位尾部,并删除
data/中所有未被最终状态引用的 regular file。symlink、目录及其他特殊条目会使恢复失败;清理不递归。 - 对主动并发文件系统路径替换/换名攻击不提供保证;现有 symlink、reparse-point 和文件类型检查不是完整沙箱。
碎片整理边界
本 crate 提供段枚举、存活块枚举和批量逻辑释放,但不实现自动 GC 或在线碎片整理策略。上层必须解析自己的块内引用,迁移仍可达数据并原子更新根/名称后,才能调用 release_blocks。普通段 frontier 之前的空洞不会被重新分配;只有整个退休段文件或大块文件成功删除时,操作系统层面的文件占用才会下降。
快速示例
[]
= "0.1.0"
= "1"
= { = "1", = ["macros", "rt-multi-thread"] }
use ;
use smallvec;
async
文档入口
构建 API 文档
cargo doc --no-deps
生成结果位于 target/doc/pi_block_device/index.html。若需立即打开,可运行 cargo doc --no-deps --open。
许可证
本项目仅以 MIT License 授权。