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

Abierto
  • ¿Algo no está bien?
#400 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 5 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
48/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
c, cpp
Área
api, search, testing

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
C++
Estrellas
241
Forks
48
Merge medio
4 d 21 h
PR fusionados (30 d)
11

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de intel/ScalableVectorSearch

Todos los issues de intel/ScalableVectorSearch

Issues similares

Más issues de C++

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.