[bug](hgraph): include reader caches in memory usage by jac0626 · Pull Request #2498 · antgroup/vsag

jac0626 · 2026-07-21T09:41:11Z

Change Type

Linked Issue

Fixes: [bug](hgraph): include reader caches in memory usage #2497

What Changed

Add an optional, default-zero Reader::GetMemoryUsage() hook for resident reader-owned caches.
Include retained base and precise readers in HGraph total and detailed memory reporting without
double-counting a shared reader.
Read Reader and visited-list pool usage dynamically so cache and query-time pool growth are
reflected immediately.
Refresh HGraph's static memory snapshot after SetImmutable() releases neighbor mutex storage.
Add regression coverage and update the English and Chinese memory documentation.

Test Evidence

Test details:

cmake --build build-reuse --target vsag -j2
# [100%] Built target vsag

cmake --build build-reuse --target functests -j2
# [100%] Built target functests

build-reuse/tests/functests "HGraph Reader Memory Usage"
# All tests passed (12 assertions in 1 test case)

1M x 128, RaBitQ2, FP32 reorder, 64 MiB reader cache, three queries:
- reader: allocator 114.92 MiB, GetMemoryUsage 100.71 MiB, difference 14.21 MiB
- mixed:  allocator 286.93 MiB, GetMemoryUsage 269.15 MiB, difference 17.77 MiB
- block:  allocator 776.93 MiB, GetMemoryUsage 759.15 MiB, difference 17.78 MiB

The reader cache and the additional 1.91 MiB query visited-list are included in each total.

Compatibility Impact

API/ABI compatibility: Adds a public virtual method with a default implementation. Existing
custom Reader implementations remain source-compatible, but should be rebuilt for binary
compatibility.
Behavior changes: HGraph memory usage now includes memory explicitly reported by retained
readers and tracks query-time pool growth.

Performance and Concurrency Impact

Performance impact: Constant-time calls to the visited-list pool and at most two retained
readers are added to GetMemoryUsage(); search paths are unchanged.
Concurrency/thread-safety impact: Reader overrides must be thread-safe. This requirement is
documented; the default implementation is stateless.

Documentation Impact

Risk and Rollback

Risk level: medium
Rollback plan: Revert the commit to restore cached HGraph-only accounting and the previous
Reader API.

Checklist

I have linked the relevant issue (required for kind/bug and kind/feature; see "Linked Issue" above)
I have added/updated tests for new behavior or bug fixes
I have considered API compatibility impact
I have updated docs if behavior/workflow changed
My commit messages follow project conventions (Conventional Commits, optional [skip ci] prefix)

vsag-bot · 2026-07-21T09:41:15Z

/label S-waiting-on-review
/waiting-on reviewer
/request-review @jiaweizone
/request-review @wxyucs
/request-review @inabao
/request-review @Copilot
/request-review @LHT129
/request-review @vsag-bot

vsag-bot · 2026-07-21T09:41:22Z

Automated pull request review failed.

Review effort: medium (139 changed lines across 9 files).

git exited with 128: fatal: destination path '/tmp/vsag-pull-request-reviews/6b56ae07-e6d0-48a1-99ac-78d37127008e/source' already exists and is not an empty directory.

No GitHub review was submitted.

mergify · 2026-07-21T09:41:49Z

Merge Protections

🟢 All 3 merge protections satisfied — ready to merge.

Show 3 satisfied protections

🟢 Require kind label

label~=^kind/

🟢 Require version label

label~=^version/

🟢 Require linked issue for feature/bug PRs

body~=(?im)(?:^|[\s\-\*])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:#\d+|[\w.\-]+/[\w.\-]+#\d+|https?://github\.com/[\w.\-]+/[\w.\-]+/issues/\d+)

gemini-code-assist

Code Review

This pull request introduces the ability to track and report memory usage for custom Reader implementations within the HGraph index. It adds a GetMemoryUsage() method to the Reader interface, updates HGraph to include reader memory in its overall and detailed memory usage statistics, and updates the documentation and tests accordingly. The feedback suggests adding a defensive null check for high_precise_codes_ in SetPreciseCodesIO to prevent potential null pointer dereferences.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-07-21T09:42:58Z

 void
 HGraph::SetPreciseCodesIO(const std::shared_ptr<Reader>& reader) {
    auto reader_param = std::make_shared<ReaderIOParameter>();
    reader_param->reader = reader;
    high_precise_codes_->InitIO(reader_param);
+    this->precise_reader_ = reader;
 }


To prevent a potential null pointer dereference, we should add a defensive null check for high_precise_codes_ before calling InitIO. Although the current serialization code path only calls SetPreciseCodesIO when has_precise_reorder() is true, adding this check makes the method robust against other callers or future refactorings.

Suggested change

void

HGraph::SetPreciseCodesIO(const std::shared_ptr<Reader>& reader) {

auto reader_param = std::make_shared<ReaderIOParameter>();

reader_param->reader = reader;

high_precise_codes_->InitIO(reader_param);

this->precise_reader_ = reader;

}

void

HGraph::SetPreciseCodesIO(const std::shared_ptr<Reader>& reader) {

auto reader_param = std::make_shared<ReaderIOParameter>();

reader_param->reader = reader;

if (this->high_precise_codes_ != nullptr) {

this->high_precise_codes_->InitIO(reader_param);

}

this->precise_reader_ = reader;

}

Copilot

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Updates HGraph memory reporting to include resident memory held by retained Reader implementations (e.g., caches), and keeps totals/detailed breakdowns accurate without double-counting shared readers.

Changes:

Add Reader::GetMemoryUsage() hook (default 0) and implement it in the test reader fixture.
Track shared and precise readers in HGraph and include them in total and detailed memory usage.
Add a regression test and update English/Chinese memory documentation.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/test_hgraph.cpp	Adds a functional regression test validating reader memory inclusion and SetImmutable snapshot refresh.
tests/fixtures/framework/test_reader.h	Extends `TestReader` API to accept/return memory usage.
tests/fixtures/framework/test_reader.cpp	Implements `TestReader::GetMemoryUsage()` and stores configured usage.
src/algorithm/hgraph/hgraph_serialize.cpp	Adds reader(s) to HGraph detailed memory breakdown, avoiding double counts.
src/algorithm/hgraph/hgraph.h	Stores retained reader pointers and declares `HGraph::GetMemoryUsage()` override.
src/algorithm/hgraph/hgraph.cpp	Refreshes memory snapshot on `SetImmutable()` and includes reader/pool usage in totals.
include/vsag/readerset.h	Introduces `Reader::GetMemoryUsage()` virtual hook with thread-safety requirement.
docs/docs/zh/src/advanced/memory.md	Documents reader memory inclusion and new detail keys in Chinese.
docs/docs/en/src/advanced/memory.md	Documents reader memory inclusion and new detail keys in English.

     * @brief Constructs a TestReader from a Binary object.
     * @param binary The binary data to wrap for reading.
     */


+    constexpr int64_t dim = 16;
+    constexpr int64_t count = 200;
+    const auto build_param = R"({
+        "dtype": "float32",
+        "metric_type": "l2",
+        "dim": 16,


+    REQUIRE(immutable_memory >= detail_sum);
+    REQUIRE(immutable_memory - detail_sum < 4096);


+`label_table`, `high_precise_codes`, `extra_infos`, `raw_vector`, `reader`, and
+`precise_reader`. Reader keys are present only when the corresponding retained reader exists.


+`extra_infos`、`raw_vector`、`reader` 和 `precise_reader`。仅在索引持有对应 Reader 时才会
+返回 Reader 相关项。SINDI 返回空 map，其他索引类型默认抛出异常。


vsag-bot

Automated inline review completed.

Review effort: medium (139 changed lines across 9 files).
Submitted 1 inline comment.

Reviewed commit 910d004.

vsag-bot · 2026-07-21T10:38:02Z

+     * @return Resident memory usage in bytes. The default implementation returns zero.
+     */
+    [[nodiscard]] virtual uint64_t
+    GetMemoryUsage() const {


[P1] Preserve binary compatibility for existing Reader subclasses

Adding this virtual slot changes the public Reader vtable. An application can load the same major-version VSAG shared library while still constructing a custom Reader compiled against v1.0.0; when HGraph::GetMemoryUsage() dispatches this new slot, that object's old vtable has no corresponding entry, causing undefined behavior or a crash. The documented requirement to rebuild callers contradicts the repository's backward-compatible minor/patch version policy and is not enforced by the unchanged major-version SONAME. Expose optional accounting without extending this vtable (for example through a separate discoverable interface), or make this a major ABI transition.

gemini-code-assist · 2026-07-22T02:56:11Z

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

wxyucs · 2026-07-24T03:55:03Z

/version 1.1

Signed-off-by: jc543239 <jc543239@antgroup.com> Assisted-by: Codex:gpt-5

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot AI review requested due to automatic review settings July 21, 2026 09:41

pull-request-size Bot added the size/L label Jul 21, 2026

vsag-bot assigned LHT129 Jul 21, 2026

vsag-bot self-requested a review July 21, 2026 09:41

mergify Bot added module/docs module/api module/testing labels Jul 21, 2026

jac0626 added kind/bug Bug fixes, defects, or unexpected behavior 修复程序错误、缺陷或异常行为 version/1.0 labels Jul 21, 2026 — with ChatGPT Codex Connector

gemini-code-assist Bot reviewed Jul 21, 2026

View reviewed changes

Copilot AI reviewed Jul 21, 2026

View reviewed changes

Copilot started reviewing on behalf of jac0626 July 21, 2026 10:26 View session

vsag-bot reviewed Jul 21, 2026

View reviewed changes

jac0626 marked this pull request as ready for review July 22, 2026 02:56

jac0626 requested review from LHT129, inabao, jiaweizone and wxyucs as code owners July 22, 2026 02:56

vsag-bot added version/1.1 and removed version/1.0 labels Jul 24, 2026

fix: account for reader memory in hgraph

186c1b0

Signed-off-by: jc543239 <jc543239@antgroup.com> Assisted-by: Codex:gpt-5

Copilot AI review requested due to automatic review settings July 24, 2026 06:56

jac0626 force-pushed the codex/fix-hgraph-reader-memory-usage branch from 910d004 to 186c1b0 Compare July 24, 2026 06:56

vsag-bot self-requested a review July 24, 2026 06:56

Copilot started reviewing on behalf of jac0626 July 24, 2026 06:56 View session

Copilot AI reviewed Jul 24, 2026

		REQUIRE(immutable_memory >= detail_sum);
		REQUIRE(immutable_memory - detail_sum < 4096);

		`label_table`, `high_precise_codes`, `extra_infos`, `raw_vector`, `reader`, and
		`precise_reader`. Reader keys are present only when the corresponding retained reader exists.

		`extra_infos`、`raw_vector`、`reader` 和 `precise_reader`。仅在索引持有对应 Reader 时才会
		返回 Reader 相关项。SINDI 返回空 map，其他索引类型默认抛出异常。

Uh oh!

Conversation

jac0626 commented Jul 21, 2026

Change Type

Linked Issue

What Changed

Test Evidence

Compatibility Impact

Performance and Concurrency Impact

Documentation Impact

Risk and Rollback

Checklist

Uh oh!

vsag-bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vsag-bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergify Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🟢 Require kind label

🟢 Require version label

🟢 Require linked issue for feature/bug PRs

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

vsag-bot left a comment

Choose a reason for hiding this comment

Uh oh!

vsag-bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot commented Jul 22, 2026

Uh oh!

wxyucs commented Jul 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vsag-bot commented Jul 21, 2026 •

edited

Loading

vsag-bot commented Jul 21, 2026 •

edited

Loading

mergify Bot commented Jul 21, 2026 •

edited

Loading