Documentation incorrectly states that OpenMP limits are process-wide, when they are actually thread-specific

[itamarst]

The README says:

Setting the maximum number of threads of the OpenMP and BLAS libraries has a global effect and impacts the whole Python process. There is no thread level isolation as these libraries do not offer thread-local APIs to configure the number of threads to use in nested parallel calls.

However, for OpenMP setting the limit is actually thread-specific, at least for some implementations (libgomp and libomp).

Consider the following program:

import threadpoolctl
import threading
import sklearn

tc = threadpoolctl.ThreadpoolController()

def print_thread_pool_sizes(context):
    print(f"== {context} ==")
    for info in threadpoolctl.threadpool_info():
        print(info["user_api"], info["prefix"], f"threads: {info['num_threads']}")
    print()

print_thread_pool_sizes("Initial main thread")

threadpoolctl.ThreadpoolController().limit(limits=1)
print_thread_pool_sizes("Main thread after setting limit")

t = threading.Thread(target=lambda: print_thread_pool_sizes("In a thread"))
t.start()
t.join()

Here are two runs, libgomp (code compiled locally on Ubuntu 24.04 + packages from PyPI):

== Initial main thread ==
blas libscipy_openblas threads: 12
blas libscipy_openblas threads: 12
openmp libgomp threads: 12

== Main thread after setting limit ==
blas libscipy_openblas threads: 1
blas libscipy_openblas threads: 1
openmp libgomp threads: 1

== In a thread ==
blas libscipy_openblas threads: 1
blas libscipy_openblas threads: 1
openmp libgomp threads: 12

And libomp/LLVM OpenMP (via Conda-Forge):

== Initial main thread ==
blas libopenblas threads: 12
openmp libomp threads: 12

== Main thread after setting limit ==
blas libopenblas threads: 1
openmp libomp threads: 1

== In a thread ==
blas libopenblas threads: 1
openmp libomp threads: 12

[ogrisel]

I agree the documentation is wrong. Would you like to open a PR for this fix?

[mvanhorn]

Implemented in #210 - docs: Correct README claim that OpenMP thread limits are process-wide.