usearch 0.2.3 → 0.4.0

package/include/usearch/usearch.hpp

@@ -85,6 +85,9 @@ inline std::size_t ceil2(std::size_t v) noexcept {
     return v;
 }
 
+/**
+ *  @brief  Inner (Dot) Product distance.
+ */
 template <typename scalar_at, typename result_at = scalar_at> struct ip_gt {
     using scalar_t = scalar_at;
     using result_t = result_at;
@@ -92,10 +95,10 @@ template <typename scalar_at, typename result_at = scalar_at> struct ip_gt {
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim, std::size_t = 0) const noexcept {
         result_type ab{};
-#if defined(__GNUC__)
-#pragma GCC ivdep
-#elif defined(__clang__)
+#if defined(__clang__)
 #pragma clang loop vectorize(enable)
+#elif defined(__GNUC__)
+#pragma GCC ivdep
 #elif defined(_OPENMP)
 #pragma omp simd reduction(+ : ab)
 #endif
@@ -105,6 +108,12 @@ template <typename scalar_at, typename result_at = scalar_at> struct ip_gt {
     }
 };
 
+/**
+ *  @brief  Cosine (Angular) distance.
+ *          Identical to the Inner Product of normalized vectors.
+ *          Unless you are running on an tiny embedded platform, this metric
+ *          is recommended over `::ip_gt` for low-precision scalars.
+ */
 template <typename scalar_at, typename result_at = scalar_at> struct cos_gt {
     using scalar_t = scalar_at;
     using result_t = result_at;
@@ -112,10 +121,10 @@ template <typename scalar_at, typename result_at = scalar_at> struct cos_gt {
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim, std::size_t = 0) const noexcept {
         result_t ab{}, a2{}, b2{};
-#if defined(__GNUC__)
-#pragma GCC ivdep
-#elif defined(__clang__)
+#if defined(__clang__)
 #pragma clang loop vectorize(enable)
+#elif defined(__GNUC__)
+#pragma GCC ivdep
 #elif defined(_OPENMP)
 #pragma omp simd reduction(+ : ab, a2, b2)
 #endif
@@ -123,10 +132,14 @@ template <typename scalar_at, typename result_at = scalar_at> struct cos_gt {
             ab += result_t(a[i]) * result_t(b[i]), //
                 a2 += square<result_t>(a[i]),      //
                 b2 += square<result_t>(b[i]);
-        return ab / (std::sqrt(a2) * std::sqrt(b2));
+        return 1 - ab / (std::sqrt(a2) * std::sqrt(b2));
     }
 };
 
+/**
+ *  @brief  Squared Euclidean (L2) distance.
+ *          Square root is avoided at the end, as it won't affect the ordering.
+ */
 template <typename scalar_at, typename result_at = scalar_at> struct l2sq_gt {
     using scalar_t = scalar_at;
     using result_t = result_at;
@@ -134,10 +147,10 @@ template <typename scalar_at, typename result_at = scalar_at> struct l2sq_gt {
 
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t dim, std::size_t = 0) const noexcept {
         result_t ab_deltas_sq{};
-#if defined(__GNUC__)
-#pragma GCC ivdep
-#elif defined(__clang__)
+#if defined(__clang__)
 #pragma clang loop vectorize(enable)
+#elif defined(__GNUC__)
+#pragma GCC ivdep
 #elif defined(_OPENMP)
 #pragma omp simd reduction(+ : ab_deltas_sq)
 #endif
@@ -159,10 +172,10 @@ template <typename scalar_at, typename result_at = std::size_t> struct hamming_g
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t elements,
                                std::size_t = 0) const noexcept {
         result_t matches{};
-#if defined(__GNUC__)
-#pragma GCC ivdep
-#elif defined(__clang__)
+#if defined(__clang__)
 #pragma clang loop vectorize(enable)
+#elif defined(__GNUC__)
+#pragma GCC ivdep
 #elif defined(_OPENMP)
 #pragma omp simd reduction(+ : matches)
 #endif
@@ -187,10 +200,10 @@ template <typename scalar_at, typename result_at = std::size_t> struct bit_hammi
     inline result_t operator()(scalar_t const* a, scalar_t const* b, std::size_t words,
                                std::size_t = 0) const noexcept {
         result_t matches{};
-#if defined(__GNUC__)
-#pragma GCC ivdep
-#elif defined(__clang__)
+#if defined(__clang__)
 #pragma clang loop vectorize(enable)
+#elif defined(__GNUC__)
+#pragma GCC ivdep
 #elif defined(_OPENMP)
 #pragma omp simd reduction(+ : matches)
 #endif
@@ -239,10 +252,10 @@ template <typename scalar_at, typename result_at = scalar_at> struct pearson_cor
         scalar_t const* a, scalar_t const* b, std::size_t dim, std::size_t = 0) const noexcept {
         result_t a_sum{}, b_sum{}, ab_sum{};
         result_t a_sq_sum{}, b_sq_sum{};
-#if defined(__GNUC__)
-#pragma GCC ivdep
-#elif defined(__clang__)
+#if defined(__clang__)
 #pragma clang loop vectorize(enable)
+#elif defined(__GNUC__)
+#pragma GCC ivdep
 #elif defined(_OPENMP)
 #pragma omp simd reduction(+ : a_sum, b_sum, ab_sum, a_sq_sum, b_sq_sum)
 #endif
@@ -291,6 +304,9 @@ template <std::size_t multiple_ak> inline std::size_t divide_round_up(std::size_
     return (num + multiple_ak - 1) / multiple_ak;
 }
 
+/**
+ *  @brief  Light-weight bitset implementation to track visited nodes during graph traversal.
+ */
 template <typename allocator_at = std::allocator<char>> class visits_bitset_gt {
     using allocator_t = allocator_at;
     using byte_t = typename allocator_t::value_type;
@@ -330,7 +346,8 @@ using visits_bitset_t = visits_bitset_gt<>;
 
 /**
  *  @brief  Similar to `std::priority_queue`, but allows raw access to underlying
- *          memory, in case you want to shuffle it or sort.
+ *          memory, in case you want to shuffle it or sort. Good for collections
+ *          from 100s to 10'000s elements.
  */
 template <typename element_at,                                //
           typename comparator_at = std::less<void>,           // <void> is needed before C++14.
@@ -347,23 +364,19 @@ class max_heap_gt {
     element_t* elements_;
     std::size_t size_;
     std::size_t capacity_;
-    std::size_t max_capacity_;
 
   public:
-    max_heap_gt(std::size_t max_capacity = 0) noexcept
-        : elements_(nullptr), size_(0), capacity_(0), max_capacity_(max_capacity) {}
+    max_heap_gt() noexcept : elements_(nullptr), size_(0), capacity_(0) {}
 
     max_heap_gt(max_heap_gt&& other) noexcept {
         std::swap(elements_, other.elements_);
         std::swap(size_, other.size_);
         std::swap(capacity_, other.capacity_);
-        std::swap(max_capacity_, other.max_capacity_);
     }
     max_heap_gt& operator=(max_heap_gt&& other) noexcept {
         std::swap(elements_, other.elements_);
         std::swap(size_, other.size_);
         std::swap(capacity_, other.capacity_);
-        std::swap(max_capacity_, other.max_capacity_);
         return *this;
     }
 
@@ -384,16 +397,12 @@ class max_heap_gt {
         }
     }
 
-    bool reserve(std::size_t n) noexcept {
-        if (n < capacity_)
+    bool reserve(std::size_t new_capacity) noexcept {
+        if (new_capacity < capacity_)
             return true;
-        if (max_capacity_ && capacity_ == max_capacity_)
-            return false;
-
-        auto new_capacity = (std::max<std::size_t>)(capacity_ * 2u, 16u);
-        if (max_capacity_)
-            new_capacity = (std::min)(new_capacity, max_capacity_);
 
+        new_capacity = ceil2(new_capacity);
+        new_capacity = (std::max<std::size_t>)(new_capacity, (std::max<std::size_t>)(capacity_ * 2u, 16u));
         auto allocator = allocator_t{};
         auto new_elements = allocator.allocate(new_capacity);
         if (!new_elements)
@@ -413,10 +422,15 @@ class max_heap_gt {
         if (!reserve(size_ + 1))
             return false;
 
+        emplace_reserved(std::forward<args_at>(args)...);
+        return true;
+    }
+
+    template <typename... args_at> //
+    void emplace_reserved(args_at&&... args) noexcept {
         new (&elements_[size_]) element_t({std::forward<args_at>(args)...});
         size_++;
         shift_up(size_ - 1);
-        return true;
     }
 
     element_t pop() noexcept {
@@ -430,10 +444,7 @@ class max_heap_gt {
 
     /** @brief Invalidates the "max-heap" property, transforming into ascending range. */
     void sort_ascending() noexcept { std::sort_heap(elements_, elements_ + size_, &less); }
-    /** @brief Invalidates the "max-heap" property, transforming into descending range. */
-    void sort_descending() noexcept { sort_ascending(), std::reverse(elements_, elements_ + size_); }
-    void sort_heap() noexcept { std::make_heap(elements_, elements_ + size_, &less); }
-    void shrink(std::size_t n) noexcept { size_ = n; }
+    void shrink(std::size_t n) noexcept { size_ = (std::min<std::size_t>)(n, size_); }
 
     element_t* data() noexcept { return elements_; }
     element_t const* data() const noexcept { return elements_; }
@@ -468,7 +479,109 @@ class max_heap_gt {
 };
 
 /**
- *
+ *  @brief  Similar to `std::priority_queue`, but allows raw access to underlying
+ *          memory and always keeps the data sorted. Ideal for small collections
+ *          under 128 elements.
+ */
+template <typename element_at,                                //
+          typename comparator_at = std::less<void>,           // <void> is needed before C++14.
+          typename allocator_at = std::allocator<element_at>> //
+class sorted_buffer_gt {
+  public:
+    using element_t = element_at;
+    using comparator_t = comparator_at;
+    using allocator_t = allocator_at;
+
+    using value_type = element_t;
+
+  private:
+    element_t* elements_;
+    std::size_t size_;
+    std::size_t capacity_;
+
+  public:
+    sorted_buffer_gt() noexcept : elements_(nullptr), size_(0), capacity_(0) {}
+
+    sorted_buffer_gt(sorted_buffer_gt&& other) noexcept {
+        std::swap(elements_, other.elements_);
+        std::swap(size_, other.size_);
+        std::swap(capacity_, other.capacity_);
+    }
+    sorted_buffer_gt& operator=(sorted_buffer_gt&& other) noexcept {
+        std::swap(elements_, other.elements_);
+        std::swap(size_, other.size_);
+        std::swap(capacity_, other.capacity_);
+        return *this;
+    }
+
+    sorted_buffer_gt(sorted_buffer_gt const&) = delete;
+    sorted_buffer_gt& operator=(sorted_buffer_gt const&) = delete;
+
+    ~sorted_buffer_gt() {
+        clear();
+        allocator_t{}.deallocate(elements_, capacity_);
+    }
+
+    bool empty() const noexcept { return !size_; }
+    std::size_t size() const noexcept { return size_; }
+    std::size_t capacity() const noexcept { return capacity_; }
+    element_t const& top() const noexcept { return elements_[size_ - 1]; }
+
+    void clear() noexcept {
+        while (size_)
+            size_--, elements_[size_].~element_t();
+    }
+
+    bool reserve(std::size_t new_capacity) noexcept {
+        if (new_capacity < capacity_)
+            return true;
+
+        new_capacity = ceil2(new_capacity);
+        new_capacity = (std::max<std::size_t>)(new_capacity, (std::max<std::size_t>)(capacity_ * 2u, 16u));
+        auto allocator = allocator_t{};
+        auto new_elements = allocator.allocate(new_capacity);
+        if (!new_elements)
+            return false;
+
+        if (size_) {
+            std::uninitialized_copy_n(elements_, size_, new_elements);
+            allocator.deallocate(elements_, capacity_);
+        }
+        elements_ = new_elements;
+        capacity_ = new_capacity;
+        return true;
+    }
+
+    template <typename... args_at> void emplace_reserved(args_at&&... args) {
+        element_t element({std::forward<args_at>(args)...});
+        std::size_t slot = std::lower_bound(elements_, elements_ + size_, element, &less) - elements_;
+        std::size_t to_move = size_ - slot;
+        element_t* source = elements_ + size_ - 1;
+        for (; to_move; --to_move, --source)
+            source[1] = source[0];
+        elements_[slot] = element;
+        size_++;
+    }
+
+    element_t pop() noexcept {
+        size_--;
+        element_t result = elements_[size_];
+        elements_[size_].~element_t();
+        return result;
+    }
+
+    void sort_ascending() noexcept {}
+    void shrink(std::size_t n) noexcept { size_ = (std::min<std::size_t>)(n, size_); }
+
+    element_t* data() noexcept { return elements_; }
+    element_t const* data() const noexcept { return elements_; }
+
+  private:
+    static bool less(element_t const& a, element_t const& b) noexcept { return comparator_t{}(a, b); }
+};
+
+/**
+ *  @brief  Tiny userspace mutex, designed to fit in a single integer.
  */
 class mutex_t {
 #if defined(WINDOWS)
@@ -517,13 +630,13 @@ static_assert(sizeof(mutex_t) == sizeof(std::int32_t), "Mutex is larger than exp
 
 using lock_t = std::unique_lock<mutex_t>;
 
-/**
- *  @brief Five-byte integer type to address node clouds with over 4B entries.
- */
 #if defined(WINDOWS)
 #pragma pack(push, 1) // Pack struct members on 1-byte alignment
 #endif
 
+/**
+ *  @brief Five-byte integer type to address node clouds with over 4B entries.
+ */
 class usearch_pack_m uint40_t {
     unsigned char octets[5];
 
@@ -561,6 +674,7 @@ class usearch_pack_m uint40_t {
         return old;
     }
 };
+
 #if defined(WINDOWS)
 #pragma pack(pop) // Reset alignment to default
 #endif
@@ -580,10 +694,9 @@ template <typename scalar_at> class span_gt {
 };
 
 /**
- *  @brief
- *      Configuration settings for the index construction.
- *      Includes the main `::connectivity` parameter (`M` in the paper)
- *      and two expansion factors - for construction and search.
+ *  @brief  Configuration settings for the index construction.
+ *          Includes the main `::connectivity` parameter (`M` in the paper)
+ *          and two expansion factors - for construction and search.
  */
 struct config_t {
 
@@ -612,10 +725,35 @@ struct config_t {
     std::size_t max_threads_search = 0;
 };
 
+struct add_config_t {
+    /// @brief Optional thread identifier for multi-threaded construction.
+    std::size_t thread{};
+    /// @brief Don't copy the ::vector, if it's persisted elsewhere.
+    bool store_vector{true};
+};
+
+struct add_result_t {
+    std::size_t new_size{};
+    std::size_t cycles{};
+    std::size_t measurements{};
+};
+
+struct search_config_t {
+    std::size_t thread{};
+    bool exact{};
+};
+
+struct search_result_t {
+    std::size_t count{};
+    std::size_t cycles{};
+    std::size_t measurements{};
+
+    inline operator std::size_t() const noexcept { return count; }
+};
+
 /**
- *  @brief
- *      Approximate Nearest Neighbors Search index using the
- *      Hierarchical Navigable Small World graph algorithm.
+ *  @brief  Approximate Nearest Neighbors Search index using the
+ *          Hierarchical Navigable Small World graph algorithm.
  *
  *  @section Features
  *      - Search for vectors of different dimensionality.
@@ -650,8 +788,15 @@ class index_gt {
     using id_t = id_at;
     using allocator_t = allocator_at;
 
+    using vector_view_t = span_gt<scalar_t const>;
+
+#if ((defined(_MSVC_LANG) && _MSVC_LANG >= 201703L) || __cplusplus >= 201703L) // C++17 ann newer
+    using distance_t =
+        typename std::invoke_result<metric_t, scalar_t const*, scalar_t const*, std::size_t, std::size_t>::type;
+#else
     using distance_t =
         typename std::result_of<metric_t(scalar_t const*, scalar_t const*, std::size_t, std::size_t)>::type;
+#endif
 
   private:
     using neighbors_count_t = id_t;
@@ -672,16 +817,18 @@ class index_gt {
         std::size_t neighbors_base_bytes{};
         std::size_t mutex_bytes{};
     };
-    struct distance_and_id_t {
+    struct candidate_t {
         distance_t first;
         id_t second;
     };
     struct compare_by_distance_t {
-        inline bool operator()(distance_and_id_t a, distance_and_id_t b) const noexcept { return a.first < b.first; }
+        inline bool operator()(candidate_t a, candidate_t b) const noexcept { return a.first < b.first; }
     };
 
-    using distances_and_ids_allocator_t = typename allocator_traits_t::template rebind_alloc<distance_and_id_t>;
-    using distances_and_ids_t = max_heap_gt<distance_and_id_t, compare_by_distance_t, distances_and_ids_allocator_t>;
+    using candidates_view_t = span_gt<candidate_t const>;
+    using candidates_allocator_t = typename allocator_traits_t::template rebind_alloc<candidate_t>;
+    using top_candidates_t = sorted_buffer_gt<candidate_t, compare_by_distance_t, candidates_allocator_t>;
+    using next_candidates_t = max_heap_gt<candidate_t, compare_by_distance_t, candidates_allocator_t>;
 
     struct neighbors_ref_t {
         neighbors_count_t& count_;
@@ -696,6 +843,8 @@ class index_gt {
         inline id_t& operator[](std::size_t i) noexcept { return neighbors_[i]; }
         inline id_t operator[](std::size_t i) const noexcept { return neighbors_[i]; }
         inline std::size_t size() const noexcept { return count_; }
+        inline void clear() noexcept { count_ = 0u; }
+        inline void push_back(id_t id) noexcept { neighbors_[count_] = id, count_++; }
     };
 
 #if defined(WINDOWS)
@@ -734,16 +883,25 @@ class index_gt {
         scalar_t* vector{};
 
         inline node_ref_t(mutex_t& m, node_head_t& h, scalar_t* s) noexcept : mutex_(&m), head(h), vector(s) {}
+        /// @brief Locks the list of neighbors for concurrent updates.
         inline lock_t lock() const noexcept { return mutex_ ? lock_t{*mutex_} : lock_t{}; }
         inline operator node_t() const noexcept { return node_t{mutex_ ? (byte_t*)mutex_ : (byte_t*)&head, vector}; }
+        inline operator vector_view_t() const noexcept { return {vector, head.dim}; }
     };
 
     struct usearch_align_m thread_context_t {
-        distances_and_ids_t top_candidates;
-        distances_and_ids_t candidates_set;
-        visits_bitset_t visits;
-        std::default_random_engine level_generator;
-        metric_t metric;
+        top_candidates_t top_candidates{};
+        next_candidates_t next_candidates{};
+        visits_bitset_t visits{};
+        std::default_random_engine level_generator{};
+        metric_t metric{};
+        std::size_t iteration_cycles{};
+        std::size_t measurements_count{};
+
+        inline distance_t measure(vector_view_t a, vector_view_t b) noexcept {
+            measurements_count++;
+            return metric(a.data(), b.data(), a.size(), b.size());
+        }
     };
 
     config_t config_{};
@@ -793,6 +951,9 @@ class index_gt {
         reserve(config.max_elements);
     }
 
+    /**
+     *  @brief  Clones the structure with the same hyper-parameters, but without contents.
+     */
     index_gt fork() noexcept(false) { return {config_, metric_, allocator_}; }
 
     ~index_gt() noexcept { clear(); }
@@ -806,6 +967,10 @@ class index_gt {
 
 #pragma region Adjusting Configuration
 
+    /**
+     *  @brief  Erases all the vectors from the index.
+     *          Will change `size()` to zero, but will keep the same `capacity()`.
+     */
     void clear() noexcept {
         std::size_t n = size_;
         for (std::size_t i = 0; i != n; ++i)
@@ -815,6 +980,9 @@ class index_gt {
         entry_id_ = 0u;
     }
 
+    /**
+     *  @brief  Swaps the underlying memory buffers and thread contexts.
+     */
     void swap(index_gt& other) noexcept {
         std::swap(config_, other.config_);
         std::swap(metric_, other.metric_);
@@ -835,6 +1003,9 @@ class index_gt {
         other.size_ = size;
     }
 
+    /**
+     *  @brief  Increases the `capacity()` of the index to allow adding more vectors.
+     */
     void reserve(std::size_t new_capacity) noexcept(false) {
 
         assert_m(new_capacity >= size_, "Can't drop existing values");
@@ -845,6 +1016,10 @@ class index_gt {
         capacity_ = new_capacity;
     }
 
+    /**
+     *  @brief  Optimizes configuration options to fit the maximum number
+     *          of neighbors in CPU-cache-aligned buffers.
+     */
     static config_t optimize(config_t const& config) noexcept {
         precomputed_constants_t pre = precompute(config);
         std::size_t bytes_per_node_base = head_bytes_k + pre.neighbors_base_bytes + pre.mutex_bytes;
@@ -859,103 +1034,140 @@ class index_gt {
 
 #pragma region Construction and Search
 
-    id_t add(                                                //
-        label_t new_label, span_gt<scalar_t const> new_span, //
-        std::size_t thread_idx = 0, bool store_vector = true) {
+    /**
+     *  @brief Inserts a new vector into the index. Thread-safe.
+     *
+     *  @param[in] label External identifier/name/descriptor for the vector.
+     *  @param[in] vector Contiguous range of scalars forming a vector view.
+     *  @param[in] config Configuration options for this specific operation.
+     */
+    add_result_t add(label_t label, vector_view_t vector, add_config_t config = {}) noexcept(false) {
 
         assert_m(!is_immutable(), "Can't add to an immutable index");
-        id_t new_id = static_cast<id_t>(size_.fetch_add(1));
-        scalar_t const* new_vector = new_span.data();
-        std::size_t new_dim = new_span.size();
+        add_result_t result;
+        result.new_size = size_.fetch_add(1);
+        id_t id = static_cast<id_t>(result.new_size);
 
-        // Determining how much memory to allocate depends on the target level.
+        // Determining how much memory to allocate depends on the target level
         lock_t new_level_lock(global_mutex_);
         level_t max_level = max_level_;
-        thread_context_t& context = thread_contexts_[thread_idx];
-        level_t new_target_level = choose_random_level(context.level_generator);
-        if (new_target_level <= max_level)
+        thread_context_t& context = thread_contexts_[config.thread];
+        level_t target_level = choose_random_level(context.level_generator);
+        if (target_level <= max_level)
             new_level_lock.unlock();
 
         // Allocate the neighbors
-        node_ref_t new_node = node_malloc(new_label, new_vector, new_dim, new_target_level, store_vector);
+        node_ref_t new_node = node_malloc(label, vector, target_level, config.store_vector);
         lock_t new_lock = new_node.lock();
-        nodes_[new_id] = new_node;
+        nodes_[id] = new_node;
 
         // Do nothing for the first element
-        if (!new_id) {
-            max_level_ = new_target_level;
-            return new_id;
+        if (!id) {
+            max_level_ = target_level;
+            return result;
         }
 
+        // Pull stats
+        result.measurements = context.measurements_count;
+        result.cycles = context.iteration_cycles;
+
         // Go down the level, tracking only the closest match
-        id_t closest_id = search_for_one(entry_id_, new_vector, new_dim, max_level, new_target_level, context);
+        id_t closest_id = search_for_one(entry_id_, vector, max_level, target_level, context);
 
-        // From `new_target_level` down perform proper extensive search.
-        for (level_t level = (std::min)(new_target_level, max_level); level >= 0; level--) {
-            search_to_insert(closest_id, new_vector, new_dim, level, context);
-            closest_id = connect_new_element(new_id, level, context);
+        // From `target_level` down perform proper extensive search
+        for (level_t level = (std::min)(target_level, max_level); level >= 0; level--) {
+            search_to_insert(closest_id, vector, level, context);
+            closest_id = connect_new_element(id, level, context);
         }
 
-        // Releasing lock for the maximum level
-        if (new_target_level > max_level) {
-            entry_id_ = new_id;
-            max_level_ = new_target_level;
+        // Normalize stats
+        result.measurements = context.measurements_count - result.measurements;
+        result.cycles = context.iteration_cycles - result.cycles;
+
+        // Updating the entry point if needed
+        if (target_level > max_level) {
+            entry_id_ = id;
+            max_level_ = target_level;
         }
-        return new_id;
+        return result;
     }
 
-    template <typename label_and_distance_callback_at>
-    void search(                                                //
-        span_gt<scalar_t const> query_span, std::size_t wanted, //
-        label_and_distance_callback_at&& callback, std::size_t thread_idx = 0) const {
+    /**
+     *  @brief Searches for the closest members to the given ::query. Thread-safe.
+     *
+     *  @param[in] query Contiguous range of scalars forming a vector view.
+     *  @param[in] wanted The upper bound for the number of results to return.
+     *  @param[in] callback Function receiving the labels and distances to matches in ascending order.
+     *  @param[in] config Configuration options for this specific operation.
+     */
+    template <typename callback_at>
+    search_result_t search(                      //
+        vector_view_t query, std::size_t wanted, //
+        callback_at&& callback, search_config_t config = {}) const noexcept(false) {
 
+        search_result_t result;
         if (!size_)
-            return;
-
-        scalar_t const* query_vec = query_span.data();
-        std::size_t query_dim = query_span.size();
+            return result;
 
         // Go down the level, tracking only the closest match
-        thread_context_t& context = thread_contexts_[thread_idx];
-        id_t closest_id = search_for_one(entry_id_, query_vec, query_dim, max_level_, 0, context);
-
-        // For bottom layer we need a more optimized procedure
-        search_to_find_in_base( //
-            closest_id, query_vec, query_dim, (std::max)(config_.expansion_search, wanted), context);
-        while (context.top_candidates.size() > wanted)
-            context.top_candidates.pop();
-
-        while (context.top_candidates.size()) {
-            distance_and_id_t top = context.top_candidates.top();
-            callback(node(top.second).head.label, top.first);
-            context.top_candidates.pop();
+        thread_context_t& context = thread_contexts_[config.thread];
+        result.measurements = context.measurements_count;
+        result.cycles = context.iteration_cycles;
+
+        if (config.exact) {
+            search_exact(query, wanted, context);
+        } else {
+            id_t closest_id = search_for_one(entry_id_, query, max_level_, 0, context);
+            std::size_t expansion = (std::max)(config_.expansion_search, wanted);
+            // For bottom layer we need a more optimized procedure
+            search_to_find_in_base(closest_id, query, expansion, context);
         }
+
+        top_candidates_t& top = context.top_candidates;
+        top.sort_ascending();
+        top.shrink(wanted);
+
+        candidate_t const* top_ordered = top.data();
+        for (std::size_t i = 0; i < top.size(); ++i)
+            callback(node(top_ordered[i].second).head.label, top_ordered[i].first);
+
+        // Normalize stats
+        result.measurements = context.measurements_count - result.measurements;
+        result.cycles = context.iteration_cycles - result.cycles;
+        result.count = top.size();
+        return result;
     }
 
-    std::size_t search(                                         //
-        span_gt<scalar_t const> query_span, std::size_t wanted, //
-        label_t* matches, distance_t* distances,                //
-        std::size_t thread_idx = 0) const {
+    /**
+     *  @brief Searches for the closest members to the given ::query. Thread-safe.
+     *  @note Convenience method for callback-based `search()`.
+     *
+     *  @param[in] query Contiguous range of scalars forming a vector view.
+     *  @param[in] wanted The upper bound for the number of results to return.
+     *  @param[out] matches Contiguous output buffer for the labels of closest members.
+     *  @param[out] distances Contiguous output buffer for the distances to the closest members.
+     *  @param[in] config Configuration options for this specific operation.
+     *  @return The number of found approximate matches. Always equal or less then ::wanted.
+     */
+    search_result_t search(                      //
+        vector_view_t query, std::size_t wanted, //
+        label_t* matches, distance_t* distances, search_config_t config = {}) const noexcept(false) {
 
-        std::size_t found = 0;
         auto callback = [&](label_t label, distance_t distance) noexcept {
             if (matches)
-                matches[found] = label;
+                *(matches++) = label;
             if (distances)
-                distances[found] = distance;
-            ++found;
+                *(distances++) = distance;
         };
-        search(query_span, wanted, callback, thread_idx);
-        std::reverse(matches, matches + found * (matches != nullptr));
-        std::reverse(distances, distances + found * (distances != nullptr));
-        return found;
+        return search(query, wanted, callback, config);
     }
 
 #pragma endregion
 
 #pragma region Serialization
 
-    struct state_t {
+  private:
+    struct serialized_state_t {
         // Check compatibility
         std::uint64_t bytes_per_label{};
         std::uint64_t bytes_per_id{};
@@ -967,12 +1179,15 @@ class index_gt {
         std::uint64_t max_level{};
     };
 
+  public:
     /**
-     *  Compatibility: Linux, MacOS, Windows.
+     *  @brief  Saves serialized binary index representation to disk,
+     *          co-locating vectors and neighbors lists.
+     *          Available on Linux, MacOS, Windows.
      */
     void save(char const* file_path) const noexcept(false) {
 
-        state_t state;
+        serialized_state_t state;
         // Check compatibility
         state.bytes_per_label = sizeof(label_t);
         state.bytes_per_id = sizeof(id_t);
@@ -1018,10 +1233,12 @@ class index_gt {
     }
 
     /**
-     *  Compatibility: Linux, MacOS, Windows.
+     *  @brief  Loads the serialized binary index representation from disk,
+     *          copying both vectors and neighbors lists into RAM.
+     *          Available on Linux, MacOS, Windows.
      */
     void load(char const* file_path) noexcept(false) {
-        state_t state;
+        serialized_state_t state;
         std::FILE* file = std::fopen(file_path, "r");
         if (!file)
             throw std::runtime_error(std::strerror(errno));
@@ -1061,7 +1278,7 @@ class index_gt {
             }
 
             std::size_t bytes_to_dump = node_dump_size(head.dim, head.level);
-            node_ref_t node_ref = node_malloc(head.label, nullptr, head.dim, head.level, true);
+            node_ref_t node_ref = node_malloc(head.label, {nullptr, head.dim}, head.level, true);
             read = std::fread((byte_t*)&node_ref.head + head_bytes_k, bytes_to_dump - head_bytes_k, 1, file);
             if (!read) {
                 std::fclose(file);
@@ -1076,13 +1293,15 @@ class index_gt {
     }
 
     /**
-     *  Compatibility: Linux, MacOS.
+     *  @brief  Memory-maps the serialized binary index representation from disk,
+     *          @b without copying the vectors and neighbors lists into RAM.
+     *          Available on Linux, MacOS, but @b not on Windows.
      */
     void view(char const* file_path) noexcept(false) {
 #if defined(WIN32) || defined(_WIN32) || defined(__WIN32__) || defined(__NT__)
         throw std::logic_error("Memory-mapping is not yet available for Windows");
 #else
-        state_t state;
+        serialized_state_t state;
         int open_flags = O_RDONLY;
 #if __linux__
         open_flags |= O_NOATIME;
@@ -1183,11 +1402,10 @@ class index_gt {
         node = node_t{};
     }
 
-    node_ref_t node_malloc(                                     //
-        label_t label, scalar_t const* vector, std::size_t dim, //
-        level_t level, bool store_vector = true) noexcept(false) {
+    node_ref_t node_malloc(label_t label, vector_view_t vector, level_t level, bool store_vector) noexcept(false) {
 
         // This function is rarely called and can be as expensive as needed for higher space-efficiency.
+        std::size_t dim = vector.size();
         std::size_t levels_bytes = pre_.neighbors_base_bytes + pre_.neighbors_bytes * level;
         std::size_t node_bytes =                  //
             pre_.mutex_bytes +                    // Optional concurrency-control
@@ -1201,10 +1419,10 @@ class index_gt {
         mutex_t* mutex = synchronize() ? (mutex_t*)data : nullptr;
         scalar_t* scalars = store_vector //
                                 ? (scalar_t*)(data + pre_.mutex_bytes + head_bytes_k + levels_bytes)
-                                : (scalar_t*)(vector);
+                                : (scalar_t*)(vector.data());
 
         std::memset(data, 0, node_bytes);
-        std::memcpy(scalars, vector, sizeof(scalar_t) * dim * (store_vector && vector));
+        std::memcpy(scalars, vector.data(), sizeof(scalar_t) * dim * (store_vector && vector.data()));
 
         node_head_t& head = *(node_head_t*)(data + pre_.mutex_bytes);
         head.label = label;
@@ -1238,68 +1456,54 @@ class index_gt {
     id_t connect_new_element(id_t new_id, level_t level, thread_context_t& context) noexcept(false) {
 
         node_ref_t new_node = node(new_id);
-        distances_and_ids_t& top_candidates = context.top_candidates;
+        top_candidates_t& top = context.top_candidates;
         std::size_t const connectivity_max = level ? config_.connectivity : pre_.connectivity_max_base;
-        span_gt<distance_and_id_t const> top = filter_heuristic(top_candidates, config_.connectivity, context.metric);
-
-        distance_and_id_t const* const top_ordered = top.data();
-        std::size_t const top_count = top.size();
-        id_t const next_closest_entry_id = top_ordered[0].second;
 
         // Outgoing links from `new_id`:
+        neighbors_ref_t new_neighbors = neighbors(new_node, level);
         {
-            neighbors_ref_t new_neighbors = neighbors(new_node, level);
-            assert_m(!new_neighbors.count_, "The newly inserted element should have blank link list");
+            assert_m(!new_neighbors.size(), "The newly inserted element should have blank link list");
+            candidates_view_t top_view = refine(top, config_.connectivity, context);
 
-            new_neighbors.count_ = static_cast<neighbors_count_t>(top_count);
-            for (std::size_t idx = 0; idx < top_count; idx++) {
+            for (std::size_t idx = 0; idx != top_view.size(); idx++) {
                 assert_m(!new_neighbors[idx], "Possible memory corruption");
-                assert_m(level <= node(top_ordered[idx].second).head.level, "Linking to missing level");
-                new_neighbors[idx] = top_ordered[idx].second;
+                assert_m(level <= node(top_view[idx].second).head.level, "Linking to missing level");
+                new_neighbors.push_back(top_view[idx].second);
             }
         }
 
         // Reverse links from the neighbors:
-        for (std::size_t idx = 0; idx < top_count; idx++) {
-            id_t close_id = top_ordered[idx].second;
+        for (id_t close_id : new_neighbors) {
             node_ref_t close_node = node(close_id);
             lock_t close_lock = close_node.lock();
 
             neighbors_ref_t close_header = neighbors(close_node, level);
-            assert_m(close_header.count_ <= connectivity_max, "Possible corruption");
+            assert_m(close_header.size() <= connectivity_max, "Possible corruption");
             assert_m(close_id != new_id, "Self-loops are impossible");
             assert_m(level <= close_node.head.level, "Linking to missing level");
 
             // If `new_id` is already present in the neighboring connections of `close_id`
             // then no need to modify any connections or run the heuristics.
-            if (close_header.count_ < connectivity_max) {
-                close_header[close_header.count_] = new_id;
-                close_header.count_++;
+            if (close_header.size() < connectivity_max) {
+                close_header.push_back(new_id);
                 continue;
             }
 
             // To fit a new connection we need to drop an existing one.
-            distances_and_ids_t& candidates = context.candidates_set;
-            candidates.clear();
-            candidates.emplace( //
-                context.metric( //
-                    new_node.vector, close_node.vector, new_node.head.dim, close_node.head.dim),
-                new_id);
-            for (id_t successor_id : close_header) {
-                node_ref_t successor_node = node(successor_id);
-                candidates.emplace( //
-                    context.metric( //
-                        successor_node.vector, close_node.vector, successor_node.head.dim, close_node.head.dim),
-                    successor_id);
-            }
-            span_gt<distance_and_id_t const> top = filter_heuristic(candidates, connectivity_max, context.metric);
+            top.clear();
+            top.reserve(close_header.size() + 1);
+            top.emplace_reserved(context.measure(new_node, close_node), new_id);
+            for (id_t successor_id : close_header)
+                top.emplace_reserved(context.measure(node(successor_id), close_node), successor_id);
 
             // Export the results:
-            for (close_header.count_ = 0u; close_header.count_ != top.size(); ++close_header.count_)
-                close_header[close_header.count_] = top[close_header.count_].second;
+            close_header.clear();
+            candidates_view_t top_view = refine(top, connectivity_max, context);
+            for (std::size_t idx = 0; idx != top_view.size(); idx++)
+                close_header.push_back(top_view[idx].second);
         }
 
-        return next_closest_entry_id;
+        return new_neighbors[0];
     }
 
     level_t choose_random_level(std::default_random_engine& level_generator) const noexcept {
@@ -1308,13 +1512,12 @@ class index_gt {
         return (level_t)r;
     }
 
-    id_t search_for_one(                                                 //
-        id_t entry_id, scalar_t const* query_vec, std::size_t query_dim, //
-        level_t begin_level, level_t end_level, thread_context_t& context) const noexcept {
+    id_t search_for_one(                        //
+        id_t closest_id, vector_view_t query,   //
+        level_t begin_level, level_t end_level, //
+        thread_context_t& context) const noexcept {
 
-        id_t closest_id = entry_id;
-        distance_t closest_dist =
-            context.metric(query_vec, node(closest_id).vector, query_dim, node(closest_id).head.dim);
+        distance_t closest_dist = context.measure(query, node(closest_id));
         for (level_t level = begin_level; level > end_level; level--) {
             bool changed;
             do {
@@ -1323,44 +1526,47 @@ class index_gt {
                 lock_t closest_lock = closest_node.lock();
                 neighbors_ref_t closest_header = neighbors_non_base(closest_node, level);
                 for (id_t candidate_id : closest_header) {
-                    node_ref_t candidate_node = node(candidate_id);
-                    distance_t candidate_dist =
-                        context.metric(query_vec, candidate_node.vector, query_dim, candidate_node.head.dim);
+                    distance_t candidate_dist = context.measure(query, node(candidate_id));
                     if (candidate_dist < closest_dist) {
                         closest_dist = candidate_dist;
                         closest_id = candidate_id;
                         changed = true;
                     }
                 }
+                context.iteration_cycles++;
             } while (changed);
         }
         return closest_id;
     }
 
-    void search_to_insert(                                               //
-        id_t start_id, scalar_t const* query_vec, std::size_t query_dim, //
-        level_t level, thread_context_t& context) noexcept(false) {
+    void search_to_insert(                                 //
+        id_t start_id, vector_view_t query, level_t level, //
+        thread_context_t& context) noexcept(false) {
 
         visits_bitset_t& visits = context.visits;
-        distances_and_ids_t& top_candidates = context.top_candidates; // pop max, push
-        distances_and_ids_t& candidates_set = context.candidates_set; // pop min, push
+        next_candidates_t& candidates = context.next_candidates; // pop min, push
+        top_candidates_t& top = context.top_candidates;          // pop max, push
+        std::size_t const top_limit = config_.expansion_add;
 
-        top_candidates.clear();
-        candidates_set.clear();
         visits.clear();
+        candidates.clear();
+        top.clear();
+        top.reserve(top_limit + 1);
 
-        distance_t closest_dist = context.metric(query_vec, node(start_id).vector, query_dim, node(start_id).head.dim);
-        top_candidates.emplace(closest_dist, start_id);
-        candidates_set.emplace(-closest_dist, start_id);
+        distance_t radius = context.measure(query, node(start_id));
+        candidates.emplace(-radius, start_id);
+        top.emplace_reserved(radius, start_id);
         visits.set(start_id);
 
-        while (!candidates_set.empty()) {
+        while (!candidates.empty()) {
 
-            distance_and_id_t candidacy = candidates_set.top();
-            if ((-candidacy.first) > closest_dist && top_candidates.size() == config_.expansion_add)
+            candidate_t candidacy = candidates.top();
+            if ((-candidacy.first) > radius && top.size() == top_limit)
                 break;
 
-            candidates_set.pop();
+            candidates.pop();
+            context.iteration_cycles++;
+
             id_t candidate_id = candidacy.second;
             node_ref_t candidate_node = node(candidate_id);
             lock_t candidate_lock = candidate_node.lock();
@@ -1372,48 +1578,48 @@ class index_gt {
                     continue;
 
                 visits.set(successor_id);
-                node_ref_t successor_node = node(successor_id);
-                distance_t successor_dist =
-                    context.metric(query_vec, successor_node.vector, query_dim, successor_node.head.dim);
-                if (top_candidates.size() < config_.expansion_add || closest_dist > successor_dist) {
-                    candidates_set.emplace(-successor_dist, successor_id);
-
-                    top_candidates.emplace(successor_dist, successor_id);
-                    if (top_candidates.size() > config_.expansion_add)
-                        top_candidates.pop();
-                    if (!top_candidates.empty())
-                        closest_dist = top_candidates.top().first;
+                distance_t successor_dist = context.measure(query, node(successor_id));
+
+                if (top.size() < top_limit || successor_dist < radius) {
+                    candidates.emplace(-successor_dist, successor_id);
+                    top.emplace_reserved(successor_dist, successor_id);
+                    if (top.size() > top_limit)
+                        top.pop();
+                    radius = top.top().first;
                 }
             }
         }
     }
 
-    void search_to_find_in_base(                                         //
-        id_t start_id, scalar_t const* query_vec, std::size_t query_dim, //
-        std::size_t expansion, thread_context_t& context) const noexcept(false) {
+    void search_to_find_in_base(                                   //
+        id_t start_id, vector_view_t query, std::size_t expansion, //
+        thread_context_t& context) const noexcept(false) {
 
         visits_bitset_t& visits = context.visits;
-        distances_and_ids_t& top_candidates = context.top_candidates; // pop max, push
-        distances_and_ids_t& candidates_set = context.candidates_set; // pop min, push
+        next_candidates_t& candidates = context.next_candidates; // pop min, push
+        top_candidates_t& top = context.top_candidates;          // pop max, push
+        std::size_t const top_limit = expansion;
 
         visits.clear();
-        top_candidates.clear();
-        candidates_set.clear();
+        candidates.clear();
+        top.clear();
+        top.reserve(top_limit + 1);
 
-        distance_t closest_dist = context.metric(query_vec, node(start_id).vector, query_dim, node(start_id).head.dim);
-        top_candidates.emplace(closest_dist, start_id);
-        candidates_set.emplace(-closest_dist, start_id);
+        distance_t radius = context.measure(query, node(start_id));
+        candidates.emplace(-radius, start_id);
+        top.emplace_reserved(radius, start_id);
         visits.set(start_id);
 
-        while (!candidates_set.empty()) {
+        while (!candidates.empty()) {
 
-            distance_and_id_t current_node_node = candidates_set.top();
-            if ((-current_node_node.first) > closest_dist)
+            candidate_t candidate = candidates.top();
+            if ((-candidate.first) > radius)
                 break;
 
-            candidates_set.pop();
+            candidates.pop();
+            context.iteration_cycles++;
 
-            id_t candidate_id = current_node_node.second;
+            id_t candidate_id = candidate.second;
             neighbors_ref_t candidate_header = neighbors_base(node(candidate_id));
 
             prefetch_neighbors(candidate_header, visits);
@@ -1422,47 +1628,56 @@ class index_gt {
                     continue;
 
                 visits.set(successor_id);
-                node_ref_t successor_node = node(successor_id);
-                distance_t successor_dist =
-                    context.metric(query_vec, successor_node.vector, query_dim, successor_node.head.dim);
-
-                if (top_candidates.size() < expansion || closest_dist > successor_dist) {
-                    candidates_set.emplace(-successor_dist, successor_id);
-
-                    top_candidates.emplace(successor_dist, successor_id);
-                    if (top_candidates.size() > expansion)
-                        top_candidates.pop();
-                    if (!top_candidates.empty())
-                        closest_dist = top_candidates.top().first;
+                distance_t successor_dist = context.measure(query, node(successor_id));
+
+                if (top.size() < top_limit || successor_dist < radius) {
+                    candidates.emplace(-successor_dist, successor_id);
+                    top.emplace_reserved(successor_dist, successor_id);
+                    if (top.size() > top_limit)
+                        top.pop();
+                    radius = top.top().first;
                 }
             }
         }
     }
 
+    void search_exact(vector_view_t query, std::size_t count, thread_context_t& context) const noexcept(false) {
+        top_candidates_t& top = context.top_candidates;
+        top.clear();
+        top.reserve(count);
+        for (std::size_t i = 0; i != nodes_.size(); ++i)
+            top.emplace_reserved(context.measure(query, node(nodes_[i])), static_cast<id_t>(i));
+    }
+
     void prefetch_neighbors(neighbors_ref_t, visits_bitset_t const&) const noexcept {}
 
-    span_gt<distance_and_id_t const> filter_heuristic( //
-        distances_and_ids_t& top_candidates, std::size_t needed, metric_t const& metric) const noexcept {
+    /**
+     *  @brief  This algorithm from the original paper implements a heuristic,
+     *          that massively reduces the number of connections a point has,
+     *          to keep only the neighbors, that are from each other.
+     */
 
-        top_candidates.sort_ascending();
-        distance_and_id_t* top_ordered = top_candidates.data();
-        std::size_t const top_count = top_candidates.size();
+    candidates_view_t refine(                      //
+        top_candidates_t& top, std::size_t needed, //
+        thread_context_t& context) const noexcept {
+
+        top.sort_ascending();
+        candidate_t* top_data = top.data();
+        std::size_t const top_count = top.size();
         if (top_count < needed)
-            return {top_ordered, top_count};
+            return {top_data, top_count};
 
         std::size_t submitted_count = 1;
         std::size_t consumed_count = 1; /// Always equal or greater than `submitted_count`.
         while (submitted_count < needed && consumed_count < top_count) {
-            distance_and_id_t candidate = top_ordered[consumed_count];
+            candidate_t candidate = top_data[consumed_count];
             node_ref_t candidate_node = node(candidate.second);
             distance_t candidate_dist = candidate.first;
             bool good = true;
             for (std::size_t idx = 0; idx < submitted_count; idx++) {
-                distance_and_id_t submitted = top_ordered[idx];
+                candidate_t submitted = top_data[idx];
                 node_ref_t submitted_node = node(submitted.second);
-                distance_t inter_result_dist = metric(            //
-                    submitted_node.vector, candidate_node.vector, //
-                    submitted_node.head.dim, candidate_node.head.dim);
+                distance_t inter_result_dist = context.measure(submitted_node, candidate_node);
                 if (inter_result_dist < candidate_dist) {
                     good = false;
                     break;
@@ -1470,13 +1685,14 @@ class index_gt {
             }
 
             if (good) {
-                top_ordered[submitted_count] = top_ordered[consumed_count];
+                top_data[submitted_count] = top_data[consumed_count];
                 submitted_count++;
             }
             consumed_count++;
         }
 
-        return {top_ordered, submitted_count};
+        top.shrink(submitted_count);
+        return {top_data, submitted_count};
     }
 };