|
| 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 |
0 commit comments