Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.14/internal/pycore_lock.h
1 // Lightweight locks and other synchronization mechanisms. 2 // 3 // These implementations are based on WebKit's WTF::Lock. See 4 // https://webkit.org/blog/6161/locking-in-webkit/ for a description of the 5 // design. 6 #ifndef Py_INTERNAL_LOCK_H 7 #define Py_INTERNAL_LOCK_H 8 #ifdef __cplusplus 9 extern "C" { 10 #endif 11 12 #ifndef Py_BUILD_CORE 13 # error "this header requires Py_BUILD_CORE define" 14 #endif 15 16 //_Py_UNLOCKED is defined as 0 and _Py_LOCKED as 1 in Include/cpython/lock.h 17 #define _Py_HAS_PARKED 2 18 #define _Py_ONCE_INITIALIZED 4 19 20 static inline int 21 PyMutex_LockFast(PyMutex *m) 22 { 23 uint8_t expected = _Py_UNLOCKED; 24 uint8_t *lock_bits = &m->_bits; 25 return _Py_atomic_compare_exchange_uint8(lock_bits, &expected, _Py_LOCKED); 26 } 27 28 // Re-initializes the mutex after a fork to the unlocked state. 29 static inline void 30 _PyMutex_at_fork_reinit(PyMutex *m) 31 { 32 memset(m, 0, sizeof(*m)); 33 } 34 35 typedef enum _PyLockFlags { 36 // Do not detach/release the GIL when waiting on the lock. 37 _Py_LOCK_DONT_DETACH = 0, 38 39 // Detach/release the GIL while waiting on the lock. 40 _PY_LOCK_DETACH = 1, 41 42 // Handle signals if interrupted while waiting on the lock. 43 _PY_LOCK_HANDLE_SIGNALS = 2, 44 } _PyLockFlags; 45 46 // Lock a mutex with an optional timeout and additional options. See 47 // _PyLockFlags for details. 48 extern PyAPI_FUNC(PyLockStatus) 49 _PyMutex_LockTimed(PyMutex *m, PyTime_t timeout_ns, _PyLockFlags flags); 50 51 // Lock a mutex with additional options. See _PyLockFlags for details. 52 static inline void 53 PyMutex_LockFlags(PyMutex *m, _PyLockFlags flags) 54 { 55 uint8_t expected = _Py_UNLOCKED; 56 if (!_Py_atomic_compare_exchange_uint8(&m->_bits, &expected, _Py_LOCKED)) { 57 _PyMutex_LockTimed(m, -1, flags); 58 } 59 } 60 61 // Unlock a mutex, returns -1 if the mutex is not locked (used for improved 62 // error messages) otherwise returns 0. 63 extern int _PyMutex_TryUnlock(PyMutex *m); 64 65 66 // PyEvent is a one-time event notification 67 typedef struct { 68 uint8_t v; 69 } PyEvent; 70 71 // Check if the event is set without blocking. Returns 1 if the event is set or 72 // 0 otherwise. 73 PyAPI_FUNC(int) _PyEvent_IsSet(PyEvent *evt); 74 75 // Set the event and notify any waiting threads. 76 // Export for '_testinternalcapi' shared extension 77 PyAPI_FUNC(void) _PyEvent_Notify(PyEvent *evt); 78 79 // Wait for the event to be set. If the event is already set, then this returns 80 // immediately. 81 PyAPI_FUNC(void) PyEvent_Wait(PyEvent *evt); 82 83 // Wait for the event to be set, or until the timeout expires. If the event is 84 // already set, then this returns immediately. Returns 1 if the event was set, 85 // and 0 if the timeout expired or thread was interrupted. If `detach` is 86 // true, then the thread will detach/release the GIL while waiting. 87 PyAPI_FUNC(int) 88 PyEvent_WaitTimed(PyEvent *evt, PyTime_t timeout_ns, int detach); 89 90 // _PyRawMutex implements a word-sized mutex that that does not depend on the 91 // parking lot API, and therefore can be used in the parking lot 92 // implementation. 93 // 94 // The mutex uses a packed representation: the least significant bit is used to 95 // indicate whether the mutex is locked or not. The remaining bits are either 96 // zero or a pointer to a `struct raw_mutex_entry` (see lock.c). 97 typedef struct { 98 uintptr_t v; 99 } _PyRawMutex; 100 101 // Slow paths for lock/unlock 102 extern void _PyRawMutex_LockSlow(_PyRawMutex *m); 103 extern void _PyRawMutex_UnlockSlow(_PyRawMutex *m); 104 105 static inline void 106 _PyRawMutex_Lock(_PyRawMutex *m) 107 { 108 uintptr_t unlocked = _Py_UNLOCKED; 109 if (_Py_atomic_compare_exchange_uintptr(&m->v, &unlocked, _Py_LOCKED)) { 110 return; 111 } 112 _PyRawMutex_LockSlow(m); 113 } 114 115 static inline void 116 _PyRawMutex_Unlock(_PyRawMutex *m) 117 { 118 uintptr_t locked = _Py_LOCKED; 119 if (_Py_atomic_compare_exchange_uintptr(&m->v, &locked, _Py_UNLOCKED)) { 120 return; 121 } 122 _PyRawMutex_UnlockSlow(m); 123 } 124 125 // Type signature for one-time initialization functions. The function should 126 // return 0 on success and -1 on failure. 127 typedef int _Py_once_fn_t(void *arg); 128 129 // (private) slow path for one time initialization 130 PyAPI_FUNC(int) 131 _PyOnceFlag_CallOnceSlow(_PyOnceFlag *flag, _Py_once_fn_t *fn, void *arg); 132 133 // Calls `fn` once using `flag`. The `arg` is passed to the call to `fn`. 134 // 135 // Returns 0 on success and -1 on failure. 136 // 137 // If `fn` returns 0 (success), then subsequent calls immediately return 0. 138 // If `fn` returns -1 (failure), then subsequent calls will retry the call. 139 static inline int 140 _PyOnceFlag_CallOnce(_PyOnceFlag *flag, _Py_once_fn_t *fn, void *arg) 141 { 142 if (_Py_atomic_load_uint8(&flag->v) == _Py_ONCE_INITIALIZED) { 143 return 0; 144 } 145 return _PyOnceFlag_CallOnceSlow(flag, fn, arg); 146 } 147 148 // A recursive mutex. The mutex should zero-initialized. 149 typedef struct { 150 PyMutex mutex; 151 unsigned long long thread; // i.e., PyThread_get_thread_ident_ex() 152 size_t level; 153 } _PyRecursiveMutex; 154 155 PyAPI_FUNC(int) _PyRecursiveMutex_IsLockedByCurrentThread(_PyRecursiveMutex *m); 156 PyAPI_FUNC(void) _PyRecursiveMutex_Lock(_PyRecursiveMutex *m); 157 extern PyLockStatus _PyRecursiveMutex_LockTimed(_PyRecursiveMutex *m, PyTime_t timeout, _PyLockFlags flags); 158 PyAPI_FUNC(void) _PyRecursiveMutex_Unlock(_PyRecursiveMutex *m); 159 extern int _PyRecursiveMutex_TryUnlock(_PyRecursiveMutex *m); 160 161 // A readers-writer (RW) lock. The lock supports multiple concurrent readers or 162 // a single writer. The lock is write-preferring: if a writer is waiting while 163 // the lock is read-locked then, new readers will be blocked. This avoids 164 // starvation of writers. 165 // 166 // In C++, the equivalent synchronization primitive is std::shared_mutex 167 // with shared ("read") and exclusive ("write") locking. 168 // 169 // The two least significant bits are used to indicate if the lock is 170 // write-locked and if there are parked threads (either readers or writers) 171 // waiting to acquire the lock. The remaining bits are used to indicate the 172 // number of readers holding the lock. 173 // 174 // 0b000..00000: unlocked 175 // 0bnnn..nnn00: nnn..nnn readers holding the lock 176 // 0bnnn..nnn10: nnn..nnn readers holding the lock and a writer is waiting 177 // 0b00000..010: unlocked with awoken writer about to acquire lock 178 // 0b00000..001: write-locked 179 // 0b00000..011: write-locked and readers or other writers are waiting 180 // 181 // Note that reader_count must be zero if the lock is held by a writer, and 182 // vice versa. The lock can only be held by readers or a writer, but not both. 183 // 184 // The design is optimized for simplicity of the implementation. The lock is 185 // not fair: if fairness is desired, use an additional PyMutex to serialize 186 // writers. The lock is also not reentrant. 187 typedef struct { 188 uintptr_t bits; 189 } _PyRWMutex; 190 191 // Read lock (i.e., shared lock) 192 PyAPI_FUNC(void) _PyRWMutex_RLock(_PyRWMutex *rwmutex); 193 PyAPI_FUNC(void) _PyRWMutex_RUnlock(_PyRWMutex *rwmutex); 194 195 // Write lock (i.e., exclusive lock) 196 PyAPI_FUNC(void) _PyRWMutex_Lock(_PyRWMutex *rwmutex); 197 PyAPI_FUNC(void) _PyRWMutex_Unlock(_PyRWMutex *rwmutex); 198 199 // Similar to linux seqlock: https://en.wikipedia.org/wiki/Seqlock 200 // We use a sequence number to lock the writer, an even sequence means we're unlocked, an odd 201 // sequence means we're locked. Readers will read the sequence before attempting to read the 202 // underlying data and then read the sequence number again after reading the data. If the 203 // sequence has not changed the data is valid. 204 // 205 // Differs a little bit in that we use CAS on sequence as the lock, instead of a separate spin lock. 206 // The writer can also detect that the undelering data has not changed and abandon the write 207 // and restore the previous sequence. 208 typedef struct { 209 uint32_t sequence; 210 } _PySeqLock; 211 212 // Lock the sequence lock for the writer 213 PyAPI_FUNC(void) _PySeqLock_LockWrite(_PySeqLock *seqlock); 214 215 // Unlock the sequence lock and move to the next sequence number. 216 PyAPI_FUNC(void) _PySeqLock_UnlockWrite(_PySeqLock *seqlock); 217 218 // Abandon the current update indicating that no mutations have occurred 219 // and restore the previous sequence value. 220 PyAPI_FUNC(void) _PySeqLock_AbandonWrite(_PySeqLock *seqlock); 221 222 // Begin a read operation and return the current sequence number. 223 PyAPI_FUNC(uint32_t) _PySeqLock_BeginRead(_PySeqLock *seqlock); 224 225 // End the read operation and confirm that the sequence number has not changed. 226 // Returns 1 if the read was successful or 0 if the read should be retried. 227 PyAPI_FUNC(int) _PySeqLock_EndRead(_PySeqLock *seqlock, uint32_t previous); 228 229 // Check if the lock was held during a fork and clear the lock. Returns 1 230 // if the lock was held and any associated data should be cleared. 231 PyAPI_FUNC(int) _PySeqLock_AfterFork(_PySeqLock *seqlock); 232 233 #ifdef __cplusplus 234 } 235 #endif 236 #endif /* !Py_INTERNAL_LOCK_H */
