[C API] Feature request: expose block-growth headroom for a dynamic index

オープン
  • 何か問題がありますか？
#396 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 5 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
72/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
c, cpp
領域
api

調査の方向性

Start in bindings/c/include/svs/c/svs_c.h beside svs_index_get_memory_usage and svs_index_get_memory_breakdown, then trace the dynamic index implementation in dynamic_index.h and its resize/unsafe_resize paths. Add the read-only API and verify it reports capacity minus size for dynamic indices, returns zero for unsupported indices, and preserves the documented error-handling shape.

索引モデルが issue の本文から書いたものです。

説明

Problem

A dynamic index's memory reservation is tracked as committed capacity, not live occupancy. add_points grows data_/graph_/status_ in blocks (dynamic_index.h, resize/unsafe_resize calls), so a block often has spare rows left over after a resize. Committed capacity therefore overstates how many bytes an insert will actually consume.

An insert-admission gate that enforces a memory budget needs to know how much of that committed capacity is still unoccupied headroom, so it can allow an insert that would land in already-allocated spare rows and cost zero real bytes. Without that visibility, the gate must charge a fixed conservative growth cost per insert, and near the budget limit it refuses inserts that would not have grown memory at all.

What is needed is a cheap way to read how many rows of spare capacity a dynamic index currently has, without walking the graph.

Requested API

Add a new C API call, alongside the existing memory-usage family (svs_index_get_memory_usage, svs_index_get_memory_breakdown in bindings/c/include/svs/c/svs_c.h):

/// @brief Get the unused row capacity of a dynamic index before its next
/// internal block resize
/// @param index The index handle
/// @param out_vectors Pointer to store the number of rows of headroom
/// @param out_err An optional error handle to capture errors
/// @return true on success, false on failure
/// @remarks O(1). Reads capacity() - size() off the dynamic index's
/// blocked dataset. Returns 0 for indices that do not support dynamic
/// growth (e.g. static/read-only indices).
SVS_API bool svs_index_get_capacity_headroom(
    svs_index_h index, size_t* out_vectors, svs_error_h out_err /*=NULL*/
);
Why this shape
  • Mirrors the existing svs_index_get_memory_usage/svs_index_get_memory_breakdown signatures and doc-comment style, so it fits the current API family added for PR #364.
  • Returns a row count, not bytes. The caller already knows per-row byte cost from its own dimension/element-size config; a row count avoids duplicating SVS's internal block-size math on the caller side. A byte count works too, if that fits the existing memory-usage API family better; the caller can convert either way.
  • O(1): a capacity() - size() read, no graph walk.
Non-goals
  • Does not need to account for Deleted slots. delete_entry marks a slot Deleted, not Empty (dynamic_index.h), and add_points's reuse scan only matches Empty (dynamic_index.h:752). Only compact() turns Deleted back into usable capacity, so headroom from block growth and headroom from delete/compact are different numbers; this request is only for the former.
  • No behavior change to add_points, resize, or compact is being requested; this is a read-only accessor.
主要言語
C++
スター
241
フォーク
48
平均マージ
4日 21時間
マージ済み PR（30日）
11

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

intel/ScalableVectorSearch のほかの issue

intel/ScalableVectorSearch の issue をすべて見る

似ている issue

C++ の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。