LevelDB 移植层（port 目录）解析：port.h 如何隔离平台细节并支撑 Mutex、压缩与 CRC32C

本文以 LevelDB 仓库 port/ 目录为对象，讲清移植层的设计目标与工作机制：包内其余代码统一包含 port/port.h，由它再分派到平台特定的 port_<platform>.h 实现；文中将结合 port_example.h 的接口规范、port_stdcxx.h 的 C++11 标准实现和 CMakeLists.txt 的特性检测流程，说明如何阅读、验证乃至移植一套 LevelDB 移植层。

移植层的定位：把平台细节挡在 port 之外

port/README.md 的核心信息可以概括为三点：

1. 该目录包含“接口与实现”，其职责是把包内其余部分与平台细节隔离开（isolate the rest of the package from platform details）；
2. 包内其他代码统一 #include "port.h"（来自本目录），而 port.h 会转而包含某个平台特定的 port_<platform>.h 文件，由它提供平台相关的具体实现；
3. 编写新的平台头文件时，应参考 port_stdcxx.h 作为“必须提供什么”的示例。

这个“一个入口头文件 + 按平台分派”的模式，意味着 db/、table/、util/ 中的上层代码从不直接引用 POSIX 线程 API 或任何特定压缩库，只依赖 leveldb::port 命名空间下的一组抽象。整个仓库中约有 30 个源文件（如 db/db_impl.cc、util/env_posix.cc、util/cache.cc、table/format.cc 等）直接包含 port/port.h，这正是 README 所述隔离策略的实际规模。

port.h：平台分派的唯一入口

port/port.h 的实现极其精简，全部逻辑就是一个宏分派：

#if defined(LEVELDB_PLATFORM_POSIX) || defined(LEVELDB_PLATFORM_WINDOWS)
#include "port/port_stdcxx.h"
#elif defined(LEVELDB_PLATFORM_CHROMIUM)
#include "port/port_chromium.h"
#endif

三个要点：

• POSIX 与 Windows 共用同一实现。两条平台宏都指向 port/port_stdcxx.h，即当前仓库唯一的真实移植层实现，它只依赖 C++11 标准库；
• 宏由构建系统注入。CMakeLists.txt 中 if (WIN32) 分支将 LEVELDB_PLATFORM_NAME 设为 LEVELDB_PLATFORM_WINDOWS，否则设为 LEVELDB_PLATFORM_POSIX，随后通过 target_compile_definitions 以 =1 的形式加到 leveldb 主库、测试与 benchmark 目标上（见 CMakeLists.txt）；
• 代码里还保留 LEVELDB_PLATFORM_CHROMIUM 分支，指向 port_chromium.h。当前仓库中并不存在该文件，从源码结构看这是为 Chromium 系构建环境预留的分派槽位——这也印证了 README 所说的“port_<platform>.h 是可插拔的”。

port_example.h：一份新平台必须满足的接口契约

README 提到新平台头文件应“按示例提供”。事实上 port/port_example.h 本身就是一份只有声明、没有实现的规格说明书，文件头部注释写明：“This file contains the specification, but not the implementations... of the types/operations/etc. that should be defined by a platform specific port_.h file.” 它定义了 leveldb::port 命名空间下共三大类、9 个必须提供的接口：

线程原语

• class Mutex：互斥锁，提供 Lock()、Unlock()、AssertHeld()。规范明确 Lock() 若对本线程已持有的锁重复加锁会死锁；AssertHeld() 实现必须快速（NDEBUG 下允许跳过所有检查）。三个方法分别标注 EXCLUSIVE_LOCK_FUNCTION()、UNLOCK_FUNCTION()、ASSERT_EXCLUSIVE_LOCK() 线程安全注解；
• class CondVar：条件变量，构造时绑定一把 Mutex*，提供 Wait()（原子地释放该锁并阻塞，直到 SignalAll() 或选中本线程的 Signal()）、Signal()（唤醒至少一个等待线程）、SignalAll()（唤醒全部）。Wait() 要求调用线程持有 *mu。

压缩接口（Snappy 与 Zstd 两套）

• bool Snappy_Compress(const char* input, size_t input_length, std::string* output)：把输入段的 snappy 压缩结果存入 *output，若本移植层不支持 snappy 则返回 false；
• bool Snappy_GetUncompressedLength(const char* input, size_t length, size_t* result)：输入像合法 snappy 压缩缓冲时，把解压后大小写入 *result 并返回 true，否则 false；
• bool Snappy_Uncompress(const char* input_data, size_t input_length, char* output)：解压到 *output，失败（输入非合法 snappy 数据）返回 false。规范要求 output 前 n 字节可写，n 为 Snappy_GetUncompressedLength 的成功返回值；
• Zstd_Compress(int level, ...)、Zstd_GetUncompressedLength(...)、Zstd_Uncompress(...) 与 Snappy 三件套语义完全对应，多了压缩级别参数。

杂项

• bool GetHeapProfile(void (*func)(void*, const char*, int), void* arg)：若不支持堆剖析返回 false；否则反复回调 (*func)(arg, data, n)，所有片段拼接即完整堆 profile（benchmarks/db_bench.cc 的 heapprofile 操作正是通过它落盘）；
• uint32_t AcceleratedCRC32C(uint32_t crc, const char* buf, size_t size)：把 buf 前 size 字节扩展进 CRC。规范约定：返回 0 表示“无法用加速方式扩展”，否则返回新的 CRC 值（0 也可能是合法 CRC）。这个“0 = 不可用”的约定是移植层与通用实现之间的回退开关。

文件里还留有一条 TODO(jorlow)：其中部分接口或许更适合放进 Env 类而非 port 层——这条注释提示读者，port 层接口清单并非不可演进的设计定论。

port_stdcxx.h：当前仓库的默认移植层实现

port/port_stdcxx.h 是 POSIX 与 Windows 共用的实现，展示了接口契约如何落到 C++11 标准库之上。

可选特性：port_config.h 的条件包含

文件开头（port_stdcxx.h）用两级机制决定是否包含构建生成的 port/port_config.h：

#if defined(LEVELDB_HAS_PORT_CONFIG_H)
#if LEVELDB_HAS_PORT_CONFIG_H
#include "port/port_config.h"
#elif defined(__has_include)
#if __has_include("port/port_config.h")
#include "port/port_config.h"
#endif
#endif

• 若构建系统定义了 LEVELDB_HAS_PORT_CONFIG_H，以它为准；
• 否则较新的编译器（支持 C++17 的 __has_include）自动探测。

CMakeLists.txt 用 configure_file 把 port/port_config.h.in 渲染到二进制目录的 include/port/port_config.h；当编译环境不具备 C++17 __has_include 能力时，再显式定义 LEVELDB_HAS_PORT_CONFIG_H=1（CMakeLists.txt）。这一套保证了同一份头文件在“CMake 构建”和“手工/旧工具链构建”两种场景下都能取到正确的特性开关。

port_config.h.in 中检测并暴露的宏为：HAVE_FDATASYNC（unistd.h 是否有 fdatasync）、HAVE_FULLFSYNC（fcntl.h 是否有 F_FULLFSYNC，macOS fsync 语义）、HAVE_O_CLOEXEC、HAVE_CRC32C、HAVE_SNAPPY、HAVE_ZSTD。注意前三者服务于 util/env_posix.cc 等文件系统的细节差异，后三者则直接决定 port 层的压缩/CRC 能力开关：

#if HAVE_CRC32C
#include <crc32c/crc32c.h>
#endif
#if HAVE_SNAPPY
#include <snappy.h>
#endif
#if HAVE_ZSTD
#define ZSTD_STATIC_LINKING_ONLY  // For ZSTD_compressionParameters.
#include <zstd.h>
#endif

Mutex 与 CondVar：对 std::mutex / std::condition_variable 的薄封装

class LOCKABLE Mutex {
 public:
  void Lock() EXCLUSIVE_LOCK_FUNCTION() { mu_.lock(); }
  void Unlock() UNLOCK_FUNCTION() { mu_.unlock(); }
  void AssertHeld() ASSERT_EXCLUSIVE_LOCK() {}
 private:
  friend class CondVar;
  std::mutex mu_;
};

（见 port_stdcxx.h）。实现要点：

• 拷贝构造/赋值被 delete，LOCKABLE 注解让它可参与 Clang 线程安全分析；
• AssertHeld() 是空实现——符合 port_example.h 中“允许跳过所有检查”的规范；
• CondVar::Wait()（port_stdcxx.h）用 std::adopt_lock 把 Mutex 私有的 std::mutex mu_ 交给 std::unique_lock，等待后 release() 交出所有权再返回，严格对应规范中“原子地释放 *mu 并阻塞”的语义；Signal()/SignalAll() 即 notify_one/notify_all。

线程安全注解全部来自 port/thread_annotations.h：该头文件在 Clang 下展开为 __attribute__((...)) 线程安全分析注解（LOCKABLE、SCOPED_LOCKABLE、EXCLUSIVE_LOCK_FUNCTION、GUARDED_BY 等共 20 余个宏），非 Clang 环境下降为 no-op 空宏。这解释了为什么 port 层类定义上会“凭空”出现这些宏——它们不改变运行期行为，只服务于静态检证。

压缩与 CRC：能力探测式实现

port_stdcxx.h 中每个压缩函数都有相同的模式：#if HAVE_SNAPPY / #if HAVE_ZSTD 内调用真实库，否则丢弃参数并 return false。例如 Snappy_Compress 会先按 snappy::MaxCompressedLength(length) 预分配输出再 RawCompress；Zstd_Compress 则通过 ZSTD_getCParams(level, std::max(length, size_t{1}), 0) 依据传入级别与实际数据长度确定压缩参数。GetHeapProfile 一律返回 false（标准实现不提供堆剖析）；AcceleratedCRC32C 在 HAVE_CRC32C 下调用 crc32c::Extend，否则按契约返回 0。

上层消费端：这些接口被谁用

port 层接口不是摆设，仓库内消费路径清晰可查：

• 块压缩：table/table_builder.cc 在写 block 时先尝试 port::Snappy_Compress（成功后再校验压缩率），失败才试 port::Zstd_Compress(r->options.zstd_compression_level, ...)；读取侧 table/format.cc 用 Snappy_GetUncompressedLength/Snappy_Uncompress 与 Zstd_* 对应解码——压缩类型的选择与回退完全经由 port 层完成；
• RAII 锁：util/mutexlock.h 定义了 MutexLock，构造即 Lock()、析构即 Unlock()，并标注 EXCLUSIVE_LOCK_FUNCTION(mu)/UNLOCK_FUNCTION()。db_impl、cache、env_posix 等模块普遍以 MutexLock l(&mu_) 管理临界区，锁的底层实现差异被这一行头文件包含彻底吸收；
• CRC 回退：util/crc32c.cc 先用 port::AcceleratedCRC32C(0, ...) 探测加速实现是否可用（返回 0 即不可用），可用则持续走硬件/CRC 库加速路径，否则回退到内置查表实现。

移植到新平台：从 README 出发的操作清单

综合 port/README.md 的指引与源码结构，为新平台（假设宏名 LEVELDB_PLATFORM_FOO）编写移植层的最小步骤是：

1. 新建 port/port_foo.h，以 port_example.h 为规格，在 leveldb::port 命名空间下实现 Mutex、CondVar、Snappy/Zstd 六个压缩函数、GetHeapProfile、AcceleratedCRC32C——任何无法支持的能力按契约返回 false 或 0 即可，无需硬凑；
2. 修改 port/port.h 的分派宏，增加 #elif defined(LEVELDB_PLATFORM_FOO) #include "port/port_foo.h" 分支；
3. 构建时定义平台宏（CMake 下等价于向 target_compile_definitions 追加 LEVELDB_PLATFORM_FOO=1），并确保该平台需要的特性开关（如 HAVE_O_CLOEXEC）经由 port_config.h.in 一类的机制注入；
4. 注意锁语义与线程注解：Mutex/CondVar 需带 port/thread_annotations.h 的注解以保留静态检查能力，且 CondVar::Wait 必须满足“持有 *mu 时原子放锁阻塞”的约束。

小结

port/README.md 虽然只有寥寥数行，却给出了理解 LevelDB 跨平台架构的钥匙：port.h 是唯一入口，port_<platform>.h 是可替换实现，port_example.h 是接口契约，port_stdcxx.h 是参照实现。当前仓库中 POSIX 与 Windows 均落在 port_stdcxx.h 的 C++11 标准库实现上，压缩、CRC、堆剖析等可选能力由 port_config.h（由 port_config.h.in 经 CMake 生成）统一开关；上层代码则通过 util/mutexlock.h、table/format.cc、util/crc32c.cc 等路径无感消费这套抽象。掌握了这四份头文件的分工，阅读或扩展 LevelDB 的任何平台相关改动都会变得直接而可控。