Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

perf(index): pin BLAS threads before numpy is imported (#1776)

Raghav Chamadiyac20b09431e7b
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.py
index 47a4f9352..faa491a9d 100644
--- a/packages/cli/src/repowise/cli/main.py
+++ b/packages/cli/src/repowise/cli/main.py
@@ -2,6 +2,17 @@
from __future__ import annotations
+# Before anything else can pull in numpy: a BLAS runtime sizes its private
+# per-thread workspace to the host's core count at import, and on a 32-core
+# machine that is ~750 MB committed and never returned, for work this pipeline
+# does single-threaded in under a second. See the module for the measurements
+# (issue #1394). This has to precede every other repowise import — one of them
+# reaching numpy first is exactly the bug.
+from repowise.core.blas_threads import limit_blas_threads
+
+limit_blas_threads()
+
+# ruff: noqa: E402 — the BLAS pin above is only effective before these run.
import click
from repowise.cli import __version__
diff --git a/packages/core/src/repowise/core/blas_threads.py b/packages/core/src/repowise/core/blas_threads.py
new file mode 100644
index 000000000..8caa78e57
--- /dev/null
+++ b/packages/core/src/repowise/core/blas_threads.py
@@ -0,0 +1,80 @@
+"""Cap the BLAS thread pool before numpy is ever imported.
+
+Importing numpy brings up a BLAS runtime, and OpenBLAS commits a private
+per-thread workspace for as many threads as the host has cores. That memory is
+committed at import, is never returned, and is invisible to ``tracemalloc``
+because no Python object owns it — which is why it went unattributed in
+``#1394`` for so long: three separate reads of the generation code could not
+find it, since it is not in the generation code and it is not Python.
+
+Measured on a 32-core Windows host, process private bytes charged to
+``import numpy`` alone, with no repowise work running at all:
+
+====================== ==========
+``OPENBLAS_NUM_THREADS`` cost
+====================== ==========
+1 6 MB
+2 38 MB
+4 103 MB
+8 231 MB
+16 488 MB
+32 (unset, = cores) 746 MB
+====================== ==========
+
+Roughly 32 MB per thread, linear, and entirely independent of repository size:
+the same 746 MB is paid indexing a ten-file repo as a ten-thousand-file one.
+
+**We do not need those threads.** The only numpy/scipy work in an index is
+PageRank over a sparse graph and small vector arithmetic. Measured on the same
+host, ``nx.pagerank`` over a 10,000-node graph allocates 1.5 MB and returns in
+well under a second, single-threaded. Threaded BLAS pays off on large dense
+matrix multiplies, which this pipeline never performs.
+
+End to end on a 876-file C# repo, peak process memory fell from 1,547 MB to
+777 MB — half — with wall clock unchanged (3m37s against 3m45s and 3m56s for
+two unpinned baselines).
+
+**``OMP_NUM_THREADS`` is deliberately not set here.** It looks like the same
+knob and is not: igraph's community detection is OpenMP-parallel and really
+does use those threads. Pinning it alongside the BLAS variables cost 18% wall
+clock (4m30s against 3m45s) on the same repo for no extra memory saving. The
+saving is entirely a BLAS-allocator effect, so only BLAS is pinned.
+
+An explicit setting from the environment always wins: someone who has tuned
+these deliberately gets what they asked for.
+"""
+
+from __future__ import annotations
+
+import os
+
+#: The per-backend thread-count variables, one per BLAS implementation numpy
+#: may be linked against. Setting one that does not apply is harmless — the
+#: absent runtime never reads it.
+_BLAS_THREAD_VARS = (
+ "OPENBLAS_NUM_THREADS",
+ "MKL_NUM_THREADS",
+ "NUMEXPR_NUM_THREADS",
+ "VECLIB_MAXIMUM_THREADS",
+)
+
+
+def limit_blas_threads(threads: int = 1) -> None:
+ """Pin every BLAS backend to *threads*, unless already set explicitly.
+
+ Must be called before the first ``import numpy`` in the process to have any
+ effect: the workspace is committed during BLAS initialisation, and a later
+ change to the environment cannot give it back.
+
+ Environment variables rather than a runtime API because the runtime APIs
+ (``threadpoolctl``, ``mkl.set_num_threads``) only exist after numpy is
+ imported, by which point the memory is already gone. Setting the
+ environment also carries to spawned worker processes for free, which
+ matters here: the parse pool and the betweenness pool each start fresh
+ interpreters that would otherwise pay the full cost again, per worker.
+ """
+ for name in _BLAS_THREAD_VARS:
+ # Respect an explicit choice. `setdefault` rather than assignment is
+ # the whole of the opt-out: `OPENBLAS_NUM_THREADS=8 repowise init`
+ # keeps eight.
+ os.environ.setdefault(name, str(threads))
diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.py
index 037ac7f4a..ff454ce83 100644
--- a/packages/server/src/repowise/server/app.py
+++ b/packages/server/src/repowise/server/app.py
@@ -7,6 +7,14 @@ scheduler) and shutdown (cleanup).
from __future__ import annotations
+# Same reason as the CLI entry point, and it matters more here: a server is
+# long-lived, so a BLAS workspace sized to the host's core count is held for
+# the process's whole life rather than one index (issue #1394).
+from repowise.core.blas_threads import limit_blas_threads
+
+limit_blas_threads()
+
+# ruff: noqa: E402 — the BLAS pin above is only effective before these run.
import logging
import os
from collections.abc import AsyncGenerator
diff --git a/tests/unit/test_blas_threads.py b/tests/unit/test_blas_threads.py
new file mode 100644
index 000000000..7caea66c4
--- /dev/null
+++ b/tests/unit/test_blas_threads.py
@@ -0,0 +1,118 @@
+"""Tests for the BLAS thread pin (issue #1394).
+
+The thing under test is a memory saving that nothing else in the suite can
+see, so these pin the two properties that make it work rather than asserting
+the saving itself: every backend variable is set, and an explicit choice from
+the environment is never overwritten.
+
+The third property — that the pin runs *before* numpy is imported — is the one
+that actually decides whether any memory is saved, and it is pinned by
+inspecting the CLI entry module's source rather than its behaviour: by the time
+a test can observe an imported numpy, the workspace is already committed and
+the damage cannot be detected from inside the same process.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+
+from repowise.core.blas_threads import _BLAS_THREAD_VARS, limit_blas_threads
+
+
[email protected](autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch):
+ for name in _BLAS_THREAD_VARS:
+ monkeypatch.delenv(name, raising=False)
+
+
+def test_pins_every_backend_to_one(monkeypatch: pytest.MonkeyPatch) -> None:
+ limit_blas_threads()
+
+ import os
+
+ # Asserting the literal "1" rather than comparing against the default
+ # argument: a change of default is a change of behaviour and should fail
+ # here rather than pass silently against itself.
+ for name in _BLAS_THREAD_VARS:
+ assert os.environ[name] == "1", name
+
+
+def test_covers_the_backend_that_actually_costs_the_memory() -> None:
+ # OpenBLAS is the one measured at ~32 MB per thread. A refactor that
+ # dropped it while keeping the others would keep every other test passing
+ # and give back none of the memory.
+ assert "OPENBLAS_NUM_THREADS" in _BLAS_THREAD_VARS
+
+
+def test_does_not_pin_openmp() -> None:
+ # Deliberately absent: igraph's community detection is OpenMP-parallel and
+ # really uses those threads. Pinning it cost 18% wall clock for no extra
+ # memory saving, so its absence is a decision, not an oversight.
+ assert "OMP_NUM_THREADS" not in _BLAS_THREAD_VARS
+
+
+def test_respects_an_explicit_setting(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("OPENBLAS_NUM_THREADS", "8")
+
+ limit_blas_threads()
+
+ import os
+
+ assert os.environ["OPENBLAS_NUM_THREADS"] == "8"
+ # The others were unset, so they still get pinned.
+ assert os.environ["MKL_NUM_THREADS"] == "1"
+
+
+def test_accepts_a_thread_count(monkeypatch: pytest.MonkeyPatch) -> None:
+ limit_blas_threads(4)
+
+ import os
+
+ assert os.environ["OPENBLAS_NUM_THREADS"] == "4"
+
+
+def _first_statements(path: Path) -> list[ast.stmt]:
+ tree = ast.parse(path.read_text(encoding="utf-8"))
+ body = tree.body
+ # Skip the module docstring and `from __future__ import annotations`.
+ return [
+ node
+ for node in body
+ if not (isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant))
+ and not (isinstance(node, ast.ImportFrom) and node.module == "__future__")
+ ]
+
+
+ "entry",
+ [
+ Path("packages/cli/src/repowise/cli/main.py"),
+ Path("packages/server/src/repowise/server/app.py"),
+ ],
+)
+def test_entry_point_pins_before_any_other_import(entry: Path) -> None:
+ """The pin must be the first thing the entry module does.
+
+ Ordering is the whole mechanism. If any import runs first and reaches
+ numpy, the BLAS workspace is committed at the host's core count and no
+ later call can shrink it — the process just silently keeps the memory.
+ """
+ assert entry.exists(), f"entry point moved: {entry}"
+ statements = _first_statements(entry)
+
+ assert statements, f"no statements found in {entry}"
+ first, second = statements[0], statements[1]
+
+ assert isinstance(first, ast.ImportFrom), (
+ f"{entry}: expected the BLAS import first, got {ast.dump(first)[:80]}"
+ )
+ assert first.module == "repowise.core.blas_threads", (
+ f"{entry}: first import is {first.module}, not the BLAS pin"
+ )
+ assert isinstance(second, ast.Expr) and isinstance(second.value, ast.Call), (
+ f"{entry}: expected limit_blas_threads() to be called immediately"
+ )
+ assert second.value.func.id == "limit_blas_threads" # type: ignore[attr-defined]