[C API] Add cancellation-poll callback to `svs_search_params`

Aperta
  • Qualcosa non va?
#400 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 5 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
c, cpp
Ambito
api, search, testing

Direzione di ricerca

Start by locating the svs_search_params and svs_index_search_topk declarations and implementation, then inspect the existing tests under bindings/c/tests/. Define the callback and cancellation error behavior at the API boundary, document the polling cadence in the header, and add tests for cancellation before start, cancellation mid-search, and no cancellation. Finish by checking the null-callback overhead against the stated benchmark.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Summary

svs_index_search_topk at pin 5717f6855a73a9ab7524748e2a10a57ed865737d
takes an svs_search_params_h but exposes no way for the caller to
interrupt a running search. The search completes fully regardless of
whether the caller wants to abandon it. This ask adds an optional
is_cancelled_fn(userdata) -> bool callback to svs_search_params;
SVS polls it at appropriate points inside the search loop and returns
partial results plus an SVS_ERROR_CANCELLED code when the callback
returns true.

Motivation

valkey-search integrates SVS as ALGORITHM SVS_VAMANA and must honour
client-side query timeouts and shutdown signals. Its existing HNSW path
polls a cancel::Token on every visited node via
hnswlib::BaseCancellationFunctor (see
valkey-io/valkey-search:src/indexes/vector_hnsw.cc:322-329), so a
canceled query returns promptly with absl::CancelledError and the
client sees -ERR Search timed out. Without an SVS equivalent, SVS
searches on large indexes run to completion after the timeout fires
and the module returns the (now-stale) results to a client that has
long since disconnected. Two user-facing consequences:

  1. Client timeouts don't fire mid-search. On large indexes with modest
    search_window_size this can stretch a query well past the
    client's configured timeout.
  2. Server shutdown is delayed by the tail of any in-flight search.

Proposed change

Add a callback field to svs_search_params. Version-gate via
SVS_C_API_VERSION so callers can compile against either the current
or the extended layout.

typedef bool (*svs_is_cancelled_fn)(void* userdata);

SVS_API bool svs_search_params_set_cancel_callback(
    svs_search_params_h params,
    svs_is_cancelled_fn fn,     /* NULL to disable */
    void* userdata,             /* opaque, passed to fn */
    svs_error_h out_err);

Semantics:

  • If a callback is set and returns true during a search, SVS aborts
    the current search and returns whatever candidates it has already
    collected in svs_search_results_t. The out-error carries
    SVS_ERROR_CANCELLED so the caller can distinguish a cancel from
    an I/O or state error.
  • If no callback is set (default), current behavior is preserved.
  • The callback may be invoked from any thread SVS uses for the
    search (in valkey-search's case, the calling reader thread with
    our custom size()=1 threadpool). It must be reentrant-safe.
  • SVS should poll the callback at a reasonable granularity --
    matching HNSW's per-visited-node poll would be ideal but per-batch
    is acceptable if per-node adds measurable overhead. Document the
    cadence.

Acceptance criteria

  1. svs_search_params_set_cancel_callback sets a callback that SVS
    polls during svs_index_search_topk.
  2. On callback returning true, the call returns non-zero
    results.n_results (partial) when at least one candidate was
    found, or zero if none were found; svs_error_get_code(err)
    returns SVS_ERROR_CANCELLED.
  3. On callback returning false throughout, results are identical
    to the non-cancelable path.
  4. On callback being NULL / unset, behavior identical to today's
    API.
  5. Poll cadence documented in the header (per-node or per-batch).
  6. Unit tests in bindings/c/tests/ cover: cancel-before-start
    (returns empty + cancelled code), cancel-mid-search (returns
    partial + cancelled code), no-cancel (identical to baseline).
  7. Cost benchmark: null-callback overhead vs. baseline is
    below 1% p50 on the standard bindings/c/tests recall dataset
    at k=10.

Non-goals

  • Preemptive thread cancellation. Cooperative poll is sufficient.
  • Cancellation on svs_index_build_dynamic, svs_index_load_dynamic,
    or svs_index_dynamic_add_points. Search is the load-bearing path;
    the mutating ops are short enough that adding cancellation is not
    worth the API surface.
Lingua principale
C++
Stelle
241
Fork
48
Merge medio
4g 21h
PR unite (30g)
11

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di intel/ScalableVectorSearch

Tutte le issue di intel/ScalableVectorSearch

Issue simili

Altre issue su C++

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.