butterfly

6️⃣ WAL 写入 1. 函数集合 12static int kvstore_log_put();static int kvstore_log_del(); 2. 函数复盘 + 规范注释 2.1 static int kvstore_log_put() 12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849/** * kvstore_log_put - 将写入操作持久到 WAL 日志文件 * * 设计定位： * - WAL 层函数 * - 只负责“把一次 PUT 操作顺序写入磁盘日志” * - 不修改内存结构，不调用 B+ 树 * * 日志格式 * PUT <key>|<crc32>\n * * 执行流程： * 1. 校验日志文件是否已打开 * 2. 构造日志内容字符串 * 3. 计算 CRC32 校验值 * 4. 写入日志文件并强制刷盘 * 5. 更新日志统计信息（大小 / 操作次数） * * snpri...

5️⃣ Recovery / Startup 内部实现 1. 函数集合 123static int kvstore_replay_log();static int kvstore_load_snapshot();static int kvstore_log_header(); 2. 函数复盘 + 规范注释 2.1 static int kvstore_replay_log() 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117/** * kvstore_replay_log - 重放 WAL 日志以重建内存索引 * * 功能： * - 从 WAL 文...

4️⃣ Debug / Utility API 1. 函数集合 123const char* kvstore_strerror();uint32_t crc32();static int kvstore_crc_check(); 2. 函数复盘 + 规范注释 2.1 void kvstore_debug_set_mode() 123456789101112131415161718192021222324252627282930313233/** * kvstore_strerror - 将 KVstore 错误码转换为可读字符串 * * 设计说明： * - 纯函数（无副作用，无状态），不进行任何 I/O 或日志输出 * - 返回的字符串为静态只读字符串，调用方不得修改 * * 使用场景： * - 调试输出 * - 日志系统 * - 对外 API 错误提示 */const char* kvstore_strerror(int err) { switch (err) { case KVSTORE_OK: retu...

3️⃣ Public API — 高级接口 1. 函数集合 12int kvstore_search();int kvstore_compact(); 2. 函数复盘 + 规范注释 2.1 int kvstore_search() 12345678910111213141516171819202122232425/** * kvstore_search - 对外查询接口（存储引擎中检索指定键的值） * * 设计原则： * 1. 这是 kvstore 的“读路径（read path）” * 2. 读操作允许在只读模式（readonly / replay 模式）下执行 * 3. 实际的数据查找完全交给底层索引结构（B+ 树） * * 注意： * - search 本身不关心系统模式（NORMAL / READONLY / REPLAY） * - 只要系统中存在索引结构，就可以安全查询 */int kvstore_search(kvstore* store, int key, long* value) { // kvstore_get // 1. 防御性 ...

2️⃣Public API — 基本操作 1. 函数集合 123int kvstore_put();int kvstore_del();int kvstore_create_snapshot(); 2. 函数复盘 + 规范注释 2.1 int kvstore_put() 12345678910111213141516171819202122/** * kvstore_put - 向存储引擎写入或更新一个键值对 * * @details * 该函数是“逻辑入口”。不做对数据进行实际的 B+ 树插入，而是将操作封装后， * 转发至 Execution 的原子写入路径 * * * [关键不变量] * - 所有用户写操作，必须先成功写 WAL，才能修改内存 * - Apply Layer（内部 put_internal） 只负责“状态变更”，不做权限和持久化判断 * * exec 只给在线写用，replay 只做 apply */int kvstore_put(kvstore* store, int key, long value) { // 1. 基础安全校验 ...

1️⃣Public API — 生命周期（最顶层入口） 1. 函数集合 12345678kvstore* kvstore_create();void kvstore_destroy();kvstore* kvstore_open();int kvstore_recover();int kvstore_log_open();int kvstore_log_close();int kvstore_close(); 2. 函数复盘 + 规范注释 2.1 kvstore* kvstore_create() 123456789101112131415161718192021222324252627282930313233/** * 初始化 kvstore 实例对象（内存分配阶段） * * @note 该函数仅在内存中创建结构。此时系统处于 KVSTORE_STATE_INIT 状态， * 在调用 kvstore_open() 或 kvstore_recover() 之前，无法进行数据操作。 */kvstore* kvstore_create() { // 1. 结构体内存分...

kvstore 架构深度解析 1. Recovery 层（恢复） 核心逻辑: 它是系统启动时的第一道防线 流程： open -> load_snapshot(加载基准数据) -> replay_log(重放增量日志) 设计原因：内存数据库必须在重启后恢复到宕机前的状态。先读快照是为了速度，后重放日志是为了数据完整性 关键函数： kvstore_recover(): 总入口。 kvstore_load_snapshot(): 从磁盘加载静态数据； kvstore_replay_log(): 逐条读取 WAL 并调用 replay_put/del 2. Logging 层 （持久化/WAL） 核心逻辑：Write-Ahead Logging (WAL)。 在修改内存前，先写入磁盘。 **设计原因：**磁盘顺序写远快于随机写。只要日志在，数据就不会丢。 关键函数： kvstore_log_put() / kvstore_log_del():将操作序列化为二进制流并写入文件。 kvstore_log_header(): 写入校验信息，防止文件损坏导致无法识别。 ...

KVStore 运行时状态与访问控制设计文档 1. 文档目的与背景 本文档用于说明 KVstore 在运行时阶段 的整体设计，重点描述： State (状态)：系统当前所处的生命周期阶段 Mode (模式)：系统对外暴露的访问语义 Readonly 协调机制：如何在不破坏一致性的前提下，安全地执行 compaction 等重量级操作 设计的核心目标是： 保证在任意时刻，KVstore 的外部行为与其内部状态严格一直，避免非法写入与状态泄漏 2.设计总览 KVstore 在运行时通过 State + Mode 的组合来约束行为： State 决定“系统当前能不能做事” （生命周期 / 健康状况） Mode 决定“系统对外怎么做事” （访问语义） 二者共同作用于 public API 的合法性检查 readonly / replay /compaction 等特殊阶段的访问控制 State 设计 3.1 State 枚举定义 123456789typedef enum { KVSTORE_STATE_INIT, // 尚未开始恢复 ...

KVStore v3 – 功能总览与执行流程梳理 版本定位： 单机、单线程、WAL + B+Tree + Snapshot 的 KV 存引擎 功能 0：系统初始化与冷启动恢复 功能描述 启动时恢复已有数据 尽量减少 WAL replay 的成本 流程 创建 kvstore 实例 初始化 B+ 树（空） 尝试加载 snapshot (如果存在) 打开 WAL 日志文件 replay WAL 中 snapshot 之后的增量日志 进入 NORMAL 模式，提供对外服务 函数调用链（关键路径） 12345678910kvstore_open() ├── bptree_create() ├── kvstore_load_snapshot() │ └── kvstore_apply_put_internal() ├── fopen(data.log) ├── kvstore_replay_log() │ ├── kvstore_crc_check() │ ├── kvstore_apply_put_internal() │ └── kvstore...

一.总览级架构分层图 12345678910111213141516171819┌────────────────────────────────────┐│ Public API Layer（对外接口层） ││ 参数校验 / 模式判断 / WAL / 调度 │└───────────────▲────────────────────┘ │┌───────────────┴────────────────────┐│ Apply Layer（应用层 / 状态变更层） ││ 只负责：把操作应用到内存状态 │└───────────────▲────────────────────┘ │┌───────────────┴────────────────────┐│ Storage Engine（存储引擎层） ││ B+Tree 的插入 / 删除 / 遍历 │└───────────────▲────────────────────┘ │┌────...