8000 DOC: add docs on thread safety in NumPy · numpy/numpy@d902c24 · GitHub
[go: up one dir, main page]
Skip to content

Commit d902c24

Browse files
ngoldbaumcharris
ngoldbaum
authored and
charris
committed
DOC: add docs on thread safety in NumPy
[skip azp][skip actions][skip cirrus]
1 parent c080180 commit d902c24

File tree

3 files changed

+61
-5
lines changed

3 files changed

+61
-5
lines changed

‎doc/source/reference/global_state.rst

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,10 @@
44
Global state
55
************
66

7-
NumPy has a few import-time, compile-time, or runtime options
8-
which change the global behaviour.
9-
Most of these are related to performance or for debugging
10-
purposes and will not be interesting to the vast majority
11-
of users.
7+
NumPy exposes global state in legacy APIs and a few import-time,
8+
compile-time, or runtime options which change the global behaviour.
9+
Most of these are related to performance or for debugging purposes and
10+
will not be interesting to the vast majority of users.
1211

1312

1413
Performance-related options
@@ -71,3 +70,10 @@ and set the ``ndarray.base``.
7170

7271
.. versionchanged:: 1.25.2
7372
This variable is only checked on the first import.
73+
74+
Legacy User DTypes
75+
==================
76+
77+
The number of legacy user DTypes is stored in ``NPY_NUMUSERTPES``, a global
78+
variable that is exposed in the NumPy C API. This means that the legacy DType
79+
API is inherently not thread-safe.

‎doc/source/reference/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ Other topics
5858

5959
array_api
6060
simd/index
61+
thread_safety
6162
global_state
6263
security
6364
distutils_status_migration

‎doc/source/reference/thread_safety.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. _thread_safety:
2+
3+
*************
4+
Thread Safety
5+
*************
6+
7+
NumPy supports use in a multithreaded context via the `threading` module in the
8+
standard library. Many NumPy operations release the GIL, so unlike many
9+
situations in Python, it is possible to improve parallel performance by
10+
exploiting multithreaded parallelism in Python.
11+
12+
The easiest performance gains happen when each worker thread owns its own array
13+
or set of array objects, with no data directly shared between threads. Because
14+
NumPy releases the GIL for many low-level operations, threads that spend most of
15+
the time in low-level code will run in parallel.
16+
17+
It is possible to share NumPy arrays between threads, but extreme care must be
18+
taken to avoid creating thread safety issues when mutating shared arrays. If
19+
two threads simultaneously read from and write to the same array, at best they
20+
will see inconsistent views of the same array data. It is also possible to crash
21+
the Python interpreter by, for example, resizing an array while another thread
22+
is reading from it to compute a ufunc operation.
23+
24+
In the future, we may add locking to ndarray to make working with shared NumPy
25+
arrays easier, but for now we suggest focusing on read-only access of arrays
26+
that are shared between threads.
27+
28+
Note that operations that *do not* release the GIL will see no performance gains
29+
from use of the `threading` module, and instead might be better served with
30+
`multiprocessing`. In particular, operations on arrays with ``dtype=object`` do
31+
not release the GIL.
32+
33+
Free-threaded Python
34+
--------------------
35+
36+
.. versionadded:: 2.1
37+
38+
Starting with NumPy 2.1 and CPython 3.13, NumPy also has experimental support
39+
for python runtimes with the GIL disabled. See
40+
https://py-free-threading.github.io for more information about installing and
41+
using free-threaded Python, as well as information about supporting it in
42+
libraries that depend on NumPy.
43+
44+
Because free-threaded Python does not have a global interpreter lock to
45+
serialize access to Python objects, there are more opportunities for threads to
46+
mutate shared state and create thread safety issues. In addition to the
47+
limitations about locking of the ndarray object noted above, this also means
48+
that arrays with ``dtype=object`` are not protected by the GIL, creating data
49+
races for python objects that are not possible outside free-threaded python.

0 commit comments

Comments
 (0)
0