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_End(PyCriticalSection *c); 78 79 PyAPI_FUNC(void) 80 PyCriticalSection2_Begin(PyCriticalSection2 *c, PyObject *a, PyObject *b); 81 82 PyAPI_FUNC(void) 83 PyCriticalSection2_End(PyCriticalSection2 *c); 84 85 #ifndef Py_GIL_DISABLED 86 # define Py_BEGIN_CRITICAL_SECTION(op) \ 87 { 88 # define Py_END_CRITICAL_SECTION() \ 89 } 90 # define Py_BEGIN_CRITICAL_SECTION2(a, b) \ 91 { 92 # define Py_END_CRITICAL_SECTION2() \ 93 } 94 #else /* !Py_GIL_DISABLED */ 95 96 // NOTE: the contents of this struct are private and may change betweeen 97 // Python releases without a deprecation period. 98 struct PyCriticalSection { 99 // Tagged pointer to an outer active critical section (or 0). 100 uintptr_t _cs_prev; 101 102 // Mutex used to protect critical section 103 PyMutex *_cs_mutex; 104 }; 105 106 // A critical section protected by two mutexes. Use 107 // Py_BEGIN_CRITICAL_SECTION2 and Py_END_CRITICAL_SECTION2. 108 // NOTE: the contents of this struct are private and may change betweeen 109 // Python releases without a deprecation period. 110 struct PyCriticalSection2 { 111 PyCriticalSection _cs_base; 112 113 PyMutex *_cs_mutex2; 114 }; 115 116 # define Py_BEGIN_CRITICAL_SECTION(op) \ 117 { \ 118 PyCriticalSection _py_cs; \ 119 PyCriticalSection_Begin(&_py_cs, _PyObject_CAST(op)) 120 121 # define Py_END_CRITICAL_SECTION() \ 122 PyCriticalSection_End(&_py_cs); \ 123 } 124 125 # define Py_BEGIN_CRITICAL_SECTION2(a, b) \ 126 { \ 127 PyCriticalSection2 _py_cs2; \ 128 PyCriticalSection2_Begin(&_py_cs2, _PyObject_CAST(a), _PyObject_CAST(b)) 129 130 # define Py_END_CRITICAL_SECTION2() \ 131 PyCriticalSection2_End(&_py_cs2); \ 132 } 133 134 #endif 135