pi_block_device 0.1.0

Asynchronous copy-on-write block storage abstractions
Documentation
# 快速开始

## 依赖与运行时

`pi_block_device` 的公共 API 不绑定 Tokio,但项目仍处于 `0.1` 阶段,不承诺公共 API 的兼容稳定性。当前 `FileBlockStore` 的异步方法内部包含同步文件 I/O,可能阻塞调用线程;延迟敏感应用可在自身运行时中把整段存储操作调度到阻塞任务设施。

发布版可直接按 crates.io 版本依赖。`write_batch` 接受 `SmallVec<[AllocatedBlock; 8]>`,因此示例还直接依赖 `smallvec`。

```toml
[dependencies]
pi_block_device = "0.1.0"
smallvec = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## 完整流程

以下 `no_run` 示例会创建或恢复 `./example-store`。路径不存在或目录严格为空时初始化;已有有效布局时恢复。

```rust,no_run
use pi_block_device::{
    AsyncBlockDevice, BlockStore, BlockStoreError, 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 = match transaction.commit().await {
        Ok(result) => result,
        Err(BlockStoreError::CommitStatusUnknown) => {
            return Err("commit status unknown; reopen and inspect roots".into());
        }
        Err(error) => return Err(error.into()),
    };
    println!(
        "committed business record {}",
        commit_result.business_record_seq().get()
    );

    let snapshot = store.open_snapshot()?;
    let lookup = RootName::new("main".to_owned())?;
    let named = snapshot
        .get_named_root(&lookup)
        .ok_or("named root missing after commit")?;

    let read_buf = store.read(named.root().block()).await?;
    assert_eq!(&read_buf.as_ref()[..17], b"hello block store");
    Ok(())
}
```

## 分配和读取长度

`WriteInput::data` 不能为空。长度不超过 512 KiB 时,`alloc` 选择能够容纳数据的最小普通槽位;普通块写入时会把剩余槽位补零,因此 `read` 返回完整槽位。超过 512 KiB 时使用独立大块,读取长度等于原始逻辑长度。

在 `commit` 成功之前,对本事务新分配块调用 `read` 会得到 `BlockNotCommitted`。仅调用 `alloc` 不会物理写入;还必须把返回的 `AllocatedBlock` 按值交给 `write_batch`。

## 根、名称和快照

- `add_root_version` 把块加入事务最终根集合;目标有效性可延迟到 `commit` 校验。
- `create_named_binding` 要求名称当前未绑定;绑定目标最终必须属于根集合。
- `remove_named_binding` 只删除名称,不删除根,目标可能成为匿名根。
- `delete_root_version` 删除根前,事务最终状态中不能再有名称引用它。
- `open_snapshot` 是同步方法,快照不随后续提交变化,也没有租期或超时。
- 块字节始终通过 `AsyncBlockDevice::read` 获取;`ReadSnapshot` 只提供根和段元数据。
- snapshot 持有打开时固定 `State`,并按其中精确引用的物理路径阻止退休删除;`ReadBuf` 另持有其来源文件的精确路径 lease。
- store 实际围栏后,旧 snapshot 仍可查询固定元数据,但新的 `read` 会被拒绝;旧 snapshot 不能绕过围栏读取块。围栏前已经取得的 `ReadBuf` 仍有效。

```rust,no_run
use pi_block_device::{BlockStore, FileBlockStore, ReadSnapshot};

async fn inspect(store: &FileBlockStore) -> Result<(), pi_block_device::BlockStoreError> {
    let snapshot = store.open_snapshot()?;
    for named in snapshot.list_named_roots() {
        println!("{} -> {}", named.name().as_str(), u64::from(named.root().block()));
    }
    for anonymous in snapshot.list_anonymous_roots() {
        println!("anonymous -> {}", u64::from(anonymous.root().block()));
    }
    Ok(())
}
```

## 错误处理

```rust,no_run
use pi_block_device::{BlockStoreError, FileBlockStore};

async fn open_store(path: &str) -> Result<FileBlockStore, BlockStoreError> {
    match FileBlockStore::open(path).await {
        Ok(store) => Ok(store),
        Err(BlockStoreError::UnsupportedFormat) => {
            eprintln!("持久格式高于当前实现,请升级程序");
            Err(BlockStoreError::UnsupportedFormat)
        }
        Err(BlockStoreError::RecoveryFailed) => {
            eprintln!("布局、日志或引用文件不一致,需要人工检查或从备份恢复");
            Err(BlockStoreError::RecoveryFailed)
        }
        Err(BlockStoreError::Io(error)) => {
            eprintln!("底层 I/O 失败: {error}");
            Err(BlockStoreError::Io(error))
        }
        Err(error) => Err(error),
    }
}
```

处置原则:`WriteTransactionBusy` 可在现有写者结束后重试;输入和根约束错误应修正事务;`CommitFailed` 表示旧状态仍是权威;`CommitStatusUnknown` 不能直接重试同一逻辑操作;实际围栏产生的 `RecoveryRequired` 要求释放当前实例并重新打开;`RecoveryFailed` 不能通过把目录当作新 store 来绕过。

## 释放块与空间回收

`release_blocks` 接受普通块和大块的混合批次。文件后端先验证整个批次,再原子更新事务 candidate;因此任一项失败时不会只释放其中一部分。pending 块返回 `BlockNotCommitted`,不存在或越界返回 `BlockNotFound`,已死亡、同批重复或同事务重复释放返回 `BlockAlreadyReleased`。如果事务最终根集合仍直接引用释放块,`commit` 返回 `InvalidWriteInput`。

普通块释放只清除位图,不回退 `frontier`,后续分配不会复用旧空洞。空 Sealed 段从状态移除;空 Active 段替换为新版本空 Active 段。被移除的段文件和大块文件在 durable 发布后进入进程内退休队列,等待 snapshot 的固定 State 路径保护和 `ReadBuf` 的精确路径 lease 解除,再由标准线程 worker 删除。文件成功删除后,文件占用归还给操作系统;这不表示普通块地址空洞可重新分配。

本 crate 不主动选择整理候选,也不解析块内容中的引用。上层必须先迁移仍需保留的数据、更新根和块内引用,再释放确认不可达的块。进程若在退休 unlink 前退出,重新打开会把最终状态未引用的 regular file 作为孤儿清理。

更多边界见[恢复与持久性](recovery-and-durability.md),完整分类见[公开 API 总览](../api/index.md)。