fix outdated doc

Author: haochengxia

.gitignore

@@ -233,4 +233,5 @@ sftp-config.json
 CMakeFiles/*
 *.pyc
 !scripts/smart_build.py
-uv.lock
+uv.lock
+.claude/

docs/src/en/api.md

@@ -40,8 +40,9 @@ Request(
 
 ### `CacheObject`
 
-Returned by `Cache.find`, `insert`, `evict`, and `to_evict`. Exposes read-only `obj_id` and
-`obj_size`.
+Returned by `Cache.find`, `insert`, and `to_evict`. Exposes read-only `obj_id` and
+`obj_size`. Note that `evict` returns `None` — it delegates to the cache's `void` eviction
+callback, so use `to_evict` if you need to inspect the victim before it is removed.
 
 ## Enumerations
 
@@ -210,7 +211,7 @@ PluginCache(
 ```
 
 Hook signatures are documented in [Plugin System](examples/plugins.md#plugincache).
-`set_hooks(...)` replaces the hooks on an existing instance.
+Hooks are fixed at construction time; build a new `PluginCache` to change them.
 
 ## Admission policies
 
@@ -320,7 +321,10 @@ create_uniform_requests(num_objects, num_requests, obj_size=4000,
                         time_span=604800, start_obj_id=0, seed=None) -> Iterator[Request]
 ```
 
-Both return an **iterator**, not a list; wrap in `list(...)` if you need to replay them twice.
+Both return a **re-iterable** generator object, not a list: each `for` loop over it starts a
+fresh pass, and with a fixed `seed` every pass yields the same sequence. There is no need to
+wrap them in `list(...)` to replay them, and for large workloads you should not — that
+materialises every `Request` at once.
 
 ## `TraceAnalyzer`
 

docs/src/en/examples/analysis.md

@@ -36,8 +36,32 @@ The constructor arguments are:
 !!! important
     The analyzer runs entirely in the C++ backend, so it only accepts a C-backed reader — in
     practice, [`TraceReader`](reader.md). Passing a `SyntheticReader` raises
-    `ReaderException: Only C/C++ reader is supported`. To analyse a synthetic workload, write it
-    out first with `Util.convert_to_oracleGeneral` and reopen it with `TraceReader`.
+    `ReaderException: Only C/C++ reader is supported`. `Util.convert_to_oracleGeneral` cannot
+    bridge the gap either — it takes a native reader, so handing it a `SyntheticReader` raises
+    `TypeError`. To analyse a synthetic workload, write its requests out as a trace file and
+    reopen that with `TraceReader`:
+
+    ```py
+    import libcachesim as lcs
+
+    synthetic = lcs.SyntheticReader(num_of_req=10000, obj_size=100, dist="zipf",
+                                    alpha=1.0, num_objects=1000, seed=42)
+
+    with open("synthetic.csv", "w") as f:
+        for req in synthetic:
+            if not req.valid:
+                break
+            f.write(f"{req.clock_time},{req.obj_id},{req.obj_size}\n")
+
+    init_params = lcs.ReaderInitParam(has_header=False, delimiter=",", obj_id_is_num=True)
+    init_params.time_field = 1
+    init_params.obj_id_field = 2
+    init_params.obj_size_field = 3
+
+    reader = lcs.TraceReader("synthetic.csv", lcs.TraceType.CSV_TRACE, init_params)
+    analyzer = lcs.TraceAnalyzer(reader, "synthetic_analysis")
+    analyzer.run()
+    ```
 
 ## Selecting analyses
 

docs/src/en/getting_started/installation.md

@@ -60,16 +60,26 @@ bash scripts/install_deps.sh
 bash scripts/install_deps_user.sh
 ```
 
-Then reinstall, passing the options through `CMAKE_ARGS`. Add `--no-cache-dir` to force a
-rebuild rather than reusing a cached wheel:
+Then reinstall, passing the options through `CMAKE_ARGS`. The flags only take effect during a
+*source* build, so the install has to be forced to run one: `--no-cache-dir` on its own is not
+enough, because pip may report `Requirement already satisfied` or install a prebuilt wheel, and
+in either case `CMAKE_ARGS` is silently ignored. Build from the checkout instead:
 
 ```bash
 # Enable one algorithm
-CMAKE_ARGS="-DENABLE_LRB=ON" pip install libcachesim --no-cache-dir
+CMAKE_ARGS="-DENABLE_LRB=ON" pip install --force-reinstall .
 
 # Or enable all three
 CMAKE_ARGS="-DENABLE_LRB=ON -DENABLE_3L_CACHE=ON -DENABLE_GLCACHE=ON" \
-    pip install libcachesim --no-cache-dir
+    pip install --force-reinstall .
+```
+
+To build from PyPI rather than a checkout, also disable wheels so that a source build actually
+happens:
+
+```bash
+CMAKE_ARGS="-DENABLE_LRB=ON" \
+    pip install --force-reinstall --no-binary libcachesim libcachesim
 ```
 
 !!! important
@@ -101,10 +111,27 @@ bash scripts/install.sh
 bash scripts/install.sh --all
 ```
 
-Building the extension requires a C++17 compiler, CMake ≥ 3.15, and Ninja. The build is driven
-by [scikit-build-core](https://scikit-build-core.readthedocs.io/), which configures and builds
-the bundled C library before compiling the [pybind11](https://pybind11.readthedocs.io/)
-bindings.
+Building the extension requires a C++17 compiler, CMake ≥ 3.15, and Ninja, plus three native
+dependencies that CMake looks for at configure time: **pkg-config**, **GLib 2.0** and
+**Zstandard**. All three are mandatory — `CMakeLists.txt` declares them with
+`find_package(PkgConfig REQUIRED)`, `pkg_check_modules(GLib REQUIRED glib-2.0)` and
+`find_package(ZSTD REQUIRED)` — and a missing one aborts configuration before any code is
+compiled, with an error such as `No package 'glib-2.0' found`.
+
+The dependency scripts above install them on the platforms they cover (`install_deps.sh` targets
+yum-based distributions and macOS). On Debian/Ubuntu, use the submodule's script or install them
+directly:
+
+```bash
+bash src/libCacheSim/scripts/install_dependency.sh
+
+# or, the minimum needed to configure the build
+sudo apt install -y pkg-config libglib2.0-dev libzstd-dev
+```
+
+The build itself is driven by [scikit-build-core](https://scikit-build-core.readthedocs.io/),
+which configures and builds the bundled C library before compiling the
+[pybind11](https://pybind11.readthedocs.io/) bindings.
 
 ## Troubleshooting
 

docs/src/zh/api.md

@@ -38,7 +38,7 @@ Request(
 
 ### `CacheObject`
 
-由 `Cache.find`、`insert`、`evict` 和 `to_evict` 返回，暴露只读的 `obj_id` 和 `obj_size`。
+由 `Cache.find`、`insert` 和 `to_evict` 返回，暴露只读的 `obj_id` 和 `obj_size`。注意 `evict` 返回的是 `None`——它转发到缓存的 `void` 淘汰回调；若需要在对象被移除前查看淘汰候选，请使用 `to_evict`。
 
 ## 枚举类型
 
@@ -192,7 +192,7 @@ PluginCache(
 )
 ```
 
-各 hook 的签名见[插件系统](examples/plugins.md#plugincache)。`set_hooks(...)` 可以替换已有实例上的 hook。
+各 hook 的签名见[插件系统](examples/plugins.md#plugincache)。hook 在构造时固定，如需更换请新建一个 `PluginCache`。
 
 ## 准入策略
 
@@ -289,7 +289,7 @@ create_uniform_requests(num_objects, num_requests, obj_size=4000,
                         time_span=604800, start_obj_id=0, seed=None) -> Iterator[Request]
 ```
 
-两者返回的都是**迭代器**而非列表；如果需要重复回放，请用 `list(...)` 包一层。
+两者返回的都是**可重复迭代**的生成器对象而非列表：每次 `for` 循环都会重新开始一轮，且在固定 `seed` 下每轮产生的序列完全相同。因此无需用 `list(...)` 包一层来重复回放；对于大规模负载更不应这样做，否则会一次性把所有 `Request` materialize 到内存中。
 
 ## `TraceAnalyzer`
 

docs/src/zh/examples/analysis.md

@@ -30,7 +30,29 @@ analyzer.run()
 - `analysis_param: AnalysisParam`（可选）——这些分析的调节参数。默认为 `AnalysisParam()`。
 
 !!! important
-    分析器完全运行在 C++ 后端，因此只接受由 C 实现的 reader——实际上就是 [`TraceReader`](reader.md)。传入 `SyntheticReader` 会抛出 `ReaderException: Only C/C++ reader is supported`。若要分析合成负载，请先用 `Util.convert_to_oracleGeneral` 将其写出，再用 `TraceReader` 重新打开。
+    分析器完全运行在 C++ 后端，因此只接受由 C 实现的 reader——实际上就是 [`TraceReader`](reader.md)。传入 `SyntheticReader` 会抛出 `ReaderException: Only C/C++ reader is supported`。`Util.convert_to_oracleGeneral` 也无法作为桥梁——它接受的是原生 reader，传入 `SyntheticReader` 会抛出 `TypeError`。若要分析合成负载，请先把它的请求写成 trace 文件，再用 `TraceReader` 打开：
+
+    ```py
+    import libcachesim as lcs
+
+    synthetic = lcs.SyntheticReader(num_of_req=10000, obj_size=100, dist="zipf",
+                                    alpha=1.0, num_objects=1000, seed=42)
+
+    with open("synthetic.csv", "w") as f:
+        for req in synthetic:
+            if not req.valid:
+                break
+            f.write(f"{req.clock_time},{req.obj_id},{req.obj_size}\n")
+
+    init_params = lcs.ReaderInitParam(has_header=False, delimiter=",", obj_id_is_num=True)
+    init_params.time_field = 1
+    init_params.obj_id_field = 2
+    init_params.obj_size_field = 3
+
+    reader = lcs.TraceReader("synthetic.csv", lcs.TraceType.CSV_TRACE, init_params)
+    analyzer = lcs.TraceAnalyzer(reader, "synthetic_analysis")
+    analyzer.run()
+    ```
 
 ## 选择分析项 {#selecting-analyses}
 

docs/src/zh/getting_started/installation.md

@@ -56,15 +56,22 @@ bash scripts/install_deps.sh
 bash scripts/install_deps_user.sh
 ```
 
-然后通过 `CMAKE_ARGS` 传入选项重新安装。加上 `--no-cache-dir` 可以强制重新构建，而不是复用缓存的 wheel：
+然后通过 `CMAKE_ARGS` 传入选项重新安装。这些选项只在**源码构建**时生效，因此必须强制走源码构建：仅加 `--no-cache-dir` 是不够的，pip 仍可能提示 `Requirement already satisfied` 或直接安装预编译 wheel，这两种情况下 `CMAKE_ARGS` 都会被静默忽略。请改为从当前 checkout 构建：
 
 ```bash
 # 启用单个算法
-CMAKE_ARGS="-DENABLE_LRB=ON" pip install libcachesim --no-cache-dir
+CMAKE_ARGS="-DENABLE_LRB=ON" pip install --force-reinstall .
 
 # 或者三个全部启用
 CMAKE_ARGS="-DENABLE_LRB=ON -DENABLE_3L_CACHE=ON -DENABLE_GLCACHE=ON" \
-    pip install libcachesim --no-cache-dir
+    pip install --force-reinstall .
+```
+
+若要从 PyPI 而不是 checkout 构建，还需要禁用 wheel，确保真正执行源码构建：
+
+```bash
+CMAKE_ARGS="-DENABLE_LRB=ON" \
+    pip install --force-reinstall --no-binary libcachesim libcachesim
 ```
 
 !!! important
@@ -90,7 +97,18 @@ bash scripts/install.sh
 bash scripts/install.sh --all
 ```
 
-构建扩展需要支持 C++17 的编译器、CMake ≥ 3.15 以及 Ninja。构建过程由 [scikit-build-core](https://scikit-build-core.readthedocs.io/) 驱动，它会先配置并构建内置的 C 库，再编译 [pybind11](https://pybind11.readthedocs.io/) 绑定。
+构建扩展需要支持 C++17 的编译器、CMake ≥ 3.15 以及 Ninja，另外还需要三个在 configure 阶段查找的原生依赖：**pkg-config**、**GLib 2.0** 和 **Zstandard**。这三者都是必需的——`CMakeLists.txt` 中分别以 `find_package(PkgConfig REQUIRED)`、`pkg_check_modules(GLib REQUIRED glib-2.0)` 和 `find_package(ZSTD REQUIRED)` 声明——缺少任意一个都会在编译任何代码之前中断配置，并报出类似 `No package 'glib-2.0' found` 的错误。
+
+上文的依赖脚本会在其支持的平台上安装它们（`install_deps.sh` 面向基于 yum 的发行版和 macOS）。在 Debian/Ubuntu 上，请使用子模块提供的脚本，或直接安装：
+
+```bash
+bash src/libCacheSim/scripts/install_dependency.sh
+
+# 或者只装配置构建所需的最小集合
+sudo apt install -y pkg-config libglib2.0-dev libzstd-dev
+```
+
+构建本身由 [scikit-build-core](https://scikit-build-core.readthedocs.io/) 驱动，它会先配置并构建内置的 C 库，再编译 [pybind11](https://pybind11.readthedocs.io/) 绑定。
 
 ## 疑难排查
 

libcachesim/__init__.py

@@ -4,6 +4,7 @@
 
 from .libcachesim_python import (
     Cache,
+    CacheObject,
     Request,
     ReqOp,
     ReaderInitParam,
@@ -77,6 +78,7 @@
 __all__ = [
     # Core classes
     "Cache",
+    "CacheObject",
     "Request",
     "ReqOp",
     "ReaderInitParam",

libcachesim/__init__.pyi

@@ -2,7 +2,7 @@ from __future__ import annotations
 from typing import Optional, Callable, Any
 from collections.abc import Iterator
 
-from .libcachesim_python import ReqOp, TraceType, SamplerType
+from .libcachesim_python import Reader, ReqOp, TraceType, SamplerType
 from .protocols import ReaderProtocol
 
 class Request:
@@ -131,7 +131,7 @@ class Cache:
     def can_insert(self, req: Request) -> bool: ...
     def insert(self, req: Request) -> CacheObject: ...
     def need_eviction(self, req: Request) -> bool: ...
-    def evict(self, req: Request) -> CacheObject: ...
+    def evict(self, req: Request) -> None: ...
     def remove(self, obj_id: int) -> bool: ...
     def to_evict(self, req: Request) -> CacheObject: ...
     def get_occupied_byte(self) -> int: ...
@@ -146,7 +146,7 @@ class CacheBase:
     def can_insert(self, req: Request) -> bool: ...
     def insert(self, req: Request) -> CacheObject: ...
     def need_eviction(self, req: Request) -> bool: ...
-    def evict(self, req: Request) -> CacheObject: ...
+    def evict(self, req: Request) -> None: ...
     def remove(self, obj_id: int) -> bool: ...
     def to_evict(self, req: Request) -> CacheObject: ...
     def get_occupied_byte(self) -> int: ...
@@ -334,14 +334,13 @@ class PluginCache(CacheBase):
         admissioner: Optional["AdmissionerBase"] = None,
         reader: Optional[ReaderProtocol] = None,
     ): ...
-    def set_hooks(self, init_hook, hit_hook, miss_hook, eviction_hook, remove_hook, free_hook=None): ...
 
 # Readers
 class TraceReader(ReaderProtocol):
     c_reader: bool
     def __init__(
         self,
-        trace: str,
+        trace: Reader | str,
         trace_type: TraceType = TraceType.UNKNOWN_TRACE,
         reader_init_params: Optional[ReaderInitParam] = None,
     ): ...

libcachesim/cache.py

@@ -77,7 +77,9 @@ def insert(self, req: Request) -> CacheObject:
     def need_eviction(self, req: Request) -> bool:
         return self._cache.need_eviction(req)
 
-    def evict(self, req: Request) -> CacheObject:
+    def evict(self, req: Request) -> None:
+        # The C eviction callback returns void, so this is always None; use
+        # to_evict() to inspect the victim before it is removed.
         return self._cache.evict(req)
 
     def remove(self, obj_id: int) -> bool: