codekingpro/portable-devtools

1#ifndef Py_CPYTHON_CRITICAL_SECTION_H2#  error "this header file must not be included directly"3#endif4 5// Python critical sections6//7// Conceptually, critical sections are a deadlock avoidance layer on top of8// per-object locks. These helpers, in combination with those locks, replace9// our usage of the global interpreter lock to provide thread-safety for10// 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 not15// present when running with the GIL. Threads may hold locks for multiple16// objects simultaneously because Python operations can nest. If threads were17// 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 (or20// locks) for a single operation at a time (typically a single lock, but some21// operations involve two locks). When a thread begins a nested operation it22// could suspend the locks for any outer operation: before beginning the nested23// operation, the locks for the outer operation are released and when the24// nested operation completes, the locks for the outer operation are25// 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 number30// of lock acquisitions and releases for nested operations, while still31// avoiding deadlocks.32//33// Additionally, the locks for any active operation are suspended around34// other potentially blocking operations, such as I/O. This is because the35// interaction between locks and blocking operations can lead to deadlocks in36// the same way as the interaction between multiple locks.37//38// Each thread's critical sections and their corresponding locks are tracked in39// a stack in `PyThreadState.critical_section`. When a thread calls40// `_PyThreadState_Detach()`, such as before a blocking I/O operation or when41// waiting to acquire a lock, the thread suspends all of its active critical42// sections, temporarily releasing the associated locks. When the thread calls43// `_PyThreadState_Attach()`, it resumes the top-most (i.e., most recent)44// critical section by reacquiring the associated lock or locks.  See45// `_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 use49// `Py_BEGIN_CRITICAL_SECTION2()`. You *CANNOT* use nested critical sections50// to lock more than one object at once, because the inner critical section51// may  suspend the outer critical sections. This API does not provide a way52// to lock more than two objects at once (though it could be added later53// if actually needed).54//55// NOTE: Critical sections implicitly behave like reentrant locks because56// attempting to acquire the same lock will suspend any outer (earlier)57// critical sections. However, they are less efficient for this use case than58// 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 70typedef struct PyCriticalSection PyCriticalSection;71typedef struct PyCriticalSection2 PyCriticalSection2;72 73PyAPI_FUNC(void)74PyCriticalSection_Begin(PyCriticalSection *c, PyObject *op);75 76PyAPI_FUNC(void)77PyCriticalSection_BeginMutex(PyCriticalSection *c, PyMutex *m);78 79PyAPI_FUNC(void)80PyCriticalSection_End(PyCriticalSection *c);81 82PyAPI_FUNC(void)83PyCriticalSection2_Begin(PyCriticalSection2 *c, PyObject *a, PyObject *b);84 85PyAPI_FUNC(void)86PyCriticalSection2_BeginMutex(PyCriticalSection2 *c, PyMutex *m1, PyMutex *m2);87 88PyAPI_FUNC(void)89PyCriticalSection2_End(PyCriticalSection2 *c);90 91#ifndef Py_GIL_DISABLED92# 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 betweeen107// Python releases without a deprecation period.108struct PyCriticalSection {109    // Tagged pointer to an outer active critical section (or 0).110    uintptr_t _cs_prev;111 112    // Mutex used to protect critical section113    PyMutex *_cs_mutex;114};115 116// A critical section protected by two mutexes. Use117// Py_BEGIN_CRITICAL_SECTION2 and Py_END_CRITICAL_SECTION2.118// NOTE: the contents of this struct are private and may change betweeen119// Python releases without a deprecation period.120struct 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#endif155