Debian Codegraph @

Include/cpython/critical_section.h

raw
1 #ifndef Py_CPYTHON_CRITICAL_SECTION_H
2 # error "this header file must not be included directly"
3 #endif
4
5 // Python critical sections
6 //
7 // Conceptually, critical sections are a deadlock avoidance layer on top of
8 // per-object locks. These helpers, in combination with those locks, replace
9 // our usage of the global interpreter lock to provide thread-safety for
10 // otherwise thread-unsafe objects, such as dict.
11 //
12 // NOTE: These APIs are no-ops in non-free-threaded builds.
13 //
14 // Straightforward per-object locking could introduce deadlocks that were not
15 // present when running with the GIL. Threads may hold locks for multiple
16 // objects simultaneously because Python operations can nest. If threads were
17 // to acquire the same locks in different orders, they would deadlock.
18 //
19 // One way to avoid deadlocks is to allow threads to hold only the lock (or
20 // locks) for a single operation at a time (typically a single lock, but some
21 // operations involve two locks). When a thread begins a nested operation it
22 // could suspend the locks for any outer operation: before beginning the nested
23 // operation, the locks for the outer operation are released and when the
24 // nested operation completes, the locks for the outer operation are
25 // reacquired.
26 //
27 // To improve performance, this API uses a variation of the above scheme.
28 // Instead of immediately suspending locks any time a nested operation begins,
29 // locks are only suspended if the thread would block. This reduces the number
30 // of lock acquisitions and releases for nested operations, while still
31 // avoiding deadlocks.
32 //
33 // Additionally, the locks for any active operation are suspended around
34 // other potentially blocking operations, such as I/O. This is because the
35 // interaction between locks and blocking operations can lead to deadlocks in
36 // the same way as the interaction between multiple locks.
37 //
38 // Each thread's critical sections and their corresponding locks are tracked in
39 // a stack in `PyThreadState.critical_section`. When a thread calls
40 // `_PyThreadState_Detach()`, such as before a blocking I/O operation or when
41 // waiting to acquire a lock, the thread suspends all of its active critical
42 // sections, temporarily releasing the associated locks. When the thread calls
43 // `_PyThreadState_Attach()`, it resumes the top-most (i.e., most recent)
44 // critical section by reacquiring the associated lock or locks. See
45 // `_PyCriticalSection_Resume()`.
46 //
47 // NOTE: Only the top-most critical section is guaranteed to be active.
48 // Operations that need to lock two objects at once must use
49 // `Py_BEGIN_CRITICAL_SECTION2()`. You *CANNOT* use nested critical sections
50 // to lock more than one object at once, because the inner critical section
51 // may suspend the outer critical sections. This API does not provide a way
52 // to lock more than two objects at once (though it could be added later
53 // if actually needed).
54 //
55 // NOTE: Critical sections implicitly behave like reentrant locks because
56 // attempting to acquire the same lock will suspend any outer (earlier)
57 // critical sections. However, they are less efficient for this use case than
58 // purposefully designed reentrant locks.
59 //
60 // Example usage:
61 // Py_BEGIN_CRITICAL_SECTION(op);
62 // ...
63 // Py_END_CRITICAL_SECTION();
64 //
65 // To lock two objects at once:
66 // Py_BEGIN_CRITICAL_SECTION2(op1, op2);
67 // ...
68 // Py_END_CRITICAL_SECTION2();
69
70 typedef struct PyCriticalSection PyCriticalSection;
71 typedef struct PyCriticalSection2 PyCriticalSection2;
72
73 PyAPI_FUNC(void)
74 PyCriticalSection_Begin(PyCriticalSection *c, PyObject *op);
75
76 PyAPI_FUNC(void)
77 PyCriticalSection_BeginMutex(PyCriticalSection *c, PyMutex *m);
78
79 PyAPI_FUNC(void)
80 PyCriticalSection_End(PyCriticalSection *c);
81
82 PyAPI_FUNC(void)
83 PyCriticalSection2_Begin(PyCriticalSection2 *c, PyObject *a, PyObject *b);
84
85 PyAPI_FUNC(void)
86 PyCriticalSection2_BeginMutex(PyCriticalSection2 *c, PyMutex *m1, PyMutex *m2);
87
88 PyAPI_FUNC(void)
89 PyCriticalSection2_End(PyCriticalSection2 *c);
90
91 #ifndef Py_GIL_DISABLED
92 # define Py_BEGIN_CRITICAL_SECTION(op) \
93 {
94 # define Py_BEGIN_CRITICAL_SECTION_MUTEX(mutex) \
95 {
96 # define Py_END_CRITICAL_SECTION() \
97 }
98 # define Py_BEGIN_CRITICAL_SECTION2(a, b) \
99 {
100 # define Py_BEGIN_CRITICAL_SECTION2_MUTEX(m1, m2) \
101 {
102 # define Py_END_CRITICAL_SECTION2() \
103 }
104 #else /* !Py_GIL_DISABLED */
105
106 // NOTE: the contents of this struct are private and may change betweeen
107 // Python releases without a deprecation period.
108 struct PyCriticalSection {
109 // Tagged pointer to an outer active critical section (or 0).
110 uintptr_t _cs_prev;
111
112 // Mutex used to protect critical section
113 PyMutex *_cs_mutex;
114 };
115
116 // A critical section protected by two mutexes. Use
117 // Py_BEGIN_CRITICAL_SECTION2 and Py_END_CRITICAL_SECTION2.
118 // NOTE: the contents of this struct are private and may change betweeen
119 // Python releases without a deprecation period.
120 struct PyCriticalSection2 {
121 PyCriticalSection _cs_base;
122
123 PyMutex *_cs_mutex2;
124 };
125
126 # define Py_BEGIN_CRITICAL_SECTION(op) \
127 { \
128 PyCriticalSection _py_cs; \
129 PyCriticalSection_Begin(&_py_cs, _PyObject_CAST(op))
130
131 # define Py_BEGIN_CRITICAL_SECTION_MUTEX(mutex) \
132 { \
133 PyCriticalSection _py_cs; \
134 PyCriticalSection_BeginMutex(&_py_cs, mutex)
135
136 # define Py_END_CRITICAL_SECTION() \
137 PyCriticalSection_End(&_py_cs); \
138 }
139
140 # define Py_BEGIN_CRITICAL_SECTION2(a, b) \
141 { \
142 PyCriticalSection2 _py_cs2; \
143 PyCriticalSection2_Begin(&_py_cs2, _PyObject_CAST(a), _PyObject_CAST(b))
144
145 # define Py_BEGIN_CRITICAL_SECTION2_MUTEX(m1, m2) \
146 { \
147 PyCriticalSection2 _py_cs2; \
148 PyCriticalSection2_BeginMutex(&_py_cs2, m1, m2)
149
150 # define Py_END_CRITICAL_SECTION2() \
151 PyCriticalSection2_End(&_py_cs2); \
152 }
153
154 #endif