Debian Codegraph @

Doc/library/threadsafety.rst

raw
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.