From c5f8c34c9b7b3e974a143cdc8b3d11febb848b3c Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Tue, 4 Nov 2025 22:28:33 -0800 Subject: [PATCH 1/4] feature: add version namespace --- include/svs/index/flat/dynamic_flat.h | 3 +++ include/svs/index/flat/flat.h | 5 +++++ include/svs/index/vamana/dynamic_index.h | 7 +++++++ include/svs/index/vamana/index.h | 6 ++++++ 4 files changed, 21 insertions(+) diff --git a/include/svs/index/flat/dynamic_flat.h b/include/svs/index/flat/dynamic_flat.h index 5a83fe22..216d31d9 100644 --- a/include/svs/index/flat/dynamic_flat.h +++ b/include/svs/index/flat/dynamic_flat.h @@ -20,6 +20,9 @@ #include #include +// svs +#include "svs/version.hpp" + // Include the flat index #include "svs/index/flat/flat.h" #include "svs/index/flat/inserters.h" diff --git a/include/svs/index/flat/flat.h b/include/svs/index/flat/flat.h index 187fc744..c135bb7e 100644 --- a/include/svs/index/flat/flat.h +++ b/include/svs/index/flat/flat.h @@ -17,6 +17,7 @@ #pragma once // Flat index utilities +#include "svs/version.hpp" #include "svs/core/logging.h" #include "svs/index/flat/inserters.h" #include "svs/index/index.h" @@ -36,6 +37,8 @@ namespace svs::index::flat { +SVS_VERSIONED_NAMESPACE_BEGIN + namespace extensions { struct FlatDistance { @@ -582,4 +585,6 @@ temporary_flat_index(Data& data, Dist distance, ThreadPoolProto threadpool_proto data, distance, threads::as_threadpool(std::move(threadpool_proto))}; } +SVS_VERSIONED_NAMESPACE_END + } // namespace svs::index::flat diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 169be199..695408a0 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -19,6 +19,9 @@ // stdlib #include +// svs +#include "svs/version.hpp" + // Include the flat index to spin-up exhaustive searches on demand. #include "svs/index/flat/flat.h" @@ -44,6 +47,8 @@ namespace svs::index::vamana { +SVS_VERSIONED_NAMESPACE_BEGIN + // Forward declaration template class BatchIterator; template @@ -1429,4 +1434,6 @@ auto auto_dynamic_assemble( std::move(logger)}; } +SVS_VERSIONED_NAMESPACE_END + } // namespace svs::index::vamana diff --git a/include/svs/index/vamana/index.h b/include/svs/index/vamana/index.h index b7c13664..0b0a675e 100644 --- a/include/svs/index/vamana/index.h +++ b/include/svs/index/vamana/index.h @@ -17,6 +17,7 @@ #pragma once // svs +#include "svs/version.hpp" #include "svs/core/data.h" #include "svs/core/graph.h" #include "svs/core/loading.h" @@ -48,6 +49,8 @@ namespace svs::index::vamana { +SVS_VERSIONED_NAMESPACE_BEGIN + template class BatchIterator; struct VamanaIndexParameters { @@ -1058,4 +1061,7 @@ void verify_and_set_default_index_parameters( throw std::invalid_argument("prune_to must be <= graph_max_degree"); } } + +SVS_VERSIONED_NAMESPACE_END + } // namespace svs::index::vamana From f9327fb9632dca9fb5256c8dcb88a5fe8d0e196d Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Tue, 4 Nov 2025 22:30:41 -0800 Subject: [PATCH 2/4] fix: add import --- include/svs/index/flat/dynamic_flat.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/include/svs/index/flat/dynamic_flat.h b/include/svs/index/flat/dynamic_flat.h index 216d31d9..6c7dd4ef 100644 --- a/include/svs/index/flat/dynamic_flat.h +++ b/include/svs/index/flat/dynamic_flat.h @@ -43,6 +43,8 @@ namespace svs::index::flat { +SVS_VERSIONED_NAMESPACE_BEGIN + /// /// Metadata tracking the state of a particular data index for DynamicFlatIndex. /// The following states have the given meaning for their corresponding slot: From 99c1dc11c494b048536ffc248291a358c7df4946 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Tue, 4 Nov 2025 22:31:56 -0800 Subject: [PATCH 3/4] fix: add version file --- include/svs/version.hpp | 131 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 include/svs/version.hpp diff --git a/include/svs/version.hpp b/include/svs/version.hpp new file mode 100644 index 00000000..1b960a1c --- /dev/null +++ b/include/svs/version.hpp @@ -0,0 +1,131 @@ +/* + * Copyright 2025 Intel Corporation + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#pragma once + +/// +/// @file version.hpp +/// @brief SVS API versioning support for integration with external libraries like Faiss +/// +/// This header defines the SVS API versioning scheme that allows: +/// 1. Stable API versions (e.g., v0, v1) with inline namespace support +/// 2. Clean integration points for external libraries +/// 3. Gradual migration between API versions +/// +/// Usage: +/// - Public APIs are wrapped in SVS_VERSIONED_NAMESPACE_BEGIN/END +/// - Users can access APIs via svs::ClassName (maps to current version) +/// - External integrators can use namespace aliases (e.g., namespace svs_api = svs::v0) +/// + +///// Version Numbers + +/// Major version number - incremented for breaking API changes +/// When this changes, a new version namespace (e.g., v0 -> v1) is created +#define SVS_VERSION_MAJOR 0 + +/// Minor version number - incremented for backward-compatible feature additions +#define SVS_VERSION_MINOR 1 + +/// Patch version number - incremented for backward-compatible bug fixes +#define SVS_VERSION_PATCH 0 + +/// Complete version string +#define SVS_VERSION_STRING "0.1.0" + +///// API Version Namespace + +/// The current API version namespace identifier +/// This defines which API generation is currently active +/// Example: v0 for the first stable API, v1 for the next major version, etc. +#define SVS_VERSION_NAMESPACE v0 + +///// Namespace Macros + +/// Begin a versioned namespace block for public APIs +/// Use this to wrap public classes, functions, and types that should be +/// stable across minor/patch releases within the same major version +#define SVS_VERSIONED_NAMESPACE_BEGIN \ + namespace svs { \ + inline namespace SVS_VERSION_NAMESPACE { + +/// End a versioned namespace block +#define SVS_VERSIONED_NAMESPACE_END \ + } /* end inline namespace SVS_VERSION_NAMESPACE */ \ + } /* end namespace svs */ + +///// Internal Namespace + +/// Internal namespace for implementation details that are not part of the stable API +/// Items in this namespace can change freely without version bumps +#define SVS_INTERNAL_NAMESPACE_BEGIN \ + namespace svs { \ + namespace internal { + +#define SVS_INTERNAL_NAMESPACE_END \ + } /* end namespace internal */ \ + } /* end namespace svs */ + +///// Version Namespace Declaration + +/// Declare the main SVS namespace with inline version namespace +/// This makes svs::Foo automatically resolve to svs::v0::Foo (or current version) +namespace svs { + /// Current API version namespace + /// All public APIs live here and are accessible as svs::ClassName + inline namespace SVS_VERSION_NAMESPACE { + // Public APIs will be defined here via SVS_VERSIONED_NAMESPACE_BEGIN/END + } + + /// Internal implementation details + /// Not part of the stable API - can change freely + namespace internal { + // Internal helpers and implementation details + } +} + +///// Integration Support + +/// Helper macro to create namespace aliases for external integrators +/// Example: SVS_CREATE_API_ALIAS(svs_api, v0) creates: namespace svs_api = svs::v0; +#define SVS_CREATE_API_ALIAS(alias_name, version_ns) \ + namespace alias_name = svs::version_ns + +/// +/// @brief Version information structure for runtime queries +/// +SVS_VERSIONED_NAMESPACE_BEGIN + +struct VersionInfo { + static constexpr int major = SVS_VERSION_MAJOR; + static constexpr int minor = SVS_VERSION_MINOR; + static constexpr int patch = SVS_VERSION_PATCH; + static constexpr const char* version_string = SVS_VERSION_STRING; + static constexpr const char* api_namespace = "v0"; // Should match SVS_VERSION_NAMESPACE + + /// Get the complete version as a string + static const char* get_version() { return version_string; } + + /// Get the API namespace identifier + static const char* get_api_namespace() { return api_namespace; } + + /// Check if this version is compatible with a requested major version + static bool is_compatible_with_major(int requested_major) { + return major == requested_major; + } +}; + +SVS_VERSIONED_NAMESPACE_END \ No newline at end of file From a6cadcf4ebd9549bd9b64866de46aa3e5f1d14c1 Mon Sep 17 00:00:00 2001 From: yuejiaointel Date: Thu, 6 Nov 2025 18:08:17 -0800 Subject: [PATCH 4/4] fix: add version to subfunctions --- include/svs/index/flat/dynamic_flat.h | 4 -- include/svs/index/flat/flat.h | 5 -- include/svs/index/vamana/dynamic_index.h | 6 -- include/svs/index/vamana/index.h | 5 -- include/svs/orchestrators/vamana.h | 1 + include/svs/version.hpp | 88 +++++++++--------------- 6 files changed, 33 insertions(+), 76 deletions(-) diff --git a/include/svs/index/flat/dynamic_flat.h b/include/svs/index/flat/dynamic_flat.h index 6c7dd4ef..d4c50f46 100644 --- a/include/svs/index/flat/dynamic_flat.h +++ b/include/svs/index/flat/dynamic_flat.h @@ -21,8 +21,6 @@ #include // svs -#include "svs/version.hpp" - // Include the flat index #include "svs/index/flat/flat.h" #include "svs/index/flat/inserters.h" @@ -43,8 +41,6 @@ namespace svs::index::flat { -SVS_VERSIONED_NAMESPACE_BEGIN - /// /// Metadata tracking the state of a particular data index for DynamicFlatIndex. /// The following states have the given meaning for their corresponding slot: diff --git a/include/svs/index/flat/flat.h b/include/svs/index/flat/flat.h index c135bb7e..187fc744 100644 --- a/include/svs/index/flat/flat.h +++ b/include/svs/index/flat/flat.h @@ -17,7 +17,6 @@ #pragma once // Flat index utilities -#include "svs/version.hpp" #include "svs/core/logging.h" #include "svs/index/flat/inserters.h" #include "svs/index/index.h" @@ -37,8 +36,6 @@ namespace svs::index::flat { -SVS_VERSIONED_NAMESPACE_BEGIN - namespace extensions { struct FlatDistance { @@ -585,6 +582,4 @@ temporary_flat_index(Data& data, Dist distance, ThreadPoolProto threadpool_proto data, distance, threads::as_threadpool(std::move(threadpool_proto))}; } -SVS_VERSIONED_NAMESPACE_END - } // namespace svs::index::flat diff --git a/include/svs/index/vamana/dynamic_index.h b/include/svs/index/vamana/dynamic_index.h index 695408a0..0954d0a3 100644 --- a/include/svs/index/vamana/dynamic_index.h +++ b/include/svs/index/vamana/dynamic_index.h @@ -20,8 +20,6 @@ #include // svs -#include "svs/version.hpp" - // Include the flat index to spin-up exhaustive searches on demand. #include "svs/index/flat/flat.h" @@ -47,8 +45,6 @@ namespace svs::index::vamana { -SVS_VERSIONED_NAMESPACE_BEGIN - // Forward declaration template class BatchIterator; template @@ -1434,6 +1430,4 @@ auto auto_dynamic_assemble( std::move(logger)}; } -SVS_VERSIONED_NAMESPACE_END - } // namespace svs::index::vamana diff --git a/include/svs/index/vamana/index.h b/include/svs/index/vamana/index.h index 0b0a675e..dcdd3d1b 100644 --- a/include/svs/index/vamana/index.h +++ b/include/svs/index/vamana/index.h @@ -17,7 +17,6 @@ #pragma once // svs -#include "svs/version.hpp" #include "svs/core/data.h" #include "svs/core/graph.h" #include "svs/core/loading.h" @@ -49,8 +48,6 @@ namespace svs::index::vamana { -SVS_VERSIONED_NAMESPACE_BEGIN - template class BatchIterator; struct VamanaIndexParameters { @@ -1062,6 +1059,4 @@ void verify_and_set_default_index_parameters( } } -SVS_VERSIONED_NAMESPACE_END - } // namespace svs::index::vamana diff --git a/include/svs/orchestrators/vamana.h b/include/svs/orchestrators/vamana.h index 6b698c4f..fddc51a8 100644 --- a/include/svs/orchestrators/vamana.h +++ b/include/svs/orchestrators/vamana.h @@ -21,6 +21,7 @@ /// @brief Main API for the Vamana type-erased orchestrator. /// +#include "svs/version.hpp" #include "svs/core/data.h" #include "svs/core/distance.h" #include "svs/core/graph.h" diff --git a/include/svs/version.hpp b/include/svs/version.hpp index 1b960a1c..6f9718e9 100644 --- a/include/svs/version.hpp +++ b/include/svs/version.hpp @@ -17,84 +17,55 @@ #pragma once /// -/// @file version.hpp -/// @brief SVS API versioning support for integration with external libraries like Faiss +/// @brief Version information and API versioning for SVS /// -/// This header defines the SVS API versioning scheme that allows: -/// 1. Stable API versions (e.g., v0, v1) with inline namespace support -/// 2. Clean integration points for external libraries -/// 3. Gradual migration between API versions +/// This header defines the SVS API versioning scheme similar to oneDAL: +/// 1. Versioned namespaces (e.g., v0, v1) for API stability +/// 2. Using declarations to bring current version to parent namespace +/// 3. Clean integration points for external libraries /// /// Usage: -/// - Public APIs are wrapped in SVS_VERSIONED_NAMESPACE_BEGIN/END -/// - Users can access APIs via svs::ClassName (maps to current version) +/// - Users can access APIs via svs::function_name (maps to current version) /// - External integrators can use namespace aliases (e.g., namespace svs_api = svs::v0) +/// - Specific versions can be accessed via svs::v0::function_name /// ///// Version Numbers +#ifndef SVS_VERSION_MAJOR /// Major version number - incremented for breaking API changes /// When this changes, a new version namespace (e.g., v0 -> v1) is created #define SVS_VERSION_MAJOR 0 +#endif +#ifndef SVS_VERSION_MINOR /// Minor version number - incremented for backward-compatible feature additions #define SVS_VERSION_MINOR 1 +#endif +#ifndef SVS_VERSION_PATCH /// Patch version number - incremented for backward-compatible bug fixes #define SVS_VERSION_PATCH 0 +#endif +#ifndef SVS_VERSION_STRING /// Complete version string #define SVS_VERSION_STRING "0.1.0" +#endif -///// API Version Namespace +///// API Version Namespace Declaration -/// The current API version namespace identifier -/// This defines which API generation is currently active -/// Example: v0 for the first stable API, v1 for the next major version, etc. -#define SVS_VERSION_NAMESPACE v0 - -///// Namespace Macros - -/// Begin a versioned namespace block for public APIs -/// Use this to wrap public classes, functions, and types that should be -/// stable across minor/patch releases within the same major version -#define SVS_VERSIONED_NAMESPACE_BEGIN \ - namespace svs { \ - inline namespace SVS_VERSION_NAMESPACE { - -/// End a versioned namespace block -#define SVS_VERSIONED_NAMESPACE_END \ - } /* end inline namespace SVS_VERSION_NAMESPACE */ \ - } /* end namespace svs */ - -///// Internal Namespace - -/// Internal namespace for implementation details that are not part of the stable API -/// Items in this namespace can change freely without version bumps -#define SVS_INTERNAL_NAMESPACE_BEGIN \ - namespace svs { \ - namespace internal { - -#define SVS_INTERNAL_NAMESPACE_END \ - } /* end namespace internal */ \ - } /* end namespace svs */ - -///// Version Namespace Declaration - -/// Declare the main SVS namespace with inline version namespace -/// This makes svs::Foo automatically resolve to svs::v0::Foo (or current version) +/// Declare the main SVS namespace with versioned APIs +/// This makes svs::function_name automatically resolve to svs::v0::function_name (current version) namespace svs { - /// Current API version namespace - /// All public APIs live here and are accessible as svs::ClassName - inline namespace SVS_VERSION_NAMESPACE { - // Public APIs will be defined here via SVS_VERSIONED_NAMESPACE_BEGIN/END + /// Current API version namespace (v0) + /// All public APIs live here and are accessible as svs::function_name via using declarations + namespace v0 { + // Public APIs will be defined in their respective headers and brought up via using declarations } - /// Internal implementation details - /// Not part of the stable API - can change freely - namespace internal { - // Internal helpers and implementation details - } + // Using declarations to bring current version APIs to parent namespace + // These will be added as we define versioned APIs in their respective headers } ///// Integration Support @@ -107,14 +78,14 @@ namespace svs { /// /// @brief Version information structure for runtime queries /// -SVS_VERSIONED_NAMESPACE_BEGIN +namespace svs::v0 { struct VersionInfo { static constexpr int major = SVS_VERSION_MAJOR; static constexpr int minor = SVS_VERSION_MINOR; static constexpr int patch = SVS_VERSION_PATCH; static constexpr const char* version_string = SVS_VERSION_STRING; - static constexpr const char* api_namespace = "v0"; // Should match SVS_VERSION_NAMESPACE + static constexpr const char* api_namespace = "v0"; /// Get the complete version as a string static const char* get_version() { return version_string; } @@ -128,4 +99,9 @@ struct VersionInfo { } }; -SVS_VERSIONED_NAMESPACE_END \ No newline at end of file +} // namespace svs::v0 + +// Bring current version APIs to parent namespace +namespace svs { + using v0::VersionInfo; +} // namespace svs \ No newline at end of file