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