| 1 |
.. _threadsafety: |
| 2 |
|
| 3 |
************************ |
| 4 |
Thread Safety Guarantees |
| 5 |
************************ |
| 6 |
|
| 7 |
This page documents thread-safety guarantees for built-in types in Python's |
| 8 |
free-threaded build. The guarantees described here apply when using Python with |
| 9 |
the :term:`GIL` disabled (free-threaded mode). When the GIL is enabled, most |
| 10 |
operations are implicitly serialized. |
| 11 |
|
| 12 |
For general guidance on writing thread-safe code in free-threaded Python, see |
| 13 |
:ref:`freethreading-python-howto`. |
| 14 |
|
| 15 |
|
| 16 |
.. _threadsafety-levels: |
| 17 |
|
| 18 |
Thread safety levels |
| 19 |
==================== |
| 20 |
|
| 21 |
The C API documentation uses the following levels to describe the thread |
| 22 |
safety guarantees of each function. The levels are listed from least to |
| 23 |
most safe. |
| 24 |
|
| 25 |
.. _threadsafety-level-incompatible: |
| 26 |
|
| 27 |
Incompatible |
| 28 |
------------ |
| 29 |
|
| 30 |
A function or operation that cannot be made safe for concurrent use even |
| 31 |
with external synchronization. Incompatible code typically accesses |
| 32 |
global state in an unsynchronized way and must only be called from a single |
| 33 |
thread throughout the program's lifetime. |
| 34 |
|
| 35 |
Example: a function that modifies process-wide state such as signal handlers |
| 36 |
or environment variables, where concurrent calls from any threads, even with |
| 37 |
external locking, can conflict with the runtime or other libraries. |
| 38 |
|
| 39 |
.. _threadsafety-level-compatible: |
| 40 |
|
| 41 |
Compatible |
| 42 |
---------- |
| 43 |
|
| 44 |
A function or operation that is safe to call from multiple threads |
| 45 |
*provided* the caller supplies appropriate external synchronization, for |
| 46 |
example by holding a :term:`lock` for the duration of each call. Without |
| 47 |
such synchronization, concurrent calls may produce :term:`race conditions |
| 48 |
<race condition>` or :term:`data races <data race>`. |
| 49 |
|
| 50 |
Example: a function that reads from or writes to an object whose internal |
| 51 |
state is not protected by a lock. Callers must ensure that no two threads |
| 52 |
access the same object at the same time. |
| 53 |
|
| 54 |
.. _threadsafety-level-distinct: |
| 55 |
|
| 56 |
Safe on distinct objects |
| 57 |
------------------------ |
| 58 |
|
| 59 |
A function or operation that is safe to call from multiple threads without |
| 60 |
external synchronization, as long as each thread operates on a **different** |
| 61 |
object. Two threads may call the function at the same time, but they must |
| 62 |
not pass the same object (or objects that share underlying state) as |
| 63 |
arguments. |
| 64 |
|
| 65 |
Example: a function that modifies fields of a struct using non-atomic |
| 66 |
writes. Two threads can each call the function on their own struct |
| 67 |
instance safely, but concurrent calls on the *same* instance require |
| 68 |
external synchronization. |
| 69 |
|
| 70 |
.. _threadsafety-level-shared: |
| 71 |
|
| 72 |
Safe on shared objects |
| 73 |
---------------------- |
| 74 |
|
| 75 |
A function or operation that is safe for concurrent use on the **same** |
| 76 |
object. The implementation uses internal synchronization (such as |
| 77 |
:term:`per-object locks <per-object lock>` or |
| 78 |
:ref:`critical sections <python-critical-section-api>`) to protect shared |
| 79 |
mutable state, so callers do not need to supply their own locking. |
| 80 |
|
| 81 |
Example: :c:func:`PyList_GetItemRef` can be called from multiple threads on the |
| 82 |
same :c:type:`PyListObject` - it uses internal synchronization to serialize |
| 83 |
access. |
| 84 |
|
| 85 |
.. _threadsafety-level-atomic: |
| 86 |
|
| 87 |
Atomic |
| 88 |
------ |
| 89 |
|
| 90 |
A function or operation that appears :term:`atomic <atomic operation>` with |
| 91 |
respect to other threads - it executes instantaneously from the perspective |
| 92 |
of other threads. This is the strongest form of thread safety. |
| 93 |
|
| 94 |
Example: :c:func:`PyMutex_IsLocked` performs an atomic read of the mutex |
| 95 |
state and can be called from any thread at any time. |
| 96 |
|
| 97 |
|
| 98 |
.. _thread-safety-list: |
| 99 |
|
| 100 |
Thread safety for list objects |
| 101 |
============================== |
| 102 |
|
| 103 |
Reading a single element from a :class:`list` is |
| 104 |
:term:`atomic <atomic operation>`: |
| 105 |
|
| 106 |
.. code-block:: |
| 107 |
:class: good |
| 108 |
|
| 109 |
lst[i] # list.__getitem__ |
| 110 |
|
| 111 |
The following methods traverse the list and use :term:`atomic <atomic operation>` |
| 112 |
reads of each item to perform their function. That means that they may |
| 113 |
return results affected by concurrent modifications: |
| 114 |
|
| 115 |
.. code-block:: |
| 116 |
:class: maybe |
| 117 |
|
| 118 |
item in lst |
| 119 |
lst.index(item) |
| 120 |
lst.count(item) |
| 121 |
|
| 122 |
All of the above operations avoid acquiring :term:`per-object locks |
| 123 |
<per-object lock>`. They do not block concurrent modifications. Other |
| 124 |
operations that hold a lock will not block these from observing intermediate |
| 125 |
states. |
| 126 |
|
| 127 |
All other operations from here on block using the :term:`per-object lock`. |
| 128 |
|
| 129 |
Writing a single item via ``lst[i] = x`` is safe to call from multiple |
| 130 |
threads and will not corrupt the list. |
| 131 |
|
| 132 |
The following operations return new objects and appear |
| 133 |
:term:`atomic <atomic operation>` to other threads: |
| 134 |
|
| 135 |
.. code-block:: |
| 136 |
:class: good |
| 137 |
|
| 138 |
lst1 + lst2 # concatenates two lists into a new list |
| 139 |
x * lst # repeats lst x times into a new list |
| 140 |
lst.copy() # returns a shallow copy of the list |
| 141 |
|
| 142 |
The following methods that only operate on a single element with no shifting |
| 143 |
required are :term:`atomic <atomic operation>`: |
| 144 |
|
| 145 |
.. code-block:: |
| 146 |
:class: good |
| 147 |
|
| 148 |
lst.append(x) # append to the end of the list, no shifting required |
| 149 |
lst.pop() # pop element from the end of the list, no shifting required |
| 150 |
|
| 151 |
The :meth:`~list.clear` method is also :term:`atomic <atomic operation>`. |
| 152 |
Other threads cannot observe elements being removed. |
| 153 |
|
| 154 |
The :meth:`~list.sort` method is not :term:`atomic <atomic operation>`. |
| 155 |
Other threads cannot observe intermediate states during sorting, but the |
| 156 |
list appears empty for the duration of the sort. |
| 157 |
|
| 158 |
The following operations may allow :term:`lock-free` operations to observe |
| 159 |
intermediate states since they modify multiple elements in place: |
| 160 |
|
| 161 |
.. code-block:: |
| 162 |
:class: maybe |
| 163 |
|
| 164 |
lst.insert(idx, item) # shifts elements |
| 165 |
lst.pop(idx) # idx not at the end of the list, shifts elements |
| 166 |
lst *= x # copies elements in place |
| 167 |
|
| 168 |
The :meth:`~list.remove` method may allow concurrent modifications since |
| 169 |
element comparison may execute arbitrary Python code (via |
| 170 |
:meth:`~object.__eq__`). |
| 171 |
|
| 172 |
:meth:`~list.extend` is safe to call from multiple threads. However, its |
| 173 |
guarantees depend on the iterable passed to it. If it is a :class:`list`, a |
| 174 |
:class:`tuple`, a :class:`set`, a :class:`frozenset`, a :class:`dict` or a |
| 175 |
:ref:`dictionary view object <dict-views>` (but not their subclasses), the |
| 176 |
``extend`` operation is safe from concurrent modifications to the iterable. |
| 177 |
Otherwise, an iterator is created which can be concurrently modified by |
| 178 |
another thread. The same applies to inplace concatenation of a list with |
| 179 |
other iterables when using ``lst += iterable``. |
| 180 |
|
| 181 |
Similarly, assigning to a list slice with ``lst[i:j] = iterable`` is safe |
| 182 |
to call from multiple threads, but ``iterable`` is only locked when it is |
| 183 |
also a :class:`list` (but not its subclasses). |
| 184 |
|
| 185 |
Operations that involve multiple accesses, as well as iteration, are never |
| 186 |
atomic. For example: |
| 187 |
|
| 188 |
.. code-block:: |
| 189 |
:class: bad |
| 190 |
|
| 191 |
# NOT atomic: read-modify-write |
| 192 |
lst[i] = lst[i] + 1 |
| 193 |
|
| 194 |
# NOT atomic: check-then-act |
| 195 |
if lst: |
| 196 |
item = lst.pop() |
| 197 |
|
| 198 |
# NOT thread-safe: iteration while modifying |
| 199 |
for item in lst: |
| 200 |
process(item) # another thread may modify lst |
| 201 |
|
| 202 |
Consider external synchronization when sharing :class:`list` instances |
| 203 |
across threads. |
| 204 |
|
| 205 |
|
| 206 |
.. _thread-safety-dict: |
| 207 |
|
| 208 |
Thread safety for dict objects |
| 209 |
============================== |
| 210 |
|
| 211 |
Creating a dictionary with the :class:`dict` constructor is atomic when the |
| 212 |
argument to it is a :class:`dict` or a :class:`tuple`. When using the |
| 213 |
:meth:`dict.fromkeys` method, dictionary creation is atomic when the |
| 214 |
argument is a :class:`dict`, :class:`tuple`, :class:`set` or |
| 215 |
:class:`frozenset`. |
| 216 |
|
| 217 |
The following operations and functions are :term:`lock-free` and |
| 218 |
:term:`atomic <atomic operation>`. |
| 219 |
|
| 220 |
.. code-block:: |
| 221 |
:class: good |
| 222 |
|
| 223 |
d[key] # dict.__getitem__ |
| 224 |
d.get(key) # dict.get |
| 225 |
key in d # dict.__contains__ |
| 226 |
len(d) # dict.__len__ |
| 227 |
|
| 228 |
All other operations from here on hold the :term:`per-object lock`. |
| 229 |
|
| 230 |
Writing or removing a single item is safe to call from multiple threads |
| 231 |
and will not corrupt the dictionary: |
| 232 |
|
| 233 |
.. code-block:: |
| 234 |
:class: good |
| 235 |
|
| 236 |
d[key] = value # write |
| 237 |
del d[key] # delete |
| 238 |
d.pop(key) # remove and return |
| 239 |
d.popitem() # remove and return last item |
| 240 |
d.setdefault(key, v) # insert if missing |
| 241 |
|
| 242 |
These operations may compare keys using :meth:`~object.__eq__`, which can |
| 243 |
execute arbitrary Python code. During such comparisons, the dictionary may |
| 244 |
be modified by another thread. For built-in types like :class:`str`, |
| 245 |
:class:`int`, and :class:`float`, that implement :meth:`~object.__eq__` in C, |
| 246 |
the underlying lock is not released during comparisons and this is not a |
| 247 |
concern. |
| 248 |
|
| 249 |
The following operations return new objects and hold the :term:`per-object lock` |
| 250 |
for the duration of the operation: |
| 251 |
|
| 252 |
.. code-block:: |
| 253 |
:class: good |
| 254 |
|
| 255 |
d.copy() # returns a shallow copy of the dictionary |
| 256 |
d | other # merges two dicts into a new dict |
| 257 |
d.keys() # returns a new dict_keys view object |
| 258 |
d.values() # returns a new dict_values view object |
| 259 |
d.items() # returns a new dict_items view object |
| 260 |
|
| 261 |
The :meth:`~dict.clear` method holds the lock for its duration. Other |
| 262 |
threads cannot observe elements being removed. |
| 263 |
|
| 264 |
The following operations lock both dictionaries. For :meth:`~dict.update` |
| 265 |
and ``|=``, this applies only when the other operand is a :class:`dict` |
| 266 |
that uses the standard dict iterator (but not subclasses that override |
| 267 |
iteration). For equality comparison, this applies to :class:`dict` and |
| 268 |
its subclasses: |
| 269 |
|
| 270 |
.. code-block:: |
| 271 |
:class: good |
| 272 |
|
| 273 |
d.update(other_dict) # both locked when other_dict is a dict |
| 274 |
d |= other_dict # both locked when other_dict is a dict |
| 275 |
d == other_dict # both locked for dict and subclasses |
| 276 |
|
| 277 |
All comparison operations also compare values using :meth:`~object.__eq__`, |
| 278 |
so for non-built-in types the lock may be released during comparison. |
| 279 |
|
| 280 |
:meth:`~dict.fromkeys` locks both the new dictionary and the iterable |
| 281 |
when the iterable is exactly a :class:`dict`, :class:`set`, or |
| 282 |
:class:`frozenset` (not subclasses): |
| 283 |
|
| 284 |
.. code-block:: |
| 285 |
:class: good |
| 286 |
|
| 287 |
dict.fromkeys(a_dict) # locks both |
| 288 |
dict.fromkeys(a_set) # locks both |
| 289 |
dict.fromkeys(a_frozenset) # locks both |
| 290 |
|
| 291 |
When updating from a non-dict iterable, only the target dictionary is |
| 292 |
locked. The iterable may be concurrently modified by another thread: |
| 293 |
|
| 294 |
.. code-block:: |
| 295 |
:class: maybe |
| 296 |
|
| 297 |
d.update(iterable) # iterable is not a dict: only d locked |
| 298 |
d |= iterable # iterable is not a dict: only d locked |
| 299 |
dict.fromkeys(iterable) # iterable is not a dict/set/frozenset: only result locked |
| 300 |
|
| 301 |
Operations that involve multiple accesses, as well as iteration, are never |
| 302 |
atomic: |
| 303 |
|
| 304 |
.. code-block:: |
| 305 |
:class: bad |
| 306 |
|
| 307 |
# NOT atomic: read-modify-write |
| 308 |
d[key] = d[key] + 1 |
| 309 |
|
| 310 |
# NOT atomic: check-then-act (TOCTOU) |
| 311 |
if key in d: |
| 312 |
del d[key] |
| 313 |
|
| 314 |
# NOT thread-safe: iteration while modifying |
| 315 |
for key, value in d.items(): |
| 316 |
process(key) # another thread may modify d |
| 317 |
|
| 318 |
To avoid time-of-check to time-of-use (TOCTOU) issues, use atomic |
| 319 |
operations or handle exceptions: |
| 320 |
|
| 321 |
.. code-block:: |
| 322 |
:class: good |
| 323 |
|
| 324 |
# Use pop() with default instead of check-then-delete |
| 325 |
d.pop(key, None) |
| 326 |
|
| 327 |
# Or handle the exception |
| 328 |
try: |
| 329 |
del d[key] |
| 330 |
except KeyError: |
| 331 |
pass |
| 332 |
|
| 333 |
To safely iterate over a dictionary that may be modified by another |
| 334 |
thread, iterate over a copy: |
| 335 |
|
| 336 |
.. code-block:: |
| 337 |
:class: good |
| 338 |
|
| 339 |
# Make a copy to iterate safely |
| 340 |
for key, value in d.copy().items(): |
| 341 |
process(key) |
| 342 |
|
| 343 |
Consider external synchronization when sharing :class:`dict` instances |
| 344 |
across threads. |
| 345 |
|
| 346 |
|
| 347 |
.. _thread-safety-set: |
| 348 |
|
| 349 |
Thread safety for set objects |
| 350 |
============================== |
| 351 |
|
| 352 |
The :func:`len` function is lock-free and :term:`atomic <atomic operation>`. |
| 353 |
|
| 354 |
The following read operation is lock-free. It does not block concurrent |
| 355 |
modifications and may observe intermediate states from operations that |
| 356 |
hold the per-object lock: |
| 357 |
|
| 358 |
.. code-block:: |
| 359 |
:class: good |
| 360 |
|
| 361 |
elem in s # set.__contains__ |
| 362 |
|
| 363 |
This operation may compare elements using :meth:`~object.__eq__`, which can |
| 364 |
execute arbitrary Python code. During such comparisons, the set may be |
| 365 |
modified by another thread. For built-in types like :class:`str`, |
| 366 |
:class:`int`, and :class:`float`, :meth:`!__eq__` does not release the |
| 367 |
underlying lock during comparisons and this is not a concern. |
| 368 |
|
| 369 |
All other operations from here on hold the per-object lock. |
| 370 |
|
| 371 |
Adding or removing a single element is safe to call from multiple threads |
| 372 |
and will not corrupt the set: |
| 373 |
|
| 374 |
.. code-block:: |
| 375 |
:class: good |
| 376 |
|
| 377 |
s.add(elem) # add element |
| 378 |
s.remove(elem) # remove element, raise if missing |
| 379 |
s.discard(elem) # remove element if present |
| 380 |
s.pop() # remove and return arbitrary element |
| 381 |
|
| 382 |
These operations also compare elements, so the same :meth:`~object.__eq__` |
| 383 |
considerations as above apply. |
| 384 |
|
| 385 |
The :meth:`~set.copy` method returns a new object and holds the per-object lock |
| 386 |
for the duration so that it is always atomic. |
| 387 |
|
| 388 |
The :meth:`~set.clear` method holds the lock for its duration. Other |
| 389 |
threads cannot observe elements being removed. |
| 390 |
|
| 391 |
The following operations only accept :class:`set` or :class:`frozenset` |
| 392 |
as operands and always lock both objects: |
| 393 |
|
| 394 |
.. code-block:: |
| 395 |
:class: good |
| 396 |
|
| 397 |
s |= other # other must be set/frozenset |
| 398 |
s &= other # other must be set/frozenset |
| 399 |
s -= other # other must be set/frozenset |
| 400 |
s ^= other # other must be set/frozenset |
| 401 |
s & other # other must be set/frozenset |
| 402 |
s | other # other must be set/frozenset |
| 403 |
s - other # other must be set/frozenset |
| 404 |
s ^ other # other must be set/frozenset |
| 405 |
|
| 406 |
:meth:`set.update`, :meth:`set.union`, :meth:`set.intersection` and |
| 407 |
:meth:`set.difference` can take multiple iterables as arguments. They all |
| 408 |
iterate through all the passed iterables and do the following: |
| 409 |
|
| 410 |
* :meth:`set.update` and :meth:`set.union` lock both objects only when |
| 411 |
the other operand is a :class:`set`, :class:`frozenset`, or :class:`dict`. |
| 412 |
* :meth:`set.intersection` and :meth:`set.difference` always try to lock |
| 413 |
all objects. |
| 414 |
|
| 415 |
:meth:`set.symmetric_difference` tries to lock both objects. |
| 416 |
|
| 417 |
The update variants of the above methods also have some differences between |
| 418 |
them: |
| 419 |
|
| 420 |
* :meth:`set.difference_update` and :meth:`set.intersection_update` try |
| 421 |
to lock all objects one-by-one. |
| 422 |
* :meth:`set.symmetric_difference_update` only locks the arguments if it is |
| 423 |
of type :class:`set`, :class:`frozenset`, or :class:`dict`. |
| 424 |
|
| 425 |
The following methods always try to lock both objects: |
| 426 |
|
| 427 |
.. code-block:: |
| 428 |
:class: good |
| 429 |
|
| 430 |
s.isdisjoint(other) # both locked |
| 431 |
s.issubset(other) # both locked |
| 432 |
s.issuperset(other) # both locked |
| 433 |
|
| 434 |
Operations that involve multiple accesses, as well as iteration, are never |
| 435 |
atomic: |
| 436 |
|
| 437 |
.. code-block:: |
| 438 |
:class: bad |
| 439 |
|
| 440 |
# NOT atomic: check-then-act |
| 441 |
if elem in s: |
| 442 |
s.remove(elem) |
| 443 |
|
| 444 |
# NOT thread-safe: iteration while modifying |
| 445 |
for elem in s: |
| 446 |
process(elem) # another thread may modify s |
| 447 |
|
| 448 |
Consider external synchronization when sharing :class:`set` instances |
| 449 |
across threads. See :ref:`freethreading-python-howto` for more information. |
| 450 |
|
| 451 |
|
| 452 |
.. _thread-safety-bytearray: |
| 453 |
|
| 454 |
Thread safety for bytearray objects |
| 455 |
=================================== |
| 456 |
|
| 457 |
The :func:`len` function is lock-free and :term:`atomic <atomic operation>`. |
| 458 |
|
| 459 |
Concatenation and comparisons use the buffer protocol, which prevents |
| 460 |
resizing but does not hold the per-object lock. These operations may |
| 461 |
observe intermediate states from concurrent modifications: |
| 462 |
|
| 463 |
.. code-block:: |
| 464 |
:class: maybe |
| 465 |
|
| 466 |
ba + other # may observe concurrent writes |
| 467 |
ba == other # may observe concurrent writes |
| 468 |
ba < other # may observe concurrent writes |
| 469 |
|
| 470 |
All other operations from here on hold the per-object lock. |
| 471 |
|
| 472 |
Reading a single element or slice is safe to call from multiple threads: |
| 473 |
|
| 474 |
.. code-block:: |
| 475 |
:class: good |
| 476 |
|
| 477 |
ba[i] # bytearray.__getitem__ |
| 478 |
ba[i:j] # slice |
| 479 |
|
| 480 |
The following operations are safe to call from multiple threads and will |
| 481 |
not corrupt the bytearray: |
| 482 |
|
| 483 |
.. code-block:: |
| 484 |
:class: good |
| 485 |
|
| 486 |
ba[i] = x # write single byte |
| 487 |
ba[i:j] = values # write slice |
| 488 |
ba.append(x) # append single byte |
| 489 |
ba.extend(other) # extend with iterable |
| 490 |
ba.insert(i, x) # insert single byte |
| 491 |
ba.pop() # remove and return last byte |
| 492 |
ba.pop(i) # remove and return byte at index |
| 493 |
ba.remove(x) # remove first occurrence |
| 494 |
ba.reverse() # reverse in place |
| 495 |
ba.clear() # remove all bytes |
| 496 |
|
| 497 |
Slice assignment locks both objects when *values* is a :class:`bytearray`: |
| 498 |
|
| 499 |
.. code-block:: |
| 500 |
:class: good |
| 501 |
|
| 502 |
ba[i:j] = other_bytearray # both locked |
| 503 |
|
| 504 |
The following operations return new objects and hold the per-object lock |
| 505 |
for the duration: |
| 506 |
|
| 507 |
.. code-block:: |
| 508 |
:class: good |
| 509 |
|
| 510 |
ba.copy() # returns a shallow copy |
| 511 |
ba * n # repeat into new bytearray |
| 512 |
|
| 513 |
The membership test holds the lock for its duration: |
| 514 |
|
| 515 |
.. code-block:: |
| 516 |
:class: good |
| 517 |
|
| 518 |
x in ba # bytearray.__contains__ |
| 519 |
|
| 520 |
All other bytearray methods (such as :meth:`~bytearray.find`, |
| 521 |
:meth:`~bytearray.replace`, :meth:`~bytearray.split`, |
| 522 |
:meth:`~bytearray.decode`, etc.) hold the per-object lock for their |
| 523 |
duration. |
| 524 |
|
| 525 |
Operations that involve multiple accesses, as well as iteration, are never |
| 526 |
atomic: |
| 527 |
|
| 528 |
.. code-block:: |
| 529 |
:class: bad |
| 530 |
|
| 531 |
# NOT atomic: check-then-act |
| 532 |
if x in ba: |
| 533 |
ba.remove(x) |
| 534 |
|
| 535 |
# NOT thread-safe: iteration while modifying |
| 536 |
for byte in ba: |
| 537 |
process(byte) # another thread may modify ba |
| 538 |
|
| 539 |
To safely iterate over a bytearray that may be modified by another |
| 540 |
thread, iterate over a copy: |
| 541 |
|
| 542 |
.. code-block:: |
| 543 |
:class: good |
| 544 |
|
| 545 |
# Make a copy to iterate safely |
| 546 |
for byte in ba.copy(): |
| 547 |
process(byte) |
| 548 |
|
| 549 |
Consider external synchronization when sharing :class:`bytearray` instances |
| 550 |
across threads. See :ref:`freethreading-python-howto` for more information. |
| 551 |
|
| 552 |
|
| 553 |
.. _thread-safety-memoryview: |
| 554 |
|
| 555 |
Thread safety for memoryview objects |
| 556 |
==================================== |
| 557 |
|
| 558 |
:class:`memoryview` objects provide access to the internal data of an |
| 559 |
underlying object without copying. Thread safety depends on both the |
| 560 |
memoryview itself and the underlying buffer exporter. |
| 561 |
|
| 562 |
The memoryview implementation uses atomic operations to track its own |
| 563 |
exports in the :term:`free-threaded build`. Creating and |
| 564 |
releasing a memoryview are thread-safe. Attribute access (e.g., |
| 565 |
:attr:`~memoryview.shape`, :attr:`~memoryview.format`) reads fields that |
| 566 |
are immutable for the lifetime of the memoryview, so concurrent reads |
| 567 |
are safe as long as the memoryview has not been released. |
| 568 |
|
| 569 |
However, the actual data accessed through the memoryview is owned by the |
| 570 |
underlying object. Concurrent access to this data is only safe if the |
| 571 |
underlying object supports it: |
| 572 |
|
| 573 |
* For immutable objects like :class:`bytes`, concurrent reads through |
| 574 |
multiple memoryviews are safe. |
| 575 |
|
| 576 |
* For mutable objects like :class:`bytearray`, reading and writing the |
| 577 |
same memory region from multiple threads without external |
| 578 |
synchronization is not safe and may result in data corruption. |
| 579 |
Note that even read-only memoryviews of mutable objects do not |
| 580 |
prevent data races if the underlying object is modified from |
| 581 |
another thread. |
| 582 |
|
| 583 |
.. code-block:: |
| 584 |
:class: bad |
| 585 |
|
| 586 |
# NOT safe: concurrent writes to the same buffer |
| 587 |
data = bytearray(1000) |
| 588 |
view = memoryview(data) |
| 589 |
# Thread 1: view[0:500] = b'x' * 500 |
| 590 |
# Thread 2: view[0:500] = b'y' * 500 |
| 591 |
|
| 592 |
.. code-block:: |
| 593 |
:class: good |
| 594 |
|
| 595 |
# Safe: use a lock for concurrent access |
| 596 |
import threading |
| 597 |
lock = threading.Lock() |
| 598 |
data = bytearray(1000) |
| 599 |
view = memoryview(data) |
| 600 |
|
| 601 |
with lock: |
| 602 |
view[0:500] = b'x' * 500 |
| 603 |
|
| 604 |
Resizing or reallocating the underlying object (such as calling |
| 605 |
:meth:`bytearray.resize`) while a memoryview is exported raises |
| 606 |
:exc:`BufferError`. This is enforced regardless of threading. |