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

未关闭
  • 哪里不对？
#400 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 5 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
48/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
活跃
技术栈
c, cpp
领域
api, search, testing

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

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.
主要语言
C++
星标
241
派生
48
平均合并
4 天 21 小时
30 天内合并 PR
11

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

intel/ScalableVectorSearch 的其他 Issue

查看 intel/ScalableVectorSearch 的全部 Issue

相似的 Issue

更多 C++ Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。