Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/cpython/critical_section.h
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
