Skip to content

DOC minimally discuss inconsistencies in openMP's limitation thread locality #209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tomMoral merged 6 commits into from
Jun 18, 2026
+22 −4
Merged

DOC minimally discuss inconsistencies in openMP's limitation thread locality #209

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bf84d87
Update docs
itamarst Jun 17, 2026
9ca9494
Clarify.
itamarst Jun 17, 2026
b14ed4b
Rewrap
itamarst Jun 17, 2026
d720470
Rephrase to be more accurate.
itamarst Jun 18, 2026
1c4dc7a
Try to be even more accurate
itamarst Jun 18, 2026
11d9357
Try to be even more accurate
itamarst Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,19 @@ Fine control of the underlying thread-pool size can be useful in
workloads that involve nested parallelism so as to mitigate
oversubscription issues.

> **Important:** In its current state, `threadpoolctl` is only designed for
> situations where BLAS and OpenMP are only called from the main Python thread.
> Or, to be more accurate, `threadpoolctl` and BLAS/OpenMP APIs should only ever
> called from the same, single Python thread. For example:
>
> * When you're using it to configure a worker in a process pool, which then calls BLAS or OpenMP APIs directly in the main thread.
> * A Jupyter notebook, where the BLAS or OpenMP APIs are being called from code running in the cell's main thread.
>
> However, once you start calling BLAS or OpenMP APIs and `threadpoolctl` from
> multiple different Python threads, the impact of the `threadpoolctl` limiting
> APIs will be very inconsistent. For more details and a plan to fix this, see
> https://github.com/joblib/threadpoolctl/issues/208

## Installation

- For users, install the last published version from PyPI:
Expand Down Expand Up @@ -322,11 +335,16 @@ https://github.com/xianyi/OpenBLAS/issues/2985).
and workarounds:
https://github.com/joblib/threadpoolctl/blob/master/multiple_openmp.md

- 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.
- Setting the maximum number of threads of the OpenMP and BLAS libraries has
inconsistent scope and semantics (thread-local vs process-wide) depending on
the underlying library. For more details see
https://github.com/joblib/threadpoolctl/issues/208
Comment thread
itamarst marked this conversation as resolved.

For example, if you're using OpenMP with libgomp (gcc) or libomp (clang), the
setting is thread-local and sets how many OpenMP threads will be started in
the current thread. On the other hand, with OpenBLAS with pthreads backend or
on Windows, the setting is process-wide and impacts the size of a process-wide
thread pool shared across all threads in the process.

## Maintainers

Expand Down
Loading