codekingpro/portable-devtools

1// Lightweight locks and other synchronization mechanisms.2//3// These implementations are based on WebKit's WTF::Lock. See4// https://webkit.org/blog/6161/locking-in-webkit/ for a description of the5// design.6#ifndef Py_INTERNAL_LOCK_H7#define Py_INTERNAL_LOCK_H8#ifdef __cplusplus9extern "C" {10#endif11 12#ifndef Py_BUILD_CORE13#  error "this header requires Py_BUILD_CORE define"14#endif15 16//_Py_UNLOCKED is defined as 0 and _Py_LOCKED as 1 in Include/cpython/lock.h17#define _Py_HAS_PARKED  218#define _Py_ONCE_INITIALIZED 419 20static inline int21PyMutex_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.29static inline void30_PyMutex_at_fork_reinit(PyMutex *m)31{32    memset(m, 0, sizeof(*m));33}34 35typedef 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. See47// _PyLockFlags for details.48extern 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.52static inline void53PyMutex_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 improved62// error messages) otherwise returns 0.63extern int _PyMutex_TryUnlock(PyMutex *m);64 65 66// PyEvent is a one-time event notification67typedef struct {68    uint8_t v;69} PyEvent;70 71// Check if the event is set without blocking. Returns 1 if the event is set or72// 0 otherwise.73PyAPI_FUNC(int) _PyEvent_IsSet(PyEvent *evt);74 75// Set the event and notify any waiting threads.76// Export for '_testinternalcapi' shared extension77PyAPI_FUNC(void) _PyEvent_Notify(PyEvent *evt);78 79// Wait for the event to be set. If the event is already set, then this returns80// immediately.81PyAPI_FUNC(void) PyEvent_Wait(PyEvent *evt);82 83// Wait for the event to be set, or until the timeout expires. If the event is84// 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` is86// true, then the thread will detach/release the GIL while waiting.87PyAPI_FUNC(int)88PyEvent_WaitTimed(PyEvent *evt, PyTime_t timeout_ns, int detach);89 90// _PyRawMutex implements a word-sized mutex that that does not depend on the91// parking lot API, and therefore can be used in the parking lot92// implementation.93//94// The mutex uses a packed representation: the least significant bit is used to95// indicate whether the mutex is locked or not. The remaining bits are either96// zero or a pointer to a `struct raw_mutex_entry` (see lock.c).97typedef struct {98    uintptr_t v;99} _PyRawMutex;100 101// Slow paths for lock/unlock102extern void _PyRawMutex_LockSlow(_PyRawMutex *m);103extern void _PyRawMutex_UnlockSlow(_PyRawMutex *m);104 105static inline void106_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 115static inline void116_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 should126// return 0 on success and -1 on failure.127typedef int _Py_once_fn_t(void *arg);128 129// (private) slow path for one time initialization130PyAPI_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.139static inline int140_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.149typedef struct {150    PyMutex mutex;151    unsigned long long thread;  // i.e., PyThread_get_thread_ident_ex()152    size_t level;153} _PyRecursiveMutex;154 155PyAPI_FUNC(int) _PyRecursiveMutex_IsLockedByCurrentThread(_PyRecursiveMutex *m);156PyAPI_FUNC(void) _PyRecursiveMutex_Lock(_PyRecursiveMutex *m);157extern PyLockStatus _PyRecursiveMutex_LockTimed(_PyRecursiveMutex *m, PyTime_t timeout, _PyLockFlags flags);158PyAPI_FUNC(void) _PyRecursiveMutex_Unlock(_PyRecursiveMutex *m);159extern int _PyRecursiveMutex_TryUnlock(_PyRecursiveMutex *m);160 161// A readers-writer (RW) lock. The lock supports multiple concurrent readers or162// a single writer. The lock is write-preferring: if a writer is waiting while163// the lock is read-locked then, new readers will be blocked. This avoids164// starvation of writers.165//166// In C++, the equivalent synchronization primitive is std::shared_mutex167// with shared ("read") and exclusive ("write") locking.168//169// The two least significant bits are used to indicate if the lock is170// 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 the172// number of readers holding the lock.173//174// 0b000..00000: unlocked175// 0bnnn..nnn00: nnn..nnn readers holding the lock176// 0bnnn..nnn10: nnn..nnn readers holding the lock and a writer is waiting177// 0b00000..010: unlocked with awoken writer about to acquire lock178// 0b00000..001: write-locked179// 0b00000..011: write-locked and readers or other writers are waiting180//181// Note that reader_count must be zero if the lock is held by a writer, and182// 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 is185// not fair: if fairness is desired, use an additional PyMutex to serialize186// writers. The lock is also not reentrant.187typedef struct {188    uintptr_t bits;189} _PyRWMutex;190 191// Read lock (i.e., shared lock)192PyAPI_FUNC(void) _PyRWMutex_RLock(_PyRWMutex *rwmutex);193PyAPI_FUNC(void) _PyRWMutex_RUnlock(_PyRWMutex *rwmutex);194 195// Write lock (i.e., exclusive lock)196PyAPI_FUNC(void) _PyRWMutex_Lock(_PyRWMutex *rwmutex);197PyAPI_FUNC(void) _PyRWMutex_Unlock(_PyRWMutex *rwmutex);198 199// Similar to linux seqlock: https://en.wikipedia.org/wiki/Seqlock200// We use a sequence number to lock the writer, an even sequence means we're unlocked, an odd201// sequence means we're locked.  Readers will read the sequence before attempting to read the202// underlying data and then read the sequence number again after reading the data.  If the203// 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 write207// and restore the previous sequence.208typedef struct {209    uint32_t sequence;210} _PySeqLock;211 212// Lock the sequence lock for the writer213PyAPI_FUNC(void) _PySeqLock_LockWrite(_PySeqLock *seqlock);214 215// Unlock the sequence lock and move to the next sequence number.216PyAPI_FUNC(void) _PySeqLock_UnlockWrite(_PySeqLock *seqlock);217 218// Abandon the current update indicating that no mutations have occurred219// and restore the previous sequence value.220PyAPI_FUNC(void) _PySeqLock_AbandonWrite(_PySeqLock *seqlock);221 222// Begin a read operation and return the current sequence number.223PyAPI_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.227PyAPI_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 1230// if the lock was held and any associated data should be cleared.231PyAPI_FUNC(int) _PySeqLock_AfterFork(_PySeqLock *seqlock);232 233#ifdef __cplusplus234}235#endif236#endif   /* !Py_INTERNAL_LOCK_H */237