pi_block_device 0.1.0

Asynchronous copy-on-write block storage abstractions
Documentation

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 后物理文件退休,以及后台日志轮转和完整检查点维护。

已实现功能

  • 缺失路径或严格空目录的 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 和 ReadBuf drop 通知,并以 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::fs I/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 之前的空洞不会被重新分配;只有整个退休段文件或大块文件成功删除时,操作系统层面的文件占用才会下降。

快速示例

[dependencies]
pi_block_device = "0.1.0"
smallvec = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
use pi_block_device::{
    AsyncBlockDevice, BlockStore, FileBlockStore, ReadSnapshot, RootName, WriteInput,
    WriteTransaction,
};
use smallvec::smallvec;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = FileBlockStore::open("./example-store").await?;
    let mut transaction = store.begin_write().await?;
    let allocated = transaction.alloc(WriteInput {
        data: b"hello block store".to_vec(),
    })?;
    let block = allocated.block_id();
    transaction.write_batch(smallvec![allocated]).await?;
    transaction.add_root_version(block)?;
    transaction.create_named_binding(RootName::new("main".to_owned())?, block)?;
    let commit_result = transaction.commit().await?;
    println!("committed record {}", commit_result.business_record_seq().get());

    let snapshot = store.open_snapshot()?;
    let root = snapshot
        .get_named_root(&RootName::new("main".to_owned())?)
        .expect("committed named root");
    let bytes = store.read(root.root().block()).await?;
    assert_eq!(&bytes.as_ref()[..17], b"hello block store");
    Ok(())
}

文档入口

构建 API 文档

cargo doc --no-deps

生成结果位于 target/doc/pi_block_device/index.html。若需立即打开,可运行 cargo doc --no-deps --open。

许可证

本项目仅以 MIT License 授权。