@@ -13,6 +13,88 @@ For general guidance on writing thread-safe code in free-threaded Python, see
1313:ref: `freethreading-python-howto `.
1414
1515
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+
1698.. _thread-safety-list :
1799
18100Thread safety for list objects
![pydoc-zh-tw[bot]](https://avatars.githubusercontent.com/in/137018?v=4&size=40){kind=avatar}
0 commit comments