docs.rs failed to build wbase-0.1.5
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build:
wbase-0.1.3
wbase : Common Foundation Primitives and Constants
Core Positioning
wbase is the Layer-0 foundational primitives library for the WeDB storage engine. It extracts cross-crate constants and fundamental state machines, eliminating circular and reverse dependencies to ensure a strictly acyclic DAG across the workspace.
All features are provided as fine-grained optional Cargo features, with no full feature, allowing callers to opt into exactly what they need with zero overhead.
Modules & Features (On-Demand, No Full Feature)
| Feature | Path | Responsibility | Dependencies |
|---|---|---|---|
addr |
wbase::addr |
48-bit address masks, ReadCache bit, LogAddress strongly typed wrapper |
None (pure bitwise ops) |
align |
wbase::align |
64B cacheline, 512B/4096B sector alignment checks and safe calculations | None (pure bitwise ops) |
backoff |
wbase::backoff |
3-stage adaptive backoff state machine (spin → yield → sleep) | None (supports reactor yield) |
thread |
wbase::thread |
High-throughput TLS monotonic thread identifier current_thread_id() |
None (TLS register reads) |
Core API & Primitives
1. addr (48-bit Log Address System)
Strict parity with C# Tsavorite / Garnet LogAddress:
- Constants:
ADDRESS_BITS = 48,ADDRESS_MASK = 0x0000_FFFF_FFFF_FFFF(up to 256TB address space). - ReadCache Bit:
READ_CACHE_BIT = 1 << 47,ABSOLUTE_ADDRESS_MASK = ADDRESS_MASK & !READ_CACHE_BIT. - Predicates & conversions:
is_valid,is_read_cache,to_absolute,with_read_cache. - Wrapper:
LogAddresstransparent struct with compact layout and display formatting.
2. align (Memory & Sector Alignment)
- Cacheline:
CACHELINE_BYTES = 64,is_cacheline_aligned,align_to_cacheline. - Sector calculations:
MIN_SECTOR_SIZE = 512,DEFAULT_SECTOR_SIZE = 4096. - Safe math:
checked_align_up(returnsNoneon overflow),align_up(saturating),align_down,is_aligned.
3. backoff (3-Stage Adaptive Backoff)
Designed for multi-core high-concurrency and compio thread-per-core reactor models:
- Stage 1 (< 32 spins):
spin_loop()CPU instruction pause. - Stage 2 (32..1024 rounds):
yield_now()OS time-slice yield. - Stage 3 (>= 1024 rounds):
sleep(50µs)synchronous sleep or async non-blocking sleep viaBackoffStage::Sleep.
4. thread (High-Throughput Thread ID)
current_thread_id() -> u64: Global atomic increment on first visit (starting from 1), cached in TLS for register-level access (< 1ns, 0 locks, 0 atomic ops).- Single source of truth for thread IDs, eliminating bus contention and ABA hazards.
Design Principles & Parity
- Zero-Cost Abstraction: All physical masks fold at compile-time with zero runtime penalty.
- compio Friendly: Backoff state machines cleanly expose stages, preventing synchronous sleep calls from freezing reactor worker threads.
- Orthogonal Decoupling: Upstream crates (
wrecord,windex,wreviv,wram,wepoch) import only their required features.
wbase : 存储底座通用基础原语与常量库
核心定位
wbase 是 WeDB 存储引擎的最底层（L0 级）公共基础原语库。抽离跨 crate 共享的核心常量与基础状态机，消除循环依赖与反向依赖，保障整个 workspace 拓扑单向无环。
所有功能模块均作为**细粒度可选特性（feature）**提供，杜绝全量 full 特性，使用方按需引入，零多余依赖与开销。
模块划分与特性（按需启用，无 full）
| 特性名 | 模块路径 | 职责说明 | 外部依赖 |
|---|---|---|---|
addr |
wbase::addr |
48 位逻辑/物理地址掩码、ReadCache 标记、LogAddress 强类型封装 |
无（纯标准库位运算） |
align |
wbase::align |
64B 缓存行、512B/4096B 扇区对齐校验与防溢出计算 | 无（纯标准库位运算） |
backoff |
wbase::backoff |
三阶自适应退避状态机（自旋 → yield 让核 → 微秒休眠） | 无（支持异步 reactor 让渡） |
thread |
wbase::thread |
高吞吐 TLS 全局唯一单调递增线程标识 current_thread_id() |
无（TLS 寄存器级访问） |
核心 API 与原语
1. addr（48 位日志地址体系）
严格对标 C# Tsavorite / Garnet LogAddress：
- 常量：
ADDRESS_BITS = 48，ADDRESS_MASK = 0x0000_FFFF_FFFF_FFFF（最大 256TB 寻址空间）。 - 读缓存标记：
READ_CACHE_BIT = 1 << 47，ABSOLUTE_ADDRESS_MASK = ADDRESS_MASK & !READ_CACHE_BIT。 - 判据与转换：
is_valid、is_read_cache、to_absolute、with_read_cache。 - 封装：
LogAddress结构体，提供紧凑无锁与格式化支持。
2. align（内存与扇区对齐）
- 缓存行：
CACHELINE_BYTES = 64，is_cacheline_aligned，align_to_cacheline。 - 扇区计算：
MIN_SECTOR_SIZE = 512，DEFAULT_SECTOR_SIZE = 4096。 - 安全计算：
checked_align_up（极值溢出返回None）、align_up（溢出安全饱和）、align_down、is_aligned。
3. backoff（三阶自适应退避）
适配多核高并发与 compio thread-per-core 反应器模型：
- 第一阶段（< 32 轮）：
spin_loop()极短指令等待。 - 第二阶段（32..1024 轮）：
yield_now()操作系统级让渡时间片。 - 第三阶段（>= 1024 轮）：
sleep(50µs)同步微睡，或供异步调用方感知BackoffStage::Sleep后执行非阻塞compio::time::sleep().await。
4. thread（高吞吐线程 ID）
current_thread_id() -> u64：首访全局原子计数器单调自增（1 起步），后续由线程本地存储（TLS）纯寄存器读取（< 1ns，0 锁，0 原子操作）。- 统一全局线程标识，天然免疫 ABA，消除模块各自维护 ID 造成的总线争用。
设计原则与对标
- 零成本抽象与单一真源：所有物理掩码在编译期直接折叠，不产生运行时损耗。
- compio 友好：退避状态机显式暴露阶段，彻底消除异步上下文误调同步阻塞 sleep 冻结 reactor 的隐患。
- 架构正交解耦：上层模块如
wrecord、windex、wreviv、wram、wepoch按需引入特定特性，彻底消除平级相互穿透。