fix: reuse visited lists across sub-pools

[jac0626]

Change Type

• Improvement/Refactor

Linked Issue

• Fixes: [improve](hgraph): reuse idle visited lists across sub-pools before allocating #2427

What Changed

• Scan all visited-list sub-pools for an idle object before allocating a new one.
• Preserve the existing thread-local sub-pool preference and non-blocking lock strategy.
• Add regression coverage for reusing an object from another sub-pool.

Test Evidence

• Other (described below)

Test details:

clang-format 15.0.7 --dry-run --Werror (changed files): passed
make test CASE='[ut][VisitedListPool]':
All tests passed (10001 assertions in 2 test cases)

Compatibility Impact

• API/ABI compatibility: none
• Behavior changes: pool allocation occurs only after all sub-pools are observed empty

Performance and Concurrency Impact

• Performance impact: reduces unnecessary large visited-list allocations
• Concurrency/thread-safety impact: retains the existing per-sub-pool mutexes and try_lock behavior

Documentation Impact

• No docs update needed

Risk and Rollback

• Risk level: low
• Rollback plan: revert the commit to restore the previous allocation policy

Checklist

• I have linked the relevant issue
• I have added/updated tests for the changed behavior
• I have considered API compatibility impact
• My commit messages follow project conventions

---

Drafted with AI assistant: Codex:gpt-5

[vsag-bot]

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

[mergify]

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Require kind label

• label~=^kind/

🟢 Require version label

• label~=^version/

[gemini-code-assist]

Code Review

This pull request updates the object retrieval logic in ResourceObjectPool to prioritize reusing existing objects across all sub-pools before constructing new ones, and adds a unit test to verify this behavior. However, the current implementation introduces a critical concurrency issue: if sub-pools are locked by other threads, try_lock() fails, causing the outer while (true) loop to busy-spin and consume 100% CPU. It is recommended to replace this loop with a single-pass check over the sub-pools, falling back to constructing a new object if no existing objects can be safely retrieved.

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]

Potential Livelock / High CPU Usage Under Concurrency

In the current implementation, if any sub-pool is locked by another thread (which is highly likely under concurrent access), try_lock() will fail, and empty_pool_count will not reach kSubPoolCount. This causes the outer while (true) loop to busy-spin indefinitely or for a very long time, consuming 100% CPU.

Solution

Instead of a busy-spin while (true) loop, we can perform a single pass over all sub-pools. If we find an available object in any sub-pool we can lock, we reuse it. If we finish the pass and find no available objects (either because they are empty or because they are locked), we safely allocate a new object. This completely avoids busy-spinning while still satisfying the goal of reusing objects across sub-pools before allocating new ones.

        for (uint64_t i = 0; i < kSubPoolCount; ++i) {
            if (sub_pool_mutexes_[pool_id].try_lock()) {
                if (!pool_[pool_id]->empty()) {
                    std::shared_ptr<T> obj = pool_[pool_id]->front();
                    pool_[pool_id]->pop_front();
                    sub_pool_mutexes_[pool_id].unlock();
                    prefer_pool_id_ = pool_id;
                    obj->source_pool_id_ = pool_id;
                    obj->Reset();
                    return obj;
                }
                sub_pool_mutexes_[pool_id].unlock();
            }
            ++pool_id;
            pool_id %= kSubPoolCount;
        }
        auto obj = this->constructor_();
        obj->source_pool_id_ = prefer_pool_id_;
        return obj;

[Copilot]

Pull request overview

This PR improves ResourceObjectPool’s allocation policy so that when a thread’s preferred sub-pool is empty, the pool will first attempt to reuse an idle object from other sub-pools before allocating a new VisitedList. This reduces peak scratch-memory growth in HGraph search workloads without changing the public API/ABI.

Changes:

• Update ResourceObjectPool::TakeOne() to scan all sub-pools for an available object before constructing a new one.
• Add a regression test that fails under the old “allocate immediately when preferred sub-pool is empty” behavior and passes with cross-sub-pool reuse.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/utils/resource_object_pool.h	Implements cross-sub-pool reuse by scanning sub-pools before allocating a new resource object.
src/utils/visited_list_test.cpp	Adds a regression test validating that no additional VisitedList allocations occur when other sub-pools still have idle objects.