wbftree 0.1.0

//! wbftree: 块级有序存储引擎与 RangeIndex 管理器
//! (1:1 对标 Garnet bftree-garnet 互操作层 + RangeIndexManager 系列 C# 服务层，经 bf-tree crate 纯 Rust 实现)
//!
//! # 模块组成
//! - [`BfTreeService`]：单树生命周期与点读/写入/扫描/CPR 快照 (对标 BfTreeService.cs)
//! - [`RangeIndexManager`]：多树注册表、惰性恢复、刷盘/检查点/截断/复制枚举 (对标 RangeIndexManager.cs*)
//! - [`RangeIndexChunkedSerializer`] / [`RangeIndexChunkedDeserializer`] / [`RangeIndexMigrationReader`]：
//!   迁移分块流协议状态机 (对标 RangeIndexChunkedSerializer/Deserializer/MigrationReader.cs)
//! - [`RangeIndexStub`]：主存储日志中的 35 字节定长存根 (对标 RangeIndexManager.Index.cs)
//!
//! # 并发模型 (thread-per-core 契合，见 sync.md)
//! 全 crate 仅提供同步 API，无运行时依赖，天然契合 compio 线程每核模型：
//! - 点读/写入路径零条带锁：引擎内部叶子闩锁保证并发安全；跨线程共享
//!   `Arc<BfTreeService>`，各核直接操作同一实例，无消息传递开销。
//! - 生命周期变更 (创建/惰性恢复/注销/删除) 才获取 [`RangeIndexLocks`] 键哈希
//!   条带写锁 (128 缓存行对齐条带，消除伪共享)；热路径绝不持锁跨引擎调用。
//! - 在线索引用 papaya 无锁字典管理，读侧 pin 快照一致，与写侧互不阻塞。
//! - 快照与写入的互斥采用「屏障位 + 在途写者计数」的 SeqCst store-buffering
//!   配对 (见 `service::WriteGuard`)，写者仅在快照窗口内短暂自旋让出，快照
//!   期间树对写静稳，保证 CPR 快照无撕裂 (较 C# 真并发 CPR 更保守但更简单)。
//! - 删除树延迟到 `Arc` 引用归零：扫描/点读持引擎 Arc 者可安全跑完 (对标
//!   C# LightEpoch 延迟释放语义，此处由引用计数天然承担)。
//!
//! # 键语义与名字空间隔离 (见 sync.md)
//! - 键全程 `&[u8]` 二进制安全，零拷贝透传引擎。
//! - 128 位键 ID 由 `gxhash128(key, 专用种子域)` 派生 (与 C# XxHash128→Guid
//!   刻意不逐位兼容，跨架构比特稳定即可)；文件名前缀即该 ID 的 32 位十六进制
//!   编码，摘要域与用户数据域隔离，复合键派生不会与用户键混淆。

#![cfg_attr(docsrs, feature(doc_cfg))]

mod chunk;
pub(crate) mod error;
mod manager;
mod service;
mod stub;
mod types;

pub use chunk::{
  MIN_CHUNK_SIZE, RangeIndexChunkedDeserializer, RangeIndexChunkedSerializer,
  RangeIndexMigrationReader, compute_checksum, compute_checksum_with_seed,
};
pub use error::{Error, Result};
pub use manager::{
  CacheAlignedLock, DEFAULT_MIGRATION_CHUNK_SIZE, INDEX_SIZE_BYTES, NUM_LOCK_STRIPES,
  RangeIndexFileEntry, RangeIndexLocks, RangeIndexManager, TreeEntry,
};
pub use service::{BfTreeService, WriteBarrierGuard};
pub use stub::{RANGE_INDEX_STUB_SIZE, RangeIndexStub};
pub use types::{
  BfTreeConfig, BfTreeDeleteResult, BfTreeInsertResult, BfTreeReadResult, ScanRecord,
  ScanReturnField, StorageBackend, StorageBackendType, TreeTuning,
};