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, optional): Trigger filesystem readahead by issuing a warm-up read of this many bytes at open time. This is skipped for reads that use O_DIRECT because direct I/O bypasses the page cache.

  • 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. Memory-buffer alignment. The I/O buffer pointer itself must also be aligned (typically to 4096 bytes on local disks, or to the FS block size on parallel filesystems). This is controlled by --l1-align-bytes (default 4096) -- raise it to match the FS block size when running on a filesystem with larger blocks. If the buffer is misaligned, the connector reports a runtime error instead of silently falling back to buffered I/O. This protects real-disk benchmark runs from accidentally measuring the page cache.

如果不确定，请先使用 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}'