Skip to content

Fix: Avoid per-item GIL acquisition without progress callbacks - #832

Closed
CLCK0622 wants to merge 1 commit into
unum-cloud:main-devfrom
CLCK0622:fix/python-gil-progress-signals
Closed

CLCK0622 wants to merge 1 commit into
unum-cloud:main-devfrom
CLCK0622:fix/python-gil-progress-signals

Conversation

@CLCK0622

Copy link
Copy Markdown
Contributor

Closes #831. Reported by @clemlesne.

When another Python thread is runnable, the add/search reporter currently waits for the GIL on every item, even without a Python progress callback. Keep empty progress callbacks native and poll Python signals from the existing reporter at 100 ms intervals. Check pending signals again after native work returns, preserving KeyboardInterrupt instead of overwriting it with an operation error. Apply the same policy to sharded search and exact search.

Python progress callbacks retain their per-item notifications, final completion report, and cancellation behavior. The C API and public Python signatures are unchanged. The interval applies at existing progress checkpoints; a long individual item, GIL contention, or remaining workers can delay interruption further.

On Apple M4 / CPython 3.11.15, the issue's seed=0 float32 input gives these median wall times with a busy Python thread and no callback (five samples per build, identical clang -O3 / NumKong=1 / OpenMP=0 builds):

Operation Threads Before ms After ms
exact 1 7918.880 9.567
bulk_add 1 7483.052 131.977
batch_search 1 975.925 38.309
exact 4 1361.832 8.922
bulk_add 4 1896.144 46.235
batch_search 4 257.705 20.665

Single-query index.search remains around 7.7 ms under contention because returning to Python still requires a GIL hand-off. Additional seven-sample AB/BA controls cover the callback path and uncontended no-callback path. For contended exact search with a callback, the one-thread median changed by +7.2% in seven samples and -1.7% in a separate 21-sample run; the four-thread seven-sample change was +3.1%. Uncontended callback timings are close. Callback counts and output SHA-256 values match before/after; the full samples are included because contended timings remain sensitive to interpreter scheduling.

Validation on macOS arm64, Python 3.11:

  • Full Python suite: 832 passed, 23 expected/platform/optional skips, including a locally built SQLite extension.
  • GIL/progress tests: 19 passed, including no-callback interruption, callback frequency/completion/cancellation, matching results, and sharded search. Against the baseline, the new no-callback interruption cases fail: add and search raise RuntimeError, exact search raises MemoryError, instead of KeyboardInterrupt.
  • Ruff check; modified Python file format check; C++ clang-format check; git diff --check.

Linux and Windows are left to the upstream CI matrix; the interruption test depends on signal delivery timing and a 15 s subprocess bound, and was only run on macOS arm64.

AI disclosure: Codex assisted with part of the code and this description.

Copilot AI balanced review requested due to automatic review settings October 29, 2026 00:40

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@ashvardanian

Copy link
Copy Markdown
Member

@CLCK0622, thanks for fixing this and for thinking about Ctrl-C too! 3.0 rewrote the Python glue in C: calls release the GIL once and never retake it without a progress handler, so #831 is gone there. Ctrl-C isn't polled on its own yet; for now a progress handler is how you cancel searches and refines. Closing this one, and the Python docs show the new calls.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants