From 8b7a3978082b99741401b5feda63da7be51ec660 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Tue, 10 Nov 2026 18:18:23 -0800 Subject: [PATCH 01/15] Save concurrent dynamic index without consolidate/compact --- bindings/c/docs/C_API_Design.md | 2 +- bindings/c/include/svs/c/svs_c.h | 4 +- bindings/c/src/index_vamana.hpp | 16 +- data/serialization.toml | 8 + include/svs/concurrent/README.md | 23 +- include/svs/concurrent/dynamic_index.h | 88 ++++++-- include/svs/core/translation.h | 4 + include/svs/index/vamana/dynamic_index.h | 206 +++++++++++++----- .../orchestrators/concurrent_dynamic_vamana.h | 6 +- 9 files changed, 272 insertions(+), 85 deletions(-) diff --git a/bindings/c/docs/C_API_Design.md b/bindings/c/docs/C_API_Design.md index aa4fdb276..c48b476e0 100644 --- a/bindings/c/docs/C_API_Design.md +++ b/bindings/c/docs/C_API_Design.md @@ -277,7 +277,7 @@ Invalid parameters are rejected with `SVS_ERROR_INVALID_ARGUMENT`; unlike the le |-----------------|----------| | `SVS_SYNC_KIND_NONE` | No internal synchronization (default); the caller must serialize access | | `SVS_SYNC_KIND_GLOBAL` | Index-wide reader/writer lock: read-only operations (search, `has_id`, `get_distance`, reconstruct, `get_size`, `get_num_threads`, memory queries, use as a conversion source) run concurrently; mutating operations (add/delete points, consolidate, compact, save, `set_num_threads`) are exclusive | -| `SVS_SYNC_KIND_FINE_GRAIN` | Backed by the concurrent Vamana index, which synchronizes updates itself: read-only operations and add/delete points, consolidate, compact all take a shared lock and run in parallel (compact still waits inside the index). Save, `set_num_threads`, memory queries and use as a conversion source are exclusive | +| `SVS_SYNC_KIND_FINE_GRAIN` | Backed by the concurrent Vamana index, which synchronizes updates itself: read-only operations and add/delete points, consolidate, compact all take a shared lock and run in parallel (compact still waits inside the index). Save takes the shared lock too: it runs alongside searches, waits for running writers, and does not consolidate or compact. `set_num_threads`, memory queries and use as a conversion source are exclusive | Synchronization limits: - `svs_index_free()` must not run concurrently with any other call on the same handle. diff --git a/bindings/c/include/svs/c/svs_c.h b/bindings/c/include/svs/c/svs_c.h index 0826c16f9..d85f01f1d 100644 --- a/bindings/c/include/svs/c/svs_c.h +++ b/bindings/c/include/svs/c/svs_c.h @@ -597,7 +597,9 @@ struct svs_memory_breakdown { /// With SVS_SYNC_KIND_FINE_GRAIN, the handle is backed by a concurrent index that /// synchronizes updates itself: add_points, delete_points, consolidate and compact take a /// shared lock and run alongside searches and each other (compact still waits for -/// in-flight operations inside the index). Only save, set_num_threads, memory queries +/// in-flight operations inside the index). save takes a shared lock and runs alongside +/// searches; the index blocks its own writers while saving and keeps deleted and empty +/// slots as they are (no consolidate or compact). Only set_num_threads, memory queries /// and use as a conversion source take an exclusive lock. /// /// @remarks Synchronization covers operations on the index only: diff --git a/bindings/c/src/index_vamana.hpp b/bindings/c/src/index_vamana.hpp index 2a193981e..096fa0f88 100644 --- a/bindings/c/src/index_vamana.hpp +++ b/bindings/c/src/index_vamana.hpp @@ -158,8 +158,9 @@ struct DynamicIndexVamana : public DynamicIndex { /// Dynamic index backed by svs::ConcurrentDynamicVamana. /// /// The index synchronizes add/delete/consolidate/compact itself, so they take the shared -/// lock alongside searches. Operations that are not thread-safe in the index (save, -/// set_num_threads) and whole-index reads (memory breakdown, use as a conversion source) +/// lock alongside searches. save() also takes the shared lock: the index excludes its own +/// writers while saving. Operations that are not thread-safe in the index +/// (set_num_threads) and whole-index reads (memory breakdown, use as a conversion source) /// take the exclusive lock. struct ConcurrentIndexVamana : public DynamicIndexVamana { ConcurrentIndexVamana( @@ -179,6 +180,17 @@ struct ConcurrentIndexVamana : public DynamicIndexVamana { size_t delete_points(std::span ids) override; + // Does not consolidate or compact; the index blocks its own writers while saving. + void save(const std::filesystem::path& directory) override { + auto lock = read_lock(); + index.save(directory / "config", directory / "graph", directory / "data"); + } + + void save(std::ostream& stream) override { + auto lock = read_lock(); + index.save(stream); + } + void consolidate() override { auto lock = read_lock(); index.consolidate(); diff --git a/data/serialization.toml b/data/serialization.toml index 24554ef08..921ac6d5a 100644 --- a/data/serialization.toml +++ b/data/serialization.toml @@ -98,6 +98,14 @@ schema_version = "v0.0.0" parameters = "table" translation = "table" +[[schemas]] + __schema__ = "vamana_dynamic_auxiliary_parameters" + __version__ = "v0.0.1" + name = "str" + parameters = "table" + translation = "table" + status = "table" + [[schemas]] __schema__ = "vamana_build_parameters" __version__ = "v0.0.1" diff --git a/include/svs/concurrent/README.md b/include/svs/concurrent/README.md index a8ba73bf0..ae7ed032c 100644 --- a/include/svs/concurrent/README.md +++ b/include/svs/concurrent/README.md @@ -84,12 +84,18 @@ storage smaller, so it must wait for every reader to finish first. It is the onl caller that takes `compact_mutex_` exclusive. It runs `consolidate_locked()` before it compacts. -### 1d. Not safe at all +### 1d. `save()` + +`save()` writes the slots as they are, with deleted and empty slots included. It does +not call `consolidate()` or `compact()`. It takes `writers_gatekeeper_` and then +`writers_mutex_` exclusive, so it waits for running writers and blocks new ones. New +writers hold the gatekeeper only while acquiring `writers_mutex_`, so they cannot +starve `save()`. Searches keep running. + +### 1e. Not safe at all Call these only when no other thread uses the index: -- `save()` - it holds no lock while it writes the files. It calls `consolidate()` - and `compact()` first, but it releases both locks before writing. - `set_alpha`, `set_prune_to`, `set_max_candidates`, `set_construction_window_size`, `set_threadpool` - plain writes, no lock. @@ -142,6 +148,8 @@ There are three groups: | Lock | Protects | Taken exclusive by | | --- | --- | --- | +| `writers_mutex_` | the index state stays unchanged while `save()` writes it | `save()` only | +| `writers_gatekeeper_` | new writers wait behind a pending `save()` | `save()` only | | `compact_mutex_` | the storage stays alive | `compact()` only | | `translator_mutex_` | the two id hash maps | `add_points`, `consolidate`, `compact`, `replace_external_id` | | `pending_insertions_mutex_` | `pending_insertions_` | `add_points` | @@ -155,10 +163,15 @@ section 3. Only shrinking is not. So `add_points`, `delete_entries`, and `consolidate` take this lock *shared*. Only `compact()` takes it exclusive, and so it waits for all of them. +**Why writers take `writers_mutex_` shared.** `add_points`, `delete_entries`, +`consolidate`, `compact` and `replace_external_id` take it first, once, and never +while holding another index lock. Searches do not take it. + **Lock order.** Always take locks in the same order. Then threads cannot deadlock. ``` +writers_gatekeeper_ -> writers_mutex_ -> compact_gatekeeper_ -> compact_mutex_ compact_mutex_ -> slot_alloc_mutex_ compact_mutex_ -> translator_mutex_ l2e_mutex_ -> e2l_mutex_ (multi index) @@ -247,8 +260,8 @@ The dataset must use a `SegmentedBlocked` allocator; this is checked at compile time. `distance` may be a functor or a `svs::DistanceType`. `batch_iterator()` returns this index's own `BatchIterator`, so it takes the locks described in 1a. -The rules from section 1 apply unchanged: `save()`, `set_threadpool()` and the -build-parameter setters still need exclusive access. +The rules from section 1 apply unchanged: `set_threadpool()` and the +build-parameter setters still need exclusive access; `save()` follows 1d. ```cpp using Data = svs::index::vamana::concurrent::SegmentedBlockedData; diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index 1fc1a8980..026f465c0 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -250,6 +250,8 @@ class MutableVamanaIndex { // compact() holds it exclusive. // // Lock acquisition order across the codebase: + // writers_gatekeeper_ -> writers_mutex_ (never reversed) + // writers_mutex_ -> compact_gatekeeper_ (never reversed) // compact_gatekeeper_ -> compact_mutex_ (never reversed) // compact_mutex_ -> slot_alloc_mutex_ (never reversed) // compact_mutex_ -> translator_mutex_ (never reversed) @@ -263,6 +265,14 @@ class MutableVamanaIndex { std::make_unique()}; // Iterators check this under compact_mutex_ before reusing cached internal IDs. size_t compaction_epoch_ = 0; + // Outermost lock. Every writer (add_points, delete_entries, consolidate, compact, + // replace_external_id) holds it shared; save() holds it exclusive so the state it + // writes is stable. Searches and other readers never take it. + std::unique_ptr writers_mutex_{ + std::make_unique()}; + // Once save() owns this gate, new writers cannot keep it waiting on writers_mutex_. + std::unique_ptr writers_gatekeeper_{ + std::make_unique()}; // Writer-only mutex serializing slot allocation in add_points std::unique_ptr slot_alloc_mutex_{std::make_unique()}; @@ -826,6 +836,7 @@ class MutableVamanaIndex { /// @param new_id The external ID to assign. Must not be mapped at all. /// ReplaceExternalIdResult replace_external_id(size_t old_id, size_t new_id) { + auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); std::lock_guard lock{*translator_mutex_}; @@ -882,6 +893,12 @@ class MutableVamanaIndex { // This is an internal method, mostly used to help implement the batch iterator. ValidBuilder internal_search_builder() const { return ValidBuilder{status_}; } + /// @brief Shared lock taken by every writer; waits behind a pending save(). + [[nodiscard]] std::shared_lock lock_writers_shared() const { + std::shared_lock gatekeeper_lock{*writers_gatekeeper_}; + return std::shared_lock(*writers_mutex_); + } + /// @brief RAII shared lock guarding data_/graph_ against compact()'s shrink /// (which frees segments). Used by searches, iterators and mutations that /// may overlap each other but must exclude compaction. @@ -1108,6 +1125,8 @@ class MutableVamanaIndex { return {}; } + auto writers_lock = lock_writers_shared(); + // Reserve slot ownership against compact(). Held for the entire call, // including the lock-free Phase 2-4 below; compact() takes this // exclusive and so will block until every in-flight add finishes. @@ -1315,6 +1334,7 @@ class MutableVamanaIndex { /// graph. /// template size_t delete_entries(const T& ids) { + auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); std::shared_lock lock{*translator_mutex_}; size_t deleted = 0; @@ -1400,6 +1420,7 @@ class MutableVamanaIndex { /// improve performance but requires more working memory. /// void compact(Idx batch_size = 1'000) { + auto writers_lock = lock_writers_shared(); std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; std::lock_guard compact_lock{*compact_mutex_}; @@ -1613,6 +1634,7 @@ class MutableVamanaIndex { ///// Mutation void consolidate() { + auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); consolidate_locked(); } @@ -1702,6 +1724,7 @@ class MutableVamanaIndex { /// @returns The number of listed IDs that were consolidated. /// template size_t consolidate(const T& ids) { + auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); // Collect the internal slots of the listed, already-soft-deleted IDs. @@ -1741,18 +1764,30 @@ class MutableVamanaIndex { get_search_parameters()}; } - static constexpr lib::Version save_version = lib::Version(0, 0, 0); + // 0.0.1 also stores the per-slot status. + static constexpr lib::Version save_version = vamana::detail::dynamic_status_version; + + // Saves the slots as they are (holes included); does not consolidate or compact. + // Blocks writers while saving; searches may continue. void save( const std::filesystem::path& config_directory, const std::filesystem::path& graph_directory, const std::filesystem::path& data_directory ) { - vamana::detail::save_dynamic_index( - *this, config_directory, graph_directory, data_directory + std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; + std::unique_lock writers_lock{*writers_mutex_}; + auto [status, translator] = snapshot_for_save(); + vamana::detail::write_dynamic_index( + *this, translator, &status, config_directory, graph_directory, data_directory ); } - void save(std::ostream& os) { vamana::detail::save_dynamic_index(*this, os); } + void save(std::ostream& os) { + std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; + std::unique_lock writers_lock{*writers_mutex_}; + auto [status, translator] = snapshot_for_save(); + vamana::detail::write_dynamic_index(*this, translator, &status, os); + } ///// ///// Calibrate @@ -1873,6 +1908,27 @@ class MutableVamanaIndex { // Not synchronized: callers must exclude concurrent mutation. const IDTranslator& view_translator() const { return translator_; } + // Slot status bytes and a translator holding only the Valid slots. The caller holds + // writers_mutex_ exclusive. + std::pair, IDTranslator> snapshot_for_save() const { + auto status = std::vector{}; + auto translator = IDTranslator{}; + auto slots = status_snapshot(); + status.reserve(slots.size()); + for (size_t i = 0, imax = slots.size(); i < imax; ++i) { + if (slots[i] == SlotMetadata::Pending) { + throw ANNEXCEPTION("Cannot save an index with pending slot {}", i); + } + status.push_back(static_cast(slots[i])); + } + for (auto pair : translator_) { + if (slots.at(pair.second) == SlotMetadata::Valid) { + translator.insert_translation(pair.first, pair.second); + } + } + return {std::move(status), std::move(translator)}; + } + // Not synchronized: callers must exclude concurrent mutation. std::vector status_snapshot() const { auto result = std::vector(status_.size()); @@ -2320,18 +2376,9 @@ auto auto_dynamic_assemble( bool SVS_UNUSED(debug_load_from_static) = false, svs::logging::logger_ptr logger = svs::logging::get() ) { - // Read the combined TOML (parameters + translation) - // and the translator binary data. - auto table = lib::detail::read_metadata(is); - - auto parameters = lib::load( - table.template cast().at("parameters").template cast() - ); - - auto translation = - table.template cast().at("translation").template cast(); - - auto translator = IDTranslator::load(translation, is); + // Read the combined TOML (parameters + translation + status) and the binary data. + auto [parameters, translator, status] = + vamana::detail::load_stream_state(is); auto data = data_loader(); auto graph = graph_loader(); @@ -2344,11 +2391,8 @@ auto auto_dynamic_assemble( ); } - auto translator_size = translator.size(); - if (translator_size != datasize) { - throw ANNEXCEPTION( - "Translator has {} IDs but should have {}", translator_size, datasize - ); + if (!status) { + status.emplace(datasize, SlotMetadata::Valid); } auto threadpool = threads::as_threadpool(std::move(threadpool_proto)); @@ -2357,7 +2401,7 @@ auto auto_dynamic_assemble( std::move(data), std::move(graph), std::move(distance), - std::vector(datasize, SlotMetadata::Valid), + *status, std::move(translator), std::move(threadpool), std::move(logger)}; diff --git a/include/svs/core/translation.h b/include/svs/core/translation.h index 88b95311f..059750bff 100644 --- a/include/svs/core/translation.h +++ b/include/svs/core/translation.h @@ -492,6 +492,10 @@ class IDTranslator { static IDTranslator load(const lib::LoadTable& table) { IDTranslator::validate(table); + // An empty translator is saved as an empty file, which open_read rejects. + if (lib::load_at(table, "num_points") == 0) { + return IDTranslator{}; + } // Now that we've more-or-less validated the metadata, time to start loading // the points. diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 8a9a64dd1..19cea316f 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -19,6 +19,7 @@ // stdlib #include #include +#include #include // Include the flat index to spin-up exhaustive searches on demand. @@ -111,31 +112,37 @@ class ValidBuilder { namespace detail { +// Version of "vamana_dynamic_auxiliary_parameters" that also stores per-slot status. +inline constexpr lib::Version dynamic_status_version = lib::Version(0, 0, 1); + +// Writes the index as-is. If `status` is given (one byte per slot), it is saved too and +// `translator` must only map `Valid` slots. template -void save_dynamic_index( +void write_dynamic_index( Index& index, + const IDTranslator& translator, + const std::vector* status, const std::filesystem::path& config_directory, const std::filesystem::path& graph_directory, const std::filesystem::path& data_directory ) { - // Post-consolidation, all entries should be "valid". - // Therefore, we don't need to save the slot metadata. - index.consolidate(); - index.compact(); - // Save auxiliary data structures. lib::save_to_disk( lib::SaveOverride([&](const lib::SaveContext& ctx) { // Save the construction parameters. - return lib::SaveTable( + auto table = lib::SaveTable( "vamana_dynamic_auxiliary_parameters", Index::save_version, { {"name", lib::save(index.name())}, {"parameters", lib::save(index.parameters(), ctx)}, - {"translation", lib::save(index.view_translator(), ctx)}, + {"translation", lib::save(translator, ctx)}, } ); + if (status != nullptr) { + table.insert("status", lib::save(lib::BinaryBlobSaver(*status), ctx)); + } + return table; }), config_directory ); @@ -146,12 +153,13 @@ void save_dynamic_index( lib::save_to_disk(index.view_graph(), graph_directory); } -template void save_dynamic_index(Index& index, std::ostream& os) { - // Post-consolidation, all entries should be "valid". - // Therefore, we don't need to save the slot metadata. - index.consolidate(); - index.compact(); - +template +void write_dynamic_index( + Index& index, + const IDTranslator& translator, + const std::vector* status, + std::ostream& os +) { lib::begin_serialization(os); auto save_table = lib::SaveTable( "vamana_dynamic_auxiliary_parameters", @@ -159,11 +167,17 @@ template void save_dynamic_index(Index& index, std::ostream& os { {"name", lib::save(index.name())}, {"parameters", lib::save(index.parameters())}, - {"translation", lib::detail::exit_hook(index.view_translator().metadata())}, + {"translation", lib::detail::exit_hook(translator.metadata())}, } ); + if (status != nullptr) { + save_table.insert("num_status", lib::save(status->size())); + } lib::save_to_stream(save_table, os); - index.view_translator().save(os); + translator.save(os); + if (status != nullptr) { + lib::write_binary(os, *status); + } // Save the dataset. lib::save_to_stream(index.view_data(), os); @@ -171,6 +185,35 @@ template void save_dynamic_index(Index& index, std::ostream& os lib::save_to_stream(index.view_graph(), os); } +template +void save_dynamic_index( + Index& index, + const std::filesystem::path& config_directory, + const std::filesystem::path& graph_directory, + const std::filesystem::path& data_directory +) { + // Post-consolidation, all entries should be "valid". + // Therefore, we don't need to save the slot metadata. + index.consolidate(); + index.compact(); + write_dynamic_index( + index, + index.view_translator(), + nullptr, + config_directory, + graph_directory, + data_directory + ); +} + +template void save_dynamic_index(Index& index, std::ostream& os) { + // Post-consolidation, all entries should be "valid". + // Therefore, we don't need to save the slot metadata. + index.consolidate(); + index.compact(); + write_dynamic_index(index, index.view_translator(), nullptr, os); +} + template < typename Index, data::ImmutableMemoryDataset Queries, @@ -1502,6 +1545,47 @@ MutableVamanaIndex( ) -> MutableVamanaIndex, Data, Dist>; namespace detail { +// Convert raw status bytes read from a version 0.0.1 file. Only 0, 1 and 2 +// (`Empty`, `Valid`, `Deleted`) are valid on disk. +template +std::vector decode_slot_status(const std::vector& raw) { + auto result = std::vector(raw.size()); + for (size_t i = 0, imax = raw.size(); i < imax; ++i) { + if (raw[i] > 2) { + throw ANNEXCEPTION("Invalid slot status {} at slot {}", unsigned(raw[i]), i); + } + result[i] = static_cast(raw[i]); + } + return result; +} + +// The translator must cover exactly the `Valid` slots. +template +void check_translator_matches_status( + const IDTranslator& translator, const std::vector& status +) { + size_t num_valid = 0; + for (size_t i = 0, imax = status.size(); i < imax; ++i) { + if (status[i] == Metadata::Valid) { + ++num_valid; + if (!translator.has_internal(i)) { + throw ANNEXCEPTION("Translator is missing internal id {}", i); + } + } + } + + auto translator_size = translator.size(); + if (translator_size != num_valid) { + throw ANNEXCEPTION( + "Translator has {} IDs but should have {}", translator_size, num_valid + ); + } +} + +inline bool is_supported_dynamic_version(const lib::Version& version) { + return version == lib::Version(0, 0, 0) || version == dynamic_status_version; +} + template struct VamanaStateLoader { ///// Loading static bool @@ -1509,7 +1593,7 @@ template struct VamanaStateLoader { // We provide the option to load from a static index. return VamanaIndexParameters::check_load_compatibility(schema, version) || (schema == "vamana_dynamic_auxiliary_parameters" && - version == lib::Version(0, 0, 0)); + is_supported_dynamic_version(version)); } // Provide a compatibility path for loading static datasets. @@ -1522,10 +1606,22 @@ template struct VamanaStateLoader { std::vector(assume_datasize, Metadata::Valid)}; } + auto status = std::vector(assume_datasize, Metadata::Valid); + if (table.version() == dynamic_status_version) { + std::vector raw = + lib::load_at>(table, "status"); + if (raw.size() != assume_datasize) { + throw ANNEXCEPTION( + "Status has {} entries but should have {}", raw.size(), assume_datasize + ); + } + status = decode_slot_status(raw); + } + return VamanaStateLoader{ SVS_LOAD_MEMBER_AT_(table, parameters), svs::lib::load_at(table, "translation"), - std::vector(assume_datasize, Metadata::Valid), + std::move(status), }; } @@ -1535,6 +1631,36 @@ template struct VamanaStateLoader { std::vector status_; }; +// Contents of a stream before the dataset: parameters, translator and (version 0.0.1) +// slot status. `status` is empty for version 0.0.0, where every slot is `Valid`. +template struct StreamState { + VamanaIndexParameters parameters; + IDTranslator translator; + std::optional> status; +}; + +template StreamState load_stream_state(std::istream& is) { + auto table = lib::detail::read_metadata(is); + auto root = table.template cast(); + if (!is_supported_dynamic_version(root.version())) { + throw ANNEXCEPTION("Unsupported dynamic index stream version {}", root.version()); + } + + auto parameters = + lib::load(root.at("parameters").template cast() + ); + auto translator = + IDTranslator::load(root.at("translation").template cast(), is); + + std::optional> status{}; + if (root.version() == dynamic_status_version) { + auto raw = std::vector(lib::load_at(root, "num_status")); + lib::read_binary(is, raw); + status = decode_slot_status(raw); + } + return {std::move(parameters), std::move(translator), std::move(status)}; +} + template VamanaStateLoader auto_load_state( ConfigProto&& config_proto, @@ -1661,24 +1787,8 @@ auto auto_dynamic_assemble( ); } - // The translator must cover exactly the valid slots; copied state may contain - // deleted or empty slots. - size_t num_valid = 0; - for (size_t i = 0; i < datasize; ++i) { - if (status[i] == SlotMetadata::Valid) { - ++num_valid; - if (!translator.has_internal(i)) { - throw ANNEXCEPTION("Translator is missing internal id {}", i); - } - } - } - - auto translator_size = translator.size(); - if (translator_size != num_valid) { - throw ANNEXCEPTION( - "Translator has {} IDs but should have {}", translator_size, num_valid - ); - } + // Copied state may contain deleted or empty slots. + detail::check_translator_matches_status(translator, status); // At this point, we should be completely validated. // Construct the index! @@ -1707,18 +1817,9 @@ auto auto_dynamic_assemble( bool SVS_UNUSED(debug_load_from_static) = false, svs::logging::logger_ptr logger = svs::logging::get() ) { - // Read the combined TOML (parameters + translation) - // and the translator binary data. - auto table = lib::detail::read_metadata(is); - - auto parameters = lib::load( - table.template cast().at("parameters").template cast() - ); - - auto translation = - table.template cast().at("translation").template cast(); - - auto translator = IDTranslator::load(translation, is); + // Read the combined TOML (parameters + translation + status) and the binary data. + auto [parameters, translator, loaded_status] = + detail::load_stream_state(is); auto data = data_loader(); auto graph = graph_loader(); @@ -1731,14 +1832,15 @@ auto auto_dynamic_assemble( ); } - auto translator_size = translator.size(); - if (translator_size != datasize) { + auto status = + loaded_status.value_or(std::vector(datasize, SlotMetadata::Valid)); + if (status.size() != datasize) { throw ANNEXCEPTION( - "Translator has {} IDs but should have {}", translator_size, datasize + "Status has {} entries but should have {}", status.size(), datasize ); } + detail::check_translator_matches_status(translator, status); - auto status = std::vector(datasize, SlotMetadata::Valid); auto threadpool = threads::as_threadpool(std::move(threadpool_proto)); return MutableVamanaIndex{ parameters, diff --git a/include/svs/orchestrators/concurrent_dynamic_vamana.h b/include/svs/orchestrators/concurrent_dynamic_vamana.h index 884e67804..e729b9fcd 100644 --- a/include/svs/orchestrators/concurrent_dynamic_vamana.h +++ b/include/svs/orchestrators/concurrent_dynamic_vamana.h @@ -38,8 +38,10 @@ namespace svs { /// The wrapped index may be searched and mutated from several threads at once: search, /// batch iteration, ``add_points``, ``delete_points``, ``consolidate``, ``compact``, ID /// inspection, ``get_distance`` and ``reconstruct_at`` are safe to call concurrently. -/// ``save``, ``set_threadpool`` and the build-parameter setters are not; call them only -/// when no other thread uses the index. See ``include/svs/concurrent/README.md``. +/// ``save`` writes the slots as they are, without consolidating or compacting; it blocks +/// writers while it runs. ``set_threadpool`` and the build-parameter setters are not safe; +/// call them only when no other thread uses the index. See +/// ``include/svs/concurrent/README.md``. /// /// The dataset must use a ``svs::index::vamana::concurrent::SegmentedBlocked`` allocator so /// that growing it never relocates storage under concurrent readers. From 5e0c57ac86e8d2392162ad4238fb2a89aec37ded Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Thu, 12 Nov 2026 13:27:43 -0800 Subject: [PATCH 02/15] Drop changes not needed for save without compact --- bindings/c/src/index_vamana.hpp | 1 - include/svs/concurrent/README.md | 4 ---- include/svs/concurrent/dynamic_index.h | 1 - include/svs/core/translation.h | 4 ---- 4 files changed, 10 deletions(-) diff --git a/bindings/c/src/index_vamana.hpp b/bindings/c/src/index_vamana.hpp index 096fa0f88..7aa643d27 100644 --- a/bindings/c/src/index_vamana.hpp +++ b/bindings/c/src/index_vamana.hpp @@ -180,7 +180,6 @@ struct ConcurrentIndexVamana : public DynamicIndexVamana { size_t delete_points(std::span ids) override; - // Does not consolidate or compact; the index blocks its own writers while saving. void save(const std::filesystem::path& directory) override { auto lock = read_lock(); index.save(directory / "config", directory / "graph", directory / "data"); diff --git a/include/svs/concurrent/README.md b/include/svs/concurrent/README.md index ae7ed032c..8a946dc43 100644 --- a/include/svs/concurrent/README.md +++ b/include/svs/concurrent/README.md @@ -163,10 +163,6 @@ section 3. Only shrinking is not. So `add_points`, `delete_entries`, and `consolidate` take this lock *shared*. Only `compact()` takes it exclusive, and so it waits for all of them. -**Why writers take `writers_mutex_` shared.** `add_points`, `delete_entries`, -`consolidate`, `compact` and `replace_external_id` take it first, once, and never -while holding another index lock. Searches do not take it. - **Lock order.** Always take locks in the same order. Then threads cannot deadlock. diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index 026f465c0..d4de01907 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -1764,7 +1764,6 @@ class MutableVamanaIndex { get_search_parameters()}; } - // 0.0.1 also stores the per-slot status. static constexpr lib::Version save_version = vamana::detail::dynamic_status_version; // Saves the slots as they are (holes included); does not consolidate or compact. diff --git a/include/svs/core/translation.h b/include/svs/core/translation.h index 059750bff..88b95311f 100644 --- a/include/svs/core/translation.h +++ b/include/svs/core/translation.h @@ -492,10 +492,6 @@ class IDTranslator { static IDTranslator load(const lib::LoadTable& table) { IDTranslator::validate(table); - // An empty translator is saved as an empty file, which open_read rejects. - if (lib::load_at(table, "num_points") == 0) { - return IDTranslator{}; - } // Now that we've more-or-less validated the metadata, time to start loading // the points. From e0ef0bc96819deecf65b53bf1526f96ec5abcd24 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Thu, 12 Nov 2026 15:05:43 -0800 Subject: [PATCH 03/15] Keep soft-deleted IDs when saving concurrent dynamic index --- include/svs/concurrent/dynamic_index.h | 36 ++++++++---------------- include/svs/index/vamana/dynamic_index.h | 16 +++++++++++ 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index d4de01907..bb88b03ab 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -457,7 +457,7 @@ class MutableVamanaIndex { /// /// * data.size() == graph.n_nodes() == status.size(). /// * ``status`` contains no ``Pending`` slots. - /// * ``translator`` maps exactly the ``Valid`` slots of ``status``. + /// * ``translator`` maps every ``Valid`` slot and no ``Empty`` slot of ``status``. template MutableVamanaIndex( const VamanaIndexParameters& config, @@ -523,17 +523,12 @@ class MutableVamanaIndex { status_[i] = s; } - if (translator_.size() != num_valid) { - throw ANNEXCEPTION( - "Translator has {} IDs but status has {} valid slots", - translator_.size(), - num_valid - ); - } for (auto pair : translator_) { - if (pair.second >= n || status[pair.second] != SlotMetadata::Valid) { + if (pair.second >= n || (status[pair.second] != SlotMetadata::Valid && + status[pair.second] != SlotMetadata::Deleted)) { throw ANNEXCEPTION( - "Translator maps external id {} to non-valid slot {}", + "Translator maps external id {} to slot {} that is not valid or " + "deleted", pair.first, pair.second ); @@ -1775,17 +1770,17 @@ class MutableVamanaIndex { ) { std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; std::unique_lock writers_lock{*writers_mutex_}; - auto [status, translator] = snapshot_for_save(); + auto status = status_bytes_for_save(); vamana::detail::write_dynamic_index( - *this, translator, &status, config_directory, graph_directory, data_directory + *this, translator_, &status, config_directory, graph_directory, data_directory ); } void save(std::ostream& os) { std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; std::unique_lock writers_lock{*writers_mutex_}; - auto [status, translator] = snapshot_for_save(); - vamana::detail::write_dynamic_index(*this, translator, &status, os); + auto status = status_bytes_for_save(); + vamana::detail::write_dynamic_index(*this, translator_, &status, os); } ///// @@ -1907,11 +1902,9 @@ class MutableVamanaIndex { // Not synchronized: callers must exclude concurrent mutation. const IDTranslator& view_translator() const { return translator_; } - // Slot status bytes and a translator holding only the Valid slots. The caller holds - // writers_mutex_ exclusive. - std::pair, IDTranslator> snapshot_for_save() const { + // Slot status bytes. The caller holds writers_mutex_ exclusive. + std::vector status_bytes_for_save() const { auto status = std::vector{}; - auto translator = IDTranslator{}; auto slots = status_snapshot(); status.reserve(slots.size()); for (size_t i = 0, imax = slots.size(); i < imax; ++i) { @@ -1920,12 +1913,7 @@ class MutableVamanaIndex { } status.push_back(static_cast(slots[i])); } - for (auto pair : translator_) { - if (slots.at(pair.second) == SlotMetadata::Valid) { - translator.insert_translation(pair.first, pair.second); - } - } - return {std::move(status), std::move(translator)}; + return status; } // Not synchronized: callers must exclude concurrent mutation. diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 19cea316f..fa8139384 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -1559,6 +1559,20 @@ std::vector decode_slot_status(const std::vector& raw) { return result; } +// Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them on delete. +template +void drop_non_valid_translations( + IDTranslator& translator, const std::vector& status +) { + auto to_drop = std::vector(); + for (auto pair : translator) { + if (pair.second < status.size() && status[pair.second] != Metadata::Valid) { + to_drop.push_back(pair.second); + } + } + translator.delete_internal(to_drop, false); +} + // The translator must cover exactly the `Valid` slots. template void check_translator_matches_status( @@ -1788,6 +1802,7 @@ auto auto_dynamic_assemble( } // Copied state may contain deleted or empty slots. + detail::drop_non_valid_translations(translator, status); detail::check_translator_matches_status(translator, status); // At this point, we should be completely validated. @@ -1839,6 +1854,7 @@ auto auto_dynamic_assemble( "Status has {} entries but should have {}", status.size(), datasize ); } + detail::drop_non_valid_translations(translator, status); detail::check_translator_matches_status(translator, status); auto threadpool = threads::as_threadpool(std::move(threadpool_proto)); From 60472b3ce4efc0e12a23433c6d8dcf35e3a86cea Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Thu, 12 Nov 2026 15:11:42 -0800 Subject: [PATCH 04/15] C API: add svs_index_load_stream_dynamic_ex --- bindings/c/docs/C_API_Design.md | 5 +- bindings/c/include/svs/c/svs_c.h | 21 +++++++ .../c/src/dispatcher_concurrent_vamana.cpp | 60 ++++++++++++++++++- .../c/src/dispatcher_concurrent_vamana.hpp | 11 ++++ bindings/c/src/index_builder.cpp | 40 +++++++------ bindings/c/src/svs_c.cpp | 34 +++++++++++ 6 files changed, 151 insertions(+), 20 deletions(-) diff --git a/bindings/c/docs/C_API_Design.md b/bindings/c/docs/C_API_Design.md index c48b476e0..a45af6a93 100644 --- a/bindings/c/docs/C_API_Design.md +++ b/bindings/c/docs/C_API_Design.md @@ -258,7 +258,8 @@ The main search structure providing vector similarity search operations. **Dynamic Index Parameters:** The `_ex` variants of the dynamic functions (`svs_index_build_dynamic_ex`, -`svs_index_load_dynamic_ex`, `svs_index_convert_dynamic_ex`, +`svs_index_load_dynamic_ex`, `svs_index_load_stream_dynamic_ex`, +`svs_index_convert_dynamic_ex`, `svs_index_builder_estimate_memory_dynamic_ex`, `svs_index_builder_estimate_search_memory_dynamic_ex`) take a versioned `const svs_dynamic_index_params_t*` instead of a bare `blocksize_bytes` argument. @@ -654,7 +655,7 @@ for full signatures, parameters, and Doxygen documentation. | **Search params** | `svs_search_params_create_vamana`, `svs_search_params_free` | | **Builder** | `svs_index_builder_create`, `svs_index_builder_set_{storage,threadpool,threadpool_custom,allocator,allocator_custom}`, `svs_index_builder_free` | | **Memory estimation** | `svs_index_builder_estimate_memory`, `svs_index_builder_estimate_memory_dynamic[_ex]`, `svs_index_builder_estimate_search_memory`, `svs_index_builder_estimate_search_memory_dynamic[_ex]`, `svs_index_builder_get_default_blocksize_bytes` | -| **Index lifecycle** | `svs_index_build`, `svs_index_build_dynamic[_ex]`, `svs_index_convert`, `svs_index_convert_dynamic[_ex]`, `svs_index_load`, `svs_index_load_dynamic[_ex]`, `svs_index_load_stream`, `svs_index_load_stream_dynamic`, `svs_index_save`, `svs_index_save_stream`, `svs_index_free` | +| **Index lifecycle** | `svs_index_build`, `svs_index_build_dynamic[_ex]`, `svs_index_convert`, `svs_index_convert_dynamic[_ex]`, `svs_index_load`, `svs_index_load_dynamic[_ex]`, `svs_index_load_stream`, `svs_index_load_stream_dynamic[_ex]`, `svs_index_save`, `svs_index_save_stream`, `svs_index_free` | | **Dynamic ops** | `svs_index_dynamic_{add_points,delete_points,has_id,consolidate,compact,get_sync_kind}` | | **Introspection** | `svs_index_get_num_threads` / `set_num_threads`, `svs_index_get_distance`, `svs_index_reconstruct`, `svs_index_get_memory_usage`, `svs_index_get_memory_breakdown` | | **Search** | `svs_index_search_topk` (+ deprecated `svs_index_search`), `svs_search_results_free` | diff --git a/bindings/c/include/svs/c/svs_c.h b/bindings/c/include/svs/c/svs_c.h index d85f01f1d..a00423a9d 100644 --- a/bindings/c/include/svs/c/svs_c.h +++ b/bindings/c/include/svs/c/svs_c.h @@ -1413,6 +1413,27 @@ SVS_API svs_index_h svs_index_load_stream_dynamic( svs_error_h out_err /*=NULL*/ ); +/// @brief Load a dynamic index from a caller-supplied stream with explicit parameters +/// @param builder The index builder handle (used for configuration) +/// @param stream The stream interface to read the index from +/// @param params Pointer to the dynamic index parameters structure, or NULL for defaults +/// @param out_err An optional error handle to capture errors +/// @return A handle to the loaded dynamic index +/// @remarks The block parameters only affect the in-memory layout, not the on-disk +/// format. The sync kind is not persisted with the index and must be passed on every load. +/// @remarks The operations table is copied, but @p stream->self is retained as-is. It only +/// needs to remain valid until this function returns. +/// @remarks Accepts both the native stream encoding and a packed directory archive. The +/// native encoding carries no total length, so a load may read up to 64 KiB past the end +/// of the index; frame the payload if embedding it in a larger stream. +/// @error SVS_ERROR_INVALID_ARGUMENT if @p params is invalid (see svs_dynamic_index_params) +SVS_API svs_index_h svs_index_load_stream_dynamic_ex( + svs_index_builder_h builder, + svs_stream_i stream, + const svs_dynamic_index_params_t* params /*=NULL*/, + svs_error_h out_err /*=NULL*/ +); + /// @brief Convert an index using new builder configuration /// @param builder The index builder handle (used for configuration) /// @param src_index The source index handle to convert from diff --git a/bindings/c/src/dispatcher_concurrent_vamana.cpp b/bindings/c/src/dispatcher_concurrent_vamana.cpp index af6daa95c..36e67a362 100644 --- a/bindings/c/src/dispatcher_concurrent_vamana.cpp +++ b/bindings/c/src/dispatcher_concurrent_vamana.cpp @@ -32,6 +32,8 @@ #include #include +#include +#include #include #include #include @@ -196,9 +198,38 @@ svs::DynamicVamana load_concurrent_vamana_index( ); } +template +svs::DynamicVamana load_stream_concurrent_vamana_index( + const svs::index::vamana::VamanaBuildParameters& SVS_UNUSED(build_params), + std::unique_ptr stream, + DataLoader SVS_UNUSED(loader), + Distance D, + svs::threads::ThreadPoolHandle pool, + const AllocatorBuilder& allocator_builder, + const svs::data::BlockingParameters& block_params, + svs::logging::logger_ptr logger +) { + using allocator_type = typename DataLoader::allocator_type; + using value_type = typename allocator_type::value_type; + using data_type = typename DataLoader::data_type; + auto allocator = allocator_type{block_params, allocator_builder.build()}; + auto graph_allocator = ConcurrentGraphAllocator{ + block_params, allocator_builder.build_for_graph()}; + + return svs::ConcurrentDynamicVamana::assemble( + *stream, + svs::make_stream_loader(graph_allocator), + svs::make_stream_loader(allocator), + std::move(D), + std::move(pool), + std::move(logger) + ); +} + using ConcurrentVamanaSource = std::variant< std::pair, std::span>, - std::filesystem::path>; + std::filesystem::path, + std::unique_ptr>; using BuildConcurrentIndexDispatcher = svs::lib::Dispatcher< svs::DynamicVamana, @@ -221,10 +252,15 @@ const BuildConcurrentIndexDispatcher& build_concurrent_vamana_index_dispatcher() d.register_target(&load_concurrent_vamana_index); }; + auto load_stream_closure = [&d]() { + d.register_target(&load_stream_concurrent_vamana_index); + }; + constexpr auto kind = ConcurrentVamanaFlavor::block_kind; for_all_specializations(build_closure); for_all_specializations(load_closure); + for_all_specializations(load_stream_closure); return d; }(); return dispatcher; @@ -293,6 +329,28 @@ svs::DynamicVamana dispatch_concurrent_vamana_index_load( ); } +svs::DynamicVamana dispatch_concurrent_vamana_index_load_stream( + const svs::index::vamana::VamanaBuildParameters& build_params, + std::unique_ptr stream, + const Storage* storage, + svs::DistanceType distance_type, + svs::threads::ThreadPoolHandle pool, + const AllocatorBuilder& allocator_builder, + const svs::data::BlockingParameters& block_params, + svs::logging::logger_ptr logger +) { + return build_concurrent_vamana_index_dispatcher().invoke( + build_params, + ConcurrentVamanaSource{std::move(stream)}, + storage, + distance_type, + std::move(pool), + allocator_builder, + block_params, + std::move(logger) + ); +} + svs::DynamicVamana dispatch_concurrent_vamana_index_copy( const svs::index::vamana::VamanaBuildParameters& build_params, const svs::DynamicVamana& src_index, diff --git a/bindings/c/src/dispatcher_concurrent_vamana.hpp b/bindings/c/src/dispatcher_concurrent_vamana.hpp index 0710e88bb..59f366dba 100644 --- a/bindings/c/src/dispatcher_concurrent_vamana.hpp +++ b/bindings/c/src/dispatcher_concurrent_vamana.hpp @@ -53,6 +53,17 @@ svs::DynamicVamana dispatch_concurrent_vamana_index_load( svs::logging::logger_ptr logger ); +svs::DynamicVamana dispatch_concurrent_vamana_index_load_stream( + const svs::index::vamana::VamanaBuildParameters& build_params, + std::unique_ptr stream, + const Storage* storage, + svs::DistanceType distance_type, + svs::threads::ThreadPoolHandle pool, + const AllocatorBuilder& allocator_builder, + const svs::data::BlockingParameters& block_params, + svs::logging::logger_ptr logger +); + // Copies between a concurrent and a regular or concurrent dynamic index; // at least one of `src_concurrent` and `dst_concurrent` must be true. svs::DynamicVamana dispatch_concurrent_vamana_index_copy( diff --git a/bindings/c/src/index_builder.cpp b/bindings/c/src/index_builder.cpp index 89ae15ba0..ee971365e 100644 --- a/bindings/c/src/index_builder.cpp +++ b/bindings/c/src/index_builder.cpp @@ -346,23 +346,29 @@ std::shared_ptr IndexBuilder::load_stream_dynamic( ) { if (algorithm->type == SVS_ALGORITHM_TYPE_VAMANA) { auto vamana_algorithm = static_cast(algorithm.get()); - - auto index = std::make_shared( - *this, - dispatch_dynamic_vamana_index_load_stream( - vamana_algorithm->build_parameters(), - std::move(stream), - storage.get(), - to_distance_type(distance_metric), - pool_builder.build(sync_kind), - allocator_builder, - block_params, - get_logger() - ), - sync_kind - ); - - return index; + const auto& build_params = vamana_algorithm->build_parameters(); + auto index = uses_concurrent_index(sync_kind) + ? dispatch_concurrent_vamana_index_load_stream( + build_params, + std::move(stream), + storage.get(), + to_distance_type(distance_metric), + pool_builder.build(sync_kind), + allocator_builder, + block_params, + get_logger() + ) + : dispatch_dynamic_vamana_index_load_stream( + build_params, + std::move(stream), + storage.get(), + to_distance_type(distance_metric), + pool_builder.build(sync_kind), + allocator_builder, + block_params, + get_logger() + ); + return make_dynamic_index(*this, std::move(index), sync_kind); } return nullptr; } diff --git a/bindings/c/src/svs_c.cpp b/bindings/c/src/svs_c.cpp index 6718861bf..5a549b3c4 100644 --- a/bindings/c/src/svs_c.cpp +++ b/bindings/c/src/svs_c.cpp @@ -1245,6 +1245,40 @@ extern "C" svs_index_h svs_index_load_stream_dynamic( ); } +extern "C" svs_index_h svs_index_load_stream_dynamic_ex( + svs_index_builder_h builder, + svs_stream_i stream, + const svs_dynamic_index_params_t* params, + svs_error_h out_err +) { + using namespace svs::c_runtime; + return wrap_exceptions( + [&]() { + EXPECT_ARG_NOT_NULL(builder); + EXPECT_ARG_NOT_NULL(stream); + NOT_IMPLEMENTED_IF( + (builder->impl->algorithm->type != SVS_ALGORITHM_TYPE_VAMANA), + "Only Vamana algorithm is currently supported for dynamic index loading" + ); + StreamBuf::validate(stream, /*need_write=*/false); + auto dynamic_params = read_dynamic_index_params(params); + auto index = builder->impl->load_stream_dynamic( + std::make_unique(*stream->ops, stream->self), + dynamic_params.block_params, + dynamic_params.sync_kind + ); + if (index == nullptr) { + SET_ERROR(out_err, SVS_ERROR_RUNTIME, "Dynamic index load failed"); + return svs_index_h{nullptr}; + } + auto result = new svs_index; + result->impl = index; + return result; + }, + out_err + ); +} + extern "C" svs_index_h svs_index_convert(svs_index_builder_h builder, svs_index_h src_index, svs_error_h out_err) { using namespace svs::c_runtime; From 2fd3fee57ed30e0f9a8adbcb89df30d77d406861 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Thu, 12 Nov 2026 15:34:02 -0800 Subject: [PATCH 05/15] Drop only soft-deleted mappings when loading into the non-concurrent index --- include/svs/index/vamana/dynamic_index.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index fa8139384..af26c4342 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -116,7 +116,7 @@ namespace detail { inline constexpr lib::Version dynamic_status_version = lib::Version(0, 0, 1); // Writes the index as-is. If `status` is given (one byte per slot), it is saved too and -// `translator` must only map `Valid` slots. +// `translator` may also map `Deleted` slots. template void write_dynamic_index( Index& index, @@ -1561,12 +1561,12 @@ std::vector decode_slot_status(const std::vector& raw) { // Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them on delete. template -void drop_non_valid_translations( +void drop_deleted_translations( IDTranslator& translator, const std::vector& status ) { auto to_drop = std::vector(); for (auto pair : translator) { - if (pair.second < status.size() && status[pair.second] != Metadata::Valid) { + if (pair.second < status.size() && status[pair.second] == Metadata::Deleted) { to_drop.push_back(pair.second); } } @@ -1802,7 +1802,7 @@ auto auto_dynamic_assemble( } // Copied state may contain deleted or empty slots. - detail::drop_non_valid_translations(translator, status); + detail::drop_deleted_translations(translator, status); detail::check_translator_matches_status(translator, status); // At this point, we should be completely validated. @@ -1854,7 +1854,7 @@ auto auto_dynamic_assemble( "Status has {} entries but should have {}", status.size(), datasize ); } - detail::drop_non_valid_translations(translator, status); + detail::drop_deleted_translations(translator, status); detail::check_translator_matches_status(translator, status); auto threadpool = threads::as_threadpool(std::move(threadpool_proto)); From e79523e2b665714fdb1f9db9026bfa5ca5df3416 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Fri, 13 Nov 2026 14:24:55 -0800 Subject: [PATCH 06/15] Keep save/load logic in place; branch on index type --- include/svs/concurrent/dynamic_index.h | 52 +++-- include/svs/index/vamana/dynamic_index.h | 255 +++++++++++------------ 2 files changed, 157 insertions(+), 150 deletions(-) diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index bb88b03ab..c7d978a64 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -182,6 +182,7 @@ class MutableVamanaIndex { static constexpr bool supports_deletions = true; static constexpr bool supports_saving = true; static constexpr bool needs_id_translation = true; + static constexpr bool saves_slot_status = true; // Type Aliases using Idx = typename Graph::index_type; @@ -1759,9 +1760,14 @@ class MutableVamanaIndex { get_search_parameters()}; } - static constexpr lib::Version save_version = vamana::detail::dynamic_status_version; + // Change notes: + // + // v0.0.0 - Initial version + // v0.0.1 - Save the status of every slot. The index is saved as it is, without + // consolidating or compacting, and soft-deleted IDs stay mapped. + // * Behavior if loading from v0.0.0: All slots are `Valid`. + static constexpr lib::Version save_version = lib::Version(0, 0, 1); - // Saves the slots as they are (holes included); does not consolidate or compact. // Blocks writers while saving; searches may continue. void save( const std::filesystem::path& config_directory, @@ -1770,17 +1776,15 @@ class MutableVamanaIndex { ) { std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; std::unique_lock writers_lock{*writers_mutex_}; - auto status = status_bytes_for_save(); - vamana::detail::write_dynamic_index( - *this, translator_, &status, config_directory, graph_directory, data_directory + vamana::detail::save_dynamic_index( + *this, config_directory, graph_directory, data_directory ); } void save(std::ostream& os) { std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; std::unique_lock writers_lock{*writers_mutex_}; - auto status = status_bytes_for_save(); - vamana::detail::write_dynamic_index(*this, translator_, &status, os); + vamana::detail::save_dynamic_index(*this, os); } ///// @@ -2363,9 +2367,31 @@ auto auto_dynamic_assemble( bool SVS_UNUSED(debug_load_from_static) = false, svs::logging::logger_ptr logger = svs::logging::get() ) { - // Read the combined TOML (parameters + translation + status) and the binary data. - auto [parameters, translator, status] = - vamana::detail::load_stream_state(is); + // Read the combined TOML (parameters + translation + status) + // and the translator binary data. + auto table = lib::detail::read_metadata(is); + auto version = table.template cast().version(); + if (version != lib::Version(0, 0, 0) && version != lib::Version(0, 0, 1)) { + throw ANNEXCEPTION("Unsupported dynamic index stream version {}", version); + } + + auto parameters = lib::load( + table.template cast().at("parameters").template cast() + ); + + auto translation = + table.template cast().at("translation").template cast(); + + auto translator = IDTranslator::load(translation, is); + + auto status = std::vector(); + if (version == lib::Version(0, 0, 1)) { + auto raw = std::vector( + lib::load_at(table.template cast(), "num_status") + ); + lib::read_binary(is, raw); + status = vamana::detail::decode_slot_status(raw); + } auto data = data_loader(); auto graph = graph_loader(); @@ -2378,8 +2404,8 @@ auto auto_dynamic_assemble( ); } - if (!status) { - status.emplace(datasize, SlotMetadata::Valid); + if (version == lib::Version(0, 0, 0)) { + status.assign(datasize, SlotMetadata::Valid); } auto threadpool = threads::as_threadpool(std::move(threadpool_proto)); @@ -2388,7 +2414,7 @@ auto auto_dynamic_assemble( std::move(data), std::move(graph), std::move(distance), - *status, + std::move(status), std::move(translator), std::move(threadpool), std::move(logger)}; diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index af26c4342..27d3d287b 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -19,7 +19,6 @@ // stdlib #include #include -#include #include // Include the flat index to spin-up exhaustive searches on demand. @@ -112,20 +111,24 @@ class ValidBuilder { namespace detail { -// Version of "vamana_dynamic_auxiliary_parameters" that also stores per-slot status. -inline constexpr lib::Version dynamic_status_version = lib::Version(0, 0, 1); - -// Writes the index as-is. If `status` is given (one byte per slot), it is saved too and -// `translator` may also map `Deleted` slots. template -void write_dynamic_index( +void save_dynamic_index( Index& index, - const IDTranslator& translator, - const std::vector* status, const std::filesystem::path& config_directory, const std::filesystem::path& graph_directory, const std::filesystem::path& data_directory ) { + // Post-consolidation, all entries should be "valid". + // Therefore, we don't need to save the slot metadata. + if constexpr (!Index::saves_slot_status) { + index.consolidate(); + index.compact(); + } + std::vector status; + if constexpr (Index::saves_slot_status) { + status = index.status_bytes_for_save(); + } + // Save auxiliary data structures. lib::save_to_disk( lib::SaveOverride([&](const lib::SaveContext& ctx) { @@ -136,11 +139,11 @@ void write_dynamic_index( { {"name", lib::save(index.name())}, {"parameters", lib::save(index.parameters(), ctx)}, - {"translation", lib::save(translator, ctx)}, + {"translation", lib::save(index.view_translator(), ctx)}, } ); - if (status != nullptr) { - table.insert("status", lib::save(lib::BinaryBlobSaver(*status), ctx)); + if constexpr (Index::saves_slot_status) { + table.insert("status", lib::save(lib::BinaryBlobSaver(status), ctx)); } return table; }), @@ -153,13 +156,18 @@ void write_dynamic_index( lib::save_to_disk(index.view_graph(), graph_directory); } -template -void write_dynamic_index( - Index& index, - const IDTranslator& translator, - const std::vector* status, - std::ostream& os -) { +template void save_dynamic_index(Index& index, std::ostream& os) { + // Post-consolidation, all entries should be "valid". + // Therefore, we don't need to save the slot metadata. + if constexpr (!Index::saves_slot_status) { + index.consolidate(); + index.compact(); + } + std::vector status; + if constexpr (Index::saves_slot_status) { + status = index.status_bytes_for_save(); + } + lib::begin_serialization(os); auto save_table = lib::SaveTable( "vamana_dynamic_auxiliary_parameters", @@ -167,16 +175,16 @@ void write_dynamic_index( { {"name", lib::save(index.name())}, {"parameters", lib::save(index.parameters())}, - {"translation", lib::detail::exit_hook(translator.metadata())}, + {"translation", lib::detail::exit_hook(index.view_translator().metadata())}, } ); - if (status != nullptr) { - save_table.insert("num_status", lib::save(status->size())); + if constexpr (Index::saves_slot_status) { + save_table.insert("num_status", lib::save(status.size())); } lib::save_to_stream(save_table, os); - translator.save(os); - if (status != nullptr) { - lib::write_binary(os, *status); + index.view_translator().save(os); + if constexpr (Index::saves_slot_status) { + lib::write_binary(os, status); } // Save the dataset. @@ -185,35 +193,6 @@ void write_dynamic_index( lib::save_to_stream(index.view_graph(), os); } -template -void save_dynamic_index( - Index& index, - const std::filesystem::path& config_directory, - const std::filesystem::path& graph_directory, - const std::filesystem::path& data_directory -) { - // Post-consolidation, all entries should be "valid". - // Therefore, we don't need to save the slot metadata. - index.consolidate(); - index.compact(); - write_dynamic_index( - index, - index.view_translator(), - nullptr, - config_directory, - graph_directory, - data_directory - ); -} - -template void save_dynamic_index(Index& index, std::ostream& os) { - // Post-consolidation, all entries should be "valid". - // Therefore, we don't need to save the slot metadata. - index.consolidate(); - index.compact(); - write_dynamic_index(index, index.view_translator(), nullptr, os); -} - template < typename Index, data::ImmutableMemoryDataset Queries, @@ -266,6 +245,7 @@ class MutableVamanaIndex { static constexpr bool supports_deletions = true; static constexpr bool supports_saving = true; static constexpr bool needs_id_translation = true; + static constexpr bool saves_slot_status = false; // Type Aliases using Idx = typename Graph::index_type; @@ -1559,47 +1539,6 @@ std::vector decode_slot_status(const std::vector& raw) { return result; } -// Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them on delete. -template -void drop_deleted_translations( - IDTranslator& translator, const std::vector& status -) { - auto to_drop = std::vector(); - for (auto pair : translator) { - if (pair.second < status.size() && status[pair.second] == Metadata::Deleted) { - to_drop.push_back(pair.second); - } - } - translator.delete_internal(to_drop, false); -} - -// The translator must cover exactly the `Valid` slots. -template -void check_translator_matches_status( - const IDTranslator& translator, const std::vector& status -) { - size_t num_valid = 0; - for (size_t i = 0, imax = status.size(); i < imax; ++i) { - if (status[i] == Metadata::Valid) { - ++num_valid; - if (!translator.has_internal(i)) { - throw ANNEXCEPTION("Translator is missing internal id {}", i); - } - } - } - - auto translator_size = translator.size(); - if (translator_size != num_valid) { - throw ANNEXCEPTION( - "Translator has {} IDs but should have {}", translator_size, num_valid - ); - } -} - -inline bool is_supported_dynamic_version(const lib::Version& version) { - return version == lib::Version(0, 0, 0) || version == dynamic_status_version; -} - template struct VamanaStateLoader { ///// Loading static bool @@ -1607,7 +1546,7 @@ template struct VamanaStateLoader { // We provide the option to load from a static index. return VamanaIndexParameters::check_load_compatibility(schema, version) || (schema == "vamana_dynamic_auxiliary_parameters" && - is_supported_dynamic_version(version)); + (version == lib::Version(0, 0, 0) || version == lib::Version(0, 0, 1))); } // Provide a compatibility path for loading static datasets. @@ -1621,7 +1560,7 @@ template struct VamanaStateLoader { } auto status = std::vector(assume_datasize, Metadata::Valid); - if (table.version() == dynamic_status_version) { + if (table.version() == lib::Version(0, 0, 1)) { std::vector raw = lib::load_at>(table, "status"); if (raw.size() != assume_datasize) { @@ -1645,36 +1584,6 @@ template struct VamanaStateLoader { std::vector status_; }; -// Contents of a stream before the dataset: parameters, translator and (version 0.0.1) -// slot status. `status` is empty for version 0.0.0, where every slot is `Valid`. -template struct StreamState { - VamanaIndexParameters parameters; - IDTranslator translator; - std::optional> status; -}; - -template StreamState load_stream_state(std::istream& is) { - auto table = lib::detail::read_metadata(is); - auto root = table.template cast(); - if (!is_supported_dynamic_version(root.version())) { - throw ANNEXCEPTION("Unsupported dynamic index stream version {}", root.version()); - } - - auto parameters = - lib::load(root.at("parameters").template cast() - ); - auto translator = - IDTranslator::load(root.at("translation").template cast(), is); - - std::optional> status{}; - if (root.version() == dynamic_status_version) { - auto raw = std::vector(lib::load_at(root, "num_status")); - lib::read_binary(is, raw); - status = decode_slot_status(raw); - } - return {std::move(parameters), std::move(translator), std::move(status)}; -} - template VamanaStateLoader auto_load_state( ConfigProto&& config_proto, @@ -1801,9 +1710,33 @@ auto auto_dynamic_assemble( ); } - // Copied state may contain deleted or empty slots. - detail::drop_deleted_translations(translator, status); - detail::check_translator_matches_status(translator, status); + // Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them. + auto to_drop = std::vector(); + for (auto pair : translator) { + if (pair.second < datasize && status[pair.second] == SlotMetadata::Deleted) { + to_drop.push_back(pair.second); + } + } + translator.delete_internal(to_drop, false); + + // The translator must cover exactly the valid slots; copied state may contain + // deleted or empty slots. + size_t num_valid = 0; + for (size_t i = 0; i < datasize; ++i) { + if (status[i] == SlotMetadata::Valid) { + ++num_valid; + if (!translator.has_internal(i)) { + throw ANNEXCEPTION("Translator is missing internal id {}", i); + } + } + } + + auto translator_size = translator.size(); + if (translator_size != num_valid) { + throw ANNEXCEPTION( + "Translator has {} IDs but should have {}", translator_size, num_valid + ); + } // At this point, we should be completely validated. // Construct the index! @@ -1832,9 +1765,31 @@ auto auto_dynamic_assemble( bool SVS_UNUSED(debug_load_from_static) = false, svs::logging::logger_ptr logger = svs::logging::get() ) { - // Read the combined TOML (parameters + translation + status) and the binary data. - auto [parameters, translator, loaded_status] = - detail::load_stream_state(is); + // Read the combined TOML (parameters + translation + status) + // and the translator binary data. + auto table = lib::detail::read_metadata(is); + auto version = table.template cast().version(); + if (version != lib::Version(0, 0, 0) && version != lib::Version(0, 0, 1)) { + throw ANNEXCEPTION("Unsupported dynamic index stream version {}", version); + } + + auto parameters = lib::load( + table.template cast().at("parameters").template cast() + ); + + auto translation = + table.template cast().at("translation").template cast(); + + auto translator = IDTranslator::load(translation, is); + + auto status = std::vector(); + if (version == lib::Version(0, 0, 1)) { + auto raw = std::vector( + lib::load_at(table.template cast(), "num_status") + ); + lib::read_binary(is, raw); + status = detail::decode_slot_status(raw); + } auto data = data_loader(); auto graph = graph_loader(); @@ -1847,15 +1802,41 @@ auto auto_dynamic_assemble( ); } - auto status = - loaded_status.value_or(std::vector(datasize, SlotMetadata::Valid)); + if (version == lib::Version(0, 0, 0)) { + status.assign(datasize, SlotMetadata::Valid); + } if (status.size() != datasize) { throw ANNEXCEPTION( "Status has {} entries but should have {}", status.size(), datasize ); } - detail::drop_deleted_translations(translator, status); - detail::check_translator_matches_status(translator, status); + + // Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them. + auto to_drop = std::vector(); + for (auto pair : translator) { + if (pair.second < datasize && status[pair.second] == SlotMetadata::Deleted) { + to_drop.push_back(pair.second); + } + } + translator.delete_internal(to_drop, false); + + // The translator must cover exactly the valid slots. + size_t num_valid = 0; + for (size_t i = 0; i < datasize; ++i) { + if (status[i] == SlotMetadata::Valid) { + ++num_valid; + if (!translator.has_internal(i)) { + throw ANNEXCEPTION("Translator is missing internal id {}", i); + } + } + } + + auto translator_size = translator.size(); + if (translator_size != num_valid) { + throw ANNEXCEPTION( + "Translator has {} IDs but should have {}", translator_size, num_valid + ); + } auto threadpool = threads::as_threadpool(std::move(threadpool_proto)); return MutableVamanaIndex{ From 80537860b0af700e3dad88d1d3f5a84b52618af5 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Fri, 13 Nov 2026 14:34:41 -0800 Subject: [PATCH 07/15] Move the consolidate comment into the non-concurrent branch --- include/svs/index/vamana/dynamic_index.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 27d3d287b..5cf718654 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -118,9 +118,9 @@ void save_dynamic_index( const std::filesystem::path& graph_directory, const std::filesystem::path& data_directory ) { - // Post-consolidation, all entries should be "valid". - // Therefore, we don't need to save the slot metadata. if constexpr (!Index::saves_slot_status) { + // Post-consolidation, all entries should be "valid". + // Therefore, we don't need to save the slot metadata. index.consolidate(); index.compact(); } @@ -157,9 +157,9 @@ void save_dynamic_index( } template void save_dynamic_index(Index& index, std::ostream& os) { - // Post-consolidation, all entries should be "valid". - // Therefore, we don't need to save the slot metadata. if constexpr (!Index::saves_slot_status) { + // Post-consolidation, all entries should be "valid". + // Therefore, we don't need to save the slot metadata. index.consolidate(); index.compact(); } From 292f21ae23e682df81625b3759973a780459aa61 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 11:17:39 -0800 Subject: [PATCH 08/15] Move svs_index_load_stream_dynamic_ex to a separate PR --- bindings/c/docs/C_API_Design.md | 5 +- bindings/c/include/svs/c/svs_c.h | 21 ------- .../c/src/dispatcher_concurrent_vamana.cpp | 60 +------------------ .../c/src/dispatcher_concurrent_vamana.hpp | 11 ---- bindings/c/src/index_builder.cpp | 40 ++++++------- bindings/c/src/svs_c.cpp | 34 ----------- 6 files changed, 20 insertions(+), 151 deletions(-) diff --git a/bindings/c/docs/C_API_Design.md b/bindings/c/docs/C_API_Design.md index a45af6a93..c48b476e0 100644 --- a/bindings/c/docs/C_API_Design.md +++ b/bindings/c/docs/C_API_Design.md @@ -258,8 +258,7 @@ The main search structure providing vector similarity search operations. **Dynamic Index Parameters:** The `_ex` variants of the dynamic functions (`svs_index_build_dynamic_ex`, -`svs_index_load_dynamic_ex`, `svs_index_load_stream_dynamic_ex`, -`svs_index_convert_dynamic_ex`, +`svs_index_load_dynamic_ex`, `svs_index_convert_dynamic_ex`, `svs_index_builder_estimate_memory_dynamic_ex`, `svs_index_builder_estimate_search_memory_dynamic_ex`) take a versioned `const svs_dynamic_index_params_t*` instead of a bare `blocksize_bytes` argument. @@ -655,7 +654,7 @@ for full signatures, parameters, and Doxygen documentation. | **Search params** | `svs_search_params_create_vamana`, `svs_search_params_free` | | **Builder** | `svs_index_builder_create`, `svs_index_builder_set_{storage,threadpool,threadpool_custom,allocator,allocator_custom}`, `svs_index_builder_free` | | **Memory estimation** | `svs_index_builder_estimate_memory`, `svs_index_builder_estimate_memory_dynamic[_ex]`, `svs_index_builder_estimate_search_memory`, `svs_index_builder_estimate_search_memory_dynamic[_ex]`, `svs_index_builder_get_default_blocksize_bytes` | -| **Index lifecycle** | `svs_index_build`, `svs_index_build_dynamic[_ex]`, `svs_index_convert`, `svs_index_convert_dynamic[_ex]`, `svs_index_load`, `svs_index_load_dynamic[_ex]`, `svs_index_load_stream`, `svs_index_load_stream_dynamic[_ex]`, `svs_index_save`, `svs_index_save_stream`, `svs_index_free` | +| **Index lifecycle** | `svs_index_build`, `svs_index_build_dynamic[_ex]`, `svs_index_convert`, `svs_index_convert_dynamic[_ex]`, `svs_index_load`, `svs_index_load_dynamic[_ex]`, `svs_index_load_stream`, `svs_index_load_stream_dynamic`, `svs_index_save`, `svs_index_save_stream`, `svs_index_free` | | **Dynamic ops** | `svs_index_dynamic_{add_points,delete_points,has_id,consolidate,compact,get_sync_kind}` | | **Introspection** | `svs_index_get_num_threads` / `set_num_threads`, `svs_index_get_distance`, `svs_index_reconstruct`, `svs_index_get_memory_usage`, `svs_index_get_memory_breakdown` | | **Search** | `svs_index_search_topk` (+ deprecated `svs_index_search`), `svs_search_results_free` | diff --git a/bindings/c/include/svs/c/svs_c.h b/bindings/c/include/svs/c/svs_c.h index a00423a9d..d85f01f1d 100644 --- a/bindings/c/include/svs/c/svs_c.h +++ b/bindings/c/include/svs/c/svs_c.h @@ -1413,27 +1413,6 @@ SVS_API svs_index_h svs_index_load_stream_dynamic( svs_error_h out_err /*=NULL*/ ); -/// @brief Load a dynamic index from a caller-supplied stream with explicit parameters -/// @param builder The index builder handle (used for configuration) -/// @param stream The stream interface to read the index from -/// @param params Pointer to the dynamic index parameters structure, or NULL for defaults -/// @param out_err An optional error handle to capture errors -/// @return A handle to the loaded dynamic index -/// @remarks The block parameters only affect the in-memory layout, not the on-disk -/// format. The sync kind is not persisted with the index and must be passed on every load. -/// @remarks The operations table is copied, but @p stream->self is retained as-is. It only -/// needs to remain valid until this function returns. -/// @remarks Accepts both the native stream encoding and a packed directory archive. The -/// native encoding carries no total length, so a load may read up to 64 KiB past the end -/// of the index; frame the payload if embedding it in a larger stream. -/// @error SVS_ERROR_INVALID_ARGUMENT if @p params is invalid (see svs_dynamic_index_params) -SVS_API svs_index_h svs_index_load_stream_dynamic_ex( - svs_index_builder_h builder, - svs_stream_i stream, - const svs_dynamic_index_params_t* params /*=NULL*/, - svs_error_h out_err /*=NULL*/ -); - /// @brief Convert an index using new builder configuration /// @param builder The index builder handle (used for configuration) /// @param src_index The source index handle to convert from diff --git a/bindings/c/src/dispatcher_concurrent_vamana.cpp b/bindings/c/src/dispatcher_concurrent_vamana.cpp index 36e67a362..af6daa95c 100644 --- a/bindings/c/src/dispatcher_concurrent_vamana.cpp +++ b/bindings/c/src/dispatcher_concurrent_vamana.cpp @@ -32,8 +32,6 @@ #include #include -#include -#include #include #include #include @@ -198,38 +196,9 @@ svs::DynamicVamana load_concurrent_vamana_index( ); } -template -svs::DynamicVamana load_stream_concurrent_vamana_index( - const svs::index::vamana::VamanaBuildParameters& SVS_UNUSED(build_params), - std::unique_ptr stream, - DataLoader SVS_UNUSED(loader), - Distance D, - svs::threads::ThreadPoolHandle pool, - const AllocatorBuilder& allocator_builder, - const svs::data::BlockingParameters& block_params, - svs::logging::logger_ptr logger -) { - using allocator_type = typename DataLoader::allocator_type; - using value_type = typename allocator_type::value_type; - using data_type = typename DataLoader::data_type; - auto allocator = allocator_type{block_params, allocator_builder.build()}; - auto graph_allocator = ConcurrentGraphAllocator{ - block_params, allocator_builder.build_for_graph()}; - - return svs::ConcurrentDynamicVamana::assemble( - *stream, - svs::make_stream_loader(graph_allocator), - svs::make_stream_loader(allocator), - std::move(D), - std::move(pool), - std::move(logger) - ); -} - using ConcurrentVamanaSource = std::variant< std::pair, std::span>, - std::filesystem::path, - std::unique_ptr>; + std::filesystem::path>; using BuildConcurrentIndexDispatcher = svs::lib::Dispatcher< svs::DynamicVamana, @@ -252,15 +221,10 @@ const BuildConcurrentIndexDispatcher& build_concurrent_vamana_index_dispatcher() d.register_target(&load_concurrent_vamana_index); }; - auto load_stream_closure = [&d]() { - d.register_target(&load_stream_concurrent_vamana_index); - }; - constexpr auto kind = ConcurrentVamanaFlavor::block_kind; for_all_specializations(build_closure); for_all_specializations(load_closure); - for_all_specializations(load_stream_closure); return d; }(); return dispatcher; @@ -329,28 +293,6 @@ svs::DynamicVamana dispatch_concurrent_vamana_index_load( ); } -svs::DynamicVamana dispatch_concurrent_vamana_index_load_stream( - const svs::index::vamana::VamanaBuildParameters& build_params, - std::unique_ptr stream, - const Storage* storage, - svs::DistanceType distance_type, - svs::threads::ThreadPoolHandle pool, - const AllocatorBuilder& allocator_builder, - const svs::data::BlockingParameters& block_params, - svs::logging::logger_ptr logger -) { - return build_concurrent_vamana_index_dispatcher().invoke( - build_params, - ConcurrentVamanaSource{std::move(stream)}, - storage, - distance_type, - std::move(pool), - allocator_builder, - block_params, - std::move(logger) - ); -} - svs::DynamicVamana dispatch_concurrent_vamana_index_copy( const svs::index::vamana::VamanaBuildParameters& build_params, const svs::DynamicVamana& src_index, diff --git a/bindings/c/src/dispatcher_concurrent_vamana.hpp b/bindings/c/src/dispatcher_concurrent_vamana.hpp index 59f366dba..0710e88bb 100644 --- a/bindings/c/src/dispatcher_concurrent_vamana.hpp +++ b/bindings/c/src/dispatcher_concurrent_vamana.hpp @@ -53,17 +53,6 @@ svs::DynamicVamana dispatch_concurrent_vamana_index_load( svs::logging::logger_ptr logger ); -svs::DynamicVamana dispatch_concurrent_vamana_index_load_stream( - const svs::index::vamana::VamanaBuildParameters& build_params, - std::unique_ptr stream, - const Storage* storage, - svs::DistanceType distance_type, - svs::threads::ThreadPoolHandle pool, - const AllocatorBuilder& allocator_builder, - const svs::data::BlockingParameters& block_params, - svs::logging::logger_ptr logger -); - // Copies between a concurrent and a regular or concurrent dynamic index; // at least one of `src_concurrent` and `dst_concurrent` must be true. svs::DynamicVamana dispatch_concurrent_vamana_index_copy( diff --git a/bindings/c/src/index_builder.cpp b/bindings/c/src/index_builder.cpp index ee971365e..89ae15ba0 100644 --- a/bindings/c/src/index_builder.cpp +++ b/bindings/c/src/index_builder.cpp @@ -346,29 +346,23 @@ std::shared_ptr IndexBuilder::load_stream_dynamic( ) { if (algorithm->type == SVS_ALGORITHM_TYPE_VAMANA) { auto vamana_algorithm = static_cast(algorithm.get()); - const auto& build_params = vamana_algorithm->build_parameters(); - auto index = uses_concurrent_index(sync_kind) - ? dispatch_concurrent_vamana_index_load_stream( - build_params, - std::move(stream), - storage.get(), - to_distance_type(distance_metric), - pool_builder.build(sync_kind), - allocator_builder, - block_params, - get_logger() - ) - : dispatch_dynamic_vamana_index_load_stream( - build_params, - std::move(stream), - storage.get(), - to_distance_type(distance_metric), - pool_builder.build(sync_kind), - allocator_builder, - block_params, - get_logger() - ); - return make_dynamic_index(*this, std::move(index), sync_kind); + + auto index = std::make_shared( + *this, + dispatch_dynamic_vamana_index_load_stream( + vamana_algorithm->build_parameters(), + std::move(stream), + storage.get(), + to_distance_type(distance_metric), + pool_builder.build(sync_kind), + allocator_builder, + block_params, + get_logger() + ), + sync_kind + ); + + return index; } return nullptr; } diff --git a/bindings/c/src/svs_c.cpp b/bindings/c/src/svs_c.cpp index 5a549b3c4..6718861bf 100644 --- a/bindings/c/src/svs_c.cpp +++ b/bindings/c/src/svs_c.cpp @@ -1245,40 +1245,6 @@ extern "C" svs_index_h svs_index_load_stream_dynamic( ); } -extern "C" svs_index_h svs_index_load_stream_dynamic_ex( - svs_index_builder_h builder, - svs_stream_i stream, - const svs_dynamic_index_params_t* params, - svs_error_h out_err -) { - using namespace svs::c_runtime; - return wrap_exceptions( - [&]() { - EXPECT_ARG_NOT_NULL(builder); - EXPECT_ARG_NOT_NULL(stream); - NOT_IMPLEMENTED_IF( - (builder->impl->algorithm->type != SVS_ALGORITHM_TYPE_VAMANA), - "Only Vamana algorithm is currently supported for dynamic index loading" - ); - StreamBuf::validate(stream, /*need_write=*/false); - auto dynamic_params = read_dynamic_index_params(params); - auto index = builder->impl->load_stream_dynamic( - std::make_unique(*stream->ops, stream->self), - dynamic_params.block_params, - dynamic_params.sync_kind - ); - if (index == nullptr) { - SET_ERROR(out_err, SVS_ERROR_RUNTIME, "Dynamic index load failed"); - return svs_index_h{nullptr}; - } - auto result = new svs_index; - result->impl = index; - return result; - }, - out_err - ); -} - extern "C" svs_index_h svs_index_convert(svs_index_builder_h builder, svs_index_h src_index, svs_error_h out_err) { using namespace svs::c_runtime; From ba02cae182267f3c97de185aa974815d03d34806 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 12:34:54 -0800 Subject: [PATCH 09/15] Test save/load of a consolidated but not compacted concurrent index --- tests/svs/concurrent/dynamic_index.cpp | 64 ++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/tests/svs/concurrent/dynamic_index.cpp b/tests/svs/concurrent/dynamic_index.cpp index 214dec205..eac5bfba2 100644 --- a/tests/svs/concurrent/dynamic_index.cpp +++ b/tests/svs/concurrent/dynamic_index.cpp @@ -565,6 +565,70 @@ CATCH_TEST_CASE( } } } + + CATCH_SECTION("Save keeps deleted and empty slots") { + // Ids [0, 100) are consolidated (Empty slots) but the index is not compacted; + // ids [200, 300) are soft-deleted (Deleted slots). + std::vector consolidated(100); + std::iota(consolidated.begin(), consolidated.end(), 0); + index.delete_entries(consolidated); + index.consolidate(); + std::vector soft_deleted(100); + std::iota(soft_deleted.begin(), soft_deleted.end(), 200); + index.delete_entries(soft_deleted); + + const auto status_before = index.status_snapshot(); + const auto num_slots = index.view_data().size(); + const auto size_before = index.size(); + CATCH_REQUIRE( + std::count( + status_before.begin(), status_before.end(), cc::SlotMetadata::Empty + ) > 0 + ); + CATCH_REQUIRE( + std::count( + status_before.begin(), status_before.end(), cc::SlotMetadata::Deleted + ) > 0 + ); + + std::stringstream stream; + index.save(stream); + + // Saving does not compact the source. + CATCH_REQUIRE(index.view_data().size() == num_slots); + CATCH_REQUIRE(index.size() == size_before); + CATCH_REQUIRE(index.status_snapshot() == status_before); + + auto deserializer = svs::lib::detail::Deserializer::build(stream); + CATCH_REQUIRE(deserializer.is_native()); + auto loaded = cc::auto_dynamic_assemble( + stream, + [&]() -> ConcurrentGraph { return ConcurrentGraph::load(stream); }, + [&]() -> ConcurrentData { + return svs::lib::load_from_stream(stream); + }, + Distance(), + num_threads + ); + + CATCH_REQUIRE(loaded.view_data().size() == num_slots); + CATCH_REQUIRE(loaded.size() == size_before); + CATCH_REQUIRE(loaded.status_snapshot() == status_before); + for (size_t i = 0; i < 400; ++i) { + const bool removed = (i < 100) || (i >= 200 && i < 300); + CATCH_REQUIRE(loaded.has_id(i) == !removed); + } + + auto expected = svs::QueryResult(queries.size(), num_neighbors); + index.search(expected.view(), queries.cview(), search_params); + auto actual = svs::QueryResult(queries.size(), num_neighbors); + loaded.search(actual.view(), queries.cview(), search_params); + for (size_t q = 0; q < queries.size(); ++q) { + for (size_t i = 0; i < num_neighbors; ++i) { + CATCH_REQUIRE(actual.index(q, i) == expected.index(q, i)); + } + } + } } CATCH_TEST_CASE( From e3d5215fc97a2247cc58c21b3c7949373a73f6ee Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 12:54:40 -0800 Subject: [PATCH 10/15] Reuse the storage lock in save instead of a new writers lock --- bindings/c/docs/C_API_Design.md | 2 +- bindings/c/include/svs/c/svs_c.h | 4 +- bindings/c/src/index_vamana.hpp | 15 +------- include/svs/concurrent/README.md | 14 +++---- include/svs/concurrent/dynamic_index.h | 38 ++++--------------- .../orchestrators/concurrent_dynamic_vamana.h | 6 +-- 6 files changed, 19 insertions(+), 60 deletions(-) diff --git a/bindings/c/docs/C_API_Design.md b/bindings/c/docs/C_API_Design.md index c48b476e0..aa4fdb276 100644 --- a/bindings/c/docs/C_API_Design.md +++ b/bindings/c/docs/C_API_Design.md @@ -277,7 +277,7 @@ Invalid parameters are rejected with `SVS_ERROR_INVALID_ARGUMENT`; unlike the le |-----------------|----------| | `SVS_SYNC_KIND_NONE` | No internal synchronization (default); the caller must serialize access | | `SVS_SYNC_KIND_GLOBAL` | Index-wide reader/writer lock: read-only operations (search, `has_id`, `get_distance`, reconstruct, `get_size`, `get_num_threads`, memory queries, use as a conversion source) run concurrently; mutating operations (add/delete points, consolidate, compact, save, `set_num_threads`) are exclusive | -| `SVS_SYNC_KIND_FINE_GRAIN` | Backed by the concurrent Vamana index, which synchronizes updates itself: read-only operations and add/delete points, consolidate, compact all take a shared lock and run in parallel (compact still waits inside the index). Save takes the shared lock too: it runs alongside searches, waits for running writers, and does not consolidate or compact. `set_num_threads`, memory queries and use as a conversion source are exclusive | +| `SVS_SYNC_KIND_FINE_GRAIN` | Backed by the concurrent Vamana index, which synchronizes updates itself: read-only operations and add/delete points, consolidate, compact all take a shared lock and run in parallel (compact still waits inside the index). Save, `set_num_threads`, memory queries and use as a conversion source are exclusive | Synchronization limits: - `svs_index_free()` must not run concurrently with any other call on the same handle. diff --git a/bindings/c/include/svs/c/svs_c.h b/bindings/c/include/svs/c/svs_c.h index d85f01f1d..0826c16f9 100644 --- a/bindings/c/include/svs/c/svs_c.h +++ b/bindings/c/include/svs/c/svs_c.h @@ -597,9 +597,7 @@ struct svs_memory_breakdown { /// With SVS_SYNC_KIND_FINE_GRAIN, the handle is backed by a concurrent index that /// synchronizes updates itself: add_points, delete_points, consolidate and compact take a /// shared lock and run alongside searches and each other (compact still waits for -/// in-flight operations inside the index). save takes a shared lock and runs alongside -/// searches; the index blocks its own writers while saving and keeps deleted and empty -/// slots as they are (no consolidate or compact). Only set_num_threads, memory queries +/// in-flight operations inside the index). Only save, set_num_threads, memory queries /// and use as a conversion source take an exclusive lock. /// /// @remarks Synchronization covers operations on the index only: diff --git a/bindings/c/src/index_vamana.hpp b/bindings/c/src/index_vamana.hpp index 7aa643d27..2a193981e 100644 --- a/bindings/c/src/index_vamana.hpp +++ b/bindings/c/src/index_vamana.hpp @@ -158,9 +158,8 @@ struct DynamicIndexVamana : public DynamicIndex { /// Dynamic index backed by svs::ConcurrentDynamicVamana. /// /// The index synchronizes add/delete/consolidate/compact itself, so they take the shared -/// lock alongside searches. save() also takes the shared lock: the index excludes its own -/// writers while saving. Operations that are not thread-safe in the index -/// (set_num_threads) and whole-index reads (memory breakdown, use as a conversion source) +/// lock alongside searches. Operations that are not thread-safe in the index (save, +/// set_num_threads) and whole-index reads (memory breakdown, use as a conversion source) /// take the exclusive lock. struct ConcurrentIndexVamana : public DynamicIndexVamana { ConcurrentIndexVamana( @@ -180,16 +179,6 @@ struct ConcurrentIndexVamana : public DynamicIndexVamana { size_t delete_points(std::span ids) override; - void save(const std::filesystem::path& directory) override { - auto lock = read_lock(); - index.save(directory / "config", directory / "graph", directory / "data"); - } - - void save(std::ostream& stream) override { - auto lock = read_lock(); - index.save(stream); - } - void consolidate() override { auto lock = read_lock(); index.consolidate(); diff --git a/include/svs/concurrent/README.md b/include/svs/concurrent/README.md index 8a946dc43..5ed2b79bd 100644 --- a/include/svs/concurrent/README.md +++ b/include/svs/concurrent/README.md @@ -84,13 +84,12 @@ storage smaller, so it must wait for every reader to finish first. It is the onl caller that takes `compact_mutex_` exclusive. It runs `consolidate_locked()` before it compacts. -### 1d. `save()` +### 1d. `save()` stops everything too `save()` writes the slots as they are, with deleted and empty slots included. It does -not call `consolidate()` or `compact()`. It takes `writers_gatekeeper_` and then -`writers_mutex_` exclusive, so it waits for running writers and blocks new ones. New -writers hold the gatekeeper only while acquiring `writers_mutex_`, so they cannot -starve `save()`. Searches keep running. +not call `consolidate()` or `compact()`. It takes the same locks as `compact()` +(`compact_gatekeeper_`, then `compact_mutex_` exclusive), so it waits for running +writers and readers, and searches wait until it is done. ### 1e. Not safe at all @@ -148,9 +147,7 @@ There are three groups: | Lock | Protects | Taken exclusive by | | --- | --- | --- | -| `writers_mutex_` | the index state stays unchanged while `save()` writes it | `save()` only | -| `writers_gatekeeper_` | new writers wait behind a pending `save()` | `save()` only | -| `compact_mutex_` | the storage stays alive | `compact()` only | +| `compact_mutex_` | the storage stays alive | `compact()`, `save()` | | `translator_mutex_` | the two id hash maps | `add_points`, `consolidate`, `compact`, `replace_external_id` | | `pending_insertions_mutex_` | `pending_insertions_` | `add_points` | | `slot_alloc_mutex_` (plain `std::mutex`) | the scan for free slots | `add_points` | @@ -167,7 +164,6 @@ so it waits for all of them. deadlock. ``` -writers_gatekeeper_ -> writers_mutex_ -> compact_gatekeeper_ -> compact_mutex_ compact_mutex_ -> slot_alloc_mutex_ compact_mutex_ -> translator_mutex_ l2e_mutex_ -> e2l_mutex_ (multi index) diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index c7d978a64..90b66a446 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -248,11 +248,9 @@ class MutableVamanaIndex { // compact()'s shrink — which frees trailing segments of the grow-stable // containers — drains in-flight readers before destroying storage. // Writers (add_points, delete_entries, consolidate) also hold it shared; - // compact() holds it exclusive. + // compact() and save() hold it exclusive. // // Lock acquisition order across the codebase: - // writers_gatekeeper_ -> writers_mutex_ (never reversed) - // writers_mutex_ -> compact_gatekeeper_ (never reversed) // compact_gatekeeper_ -> compact_mutex_ (never reversed) // compact_mutex_ -> slot_alloc_mutex_ (never reversed) // compact_mutex_ -> translator_mutex_ (never reversed) @@ -266,14 +264,6 @@ class MutableVamanaIndex { std::make_unique()}; // Iterators check this under compact_mutex_ before reusing cached internal IDs. size_t compaction_epoch_ = 0; - // Outermost lock. Every writer (add_points, delete_entries, consolidate, compact, - // replace_external_id) holds it shared; save() holds it exclusive so the state it - // writes is stable. Searches and other readers never take it. - std::unique_ptr writers_mutex_{ - std::make_unique()}; - // Once save() owns this gate, new writers cannot keep it waiting on writers_mutex_. - std::unique_ptr writers_gatekeeper_{ - std::make_unique()}; // Writer-only mutex serializing slot allocation in add_points std::unique_ptr slot_alloc_mutex_{std::make_unique()}; @@ -832,7 +822,6 @@ class MutableVamanaIndex { /// @param new_id The external ID to assign. Must not be mapped at all. /// ReplaceExternalIdResult replace_external_id(size_t old_id, size_t new_id) { - auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); std::lock_guard lock{*translator_mutex_}; @@ -889,12 +878,6 @@ class MutableVamanaIndex { // This is an internal method, mostly used to help implement the batch iterator. ValidBuilder internal_search_builder() const { return ValidBuilder{status_}; } - /// @brief Shared lock taken by every writer; waits behind a pending save(). - [[nodiscard]] std::shared_lock lock_writers_shared() const { - std::shared_lock gatekeeper_lock{*writers_gatekeeper_}; - return std::shared_lock(*writers_mutex_); - } - /// @brief RAII shared lock guarding data_/graph_ against compact()'s shrink /// (which frees segments). Used by searches, iterators and mutations that /// may overlap each other but must exclude compaction. @@ -1121,8 +1104,6 @@ class MutableVamanaIndex { return {}; } - auto writers_lock = lock_writers_shared(); - // Reserve slot ownership against compact(). Held for the entire call, // including the lock-free Phase 2-4 below; compact() takes this // exclusive and so will block until every in-flight add finishes. @@ -1330,7 +1311,6 @@ class MutableVamanaIndex { /// graph. /// template size_t delete_entries(const T& ids) { - auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); std::shared_lock lock{*translator_mutex_}; size_t deleted = 0; @@ -1416,7 +1396,6 @@ class MutableVamanaIndex { /// improve performance but requires more working memory. /// void compact(Idx batch_size = 1'000) { - auto writers_lock = lock_writers_shared(); std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; std::lock_guard compact_lock{*compact_mutex_}; @@ -1630,7 +1609,6 @@ class MutableVamanaIndex { ///// Mutation void consolidate() { - auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); consolidate_locked(); } @@ -1720,7 +1698,6 @@ class MutableVamanaIndex { /// @returns The number of listed IDs that were consolidated. /// template size_t consolidate(const T& ids) { - auto writers_lock = lock_writers_shared(); auto compact_lock = lock_storage_shared(); // Collect the internal slots of the listed, already-soft-deleted IDs. @@ -1768,22 +1745,23 @@ class MutableVamanaIndex { // * Behavior if loading from v0.0.0: All slots are `Valid`. static constexpr lib::Version save_version = lib::Version(0, 0, 1); - // Blocks writers while saving; searches may continue. + // Takes the storage lock exclusive like compact(): in-flight writers finish first and + // searches wait. Does not consolidate or compact. void save( const std::filesystem::path& config_directory, const std::filesystem::path& graph_directory, const std::filesystem::path& data_directory ) { - std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; - std::unique_lock writers_lock{*writers_mutex_}; + std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; + std::lock_guard compact_lock{*compact_mutex_}; vamana::detail::save_dynamic_index( *this, config_directory, graph_directory, data_directory ); } void save(std::ostream& os) { - std::lock_guard gatekeeper_lock{*writers_gatekeeper_}; - std::unique_lock writers_lock{*writers_mutex_}; + std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; + std::lock_guard compact_lock{*compact_mutex_}; vamana::detail::save_dynamic_index(*this, os); } @@ -1906,7 +1884,7 @@ class MutableVamanaIndex { // Not synchronized: callers must exclude concurrent mutation. const IDTranslator& view_translator() const { return translator_; } - // Slot status bytes. The caller holds writers_mutex_ exclusive. + // Slot status bytes. The caller holds compact_mutex_ exclusive. std::vector status_bytes_for_save() const { auto status = std::vector{}; auto slots = status_snapshot(); diff --git a/include/svs/orchestrators/concurrent_dynamic_vamana.h b/include/svs/orchestrators/concurrent_dynamic_vamana.h index e729b9fcd..884e67804 100644 --- a/include/svs/orchestrators/concurrent_dynamic_vamana.h +++ b/include/svs/orchestrators/concurrent_dynamic_vamana.h @@ -38,10 +38,8 @@ namespace svs { /// The wrapped index may be searched and mutated from several threads at once: search, /// batch iteration, ``add_points``, ``delete_points``, ``consolidate``, ``compact``, ID /// inspection, ``get_distance`` and ``reconstruct_at`` are safe to call concurrently. -/// ``save`` writes the slots as they are, without consolidating or compacting; it blocks -/// writers while it runs. ``set_threadpool`` and the build-parameter setters are not safe; -/// call them only when no other thread uses the index. See -/// ``include/svs/concurrent/README.md``. +/// ``save``, ``set_threadpool`` and the build-parameter setters are not; call them only +/// when no other thread uses the index. See ``include/svs/concurrent/README.md``. /// /// The dataset must use a ``svs::index::vamana::concurrent::SegmentedBlocked`` allocator so /// that growing it never relocates storage under concurrent readers. From fee726f454aa2062fc42d950523ec803bb2b3975 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 13:47:49 -0800 Subject: [PATCH 11/15] Drop documentation-only additions --- data/serialization.toml | 8 -------- include/svs/concurrent/README.md | 17 +++++------------ include/svs/concurrent/dynamic_index.h | 10 +--------- include/svs/index/vamana/dynamic_index.h | 2 +- 4 files changed, 7 insertions(+), 30 deletions(-) diff --git a/data/serialization.toml b/data/serialization.toml index 921ac6d5a..24554ef08 100644 --- a/data/serialization.toml +++ b/data/serialization.toml @@ -98,14 +98,6 @@ schema_version = "v0.0.0" parameters = "table" translation = "table" -[[schemas]] - __schema__ = "vamana_dynamic_auxiliary_parameters" - __version__ = "v0.0.1" - name = "str" - parameters = "table" - translation = "table" - status = "table" - [[schemas]] __schema__ = "vamana_build_parameters" __version__ = "v0.0.1" diff --git a/include/svs/concurrent/README.md b/include/svs/concurrent/README.md index 5ed2b79bd..6b1009add 100644 --- a/include/svs/concurrent/README.md +++ b/include/svs/concurrent/README.md @@ -80,18 +80,11 @@ share nothing. ### 1c. `compact()` stops everything You may call `compact()` at any time, but it blocks all other work. It makes the -storage smaller, so it must wait for every reader to finish first. It is the only -caller that takes `compact_mutex_` exclusive. It runs `consolidate_locked()` -before it compacts. +storage smaller, so it must wait for every reader to finish first. It runs +`consolidate_locked()` before it compacts. `save()` takes the same locks and writes +the slots as they are, without consolidating or compacting. -### 1d. `save()` stops everything too - -`save()` writes the slots as they are, with deleted and empty slots included. It does -not call `consolidate()` or `compact()`. It takes the same locks as `compact()` -(`compact_gatekeeper_`, then `compact_mutex_` exclusive), so it waits for running -writers and readers, and searches wait until it is done. - -### 1e. Not safe at all +### 1d. Not safe at all Call these only when no other thread uses the index: @@ -253,7 +246,7 @@ time. `distance` may be a functor or a `svs::DistanceType`. `batch_iterator()` returns this index's own `BatchIterator`, so it takes the locks described in 1a. The rules from section 1 apply unchanged: `set_threadpool()` and the -build-parameter setters still need exclusive access; `save()` follows 1d. +build-parameter setters still need exclusive access. ```cpp using Data = svs::index::vamana::concurrent::SegmentedBlockedData; diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index 90b66a446..391fc2a46 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -1737,16 +1737,8 @@ class MutableVamanaIndex { get_search_parameters()}; } - // Change notes: - // - // v0.0.0 - Initial version - // v0.0.1 - Save the status of every slot. The index is saved as it is, without - // consolidating or compacting, and soft-deleted IDs stay mapped. - // * Behavior if loading from v0.0.0: All slots are `Valid`. static constexpr lib::Version save_version = lib::Version(0, 0, 1); - // Takes the storage lock exclusive like compact(): in-flight writers finish first and - // searches wait. Does not consolidate or compact. void save( const std::filesystem::path& config_directory, const std::filesystem::path& graph_directory, @@ -2345,7 +2337,7 @@ auto auto_dynamic_assemble( bool SVS_UNUSED(debug_load_from_static) = false, svs::logging::logger_ptr logger = svs::logging::get() ) { - // Read the combined TOML (parameters + translation + status) + // Read the combined TOML (parameters + translation) // and the translator binary data. auto table = lib::detail::read_metadata(is); auto version = table.template cast().version(); diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 5cf718654..f40e9a473 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -1765,7 +1765,7 @@ auto auto_dynamic_assemble( bool SVS_UNUSED(debug_load_from_static) = false, svs::logging::logger_ptr logger = svs::logging::get() ) { - // Read the combined TOML (parameters + translation + status) + // Read the combined TOML (parameters + translation) // and the translator binary data. auto table = lib::detail::read_metadata(is); auto version = table.template cast().version(); From cfb2a0204bedf0c421fef5e371e71ca47e6cad5d Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 14:47:14 -0800 Subject: [PATCH 12/15] Use status_snapshot() in save; drop checks the previous version did not have --- include/svs/concurrent/dynamic_index.h | 25 ++------- include/svs/index/vamana/dynamic_index.h | 69 ++++++++---------------- 2 files changed, 25 insertions(+), 69 deletions(-) diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index 391fc2a46..cab044ded 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -1876,20 +1876,6 @@ class MutableVamanaIndex { // Not synchronized: callers must exclude concurrent mutation. const IDTranslator& view_translator() const { return translator_; } - // Slot status bytes. The caller holds compact_mutex_ exclusive. - std::vector status_bytes_for_save() const { - auto status = std::vector{}; - auto slots = status_snapshot(); - status.reserve(slots.size()); - for (size_t i = 0, imax = slots.size(); i < imax; ++i) { - if (slots[i] == SlotMetadata::Pending) { - throw ANNEXCEPTION("Cannot save an index with pending slot {}", i); - } - status.push_back(static_cast(slots[i])); - } - return status; - } - // Not synchronized: callers must exclude concurrent mutation. std::vector status_snapshot() const { auto result = std::vector(status_.size()); @@ -2341,9 +2327,6 @@ auto auto_dynamic_assemble( // and the translator binary data. auto table = lib::detail::read_metadata(is); auto version = table.template cast().version(); - if (version != lib::Version(0, 0, 0) && version != lib::Version(0, 0, 1)) { - throw ANNEXCEPTION("Unsupported dynamic index stream version {}", version); - } auto parameters = lib::load( table.template cast().at("parameters").template cast() @@ -2356,11 +2339,9 @@ auto auto_dynamic_assemble( auto status = std::vector(); if (version == lib::Version(0, 0, 1)) { - auto raw = std::vector( - lib::load_at(table.template cast(), "num_status") + status.resize(lib::load_at(table.template cast(), "num_status") ); - lib::read_binary(is, raw); - status = vamana::detail::decode_slot_status(raw); + lib::read_binary(is, status); } auto data = data_loader(); @@ -2374,7 +2355,7 @@ auto auto_dynamic_assemble( ); } - if (version == lib::Version(0, 0, 0)) { + if (version != lib::Version(0, 0, 1)) { status.assign(datasize, SlotMetadata::Valid); } diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index f40e9a473..7fdc32bc1 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -126,7 +126,12 @@ void save_dynamic_index( } std::vector status; if constexpr (Index::saves_slot_status) { - status = index.status_bytes_for_save(); + for (auto slot : index.status_snapshot()) { + if (slot == decltype(slot)::Pending) { + throw ANNEXCEPTION("Cannot save an index with pending slots"); + } + status.push_back(static_cast(slot)); + } } // Save auxiliary data structures. @@ -165,7 +170,12 @@ template void save_dynamic_index(Index& index, std::ostream& os } std::vector status; if constexpr (Index::saves_slot_status) { - status = index.status_bytes_for_save(); + for (auto slot : index.status_snapshot()) { + if (slot == decltype(slot)::Pending) { + throw ANNEXCEPTION("Cannot save an index with pending slots"); + } + status.push_back(static_cast(slot)); + } } lib::begin_serialization(os); @@ -1525,20 +1535,6 @@ MutableVamanaIndex( ) -> MutableVamanaIndex, Data, Dist>; namespace detail { -// Convert raw status bytes read from a version 0.0.1 file. Only 0, 1 and 2 -// (`Empty`, `Valid`, `Deleted`) are valid on disk. -template -std::vector decode_slot_status(const std::vector& raw) { - auto result = std::vector(raw.size()); - for (size_t i = 0, imax = raw.size(); i < imax; ++i) { - if (raw[i] > 2) { - throw ANNEXCEPTION("Invalid slot status {} at slot {}", unsigned(raw[i]), i); - } - result[i] = static_cast(raw[i]); - } - return result; -} - template struct VamanaStateLoader { ///// Loading static bool @@ -1563,12 +1559,10 @@ template struct VamanaStateLoader { if (table.version() == lib::Version(0, 0, 1)) { std::vector raw = lib::load_at>(table, "status"); - if (raw.size() != assume_datasize) { - throw ANNEXCEPTION( - "Status has {} entries but should have {}", raw.size(), assume_datasize - ); - } - status = decode_slot_status(raw); + status.resize(raw.size()); + std::transform(raw.begin(), raw.end(), status.begin(), [](uint8_t s) { + return static_cast(s); + }); } return VamanaStateLoader{ @@ -1769,9 +1763,6 @@ auto auto_dynamic_assemble( // and the translator binary data. auto table = lib::detail::read_metadata(is); auto version = table.template cast().version(); - if (version != lib::Version(0, 0, 0) && version != lib::Version(0, 0, 1)) { - throw ANNEXCEPTION("Unsupported dynamic index stream version {}", version); - } auto parameters = lib::load( table.template cast().at("parameters").template cast() @@ -1784,11 +1775,9 @@ auto auto_dynamic_assemble( auto status = std::vector(); if (version == lib::Version(0, 0, 1)) { - auto raw = std::vector( - lib::load_at(table.template cast(), "num_status") + status.resize(lib::load_at(table.template cast(), "num_status") ); - lib::read_binary(is, raw); - status = detail::decode_slot_status(raw); + lib::read_binary(is, status); } auto data = data_loader(); @@ -1802,35 +1791,21 @@ auto auto_dynamic_assemble( ); } - if (version == lib::Version(0, 0, 0)) { + if (version != lib::Version(0, 0, 1)) { status.assign(datasize, SlotMetadata::Valid); } - if (status.size() != datasize) { - throw ANNEXCEPTION( - "Status has {} entries but should have {}", status.size(), datasize - ); - } // Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them. auto to_drop = std::vector(); for (auto pair : translator) { - if (pair.second < datasize && status[pair.second] == SlotMetadata::Deleted) { + if (pair.second < status.size() && status[pair.second] == SlotMetadata::Deleted) { to_drop.push_back(pair.second); } } translator.delete_internal(to_drop, false); - // The translator must cover exactly the valid slots. - size_t num_valid = 0; - for (size_t i = 0; i < datasize; ++i) { - if (status[i] == SlotMetadata::Valid) { - ++num_valid; - if (!translator.has_internal(i)) { - throw ANNEXCEPTION("Translator is missing internal id {}", i); - } - } - } - + auto num_valid = + static_cast(std::count(status.begin(), status.end(), SlotMetadata::Valid)); auto translator_size = translator.size(); if (translator_size != num_valid) { throw ANNEXCEPTION( From e24bd2e6dd506da82202168bd5ba41cde882b7ef Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 15:09:29 -0800 Subject: [PATCH 13/15] Add a save lock so searches keep running during save --- bindings/c/docs/C_API_Design.md | 2 +- bindings/c/include/svs/c/svs_c.h | 3 +- bindings/c/src/index_vamana.hpp | 15 +++++++-- include/svs/concurrent/README.md | 10 ++++-- include/svs/concurrent/dynamic_index.h | 33 +++++++++++++++---- include/svs/index/vamana/dynamic_index.h | 6 ++-- .../orchestrators/concurrent_dynamic_vamana.h | 5 +-- 7 files changed, 57 insertions(+), 17 deletions(-) diff --git a/bindings/c/docs/C_API_Design.md b/bindings/c/docs/C_API_Design.md index aa4fdb276..9a8042ff5 100644 --- a/bindings/c/docs/C_API_Design.md +++ b/bindings/c/docs/C_API_Design.md @@ -277,7 +277,7 @@ Invalid parameters are rejected with `SVS_ERROR_INVALID_ARGUMENT`; unlike the le |-----------------|----------| | `SVS_SYNC_KIND_NONE` | No internal synchronization (default); the caller must serialize access | | `SVS_SYNC_KIND_GLOBAL` | Index-wide reader/writer lock: read-only operations (search, `has_id`, `get_distance`, reconstruct, `get_size`, `get_num_threads`, memory queries, use as a conversion source) run concurrently; mutating operations (add/delete points, consolidate, compact, save, `set_num_threads`) are exclusive | -| `SVS_SYNC_KIND_FINE_GRAIN` | Backed by the concurrent Vamana index, which synchronizes updates itself: read-only operations and add/delete points, consolidate, compact all take a shared lock and run in parallel (compact still waits inside the index). Save, `set_num_threads`, memory queries and use as a conversion source are exclusive | +| `SVS_SYNC_KIND_FINE_GRAIN` | Backed by the concurrent Vamana index, which synchronizes updates itself: read-only operations and add/delete points, consolidate, compact all take a shared lock and run in parallel (compact still waits inside the index). Save takes the shared lock too: it runs alongside searches and makes writers wait. `set_num_threads`, memory queries and use as a conversion source are exclusive | Synchronization limits: - `svs_index_free()` must not run concurrently with any other call on the same handle. diff --git a/bindings/c/include/svs/c/svs_c.h b/bindings/c/include/svs/c/svs_c.h index 0826c16f9..2cbe6a964 100644 --- a/bindings/c/include/svs/c/svs_c.h +++ b/bindings/c/include/svs/c/svs_c.h @@ -597,7 +597,8 @@ struct svs_memory_breakdown { /// With SVS_SYNC_KIND_FINE_GRAIN, the handle is backed by a concurrent index that /// synchronizes updates itself: add_points, delete_points, consolidate and compact take a /// shared lock and run alongside searches and each other (compact still waits for -/// in-flight operations inside the index). Only save, set_num_threads, memory queries +/// in-flight operations inside the index). save also takes a shared lock: it runs +/// alongside searches and makes writers wait. Only set_num_threads, memory queries /// and use as a conversion source take an exclusive lock. /// /// @remarks Synchronization covers operations on the index only: diff --git a/bindings/c/src/index_vamana.hpp b/bindings/c/src/index_vamana.hpp index 2a193981e..7aa643d27 100644 --- a/bindings/c/src/index_vamana.hpp +++ b/bindings/c/src/index_vamana.hpp @@ -158,8 +158,9 @@ struct DynamicIndexVamana : public DynamicIndex { /// Dynamic index backed by svs::ConcurrentDynamicVamana. /// /// The index synchronizes add/delete/consolidate/compact itself, so they take the shared -/// lock alongside searches. Operations that are not thread-safe in the index (save, -/// set_num_threads) and whole-index reads (memory breakdown, use as a conversion source) +/// lock alongside searches. save() also takes the shared lock: the index excludes its own +/// writers while saving. Operations that are not thread-safe in the index +/// (set_num_threads) and whole-index reads (memory breakdown, use as a conversion source) /// take the exclusive lock. struct ConcurrentIndexVamana : public DynamicIndexVamana { ConcurrentIndexVamana( @@ -179,6 +180,16 @@ struct ConcurrentIndexVamana : public DynamicIndexVamana { size_t delete_points(std::span ids) override; + void save(const std::filesystem::path& directory) override { + auto lock = read_lock(); + index.save(directory / "config", directory / "graph", directory / "data"); + } + + void save(std::ostream& stream) override { + auto lock = read_lock(); + index.save(stream); + } + void consolidate() override { auto lock = read_lock(); index.consolidate(); diff --git a/include/svs/concurrent/README.md b/include/svs/concurrent/README.md index 6b1009add..46f0a81e8 100644 --- a/include/svs/concurrent/README.md +++ b/include/svs/concurrent/README.md @@ -81,8 +81,9 @@ share nothing. You may call `compact()` at any time, but it blocks all other work. It makes the storage smaller, so it must wait for every reader to finish first. It runs -`consolidate_locked()` before it compacts. `save()` takes the same locks and writes -the slots as they are, without consolidating or compacting. +`consolidate_locked()` before it compacts. `save()` takes `save_gatekeeper_` and +`save_mutex_` exclusive, so writers wait while searches keep running. It writes the +slots as they are. ### 1d. Not safe at all @@ -140,7 +141,9 @@ There are three groups: | Lock | Protects | Taken exclusive by | | --- | --- | --- | -| `compact_mutex_` | the storage stays alive | `compact()`, `save()` | +| `save_mutex_` | the index state stays unchanged while `save()` writes it | `save()` only | +| `save_gatekeeper_` | new writers wait behind a pending `save()` | `save()` only | +| `compact_mutex_` | the storage stays alive | `compact()` only | | `translator_mutex_` | the two id hash maps | `add_points`, `consolidate`, `compact`, `replace_external_id` | | `pending_insertions_mutex_` | `pending_insertions_` | `add_points` | | `slot_alloc_mutex_` (plain `std::mutex`) | the scan for free slots | `add_points` | @@ -157,6 +160,7 @@ so it waits for all of them. deadlock. ``` +save_gatekeeper_ -> save_mutex_ -> compact_gatekeeper_ -> compact_mutex_ compact_mutex_ -> slot_alloc_mutex_ compact_mutex_ -> translator_mutex_ l2e_mutex_ -> e2l_mutex_ (multi index) diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index cab044ded..c1642d67f 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -248,10 +248,11 @@ class MutableVamanaIndex { // compact()'s shrink — which frees trailing segments of the grow-stable // containers — drains in-flight readers before destroying storage. // Writers (add_points, delete_entries, consolidate) also hold it shared; - // compact() and save() hold it exclusive. + // compact() holds it exclusive. // // Lock acquisition order across the codebase: - // compact_gatekeeper_ -> compact_mutex_ (never reversed) + // save_gatekeeper_ -> save_mutex_ -> compact_gatekeeper_ -> compact_mutex_ + // (never reversed) // compact_mutex_ -> slot_alloc_mutex_ (never reversed) // compact_mutex_ -> translator_mutex_ (never reversed) // slot_alloc_mutex_ and translator_mutex_ are never held simultaneously @@ -264,6 +265,13 @@ class MutableVamanaIndex { std::make_unique()}; // Iterators check this under compact_mutex_ before reusing cached internal IDs. size_t compaction_epoch_ = 0; + // Outermost lock. Writers (add_points, delete_entries, consolidate, compact, + // replace_external_id) hold it shared; save() holds it exclusive. Searches never take + // it. + std::unique_ptr save_mutex_{std::make_unique()}; + // Once save() owns this gate, new writers cannot keep it waiting on save_mutex_. + std::unique_ptr save_gatekeeper_{ + std::make_unique()}; // Writer-only mutex serializing slot allocation in add_points std::unique_ptr slot_alloc_mutex_{std::make_unique()}; @@ -822,6 +830,7 @@ class MutableVamanaIndex { /// @param new_id The external ID to assign. Must not be mapped at all. /// ReplaceExternalIdResult replace_external_id(size_t old_id, size_t new_id) { + auto save_lock = lock_save_shared(); auto compact_lock = lock_storage_shared(); std::lock_guard lock{*translator_mutex_}; @@ -878,6 +887,12 @@ class MutableVamanaIndex { // This is an internal method, mostly used to help implement the batch iterator. ValidBuilder internal_search_builder() const { return ValidBuilder{status_}; } + /// @brief Shared lock taken first by every writer; waits behind a pending save(). + [[nodiscard]] std::shared_lock lock_save_shared() const { + std::shared_lock gatekeeper_lock{*save_gatekeeper_}; + return std::shared_lock(*save_mutex_); + } + /// @brief RAII shared lock guarding data_/graph_ against compact()'s shrink /// (which frees segments). Used by searches, iterators and mutations that /// may overlap each other but must exclude compaction. @@ -1104,6 +1119,8 @@ class MutableVamanaIndex { return {}; } + auto save_lock = lock_save_shared(); + // Reserve slot ownership against compact(). Held for the entire call, // including the lock-free Phase 2-4 below; compact() takes this // exclusive and so will block until every in-flight add finishes. @@ -1311,6 +1328,7 @@ class MutableVamanaIndex { /// graph. /// template size_t delete_entries(const T& ids) { + auto save_lock = lock_save_shared(); auto compact_lock = lock_storage_shared(); std::shared_lock lock{*translator_mutex_}; size_t deleted = 0; @@ -1396,6 +1414,7 @@ class MutableVamanaIndex { /// improve performance but requires more working memory. /// void compact(Idx batch_size = 1'000) { + auto save_lock = lock_save_shared(); std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; std::lock_guard compact_lock{*compact_mutex_}; @@ -1609,6 +1628,7 @@ class MutableVamanaIndex { ///// Mutation void consolidate() { + auto save_lock = lock_save_shared(); auto compact_lock = lock_storage_shared(); consolidate_locked(); } @@ -1698,6 +1718,7 @@ class MutableVamanaIndex { /// @returns The number of listed IDs that were consolidated. /// template size_t consolidate(const T& ids) { + auto save_lock = lock_save_shared(); auto compact_lock = lock_storage_shared(); // Collect the internal slots of the listed, already-soft-deleted IDs. @@ -1744,16 +1765,16 @@ class MutableVamanaIndex { const std::filesystem::path& graph_directory, const std::filesystem::path& data_directory ) { - std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; - std::lock_guard compact_lock{*compact_mutex_}; + std::lock_guard gatekeeper_lock{*save_gatekeeper_}; + std::lock_guard save_lock{*save_mutex_}; vamana::detail::save_dynamic_index( *this, config_directory, graph_directory, data_directory ); } void save(std::ostream& os) { - std::lock_guard gatekeeper_lock{*compact_gatekeeper_}; - std::lock_guard compact_lock{*compact_mutex_}; + std::lock_guard gatekeeper_lock{*save_gatekeeper_}; + std::lock_guard save_lock{*save_mutex_}; vamana::detail::save_dynamic_index(*this, os); } diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 7fdc32bc1..24c025d02 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -1704,7 +1704,8 @@ auto auto_dynamic_assemble( ); } - // Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them. + // A file saved by the concurrent index can still contain deleted IDs. The dynamic + // index checks IDs only in the translator (has_id), so remove them. auto to_drop = std::vector(); for (auto pair : translator) { if (pair.second < datasize && status[pair.second] == SlotMetadata::Deleted) { @@ -1795,7 +1796,8 @@ auto auto_dynamic_assemble( status.assign(datasize, SlotMetadata::Valid); } - // Saved concurrent indexes keep soft-deleted IDs mapped; this index erases them. + // A file saved by the concurrent index can still contain deleted IDs. The dynamic + // index checks IDs only in the translator (has_id), so remove them. auto to_drop = std::vector(); for (auto pair : translator) { if (pair.second < status.size() && status[pair.second] == SlotMetadata::Deleted) { diff --git a/include/svs/orchestrators/concurrent_dynamic_vamana.h b/include/svs/orchestrators/concurrent_dynamic_vamana.h index 884e67804..fd89eac28 100644 --- a/include/svs/orchestrators/concurrent_dynamic_vamana.h +++ b/include/svs/orchestrators/concurrent_dynamic_vamana.h @@ -38,8 +38,9 @@ namespace svs { /// The wrapped index may be searched and mutated from several threads at once: search, /// batch iteration, ``add_points``, ``delete_points``, ``consolidate``, ``compact``, ID /// inspection, ``get_distance`` and ``reconstruct_at`` are safe to call concurrently. -/// ``save``, ``set_threadpool`` and the build-parameter setters are not; call them only -/// when no other thread uses the index. See ``include/svs/concurrent/README.md``. +/// ``save`` is safe alongside searches and blocks writers while it runs. +/// ``set_threadpool`` and the build-parameter setters are not safe; call them only when no +/// other thread uses the index. See ``include/svs/concurrent/README.md``. /// /// The dataset must use a ``svs::index::vamana::concurrent::SegmentedBlocked`` allocator so /// that growing it never relocates storage under concurrent readers. From 420cb94012e7b345a669c17405e25c8d2d7a538e Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Mon, 16 Nov 2026 15:56:42 -0800 Subject: [PATCH 14/15] Restore README sentence and blank-line layout --- include/svs/concurrent/README.md | 5 +++-- include/svs/concurrent/dynamic_index.h | 1 - 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/include/svs/concurrent/README.md b/include/svs/concurrent/README.md index 46f0a81e8..4d9cb2a83 100644 --- a/include/svs/concurrent/README.md +++ b/include/svs/concurrent/README.md @@ -80,8 +80,9 @@ share nothing. ### 1c. `compact()` stops everything You may call `compact()` at any time, but it blocks all other work. It makes the -storage smaller, so it must wait for every reader to finish first. It runs -`consolidate_locked()` before it compacts. `save()` takes `save_gatekeeper_` and +storage smaller, so it must wait for every reader to finish first. It is the only +caller that takes `compact_mutex_` exclusive. It runs `consolidate_locked()` +before it compacts. `save()` takes `save_gatekeeper_` and `save_mutex_` exclusive, so writers wait while searches keep running. It writes the slots as they are. diff --git a/include/svs/concurrent/dynamic_index.h b/include/svs/concurrent/dynamic_index.h index c1642d67f..da0538dc4 100644 --- a/include/svs/concurrent/dynamic_index.h +++ b/include/svs/concurrent/dynamic_index.h @@ -1759,7 +1759,6 @@ class MutableVamanaIndex { } static constexpr lib::Version save_version = lib::Version(0, 0, 1); - void save( const std::filesystem::path& config_directory, const std::filesystem::path& graph_directory, From ace05fc9e0e9ec507caf085898ee3e051c2ad77b Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Tue, 17 Nov 2026 11:08:06 -0800 Subject: [PATCH 15/15] Test loading a concurrent save into the dynamic index --- tests/svs/concurrent/dynamic_index.cpp | 57 ++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/tests/svs/concurrent/dynamic_index.cpp b/tests/svs/concurrent/dynamic_index.cpp index eac5bfba2..8fef4f2f7 100644 --- a/tests/svs/concurrent/dynamic_index.cpp +++ b/tests/svs/concurrent/dynamic_index.cpp @@ -628,6 +628,63 @@ CATCH_TEST_CASE( CATCH_REQUIRE(actual.index(q, i) == expected.index(q, i)); } } + + // The same save must also load into the dynamic index: same size, same + // visible ids, same search results. + auto check_loaded = [&](auto& dynamic) { + CATCH_REQUIRE(dynamic.size() == size_before); + for (size_t i = 0; i < 400; ++i) { + const bool removed = (i < 100) || (i >= 200 && i < 300); + CATCH_REQUIRE(dynamic.has_id(i) == !removed); + } + auto got = svs::QueryResult(queries.size(), num_neighbors); + dynamic.search(got.view(), queries.cview(), search_params); + for (size_t q = 0; q < queries.size(); ++q) { + for (size_t i = 0; i < num_neighbors; ++i) { + CATCH_REQUIRE(got.index(q, i) == expected.index(q, i)); + } + } + }; + + stream.clear(); + stream.seekg(0); + auto stream_deserializer = svs::lib::detail::Deserializer::build(stream); + CATCH_REQUIRE(stream_deserializer.is_native()); + std::istream& is = stream; // select the `std::istream&` overload + auto from_stream = svs::index::vamana::auto_dynamic_assemble( + is, + svs::lib::Lazy([&]() { + return svs::graphs::SimpleBlockedGraph::load(stream); + }), + svs::lib::Lazy([&]() { + return svs::lib::load_from_stream>(stream); + }), + Distance(), + num_threads + ); + check_loaded(from_stream); + + svs::lib::UniqueTempDirectory tempdir{"svs_concurrent_save_to_dynamic"}; + std::filesystem::create_directories(tempdir.get() / "config"); + std::filesystem::create_directories(tempdir.get() / "graph"); + std::filesystem::create_directories(tempdir.get() / "data"); + index.save( + tempdir.get() / "config", tempdir.get() / "graph", tempdir.get() / "data" + ); + auto from_directory = svs::index::vamana::auto_dynamic_assemble( + tempdir.get() / "config", + svs::lib::Lazy([&]() { + return svs::graphs::SimpleBlockedGraph::load( + tempdir.get() / "graph" + ); + }), + svs::lib::Lazy([&]() { + return svs::data::BlockedData::load(tempdir.get() / "data"); + }), + Distance(), + num_threads + ); + check_loaded(from_directory); } }