Repository navigation
[Docs] complete documentations - #2
haochengxia wants to merge 5 commits into
Conversation
|
@codex review |
![chatgpt-codex-connector[bot]](/s/com/githubusercontent/avatars/G.https/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
π‘ Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a60050eddf
βΉοΈ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with π.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
π‘ Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 62c3a20e91
βΉοΈ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with π.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Four English pages were `[TBD]` placeholders and `examples/simulation.md` carried 19 more `[TBD]` sections. Fill them in, verified against the wrapper source rather than assumed: - `getting_started/installation.md`: requirements, PyPI install, the three optional ML-backed algorithms and their CMake flags, source builds. - `examples/analysis.md`: all 11 `AnalysisOption` fields and 5 `AnalysisParam` fields with real defaults, output files, and the C-reader-only restriction. - `api.md`: hand-written reference for the full exported surface, including the actual enum members (`ReqOp` is `OP_*`, not `READ`/`WRITE`). - `developer.md`: layout, build system, testing, adding an algorithm, docs workflow, CI, releasing. - `examples/simulation.md`: real parameters and defaults for every algorithm, plus the missing `Size` section, the `cache_size`-as-ratio behaviour, and a `CacheBase` method table. Corrections to existing content: Python floor is 3.10 (not 3.9) per `requires-python`; `int_freq` -> `init_freq`; a quickstart snippet used an undefined `lcs`; the FAQ used an absolute URL that broke under locale fallback. Two lists rendered as literal `*` characters because they lacked a preceding blank line. The Chinese tree was three orphaned files at non-mirroring paths, so they never rendered, and they documented an API that does not exist (`cache.get_hit_ratio()`, `PythonHookCache`, `SyntheticReader(dist=...)`). Delete them and translate all ten pages at paths mirroring `en/`. Link-target headings carry explicit `attr_list` anchor IDs so cross-page anchors resolve identically in both languages. `nav_translations` gains the three labels that were still English, and `Getting Started` becomes "ε ₯ι¨ζε" so it no longer collides with the Quickstart page's own title. `mkdocs build --strict` passes and all 11 anchors are present in the built HTML. Also ignore `docs/site/`, since the existing rule only covered `/site` at the repo root. [Fix] Correct wrong signatures in the type stubs These are the signatures users see in their IDE, and four were wrong: - `TraceAnalyzer.__init__` declared a leading `analyzer` parameter that does not exist and made `analysis_param`/`analysis_option` required. The real signature is `(reader, output_path, analysis_param=None, analysis_option=None)` per `trace_analyzer.py`. - `TraceReader.__init__` declared `**kwargs`; it actually takes `(trace, trace_type=UNKNOWN_TRACE, reader_init_params=None)`, and exposes `c_reader`, which callers rely on to pick the C fast path. - `Request.op` defaulted to `ReqOp.READ`, which is not a member of the enum. `export_cache.cpp` binds the default as `OP_NOP`. - `CacheBase.set_cache_size` was missing. [Feat] Add MQ, LRU-K and Clock2QPlus bindings Bump the libCacheSim submodule to the latest develop (dbf8423..373aee9), which brings three new eviction algorithms, and expose them in Python. New algorithms: - LRUK: evicts by largest backward K-distance (k) - MQ: multi-queue hierarchy with a Qout ghost queue (n_queue, lifetime, qout_size_ratio) - Clock2QPlus: 2Q variant over a Clock main cache (fifo_size_ratio, ghost_size_ratio, move_to_main_threshold, corr_window_ratio) Each is wired through export_cache.cpp, cache.py, __init__.py and the type stubs, covered by the shared parametrized tests, and documented in both the English and Chinese algorithm reference. Two fixes to existing bindings found while checking the docs against the implementation: - BeladySize was unusable: it emitted the key "n-samples" while the C parser only accepts "n-sample", so every construction hit ERROR() and aborted the interpreter. It was absent from every test parametrize list, which is why this went unnoticed. Added regression tests for BeladySize and Belady. - WTinyLFU's window_size was described as a fraction of the main cache. WTinyLFU.c scales the total cache size by it and gives the main cache the remainder, so the docstring and both translations now say total. Also completed the CacheBase type stub, which was missing its admissioner parameter. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> [Fix] Lower macOS deployment target to 11.0 The pin tracked the GitHub runner OS rather than a real requirement (see 77790b4, "As GitHub upgrades its macOS machine to 15.0"). Those are unrelated: the deployment target sets the minimum macOS a wheel supports, so following the runner silently dropped every macOS below it. scikit-build-core gives cmake.define the highest precedence when deriving the wheel's platform tag, so every build produced a macosx_15_0_arm64 wheel. That is incompatible with the macos-14 matrix leg, and with the python-build-standalone interpreters from `uv python install`, which target macOS 11.0 -- so `uv pip install -e .` rejected the wheel it had just built. libCacheSim itself pins no deployment target anywhere and needs only C++17, so 11.0 (the floor for Apple Silicon) is safe. Wheels are now tagged macosx_11_0_arm64 and install on macOS 11+ instead of 15+ only.
b14964f to
c0522ed
Compare
There was a problem hiding this comment.
π‘ Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c0522edc08
βΉοΈ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with π.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
π‘ Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d6e67e7a75
βΉοΈ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with π.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
π‘ Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f094f395ea
βΉοΈ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with π.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
π‘ Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4fd9d57fb0
βΉοΈ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with π.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| `scripts/install_deps.sh` installs them on Debian/Ubuntu, CentOS/RHEL and macOS, picking the | ||
| package manager to use automatically. It calls `sudo` only when not already running as root: |
There was a problem hiding this comment.
On CentOS/RHEL, when a normal user with sudo follows this instruction, the script sets SUDO=sudo but still invokes yum install, yum groupinstall, and repository configuration directly without that prefix. Those commands fail for lack of privileges, so the documented dependency setup only works when already root; either apply the elevation helper throughout the yum branch or qualify this guidance.
Useful? React with πΒ / π.
| 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 |
There was a problem hiding this comment.
When the cache is LHD, insert returns None rather than a CacheObjectβthe test suite already special-cases LHD for this behavior. Code written against this new API promise can therefore fail when it dereferences the result; document the return as optional or call out the LHD exception, and align the stub accordingly.
Useful? React with πΒ / π.
No description provided.