mmap 不适合直接做 KV 存储主存结构，因其仅提供内存映射，不支持索引、序列化、指针持久化及跨进程一致性；需自行设计固定布局的哈希索引（如桶数组+偏移量）、序列化存储与原子更新，并配合文件锁、msync 和正确 mmap 流程保障可靠性。
为什么 mmap 不适合直接做 Key-Value 存储的主存结构
mmap 本身只是把文件（或匿名内存）映射成进程地址空间的一段可读写区域，它不提供索引、哈希、冲突处理或序列化能力。直接在 mmap 区域上手写 std::map 或 std::unordered_map 会崩溃——因为这些容器内部指针指向的是堆内存，而 mmap 区域重启后地址可能变化，且 STL 容器对象无法跨进程/重启持久化。
真正能用 mmap 加速 KV 的地方，是「数据页存储层」：即把序列化的 key-value 对连续写入 mmap 文件，并用独立的、固定布局的元数据结构（比如哈希桶数组 + 偏移量索引）来管理它们。
- 必须自己实现序列化（如
memcpy固定长度 key+value 到 mmap 区），不能依赖std::string或指针字段 - 所有偏移量（offset）必须用
uint64_t等固定宽度整型，不能用裸指针 - 哈希表头、B+ 树节点等元数据需放在 mmap 起始处，且结构体必须
#pragma pack(1)避免对齐差异 - 写操作需配合
msync(MS_SYNC)和fdatasync()保证落盘，否则断电=丢数据
如何设计一个可 mmap 的哈希索引结构
核心思路：把哈希桶数组和数据区分离，桶中只存 uint64_t data_offset，数据区紧随其后线性存放序列化记录。这样整个结构可完整映射，且支持 mremap 扩容（但需重算哈希并迁移）。
示例头部结构：
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
立即学习“C++免费学习笔记（深入）”；
#pragma pack(1)
struct MMapKVHeader {
uint64_t magic; // 如 0x4B564D415021 用于校验
uint64_t bucket_count; // 哈希桶数量（必须是 2 的幂）
uint64_t data_size; // 当前已用数据区字节数
uint64_t max_size; // 文件总大小（含 header）
};
- 哈希函数必须确定性且与平台无关，推荐
xxh3_64bits（需静态链接或自包含实现），避免std::hash - 桶数组紧跟 header，每个桶是
uint64_t，值为 0 表示空，否则指向 data 区起始偏移 - data 区每条记录格式：
uint32_t key_len+key_bytes+uint32_t val_len+val_bytes，无 padding - 插入时需原子更新 bucket 和 data_size：用
__atomic_fetch_add或std::atomic_ref（C++20）
open/mmap/ftruncate 的正确调用顺序和错误检查
常见错误是先 mmap 再 ftruncate，导致映射区尾部不可写；或者忽略 MAP_SHARED 导致修改不落盘。
- 必须先
open(..., O_RDWR | O_CREAT)，再ftruncate(fd, size)扩大文件，最后mmap(..., PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0) -
mmap返回MAP_FAILED时，要检查errno：常见ENOMEM（虚拟内存不足）、EINVAL（size 为 0 或 offset 未对齐） - 扩容时不能直接
mremap：Linux 下mremap要求原映射是MAP_ANONYMOUS或文件映射且文件已ftruncate，且新大小不能超过文件大小 - 务必在
munmap前调用msync(addr, len, MS_SYNC)，否则脏页可能延迟写入甚至丢失
多进程并发读写时的锁与一致性陷阱
mmap 本身不提供同步机制。多个进程同时写同一个文件映射，会导致数据错乱，即使用了原子操作，也解决不了哈希桶重哈希期间的数据迁移一致性问题。
- 推荐用
fcntl文件锁（F_WRLCK）控制写操作临界区，粒度到整个文件或按哈希段分片（如 bucket_range_lock） - 读操作可无锁，但必须确保读到的
data_offset非零后再访问 data 区，且检查该 offset 是否（防止读到未提交的脏数据） - 不要用
pthread_mutex_t存在 mmap 区里：它依赖内核 futex，跨进程需设置PTHREAD_PROCESS_SHARED，且初始化复杂；更稳妥是用sem_t（命名信号量）或file locking - 删除操作不是清零 offset，而是置为特殊标记（如
UINT64_MAX），并在后台 compact 阶段回收空间——否则并发读可能读到“已删但未覆盖”的旧值
真正的难点不在 mmap 映射，而在如何让哈希表在扩容、删除、多进程视角下保持逻辑一致。哪怕最简单的线性探测哈希，也要处理好“写一半被中断”这种场景——所以生产级实现几乎都引入 WAL（预写日志）或 copy-on-write 页管理。纯 mmap KV 只适合只读为主、写入低频、且能接受单点故障的嵌入式场景。
