# 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 和 `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` 之前的空洞不会被重新分配;只有整个退休段文件或大块文件成功删除时,操作系统层面的文件占用才会下降。
## 快速示例
```toml
[dependencies]
pi_block_device = "0.1.0"
smallvec = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```
```rust,no_run
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(())
}
```
## 文档入口
- [使用指南](docs/guide/index.md)
- [快速开始](docs/guide/getting-started.md)
- [恢复与持久性](docs/guide/recovery-and-durability.md)
- [公开 API 总览](docs/api/index.md)
- [安全策略](SECURITY.md)
- [变更记录](CHANGELOG.md)
## 构建 API 文档
```console
cargo doc --no-deps
```
生成结果位于 `target/doc/pi_block_device/index.html`。若需立即打开,可运行 `cargo doc --no-deps --open`。
## 许可证
本项目仅以 [MIT License](LICENSE) 授权。