perf(graph): intrusive list in VisitedListPool & multi-threaded search benchmarks

- Replaces std::deque<std::unique_ptr<VisitedList>> with an allocation-free IntrusiveList
- Avoids dynamic heap reallocations during high-throughput graph traversal
- Adds multi-threaded search scaling regression tests (HighDim/LowDim up to 8 threads) across SizeBoundedGraph, ReadOnlyGraph, and DynamicGraph

Author: Neiko2002

cpp/deglib/include/deglib/graph/intrusive_list.h

@@ -0,0 +1,73 @@
+#pragma once
+
+#include <utility>
+
+namespace deglib::graph {
+
+/*
+Usage:
+
+``` 
+struct Entry {
+    Entry* next_; // list hooks
+    Entry* prev_; // list hooks
+    // ... other members
+};
+
+using List = IntrusiveList<Entry, &Entry::next_, &Entry::prev_>;
+```
+
+Make sure entries added to the list have a stable address.
+
+
+Implementation adapted from
+https://github.com/facebookexperimental/libunifex/blob/main/include/unifex/detail/intrusive_list.hpp
+ */
+template <class T, T* T::*Next, T* T::*Prev>
+class IntrusiveList
+{
+  private:
+    T* head_{};
+    T* tail_{};
+
+  public:
+    IntrusiveList() = default;
+
+    IntrusiveList(const IntrusiveList&) = delete;
+
+    IntrusiveList(IntrusiveList&& other) noexcept
+        : head_(std::exchange(other.head_, nullptr)), tail_(std::exchange(other.tail_, nullptr))
+    {
+    }
+
+    ~IntrusiveList() = default;
+
+    IntrusiveList& operator=(const IntrusiveList&) = delete;
+    IntrusiveList& operator=(IntrusiveList&&) = delete;
+
+    [[nodiscard]] bool empty() const noexcept { return head_ == nullptr; }
+
+    void push_back(T* item) noexcept
+    {
+        item->*Prev = tail_;
+        item->*Next = nullptr;
+        if (tail_ == nullptr)
+            head_ = item;
+        else
+            tail_->*Next = item;
+        tail_ = item;
+    }
+
+    [[nodiscard]] T* pop_front() noexcept
+    {
+        T* item = head_;
+        head_ = item->*Next;
+        if (head_ != nullptr)
+            head_->*Prev = nullptr;
+        else
+            tail_ = nullptr;
+        return item;
+    }
+};
+
+}  // namespace deglib::graph

cpp/deglib/include/deglib/graph/visited_list_pool.h

@@ -1,9 +1,10 @@
 #pragma once
 
+#include "intrusive_list.h"
+
 #include <algorithm>
 #include <mutex>
-#include <vector>
-#include <deque>
+#include <memory>
 #include <cstdint>
 #include <memory>
 
@@ -12,14 +13,20 @@
  */
 namespace deglib::graph {
 
+class VisitedListPool;
+
 class VisitedList {
 private:
-    uint16_t current_tag_{1};
+    friend VisitedListPool;
+
+    VisitedList* next_;
+    VisitedList* prev_;
     std::unique_ptr<uint16_t[]> slots_;
-    unsigned int num_elements_;
+    uint32_t num_elements_;
+    uint16_t current_tag_{1};
 
 public:
-    explicit VisitedList(int numelements1) : slots_(std::make_unique<uint16_t[]>(numelements1)), num_elements_(numelements1) {}
+    explicit VisitedList(uint32_t numelements1) : slots_(std::make_unique<uint16_t[]>(numelements1)), num_elements_(numelements1) {}
 
     [[nodiscard]] auto* get_visited() const {
         return slots_.get();
@@ -32,34 +39,38 @@ class VisitedList {
     void reset() {
         ++current_tag_;
         if (current_tag_ == 0) {
-            std::fill_n(slots_.get(), num_elements_, 0);
+            std::fill_n(slots_.get(), num_elements_, uint16_t{});
             ++current_tag_;
         }
     }
 };
 
 class VisitedListPool {
 private:
-    using ListPtr = std::unique_ptr<VisitedList>;
-
-    std::deque<ListPtr> pool_;
+    IntrusiveList<VisitedList, &VisitedList::next_, &VisitedList::prev_> pool_;
     std::mutex pool_guard_;
-    int num_elements_;
+    uint32_t num_elements_;
 
  public:
-    VisitedListPool(int initmaxpools, int numelements) : num_elements_(numelements) {
-        for (int i = 0; i < initmaxpools; i++)
-            pool_.push_front(std::make_unique<VisitedList>(numelements));
+    VisitedListPool(uint32_t initmaxpools, uint32_t numelements) : num_elements_(numelements) {
+        for (uint32_t i = 0; i < initmaxpools; i++)
+            pool_.push_back(new VisitedList(numelements));
+    }
+
+    ~VisitedListPool() noexcept {
+        while (!pool_.empty()) {
+            delete pool_.pop_front();
+        }
     }
 
     class FreeVisitedList {
         private:
             friend VisitedListPool;
 
             VisitedListPool& pool_;
-            ListPtr list_;
+            VisitedList& list_;
 
-            FreeVisitedList(VisitedListPool& pool, ListPtr list) : pool_(pool), list_(std::move(list)) {}
+            FreeVisitedList(VisitedListPool& pool, VisitedList& list) : pool_(pool), list_(list) {}
 
         public:        
             FreeVisitedList(const FreeVisitedList& other) = delete;
@@ -68,36 +79,35 @@ class VisitedListPool {
             FreeVisitedList& operator=(FreeVisitedList&& other) = delete;
 
             ~FreeVisitedList() noexcept {
-                pool_.releaseVisitedList(std::move(list_));
+                pool_.releaseVisitedList(list_);
             }
 
             auto operator->() const {
-                return list_.get();
+                return &list_;
             }
     };
 
-    FreeVisitedList getFreeVisitedList() {
-        ListPtr rez = popVisitedList();
+    [[nodiscard]] FreeVisitedList getFreeVisitedList() {
+        auto rez = popVisitedList();
         if (rez) {
             rez->reset();
         } else {
-            rez = std::make_unique<VisitedList>(num_elements_);
+            rez = new VisitedList(num_elements_);
         }
-        return {*this, std::move(rez)};
+        return {*this, *rez};
     }
 
 private:
-    void releaseVisitedList(ListPtr vl) {
+    void releaseVisitedList(VisitedList& vl) {
         std::unique_lock <std::mutex> lock(pool_guard_);
-        pool_.push_back(std::move(vl));
+        pool_.push_back(&vl);
     }
 
-    ListPtr popVisitedList() {
-        ListPtr rez;
+    VisitedList* popVisitedList() {
+        VisitedList* rez{};
         std::unique_lock <std::mutex> lock(pool_guard_);
         if (!pool_.empty()) {
-            rez = std::move(pool_.front());
-            pool_.pop_front();
+            rez = pool_.pop_front();
         }
         return rez;
     }

cpp/test/src/common/test_helpers.h

@@ -754,6 +754,135 @@ inline static void run_regression_test(const char* name, deglib::distances::Metr
     }
 }
 
+// ---------------------------------------------------------------------------
+// Multi-threaded Search Benchmark Helper
+// ---------------------------------------------------------------------------
+template <typename GraphType>
+inline void run_multithreaded_search_benchmark(
+    const std::string& name,
+    const GraphType& graph,
+    const std::vector<float>& query_data,
+    size_t query_count,
+    size_t dim,
+    uint32_t search_k,
+    float search_eps,
+    const std::vector<std::vector<uint32_t>>& gt_data,
+    const std::vector<uint32_t>& thread_counts = {1, 2, 4, 8},
+    size_t num_runs = 50)
+{
+    const size_t feature_bytes = dim * sizeof(float);
+    const std::byte* query_bytes = reinterpret_cast<const std::byte*>(query_data.data());
+
+    std::cout << "\n--- [" << name << "] Multi-Threaded Search Scaling ---" << std::endl;
+
+    double baseline_qps = 0.0;
+
+    for (uint32_t num_threads : thread_counts)
+    {
+        // Warmup
+        {
+            std::vector<std::thread> warmup_threads;
+            warmup_threads.reserve(num_threads);
+            for (uint32_t t = 0; t < num_threads; ++t)
+            {
+                warmup_threads.emplace_back([&, t]() {
+                    size_t q_start = (t * query_count) / num_threads;
+                    size_t q_end = ((t + 1) * query_count) / num_threads;
+                    for (size_t q = q_start; q < q_end; ++q)
+                    {
+                        const std::byte* q_ptr = query_bytes + q * feature_bytes;
+                        std::span<const float> q_span(reinterpret_cast<const float*>(q_ptr), dim);
+                        auto result = graph.search(q_span, search_k, search_eps, nullptr, 0);
+                    }
+                });
+            }
+            for (auto& wt : warmup_threads) wt.join();
+        }
+
+        // Measured benchmark runs: spawn threads once and run all benchmark iterations inside workers
+        std::atomic<size_t> total_correct{0};
+        std::vector<std::thread> workers;
+        workers.reserve(num_threads);
+
+        auto t_start = std::chrono::high_resolution_clock::now();
+
+        for (uint32_t t = 0; t < num_threads; ++t)
+        {
+            workers.emplace_back([&, t]() {
+                size_t local_correct = 0;
+                size_t q_start = (t * query_count) / num_threads;
+                size_t q_end = ((t + 1) * query_count) / num_threads;
+
+                for (size_t r = 0; r < num_runs; ++r)
+                {
+                    for (size_t q = q_start; q < q_end; ++q)
+                    {
+                        const std::byte* q_ptr = query_bytes + q * feature_bytes;
+                        std::span<const float> q_span(reinterpret_cast<const float*>(q_ptr), dim);
+                        auto result = graph.search(q_span, search_k, search_eps, nullptr, 0);
+
+                        if (r == 0)
+                        {
+                            std::unordered_set<uint32_t> gt_set;
+                            if (!gt_data.empty() && q < gt_data.size())
+                            {
+                                size_t eval_k = std::min(static_cast<size_t>(search_k), gt_data[q].size());
+                                for (size_t i = 0; i < eval_k; ++i)
+                                {
+                                    gt_set.insert(gt_data[q][i]);
+                                }
+                            }
+
+                            while (!result.empty())
+                            {
+                                auto top_item = result.top();
+                                result.pop();
+                                uint32_t ext_label = graph.getExternalLabel(top_item.getIdentifier());
+                                if (gt_set.count(ext_label))
+                                {
+                                    local_correct++;
+                                }
+                            }
+                        }
+                    }
+                }
+
+                total_correct += local_correct;
+            });
+        }
+
+        for (auto& worker : workers)
+        {
+            worker.join();
+        }
+
+        auto t_end = std::chrono::high_resolution_clock::now();
+        double duration_secs = std::chrono::duration<double>(t_end - t_start).count();
+        size_t total_queries = query_count * num_runs;
+        double avg_qps = static_cast<double>(total_queries) / duration_secs;
+        double avg_recall = static_cast<double>(total_correct.load()) / static_cast<double>(query_count * search_k);
+
+        if (num_threads == 1 || baseline_qps == 0.0)
+        {
+            baseline_qps = avg_qps;
+            std::cout << "  Threads: " << num_threads
+                      << " | QPS: " << std::fixed << std::setprecision(1) << avg_qps
+                      << " | Recall: " << std::setprecision(3) << avg_recall
+                      << " | Speedup: 1.00x (baseline)" << std::endl;
+        }
+        else
+        {
+            double speedup = avg_qps / baseline_qps;
+            std::cout << "  Threads: " << num_threads
+                      << " | QPS: " << std::fixed << std::setprecision(1) << avg_qps
+                      << " | Recall: " << std::setprecision(3) << avg_recall
+                      << " | Speedup: " << std::setprecision(2) << speedup << "x" << std::endl;
+        }
+
+        EXPECT_GE(avg_recall + 1e-5, 0.85);
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Checksums for dataset determinism verification
 // ---------------------------------------------------------------------------