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. Length alignment. The transfer length must be a multiple of the filesystem's block size. With use_odirect: true the adapter automatically transfers each object's full alignment-padded L1 slot (logical bytes plus padding up to --l1-align-bytes), so this requirement holds even when KV chunk byte sizes are not multiples of the block size; on-disk files are correspondingly padded, and loads must run with the same use_odirect and --l1-align-bytes settings as the stores. Raise --l1-align-bytes to match the block size on filesystems with large blocks (GPFS and similar parallel filesystems often use several 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}'