FS（原生）#

一个由原生 C++ LMCacheFSClient 支持的文件系统 L2 适配器，封装在 NativeConnectorL2Adapter 中。I/O 通过一个 C++ 工作线程池进行调度，使用 eventfd 驱动的完成机制，在单个 Python 线程上提供真实的 I/O 队列深度。

必填字段：

  • base_path: 存储 KV Cache 文件的目录。

可选字段：

  • num_workers（int，默认值 4，> 0）：连接器内部的 C++ 工作线程数量。这是真正的 I/O 队列深度——提高此值以在总带宽超过每个流带宽的文件系统上提升吞吐量。

  • relative_tmp_dir（str，默认值 ""）：写入临时文件所使用的相对子目录，写入完成后执行原子重命名。

  • use_odirect（bool，默认值 false）：通过 O_DIRECT 绕过页面缓存，启用后方可测量真实的磁盘带宽。请参阅下方的对齐注意事项。

  • read_ahead_size（int，可选）：打开文件时预读指定字节数以触发文件系统的预读机制。

  • max_capacity_gb（float，默认值 0）：用于客户端使用量跟踪的最大 L2 容量（单位：GB）。默认值 0 表示禁用跟踪。

重要

O_DIRECT 有两个独立的对齐要求：

  1. 长度对齐。 传输长度必须是文件系统块大小的倍数。连接器在构造时查询磁盘块大小，并在每次操作时检查 len % disk_block_size。如果长度 不是 倍数，连接器会默默回退到缓冲打开（不使用 O_DIRECT）进行该操作——正确性得以保留，但您无法获得真正的直接 I/O。为了确保实际使用 O_DIRECT，选择 --chunk-size 使得每块的字节大小是文件系统块大小的倍数。GPFS 和类似的并行文件系统通常使用较大的块（例如几个 MiB）。

  2. 内存缓冲区对齐。 I/O 缓冲区指针本身也必须对齐（本地磁盘通常要求对齐到 4096 字节，并行文件系统则要求对齐到 FS 块大小）。这由 --l1-align-bytes 控制（默认值为 4096）——在块较大的文件系统上运行时，请相应调高此值以匹配 FS 块大小。若缓冲区未对齐，底层 read/write 系统调用将返回 EINVAL（该错误不会被上述长度回退路径捕获，会直接以运行时错误的形式抛出）。

如果不确定，请先使用 use_odirect: false 并确认正确性，然后再启用 O_DIRECT。

配置示例：

# Basic native FS adapter
--l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2"}'

# Many worker threads for a parallel filesystem (e.g. GPFS, Lustre)
--l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2", "num_workers": 32}'

# O_DIRECT for real-disk benchmarking
--l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2", "num_workers": 32, "use_odirect": true}'

仅缓冲区模式示例。 L1 充当纯写缓冲区，吸收待处理数据块的峰值突发，同时 C++ 工作线程池将其排空至磁盘；存储完成后 L1 中不保留任何内容：

lmcache server \
    --host 0.0.0.0 --port 5555 \
    --max-workers 32 \
    --l1-size-gb 32 --l1-use-lazy \
    --eviction-policy noop \
    --l2-store-policy skip_l1 \
    --l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2", "num_workers": 32, "use_odirect": true}'