1 /*
2 * Portable condition variable support for windows and pthreads.
3 * Everything is inline, this header can be included where needed.
4 *
5 * APIs generally return 0 on success and non-zero on error,
6 * and the caller needs to use its platform's error mechanism to
7 * discover the error (errno, or GetLastError())
8 *
9 * Note that some implementations cannot distinguish between a
10 * condition variable wait time-out and successful wait. Most often
11 * the difference is moot anyway since the wait condition must be
12 * re-checked.
13 * PyCOND_TIMEDWAIT, in addition to returning negative on error,
14 * thus returns 0 on regular success, 1 on timeout
15 * or 2 if it can't tell.
16 *
17 * There are at least two caveats with using these condition variables,
18 * due to the fact that they may be emulated with Semaphores on
19 * Windows:
20 * 1) While PyCOND_SIGNAL() will wake up at least one thread, we
21 * cannot currently guarantee that it will be one of the threads
22 * already waiting in a PyCOND_WAIT() call. It _could_ cause
23 * the wakeup of a subsequent thread to try a PyCOND_WAIT(),
24 * including the thread doing the PyCOND_SIGNAL() itself.
25 * The same applies to PyCOND_BROADCAST(), if N threads are waiting
26 * then at least N threads will be woken up, but not necessarily
27 * those already waiting.
28 * For this reason, don't make the scheduling assumption that a
29 * specific other thread will get the wakeup signal
30 * 2) The _mutex_ must be held when calling PyCOND_SIGNAL() and
31 * PyCOND_BROADCAST().
32 * While e.g. the posix standard strongly recommends that the mutex
33 * associated with the condition variable is held when a
34 * pthread_cond_signal() call is made, this is not a hard requirement,
35 * although scheduling will not be "reliable" if it isn't. Here
36 * the mutex is used for internal synchronization of the emulated
37 * Condition Variable.
38 */
39
40 #ifndef _CONDVAR_IMPL_H_
41 #define _CONDVAR_IMPL_H_
42
43 #include "Python.h"
44 #include "pycore_condvar.h"
45
46 #ifdef _POSIX_THREADS
47 /*
48 * POSIX support
49 */
50
51 /* These private functions are implemented in Python/thread_pthread.h */
52 int _PyThread_cond_init(PyCOND_T *cond);
53 void _PyThread_cond_after(long long us, struct timespec *abs);
54
55 /* The following functions return 0 on success, nonzero on error */
56 #define PyMUTEX_INIT(mut) pthread_mutex_init((mut), NULL)
57 #define PyMUTEX_FINI(mut) pthread_mutex_destroy(mut)
58 #define PyMUTEX_LOCK(mut) pthread_mutex_lock(mut)
59 #define PyMUTEX_UNLOCK(mut) pthread_mutex_unlock(mut)
60
61 #define PyCOND_INIT(cond) _PyThread_cond_init(cond)
62 #define PyCOND_FINI(cond) pthread_cond_destroy(cond)
63 #define PyCOND_SIGNAL(cond) pthread_cond_signal(cond)
64 #define PyCOND_BROADCAST(cond) pthread_cond_broadcast(cond)
65 #define PyCOND_WAIT(cond, mut) pthread_cond_wait((cond), (mut))
66
67 /* return 0 for success, 1 on timeout, -1 on error */
68 Py_LOCAL_INLINE(int)
69 PyCOND_TIMEDWAIT(PyCOND_T *cond, PyMUTEX_T *mut, long long us)
70 {
71 struct timespec abs_timeout;
72 _PyThread_cond_after(us, &abs_timeout);
73 int ret = pthread_cond_timedwait(cond, mut, &abs_timeout);
74 if (ret == ETIMEDOUT) {
75 return 1;
76 }
77 if (ret) {
78 return -1;
79 }
80 return 0;
81 }
82
83 #elif defined(NT_THREADS)
84 /*
85 * Windows (XP, 2003 server and later, as well as (hopefully) CE) support
86 *
87 * Emulated condition variables ones that work with XP and later, plus
88 * example native support on VISTA and onwards.
89 */
90
91 #if _PY_EMULATED_WIN_CV
92
93 /* The mutex is a CriticalSection object and
94 The condition variables is emulated with the help of a semaphore.
95
96 This implementation still has the problem that the threads woken
97 with a "signal" aren't necessarily those that are already
98 waiting. It corresponds to listing 2 in:
99 http://birrell.org/andrew/papers/ImplementingCVs.pdf
100
101 Generic emulations of the pthread_cond_* API using
102 earlier Win32 functions can be found on the web.
103 The following read can be give background information to these issues,
104 but the implementations are all broken in some way.
105 http://www.cse.wustl.edu/~schmidt/win32-cv-1.html
106 */
107
108 Py_LOCAL_INLINE(int)
109 PyMUTEX_INIT(PyMUTEX_T *cs)
110 {
111 InitializeCriticalSection(cs);
112 return 0;
113 }
114
115 Py_LOCAL_INLINE(int)
116 PyMUTEX_FINI(PyMUTEX_T *cs)
117 {
118 DeleteCriticalSection(cs);
119 return 0;
120 }
121
122 Py_LOCAL_INLINE(int)
123 PyMUTEX_LOCK(PyMUTEX_T *cs)
124 {
125 EnterCriticalSection(cs);
126 return 0;
127 }
128
129 Py_LOCAL_INLINE(int)
130 PyMUTEX_UNLOCK(PyMUTEX_T *cs)
131 {
132 LeaveCriticalSection(cs);
133 return 0;
134 }
135
136
137 Py_LOCAL_INLINE(int)
138 PyCOND_INIT(PyCOND_T *cv)
139 {
140 /* A semaphore with a "large" max value, The positive value
141 * is only needed to catch those "lost wakeup" events and
142 * race conditions when a timed wait elapses.
143 */
144 cv->sem = CreateSemaphore(NULL, 0, 100000, NULL);
145 if (cv->sem==NULL)
146 return -1;
147 cv->waiting = 0;
148 return 0;
149 }
150
151 Py_LOCAL_INLINE(int)
152 PyCOND_FINI(PyCOND_T *cv)
153 {
154 return CloseHandle(cv->sem) ? 0 : -1;
155 }
156
157 /* this implementation can detect a timeout. Returns 1 on timeout,
158 * 0 otherwise (and -1 on error)
159 */
160 Py_LOCAL_INLINE(int)
161 _PyCOND_WAIT_MS(PyCOND_T *cv, PyMUTEX_T *cs, DWORD ms)
162 {
163 DWORD wait;
164 cv->waiting++;
165 PyMUTEX_UNLOCK(cs);
166 /* "lost wakeup bug" would occur if the caller were interrupted here,
167 * but we are safe because we are using a semaphore which has an internal
168 * count.
169 */
170 wait = WaitForSingleObjectEx(cv->sem, ms, FALSE);
171 PyMUTEX_LOCK(cs);
172 if (wait != WAIT_OBJECT_0)
173 --cv->waiting;
174 /* Here we have a benign race condition with PyCOND_SIGNAL.
175 * When failure occurs or timeout, it is possible that
176 * PyCOND_SIGNAL also decrements this value
177 * and signals releases the mutex. This is benign because it
178 * just means an extra spurious wakeup for a waiting thread.
179 * ('waiting' corresponds to the semaphore's "negative" count and
180 * we may end up with e.g. (waiting == -1 && sem.count == 1). When
181 * a new thread comes along, it will pass right through, having
182 * adjusted it to (waiting == 0 && sem.count == 0).
183 */
184
185 if (wait == WAIT_FAILED)
186 return -1;
187 /* return 0 on success, 1 on timeout */
188 return wait != WAIT_OBJECT_0;
189 }
190
191 Py_LOCAL_INLINE(int)
192 PyCOND_WAIT(PyCOND_T *cv, PyMUTEX_T *cs)
193 {
194 int result = _PyCOND_WAIT_MS(cv, cs, INFINITE);
195 return result >= 0 ? 0 : result;
196 }
197
198 Py_LOCAL_INLINE(int)
199 PyCOND_TIMEDWAIT(PyCOND_T *cv, PyMUTEX_T *cs, long long us)
200 {
201 return _PyCOND_WAIT_MS(cv, cs, (DWORD)(us/1000));
202 }
203
204 Py_LOCAL_INLINE(int)
205 PyCOND_SIGNAL(PyCOND_T *cv)
206 {
207 /* this test allows PyCOND_SIGNAL to be a no-op unless required
208 * to wake someone up, thus preventing an unbounded increase of
209 * the semaphore's internal counter.
210 */
211 if (cv->waiting > 0) {
212 /* notifying thread decreases the cv->waiting count so that
213 * a delay between notify and actual wakeup of the target thread
214 * doesn't cause a number of extra ReleaseSemaphore calls.
215 */
216 cv->waiting--;
217 return ReleaseSemaphore(cv->sem, 1, NULL) ? 0 : -1;
218 }
219 return 0;
220 }
221
222 Py_LOCAL_INLINE(int)
223 PyCOND_BROADCAST(PyCOND_T *cv)
224 {
225 int waiting = cv->waiting;
226 if (waiting > 0) {
227 cv->waiting = 0;
228 return ReleaseSemaphore(cv->sem, waiting, NULL) ? 0 : -1;
229 }
230 return 0;
231 }
232
233 #else /* !_PY_EMULATED_WIN_CV */
234
235 Py_LOCAL_INLINE(int)
236 PyMUTEX_INIT(PyMUTEX_T *cs)
237 {
238 InitializeSRWLock(cs);
239 return 0;
240 }
241
242 Py_LOCAL_INLINE(int)
243 PyMUTEX_FINI(PyMUTEX_T *cs)
244 {
245 return 0;
246 }
247
248 Py_LOCAL_INLINE(int)
249 PyMUTEX_LOCK(PyMUTEX_T *cs)
250 {
251 AcquireSRWLockExclusive(cs);
252 return 0;
253 }
254
255 Py_LOCAL_INLINE(int)
256 PyMUTEX_UNLOCK(PyMUTEX_T *cs)
257 {
258 ReleaseSRWLockExclusive(cs);
259 return 0;
260 }
261
262
263 Py_LOCAL_INLINE(int)
264 PyCOND_INIT(PyCOND_T *cv)
265 {
266 InitializeConditionVariable(cv);
267 return 0;
268 }
269 Py_LOCAL_INLINE(int)
270 PyCOND_FINI(PyCOND_T *cv)
271 {
272 return 0;
273 }
274
275 Py_LOCAL_INLINE(int)
276 PyCOND_WAIT(PyCOND_T *cv, PyMUTEX_T *cs)
277 {
278 return SleepConditionVariableSRW(cv, cs, INFINITE, 0) ? 0 : -1;
279 }
280
281 /* This implementation makes no distinction about timeouts. Signal
282 * 2 to indicate that we don't know.
283 */
284 Py_LOCAL_INLINE(int)
285 PyCOND_TIMEDWAIT(PyCOND_T *cv, PyMUTEX_T *cs, long long us)
286 {
287 return SleepConditionVariableSRW(cv, cs, (DWORD)(us/1000), 0) ? 2 : -1;
288 }
289
290 Py_LOCAL_INLINE(int)
291 PyCOND_SIGNAL(PyCOND_T *cv)
292 {
293 WakeConditionVariable(cv);
294 return 0;
295 }
296
297 Py_LOCAL_INLINE(int)
298 PyCOND_BROADCAST(PyCOND_T *cv)
299 {
300 WakeAllConditionVariable(cv);
301 return 0;
302 }
303
304
305 #endif /* _PY_EMULATED_WIN_CV */
306
307 #endif /* _POSIX_THREADS, NT_THREADS */
308
309 #endif /* _CONDVAR_IMPL_H_ */