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

Aberta
  • Algo errado?
#400 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 5 dias

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
48/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
c, cpp
Domínio
api, search, testing

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.
Linguagem predominante
C++
Estrelas
241
Forks
48
Merge médio
4d 21h
PRs com merge (30d)
11

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de intel/ScalableVectorSearch

Todas as issues de intel/ScalableVectorSearch

Issues semelhantes

Mais issues de C++

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.