# 公开 API 总览
本页覆盖当前 crate 根导出的公共 trait/API;项目仍处于 `0.1` 阶段,不承诺兼容稳定性。docs.rs 风格路径均以 `pi_block_device::` 开头;实现源码见 [`src/lib.rs`](../../src/lib.rs)、[`src/file/mod.rs`](../../src/file/mod.rs)、[`src/file/snapshot.rs`](../../src/file/snapshot.rs)、[`src/file/read.rs`](../../src/file/read.rs) 和 [`src/file/transaction.rs`](../../src/file/transaction.rs)。
## 后端入口
### `pi_block_device::FileBlockStore`
文件系统与追加日志后端,公开固有方法只有:
- `FileBlockStore::open(path: impl AsRef<Path>) -> Result<FileBlockStore, BlockStoreError>`:异步打开、初始化或恢复。缺失路径和严格空目录会初始化;已有有效布局会恢复;其他非空目录不会被静默重建。
它实现 `BlockDeviceInfo`、`BlockDeviceMetrics`、`AsyncBlockDevice` 和 `BlockStore`。具体 `ReadBuf`、`Snapshot`、`Transaction` 类型由关联类型返回,未从 crate 根单独导出;调用方应通过 trait 方法和类型推导使用。
## 公共 trait
### `pi_block_device::BlockDeviceInfo`
- `device_id(&self) -> DeviceId`:返回跨重启持久的设备身份。文件后端的状态锁中毒时此无失败通道的方法会 panic。
- `base_block_size(&self) -> u64`:文件后端固定为 4096。
- `supported_block_sizes(&self) -> &'static [u64]`:文件后端返回 15 个普通槽位尺寸,不包含大块。
- `capabilities(&self) -> BlockDeviceCapabilities`:文件后端三项均为 `false`。
### `pi_block_device::BlockDeviceMetrics`
- `metrics(&self) -> BlockDeviceMetricsSnapshot`:同步取得不可变指标快照。文件后端当前只返回零值占位,尚未连接真实计数器。
### `pi_block_device::AsyncBlockDevice`
继承 `BlockDeviceInfo + BlockDeviceMetrics + Send + Sync + 'static`。
- 关联类型 `ReadBuf: AsRef<[u8]> + Send + 'static`:拥有稳定字节视图,不要求 `Clone` 或 `Sync`。
- `read(&self, block: BlockId) -> Result<Self::ReadBuf, BlockStoreError>`:异步读取已提交块。
文件后端特有行为:Active 普通段复制并返回完整槽位,短写尾部为零;Sealed 普通段可返回只读映射范围;大块可返回完整文件只读映射,长度等于逻辑长度。返回缓冲独立持有数据或映射,释放 store 后仍有效。方法可能执行阻塞文件 I/O。
### `pi_block_device::BlockStore`
- 关联类型 `Snapshot: ReadSnapshot`。
- 关联类型 `Transaction: WriteTransaction`。
- `open_snapshot(&self) -> Result<Self::Snapshot, BlockStoreError>`:同步固定当前完整已提交状态。
- `begin_write(&self) -> Result<Self::Transaction, BlockStoreError>`:异步获取单写者事务;已有写者返回 `WriteTransactionBusy`。
### `pi_block_device::ReadSnapshot`
继承 `Send + Sync + 'static`。所有迭代器都借用快照,公共合同不保证枚举顺序。
- GAT `NamedRoots<'a>: Iterator<Item = &'a NamedRoot> where Self: 'a`。
- GAT `AnonymousRoots<'a>: Iterator<Item = &'a AnonymousRoot> where Self: 'a`。
- GAT `SegmentInfos<'a>: Iterator<Item = &'a SegmentInfo> where Self: 'a`。
- GAT `LiveBlocks<'a>: Iterator<Item = BlockId> where Self: 'a`。
- `list_named_roots(&self) -> Self::NamedRoots<'_>`:枚举名称绑定。
- `list_anonymous_roots(&self) -> Self::AnonymousRoots<'_>`:枚举无名称绑定的根。
- `get_named_root(&self, name: &RootName) -> Option<&NamedRoot>`:按名称查询,缺失返回 `None`。
- `get_root(&self, block: BlockId) -> Option<&RootVersion>`:按块查询根版本,缺失返回 `None`。
- `segment_infos(&self) -> Self::SegmentInfos<'_>`:枚举快照中的 Active/Sealed 普通段。
- `live_blocks(&self, segment: SegmentId) -> Result<Self::LiveBlocks<'_>, BlockStoreError>`:跨 store、跨快照或未知句柄返回 `SegmentNotFound`。
文件快照持有打开时固定 `State` 的 `Arc`,固定根、段表和位图;后续提交不会改变它。退休删除按该固定 State 是否精确引用目标物理路径判断保护。快照采用 RAII,没有租期或超时。
### `pi_block_device::WriteTransaction`
- `alloc(&mut self, input: WriteInput) -> Result<AllocatedBlock, BlockStoreError>`:同步选择最小普通槽位或独立大块,预留最终 `BlockId`,但不物理写入、不提交。
- `write_batch(&mut self, blocks: SmallVec<[AllocatedBlock; 8]>) -> Result<(), BlockStoreError>`:异步、按值消费一批分配凭证;凭证只能由创建它的同一 store 和同一事务消费。
- `add_root_version(&mut self, block: BlockId) -> Result<(), BlockStoreError>`:把块加入事务最终根集合。
- `create_named_binding(&mut self, name: RootName, target: BlockId) -> Result<(), BlockStoreError>`:创建名称绑定;同名当前已存在时立即失败。
- `remove_named_binding(&mut self, name: &RootName) -> Result<(), BlockStoreError>`:删除名称绑定,不自动删除根。
- `delete_root_version(&mut self, target: BlockId) -> Result<(), BlockStoreError>`:暂存根删除;缺失或仍被命名可延迟到提交校验。
- `release_blocks(&mut self, blocks: Vec<BlockId>) -> Result<(), BlockStoreError>`:即时区分普通块和大块,先验证整个批次,再原子更新事务 candidate。普通槽位清除位图但不回退 `frontier`;空 Sealed 段移除,空 Active 段替换为新版本空 Active 段。pending 块返回 `BlockNotCommitted`,不存在/越界返回 `BlockNotFound`,已死亡或重复释放返回 `BlockAlreadyReleased`。最终根若仍引用释放块,`commit` 返回 `InvalidWriteInput`。
- `commit(&mut self) -> Result<CommitResult, BlockStoreError>`:异步提交事务,刷盘数据,durable 追加单条 Delta,再发布内存状态;成功结果提供业务记录序号和提交后维护结果。
文件后端只有一个写者。未提交事务 drop 等同中止;`write_batch` 取消会关闭事务;commit durable 移交后的取消不会停止后台提交,并会围栏当前 store。释放产生的物理路径仅在 durable 发布后进入进程内退休队列;标准线程 worker 等待 snapshot 的固定 State 路径保护和 `ReadBuf` 的精确路径 lease 解除后 unlink。
## 公共值类型
### `pi_block_device::BlockId`
私有 `u64` 表示的持久块标识,派生 `Clone + Copy + Debug + Eq + PartialEq`。
- `level(self) -> u8`:普通块为 0..=14,大块为 15。
- `segment_version(self) -> Option<u32>`:普通块段版本;大块为 `None`。
- `block_index(self) -> Option<u32>`:普通块槽位索引;大块为 `None`。
- `large_block_id(self) -> Option<u64>`:大块编号;普通块为 `None`。
- `slot_size(self) -> Option<u64>`:普通块槽位字节数;大块为 `None`。
- `TryFrom<u64, Error = BlockStoreError>`:验证原始编码;非法值返回 `InvalidBlockId`。
- `From<BlockId> for u64`:无损取回原始编码。
### `pi_block_device::DeviceId`
私有 `[u8; 16]` 表示,无公开构造器。`as_bytes(&self) -> &[u8; 16]` 返回持久设备身份原始字节;没有 UUID 文本、解析或数值转换合同。
### `pi_block_device::BlockDeviceCapabilities`
字段 `compression`、`encryption`、`data_checksums` 均私有,无公开构造器。getter 为 `compression()`、`encryption()`、`data_checksums()`,都返回 `bool`。
### `pi_block_device::BlockDeviceMetricsSnapshot`
字段全部私有,无公开构造器。getter 为:
- `used_bytes() -> u64`、`free_bytes() -> u64`、`available_bytes() -> Option<u64>`。
- `read_ops() -> u64`、`read_bytes() -> u64`、`write_ops() -> u64`、`write_bytes() -> u64`。
- `commit_ok() -> u64`、`commit_failed() -> u64`、`recovery_count() -> u64`、`reclaimed_bytes() -> u64`。
文件后端当前所有 `u64` getter 返回 0,`available_bytes` 返回 `None`;这不是已完成的指标实现。
### `pi_block_device::WriteInput`
唯一公开字段是 `data: Vec<u8>`。空向量由 `alloc` 拒绝;普通块不足槽位的尾部补零。
### `pi_block_device::AllocatedBlock`
字段私有,无公开构造器,不实现 `Clone`。`block_id(&self) -> BlockId` 查看最终块标识而不消费凭证;之后仍须把凭证按值交给 `write_batch`。
### `pi_block_device::RootName`
私有 `String` 新类型。`RootName::new(value: String)` 对空字符串返回 `RootNameEmpty`;`as_str(&self) -> &str` 借用原始名称。
### `pi_block_device::RootVersion`
字段私有,无公开构造器,只由快照返回。`block(&self) -> BlockId` 返回根引用块。
### `pi_block_device::NamedRoot`
字段 `name`、`root` 私有,无公开构造器。`name(&self) -> &RootName`,`root(&self) -> &RootVersion`。
### `pi_block_device::AnonymousRoot`
字段 `root` 私有,无公开构造器。`root(&self) -> &RootVersion`。
### `pi_block_device::SegmentState`
公开变体完整集合:`SegmentState::Active` 和 `SegmentState::Sealed`。没有公开 `Retired` 变体。
### `pi_block_device::SegmentId`
字段私有、无公开构造器、无数值转换、不可作为持久标识。只能从 `SegmentInfo::segment` 取得,并交回同一快照的 `live_blocks`。
### `pi_block_device::SegmentInfo`
字段 `segment`、`level`、`slot_size`、`frontier`、`live_count`、`state` 均私有,无公开构造器。
- `segment(&self) -> SegmentId`:返回快照作用域段句柄。
- `level(&self) -> u8`:普通段级别 0..=14。
- `slot_size(&self) -> u64`:槽位字节数。
- `frontier(&self) -> u64`:曾分配槽位数,有效索引范围为 `0..frontier`。
- `live_count(&self) -> u64`:快照位图中的存活槽位数。
- `state(&self) -> SegmentState`:Active 或 Sealed。
## `pi_block_device::BlockStoreError`
公开错误枚举实现 `Debug`、`Display`、`std::error::Error`、`PartialEq` 和 `Eq`。除 `Io` 外,`Display` 输出变体名;`Io` 保留底层 `std::io::Error` 作为 `source`。
| `Io(std::io::Error)` | 底层 I/O 失败,保留错误来源。 |
| `InvalidBlockId` | 块编码或 checked 算术范围无效。 |
| `BlockNotFound` | 编码合法但当前已提交状态中不存在或不存活。 |
| `BlockNotCommitted` | 块属于当前未提交分配。 |
| `BlockCorrupted` | 已提交状态声明的物理范围与文件不一致。 |
| `InvalidWriteInput` | 写入为空或输入/最终状态不符合约束。 |
| `AllocatedBlockNotOwned` | 分配凭证不属于当前 store/事务。 |
| `AllocatedBlockAlreadyWritten` | 防御性重复写分类;线性安全 API 通常不可触发。 |
| `AllocatedBlockNotWritten` | 提交时仍有分配未成功写入。 |
| `BlockAlreadyReleased` | 文件后端用于基础块已死亡、同批重复或同事务重复释放。 |
| `SegmentNotFound` | 段不存在,或 `SegmentId` 不属于当前快照。 |
| `RootNotFound` | 根不存在或新根目标不可接受。 |
| `RootAlreadyDeleted` | 同一事务重复请求删除根。 |
| `RootStillNamed` | 待删除根在最终状态仍有名称引用。 |
| `RootNameEmpty` | 根名称为空。 |
| `RootNameAlreadyBound` | 名称已经绑定。 |
| `NamedBindingNotFound` | 待删除名称绑定不存在。 |
| `NamedBindingTargetNotFound` | 名称最终目标不在根集合。 |
| `WriteTransactionBusy` | 单写者门禁已被占用。 |
| `WriteTransactionClosed` | 事务已关闭、写入失败或写入被取消。 |
| `NoSpace` | 当前布局无法继续安全分配。 |
| `SegmentVersionExhausted` | 28 位普通段版本空间耗尽。 |
| `LargeBlockIdExhausted` | 大块编号空间耗尽。 |
| `CommitFailed` | 提交明确未持久成功,旧状态仍是权威。 |
| `CommitStatusUnknown` | 提交可能已持久生效;当前 store 随后需要恢复。 |
| `RecoveryRequired` | 当前实例已被安全围栏,必须重新打开;也可能表示锁中毒或退休/补偿清理无法安全完成。 |
| `RecoveryFailed` | 恢复时布局、日志、引用文件或清理无法建立可信状态。 |
| `RecordTooLarge` | Delta 或未来完整 checkpoint 超过 codec 配置上限、append-log envelope 上限,或长度计算溢出;在数据文件同步和日志追加前返回。 |
| `UnsupportedFormat` | 持久格式版本高于当前实现。 |
## 恢复、围栏与依赖边界
- store 实际进入 `RecoveryRequired` 围栏后,新的 `read`、`open_snapshot` 和 `begin_write` 会被拒绝;既有事务变更也会被拒绝。
- 围栏前取得的旧 snapshot 仍可查询固定元数据,但不能绕过 store 围栏发起新的块读取;围栏前已返回的 `ReadBuf` 仍有效。
- 对日志末尾物理未完成最终帧的容忍依赖 `pi_append_log`。完整帧校验失败、业务解码失败或中间损坏仍为 `RecoveryFailed`;本仓库尚无该尾帧行为的独立端到端集成证据,不将其列为强保证。
- crate 直接依赖 crates.io 上的 `pi_append_log = "0.1.0"`,发布包和仓库构建使用相同依赖来源。
## 文件后端维护、释放、退休与限制
- `release_blocks` 已实现逻辑释放,但整理/释放候选由上层选择,块内容中的引用也由上层维护;本 crate 只拒绝最终根集合直接引用已释放块。
- 普通槽位释放后不会复用 `frontier` 之前的旧空洞。物理段文件或大块文件成功 unlink 后才把占用归还给操作系统,不能概括为块空间可复用。
- durable 发布后的退休队列仅存在于进程内。worker 由 enqueue、snapshot drop、`ReadBuf` drop 通知唤醒,并对受保护路径或删除失败采用 10/25/50/100 ms 有限退避;unlink `NotFound` 视为完成,其他失败保留队列项等待重试。
- 进程在队列清空前退出不会丢失最终状态;重新打开会删除最终 State 未引用的 regular file,完成重启孤儿清理。
- 活动日志达到 4 MiB 后,成功提交会在发布 State 并释放写门禁后通知标准线程维护 worker。worker 在取得同一单写者门禁后捕获最新 State,执行 rotate、新 Active 首 checkpoint durable 写入和旧结构 archive;维护期间新写事务返回 `WriteTransactionBusy`,只读 snapshot 和已有读取保持可用。
- rotate 或首 checkpoint 失败会围栏为 `RecoveryRequired`;archive 失败保持 Ready,并保留 closed 句柄自动重试。恢复取得的 closed 结构也会进入该归档队列。
- `metrics` 是零值占位,不代表真实容量或操作计数。
- 日志压缩、数据压缩、加密和数据 checksum 未实现,三个能力标志均为 `false`。
- 异步方法执行同步文件 I/O,可能阻塞执行器线程。
- 恢复会截断 Active 冗余完整槽位尾部,并删除 `data/` 中所有未引用 regular file,包括普通段、大块、未知名和非 UTF-8 名称文件;symlink、目录及其他特殊条目导致恢复失败,且不会递归。
- Unix、Windows 和其他平台均不保证抵御主动并发文件系统路径替换/换名攻击;现有 symlink、reparse-point 和文件类型检查不是完整沙箱。
- Windows 目录同步对 `PermissionDenied`/`InvalidInput` 采用 best effort;Unix 与其他平台的目录同步错误正常传播。
使用流程见[快速开始](../guide/getting-started.md),恢复处置见[恢复与持久性](../guide/recovery-and-durability.md)。