这是一个基于 C++17 的零依赖简单内存键值缓存项目 包含:
- 有界的 LRU 缓存淘汰机制
- local cli | remote cli | server | client 包装
- 网络服务/客户端封装
- 服务端 AOF 缓存文件回放重建
cmake -B build
cmake --build build产物:
KVCache-LocalCli本地cliKVCache-RemoteCli远程cliKVCache-Client客户端KVCache-Server服务端kv_tests测试
ctest --test-dir build --output-on-failure./build/KVCache-LocalCli put name "hello world"
./build/KVCache-LocalCli get name
printf 'put a 1\nput b 2\nget a\nlst\n' | ./build/KVCache-LocalCli- 参数:
KVCache-LocalCli <command> [args...] - 无 argv 时进入 stdin 会话:先打印命令列表,逐行执行,空行跳过;C-D EOF 退出
- 本地固定
kv.aof、fsyncalways;会话默认容量 64
printf 'put a 1\nget a\n' | ./build/KVCache-RemoteCli --port 7379- 参数:
KVCache-RemoteCli [--host <ip>] [--port <n>] - 命令从 stdin 逐行读取;非 tty 时整批发送再统一收响应
./build/KVCache-Client --port 7379 get a- 参数:
KVCache-Client [--host <ip>] [--port <n>] <command> [args...]
库接口(client.hpp):
#include "kv/client.hpp"
kv::Client client;
client.connect("127.0.0.1", 7379);
std::string payload;
client.request(kv::cmd_put("k", "v"), payload);
client.request(kv::cmd_get("k"), payload);
// 批量(流水线): 发送不等待, 再按条数收
client.send_batch({kv::cmd_put("a", "1"), kv::cmd_put("b", "2")});
std::vector<std::string> out;
client.recv_batch(2, out);connect/close/is_open;send/recv原语;send_batch/recv_batch流水线;request/request_batch发+收- 命令工厂:
cmd_put/cmd_get/cmd_del/cmd_clr/cmd_lst/cmd_help - 链接
kvcache_net;单线程、阻塞式、非线程安全
./build/KVCache-Server --port 7379 --capacity 64 --aof kv.aof --fsync always- 参数:
KVCache-Server --port <n> [--bind <ip>] [--capacity <n>] [--aof <path>] [--fsync always|group|os] [--fsync-interval <ms>]--bind默认127.0.0.1;绑0.0.0.0会暴露到网络且无认证,谨慎使用--capacity默认 64;--aof默认kv.aof--fsync-interval仅group模式生效,默认 1ms
库接口(server.hpp):
struct ServerConfig { /* bind / port / capacity / aof_path / fsync / fsync_interval_ms */ };
class Server {
explicit Server(ServerConfig config);
bool run();
};| 命令 | 说明 |
|---|---|
put k v |
新增或覆盖;满员时淘汰最久未用 |
get k |
读取并刷新 recency;存在输出 k->v,否则 'k' not found |
del k |
删除(立即释放内存) |
clr |
清空 |
lst |
按键名列出全部 kv |
CLI 输入按空白分词,单/双引号内可含空格/逗号,\ 转义;网络调用参数原样传递。
命令表是单一真相源:regcmd.cpp 的 CommandSpec[] 由 commands() 暴露,加/改命令只改命令表 + handler。
布局(数组式侵入链,下标代替指针,-1 为空):
struct Slot {
std::string key; // 键
std::string value; // 值
int prev; // 前驱下标
int next; // 后继下标
};cache: vector<Slot>:固定容量槽catalog: unordered_map<string,int>:键 -> 槽下标frstk: vector<int>:空闲槽栈,删除/淘汰后回收槽head_:MRU 端;tail_:LRU 端
语义:get 命中 / put 已存在键 -> 摘下挂到 head_;put 新键无空闲槽 -> 淘汰 tail_ 槽再复用。删除与淘汰都同步删 catalog。
请求帧: [1B ver=1][4B body_len][body]
body = [1B cmdargs][1B cmd_len][cmd][arg_i: 4B len + bytes] * cmdargs
响应帧: [1B ver=1][4B body_len][body]
body = 结果文本字节 (长度 0 = 无输出)
- 参数原样字节、无转义、空值可表达;
cmdargs为命令参数个数(不含命令名) body_len ≤ 1MB;cmd_len == 0非法;版本不匹配则关闭连接
由
kv::Journal管理
- 模块边界:
Engine只持有Journal*;文件 IO、记录编解码、回放都在独立Journal模块 - 记录格式:
[1B op][4B klen][key][4B vlen][value],长度前缀,值可含任意字节 - 写路径:
put/del/clr先append再改内存;append 失败则不修改内存,保证日志与内存一致 - 回放:启动时逐条读取并回调重建缓存;写驱动语义,LRU 只按写序重建
- 坏尾:末尾不完整记录自动截断恢复
- fsync 策略:
always每次追加立即落盘group合并一批写:dirty标记 +last_fsync时间 + 写计数,超过--fsync-interval统一 fsync,响应按pending_sync放行os交给系统回写- fsync 失败:关闭待落盘连接,不返回假 ACK
include/kv/
engine.hpp kv::Engine:有界 LRU 缓存
cli.hpp tokenize/parse/CommandSpec/commands() 命令表视图
regcmd.hpp kv::exec(…, out):查表执行入口
journal.hpp 持久化:操作日志读写与回放
net.hpp 帧编解码与 socket 原语
client.hpp kv::Client 客户端库
server.hpp kv::Server 网络服务
src/kv/
engine.cpp 槽位池 + 侵入链 LRU
cli.cpp 分词/解析
regcmd.cpp 命令 handler、命令表、分发
journal.cpp 日志编解码 + 文件 IO + 坏尾截断
net.cpp 帧编解码
client.cpp Client 实现
server.cpp Server 事件循环
example/
local_cli_main.cpp 本地 CLI
remote_cli_main.cpp 网络 CLI
client_main.cpp 客户端库示例
server_main.cpp 服务端入口
tests/
test_engine.cpp LRU 语义
test_cli.cpp tokenize/parse/exec
test_journal.cpp 日志/坏尾/引擎钩子
test_net.cpp 帧编解码
test_client.cpp 客户端与假服务端集成