remove build_result completely and remove build() overloads that return build_result

Author: HowardHuang1

c/src/neighbors/cagra.cpp

@@ -200,21 +200,21 @@ void _build(cuvsResources_t res,
     // Device `cagra::build` requires a row stride compatible with 16-byte alignment; bare DLPack
     // buffers (e.g. small dim) are often tightly packed and must be copied via `make_padded_dataset`.
     if (cuvs::neighbors::device_matrix_row_width_matches_cagra_required(mds)) {
-      auto view      = cuvs::neighbors::make_padded_dataset_view(*res_ptr, mds);
-      auto build_res = cuvs::neighbors::cagra::build(*res_ptr, index_params, view);
-      auto* raw      = new cuvs::neighbors::cagra::index<T, uint32_t>(std::move(build_res.idx));
+      auto view  = cuvs::neighbors::make_padded_dataset_view(*res_ptr, mds);
+      auto index = cuvs::neighbors::cagra::build(*res_ptr, index_params, view);
+      auto* raw  = new cuvs::neighbors::cagra::index<T, uint32_t>(std::move(index));
       assign_standalone_index<T>(output_index, output_index->dtype, raw);
     } else {
-      auto padded    = cuvs::neighbors::make_padded_dataset(*res_ptr, mds);
-      auto build_res = cuvs::neighbors::cagra::build(*res_ptr, index_params, padded->as_dataset_view());
+      auto padded = cuvs::neighbors::make_padded_dataset(*res_ptr, mds);
+      auto index  = cuvs::neighbors::cagra::build(*res_ptr, index_params, padded->as_dataset_view());
       if (index_params.compression.has_value()) {
-        auto* raw = new cuvs::neighbors::cagra::index<T, uint32_t>(std::move(build_res.idx));
+        auto* raw = new cuvs::neighbors::cagra::index<T, uint32_t>(std::move(index));
         assign_standalone_index<T>(output_index, output_index->dtype, raw);
       } else {
         auto* holder = new cuvs_cagra_c_api_lifetime_holder<T>{
           cuvs::neighbors::wrap_any_owning(std::move(padded)),
           raft::device_matrix<T, int64_t>(*res_ptr),
-          std::move(build_res.idx)};
+          std::move(index)};
         assign_lifetime_holder<T>(output_index, output_index->dtype, holder);
       }
     }
@@ -232,16 +232,16 @@ void _build(cuvsResources_t res,
         nullptr, std::move(storage), std::move(result.idx)};
       assign_lifetime_holder<T>(output_index, output_index->dtype, holder);
     } else {
-      auto padded    = cuvs::neighbors::make_padded_dataset(*res_ptr, mds);
-      auto build_res = cuvs::neighbors::cagra::build(*res_ptr, index_params, padded->as_dataset_view());
+      auto padded = cuvs::neighbors::make_padded_dataset(*res_ptr, mds);
+      auto index  = cuvs::neighbors::cagra::build(*res_ptr, index_params, padded->as_dataset_view());
       if (index_params.compression.has_value()) {
-        auto* raw = new cuvs::neighbors::cagra::index<T, uint32_t>(std::move(build_res.idx));
+        auto* raw = new cuvs::neighbors::cagra::index<T, uint32_t>(std::move(index));
         assign_standalone_index<T>(output_index, output_index->dtype, raw);
       } else {
         auto* holder = new cuvs_cagra_c_api_lifetime_holder<T>{
           cuvs::neighbors::wrap_any_owning(std::move(padded)),
           raft::device_matrix<T, int64_t>(*res_ptr),
-          std::move(build_res.idx)};
+          std::move(index)};
         assign_lifetime_holder<T>(output_index, output_index->dtype, holder);
       }
     }

cpp/bench/ann/src/cuvs/cuvs_cagra_wrapper.h

@@ -227,21 +227,21 @@ void cuvs_cagra<T, IdxT>::build(const T* dataset, size_t nrow)
       cudaPointerAttributes ptr_attrs{};
       RAFT_CUDA_TRY(cudaPointerGetAttributes(&ptr_attrs, mds.data_handle()));
       const bool device_src = (reinterpret_cast<T const*>(ptr_attrs.devicePointer) != nullptr);
-      // `build_result` is move-only; use a non-const `br` per branch so
-      // `std::move(br.idx)` moves (a const `br` would try to copy the deleted
+      // `cagra::index` is move-only; use a non-const `index` per branch so
+      // `std::move(index)` moves (a const `index` would try to copy the deleted
       // cagra::index copy ctor).
       if (device_src && src_stride == required_stride) {
         auto const pdv    = cuvs::neighbors::make_padded_dataset_view(handle_, mds);
         *input_dataset_v_ = raft::make_device_matrix_view<const T, int64_t, raft::row_major>(
           mds.data_handle(), static_cast<int64_t>(nrow), static_cast<int64_t>(dim_));
-        auto br = cuvs::neighbors::cagra::build<T, IdxT>(handle_, params, pdv);
-        index_  = std::make_shared<cuvs::neighbors::cagra::index<T, IdxT>>(std::move(br.idx));
+        auto index = cuvs::neighbors::cagra::build<T, IdxT>(handle_, params, pdv);
+        index_     = std::make_shared<cuvs::neighbors::cagra::index<T, IdxT>>(std::move(index));
       } else {
         auto padded = cuvs::neighbors::make_padded_dataset(handle_, mds);
-        auto br =
+        auto index =
           cuvs::neighbors::cagra::build<T, IdxT>(handle_, params, padded->as_dataset_view());
         *dataset_ = std::move(padded->data_);
-        index_    = std::make_shared<cuvs::neighbors::cagra::index<T, IdxT>>(std::move(br.idx));
+        index_    = std::make_shared<cuvs::neighbors::cagra::index<T, IdxT>>(std::move(index));
       }
     }
   } else {
@@ -297,16 +297,14 @@ void cuvs_cagra<T, IdxT>::build(const T* dataset, size_t nrow)
           RAFT_CUDA_TRY(cudaPointerGetAttributes(&sub_attrs, mds_sub.data_handle()));
           const bool sub_device = (reinterpret_cast<T const*>(sub_attrs.devicePointer) != nullptr);
           if (sub_device && src_sub == req_sub) {
-            sub_index = std::move(
-              cuvs::neighbors::cagra::build<T, IdxT>(
-                handle_, params, cuvs::neighbors::make_padded_dataset_view(handle_, mds_sub))
-                .idx);
+            sub_index = cuvs::neighbors::cagra::build<T, IdxT>(
+              handle_, params, cuvs::neighbors::make_padded_dataset_view(handle_, mds_sub));
           } else {
             auto padded_sub = cuvs::neighbors::make_padded_dataset(handle_, mds_sub);
-            auto out        = cuvs::neighbors::cagra::build<T, IdxT>(
+            auto index      = cuvs::neighbors::cagra::build<T, IdxT>(
               handle_, params, padded_sub->as_dataset_view());
             sub_dataset_buffers_->push_back(std::move(padded_sub->data_));
-            sub_index = std::move(out.idx);
+            sub_index = std::move(index);
           }
         } else {
           auto mds_sub           = sub_dev;
@@ -318,16 +316,14 @@ void cuvs_cagra<T, IdxT>::build(const T* dataset, size_t nrow)
           RAFT_CUDA_TRY(cudaPointerGetAttributes(&sub_attrs, mds_sub.data_handle()));
           const bool sub_device = (reinterpret_cast<T const*>(sub_attrs.devicePointer) != nullptr);
           if (sub_device && src_sub == req_sub) {
-            sub_index = std::move(
-              cuvs::neighbors::cagra::build<T, IdxT>(
-                handle_, params, cuvs::neighbors::make_padded_dataset_view(handle_, mds_sub))
-                .idx);
+            sub_index = cuvs::neighbors::cagra::build<T, IdxT>(
+              handle_, params, cuvs::neighbors::make_padded_dataset_view(handle_, mds_sub));
           } else {
             auto padded_sub = cuvs::neighbors::make_padded_dataset(handle_, mds_sub);
-            auto out        = cuvs::neighbors::cagra::build<T, IdxT>(
+            auto index      = cuvs::neighbors::cagra::build<T, IdxT>(
               handle_, params, padded_sub->as_dataset_view());
             sub_dataset_buffers_->push_back(std::move(padded_sub->data_));
-            sub_index = std::move(out.idx);
+            sub_index = std::move(index);
           }
         }
       }

cpp/include/cuvs/neighbors/cagra.hpp

@@ -384,8 +384,6 @@ static_assert(std::is_aggregate_v<search_params>);
 template <typename T, typename IdxT>
 struct index;
 template <typename T, typename IdxT>
-struct build_result;
-template <typename T, typename IdxT>
 struct ace_build_result;
 
 template <typename T, typename IdxT>
@@ -958,22 +956,6 @@ struct index : cuvs::neighbors::index {
  * @}
  */
 
-/**
- * Result of `cagra::build` for APIs that return extra state alongside the index. Host-matrix builds
- * that attach a padded device copy on the index store it in `index::index_owning_dataset_storage_`
- * when needed. When deprecated `index_params::compression` is set, VPQ is trained inside `build`
- * and stored on the index. Otherwise, for explicit VPQ, train with
- * `cuvs::preprocessing::quantize::pq::make_vpq_dataset` and attach via `index::update_dataset` with
- * `vpq.as_dataset_view()` while keeping the `vpq_dataset` alive.
- */
-template <typename T, typename IdxT>
-struct build_result {
-  cuvs::neighbors::cagra::index<T, IdxT> idx;
-
-  /** Implicit conversion to index (moves `idx` out). */
-  operator cuvs::neighbors::cagra::index<T, IdxT>() && { return std::move(idx); }
-};
-
 /**
  * Result of merging CAGRA indices. The index holds a view over \p dataset; caller must keep
  * \p dataset alive for the lifetime of \p idx. If \p index_params passed to \p cagra::merge had
@@ -1036,7 +1018,7 @@ struct ace_build_result {
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset_view` / `make_padded_dataset` for the view. Matrix overloads do
  *             not support VPQ compression.
  */
@@ -1082,7 +1064,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset` for host uploads. For ACE returning `ace_build_result`, use
  *             `build_ace`. Matrix overloads do not support VPQ compression.
  */
@@ -1128,7 +1110,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset_view` / `make_padded_dataset` for the view. Matrix overloads do
  *             not support VPQ compression.
  */
@@ -1173,7 +1155,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset` for host uploads. For ACE returning `ace_build_result`, use
  *             `build_ace`. Matrix overloads do not support VPQ compression.
  */
@@ -1220,7 +1202,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset_view` / `make_padded_dataset` for the view. Matrix overloads do
  *             not support VPQ compression.
  */
@@ -1268,7 +1250,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset` for host uploads. For ACE returning `ace_build_result`, use
  *             `build_ace`. Matrix overloads do not support VPQ compression.
  */
@@ -1316,7 +1298,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset_view` / `make_padded_dataset` for the view. Matrix overloads do
  *             not support VPQ compression.
  */
@@ -1364,7 +1346,7 @@ auto build(raft::resources const& res,
  *
  * @return the constructed cagra index
  *
- * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `build_result`, using
+ * @deprecated Prefer `cagra::build(res, params, dataset_view)` returning `cagra::index`, using
  *             `make_padded_dataset` for host uploads. For ACE returning `ace_build_result`, use
  *             `build_ace`. Matrix overloads do not support VPQ compression.
  */
@@ -1381,7 +1363,7 @@ auto build(raft::resources const& res,
  *
  * Requires `graph_build_params` to be `ace_params`. For a single `cagra::index` return with
  * internal lifetime management, use `cagra::build(res, params, host_view)` (backward
- * compatible). For the generic padded-`dataset_view` path that returns `build_result`, use
+ * compatible). For the generic padded-`dataset_view` path, use
  * `cagra::build(res, params, make_padded_dataset* / view)`.
  */
 auto build_ace(raft::resources const& res,
@@ -1425,7 +1407,7 @@ template <typename T, typename IdxT = uint32_t>
 auto build(raft::resources const& res,
            const cuvs::neighbors::cagra::index_params& params,
            cuvs::neighbors::any_dataset_view<T, int64_t> const& dataset)
-  -> cuvs::neighbors::cagra::build_result<T, IdxT>;
+  -> cuvs::neighbors::cagra::index<T, IdxT>;
 
 /**
  * @brief Same as `build<T, IdxT>(res, params, dataset_view)` but deduces \p T from
@@ -1439,7 +1421,7 @@ template <typename T, typename IdxT = uint32_t>
 auto build(raft::resources const& res,
            const cuvs::neighbors::cagra::index_params& params,
            cuvs::neighbors::device_padded_dataset_view<T, int64_t> const& dataset)
-  -> cuvs::neighbors::cagra::build_result<T, IdxT>
+  -> cuvs::neighbors::cagra::index<T, IdxT>
 {
   return cuvs::neighbors::cagra::build<T, IdxT>(
     res, params, cuvs::neighbors::any_dataset_view<T, int64_t>(dataset));

cpp/src/neighbors/cagra.cuh

@@ -325,8 +325,7 @@ index<T, IdxT> build(
     "device data, use cagra::build with raft::device_matrix_view or a device dataset_view.");
   auto hview = raft::make_host_matrix_view<const T, int64_t, row_major>(
     dataset.data_handle(), dataset.extent(0), dataset.extent(1));
-  auto bres = detail::build_from_host_matrix<T, IdxT>(res, params, hview);
-  return std::move(bres.idx);
+  return detail::build_from_host_matrix<T, IdxT>(res, params, hview);
 }
 
 /**
@@ -337,9 +336,9 @@ index<T, IdxT> build(
  * stores the original view when `attach_dataset_on_build` is true.
  */
 template <typename T, typename IdxT>
-build_result<T, IdxT> build(raft::resources const& res,
-                            const index_params& params,
-                            cuvs::neighbors::any_dataset_view<T, int64_t> const& dataset)
+index<T, IdxT> build(raft::resources const& res,
+                     const index_params& params,
+                     cuvs::neighbors::any_dataset_view<T, int64_t> const& dataset)
 {
   return cuvs::neighbors::cagra::detail::build_from_device_matrix<T, IdxT>(res, params, dataset);
 }

cpp/src/neighbors/cagra_build_inst.cu.in

@@ -32,12 +32,8 @@ auto build(raft::resources const& handle,
            raft::device_matrix_view<const data_t, int64_t, raft::row_major> dataset)
   -> cuvs::neighbors::cagra::index<data_t, index_t>
 {
-  // `build` on `any_dataset_view` returns `build_result`; convert to `index` via implicit
-  // conversion.
   auto padded = cuvs::neighbors::make_padded_dataset_view(handle, dataset);
-  cuvs::neighbors::cagra::index<data_t, index_t> out =
-    cuvs::neighbors::cagra::build(handle, params, padded);
-  return out;
+  return cuvs::neighbors::cagra::build(handle, params, padded);
 }
 
 // TODO(removal): Deprecated build(host_matrix_view)->index (delete with cagra.hpp declarations).
@@ -55,9 +51,8 @@ auto build(raft::resources const& handle,
     return ::cuvs::neighbors::cagra::finalize_index_from_ace(
       ::cuvs::neighbors::cagra::detail::build_ace<data_t, index_t>(handle, params, dataset));
   }
-  auto bres = ::cuvs::neighbors::cagra::detail::build_from_host_matrix<data_t, index_t>(
+  return ::cuvs::neighbors::cagra::detail::build_from_host_matrix<data_t, index_t>(
     handle, params, dataset);
-  return std::move(bres.idx);
 }
 
 auto build_ace(raft::resources const& handle,
@@ -68,7 +63,8 @@ auto build_ace(raft::resources const& handle,
   RAFT_EXPECTS(
     std::holds_alternative<graph_build_params::ace_params>(params.graph_build_params),
     "cagra::build_ace requires graph_build_params to be ace_params. For cagra::index, use "
-    "cagra::build(res, params, host_view). For build_result, use cagra::build(res, params, view).");
+    "cagra::build(res, params, host_view). For non-ACE views, use cagra::build(res, params, "
+    "dataset_view).");
   RAFT_EXPECTS(raft::get_device_for_address(dataset.data_handle()) == -1,
                "ACE: Dataset must be on host for ACE build");
   return ::cuvs::neighbors::cagra::detail::build_ace<data_t, index_t>(handle, params, dataset);
@@ -77,7 +73,7 @@ auto build_ace(raft::resources const& handle,
 // Definition lives in cagra.cuh; callers that only include cagra.hpp need this symbol in libcuvs.
 // The device_matrix_view overload above may inline the any_dataset_view template, so emit it
 // explicitly.
-template build_result<data_t, index_t> build<data_t, index_t>(
+template cuvs::neighbors::cagra::index<data_t, index_t> build<data_t, index_t>(
   raft::resources const& res,
   const index_params& params,
   cuvs::neighbors::any_dataset_view<data_t, int64_t> const& dataset);