blob: e022dc793883dc67a5a2431da4f820ff7e925c8f [file] [log] [blame]
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +00001/*
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.
Kristjan Valur Jonsson0006aac2012-06-19 16:30:28 +000016 *
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.
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +000038 */
39
40#ifndef _CONDVAR_H_
41#define _CONDVAR_H_
42
43#include "Python.h"
44
45#ifndef _POSIX_THREADS
46/* This means pthreads are not implemented in libc headers, hence the macro
47 not present in unistd.h. But they still can be implemented as an external
48 library (e.g. gnu pth in pthread emulation) */
49# ifdef HAVE_PTHREAD_H
50# include <pthread.h> /* _POSIX_THREADS */
51# endif
52#endif
53
54#ifdef _POSIX_THREADS
55/*
56 * POSIX support
57 */
58#define Py_HAVE_CONDVAR
59
60#include <pthread.h>
61
62#define PyCOND_ADD_MICROSECONDS(tv, interval) \
63do { \
64 tv.tv_usec += (long) interval; \
65 tv.tv_sec += tv.tv_usec / 1000000; \
66 tv.tv_usec %= 1000000; \
67} while (0)
68
69/* We assume all modern POSIX systems have gettimeofday() */
70#ifdef GETTIMEOFDAY_NO_TZ
71#define PyCOND_GETTIMEOFDAY(ptv) gettimeofday(ptv)
72#else
73#define PyCOND_GETTIMEOFDAY(ptv) gettimeofday(ptv, (struct timezone *)NULL)
74#endif
75
76/* The following functions return 0 on success, nonzero on error */
77#define PyMUTEX_T pthread_mutex_t
78#define PyMUTEX_INIT(mut) pthread_mutex_init((mut), NULL)
79#define PyMUTEX_FINI(mut) pthread_mutex_destroy(mut)
80#define PyMUTEX_LOCK(mut) pthread_mutex_lock(mut)
81#define PyMUTEX_UNLOCK(mut) pthread_mutex_unlock(mut)
82
83#define PyCOND_T pthread_cond_t
84#define PyCOND_INIT(cond) pthread_cond_init((cond), NULL)
85#define PyCOND_FINI(cond) pthread_cond_destroy(cond)
86#define PyCOND_SIGNAL(cond) pthread_cond_signal(cond)
87#define PyCOND_BROADCAST(cond) pthread_cond_broadcast(cond)
88#define PyCOND_WAIT(cond, mut) pthread_cond_wait((cond), (mut))
89
90/* return 0 for success, 1 on timeout, -1 on error */
91Py_LOCAL_INLINE(int)
92PyCOND_TIMEDWAIT(PyCOND_T *cond, PyMUTEX_T *mut, long us)
93{
94 int r;
95 struct timespec ts;
96 struct timeval deadline;
97
98 PyCOND_GETTIMEOFDAY(&deadline);
99 PyCOND_ADD_MICROSECONDS(deadline, us);
100 ts.tv_sec = deadline.tv_sec;
101 ts.tv_nsec = deadline.tv_usec * 1000;
102
103 r = pthread_cond_timedwait((cond), (mut), &ts);
104 if (r == ETIMEDOUT)
105 return 1;
106 else if (r)
107 return -1;
108 else
109 return 0;
110}
111
112#elif defined(NT_THREADS)
113/*
114 * Windows (XP, 2003 server and later, as well as (hopefully) CE) support
115 *
116 * Emulated condition variables ones that work with XP and later, plus
117 * example native support on VISTA and onwards.
118 */
119#define Py_HAVE_CONDVAR
120
121
122/* include windows if it hasn't been done before */
123#define WIN32_LEAN_AND_MEAN
124#include <windows.h>
125
126/* options */
127/* non-emulated condition variables are provided for those that want
128 * to target Windows Vista. Modify this macro to enable them.
129 */
130#ifndef _PY_EMULATED_WIN_CV
131#define _PY_EMULATED_WIN_CV 1 /* use emulated condition variables */
132#endif
133
134/* fall back to emulation if not targeting Vista */
135#if !defined NTDDI_VISTA || NTDDI_VERSION < NTDDI_VISTA
136#undef _PY_EMULATED_WIN_CV
137#define _PY_EMULATED_WIN_CV 1
138#endif
139
140
141#if _PY_EMULATED_WIN_CV
142
143/* The mutex is a CriticalSection object and
144 The condition variables is emulated with the help of a semaphore.
145 Semaphores are available on Windows XP (2003 server) and later.
146 We use a Semaphore rather than an auto-reset event, because although
147 an auto-resent event might appear to solve the lost-wakeup bug (race
148 condition between releasing the outer lock and waiting) because it
149 maintains state even though a wait hasn't happened, there is still
150 a lost wakeup problem if more than one thread are interrupted in the
151 critical place. A semaphore solves that, because its state is counted,
152 not Boolean.
153 Because it is ok to signal a condition variable with no one
154 waiting, we need to keep track of the number of
155 waiting threads. Otherwise, the semaphore's state could rise
156 without bound. This also helps reduce the number of "spurious wakeups"
157 that would otherwise happen.
158
Kristjan Valur Jonsson0006aac2012-06-19 16:30:28 +0000159 This implementation still has the problem that the threads woken
160 with a "signal" aren't necessarily those that are already
161 waiting. It corresponds to listing 2 in:
162 http://birrell.org/andrew/papers/ImplementingCVs.pdf
163
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000164 Generic emulations of the pthread_cond_* API using
165 earlier Win32 functions can be found on the Web.
Kristján Valur Jónsson32eccca2013-03-19 20:18:37 -0700166 The following read can be give background information to these issues,
167 but the implementations are all broken in some way.
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000168 http://www.cse.wustl.edu/~schmidt/win32-cv-1.html
169*/
170
171typedef CRITICAL_SECTION PyMUTEX_T;
172
173Py_LOCAL_INLINE(int)
174PyMUTEX_INIT(PyMUTEX_T *cs)
175{
176 InitializeCriticalSection(cs);
177 return 0;
178}
179
180Py_LOCAL_INLINE(int)
181PyMUTEX_FINI(PyMUTEX_T *cs)
182{
183 DeleteCriticalSection(cs);
184 return 0;
185}
186
187Py_LOCAL_INLINE(int)
188PyMUTEX_LOCK(PyMUTEX_T *cs)
189{
190 EnterCriticalSection(cs);
191 return 0;
192}
193
194Py_LOCAL_INLINE(int)
195PyMUTEX_UNLOCK(PyMUTEX_T *cs)
196{
197 LeaveCriticalSection(cs);
198 return 0;
199}
200
201/* The ConditionVariable object. From XP onwards it is easily emulated with
202 * a Semaphore
203 */
204
205typedef struct _PyCOND_T
206{
207 HANDLE sem;
Kristjan Valur Jonsson16170772012-06-19 10:10:09 +0000208 int waiting; /* to allow PyCOND_SIGNAL to be a no-op */
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000209} PyCOND_T;
210
211Py_LOCAL_INLINE(int)
212PyCOND_INIT(PyCOND_T *cv)
213{
214 /* A semaphore with a "large" max value, The positive value
215 * is only needed to catch those "lost wakeup" events and
216 * race conditions when a timed wait elapses.
217 */
218 cv->sem = CreateSemaphore(NULL, 0, 100000, NULL);
219 if (cv->sem==NULL)
220 return -1;
221 cv->waiting = 0;
222 return 0;
223}
224
225Py_LOCAL_INLINE(int)
226PyCOND_FINI(PyCOND_T *cv)
227{
228 return CloseHandle(cv->sem) ? 0 : -1;
229}
230
231/* this implementation can detect a timeout. Returns 1 on timeout,
232 * 0 otherwise (and -1 on error)
233 */
234Py_LOCAL_INLINE(int)
235_PyCOND_WAIT_MS(PyCOND_T *cv, PyMUTEX_T *cs, DWORD ms)
236{
237 DWORD wait;
238 cv->waiting++;
239 PyMUTEX_UNLOCK(cs);
240 /* "lost wakeup bug" would occur if the caller were interrupted here,
241 * but we are safe because we are using a semaphore wich has an internal
242 * count.
243 */
Martin v. Löwisb26a9b12013-01-25 14:25:48 +0100244 wait = WaitForSingleObjectEx(cv->sem, ms, FALSE);
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000245 PyMUTEX_LOCK(cs);
246 if (wait != WAIT_OBJECT_0)
247 --cv->waiting;
248 /* Here we have a benign race condition with PyCOND_SIGNAL.
249 * When failure occurs or timeout, it is possible that
250 * PyCOND_SIGNAL also decrements this value
251 * and signals releases the mutex. This is benign because it
252 * just means an extra spurious wakeup for a waiting thread.
Kristjan Valur Jonsson16170772012-06-19 10:10:09 +0000253 * ('waiting' corresponds to the semaphore's "negative" count and
254 * we may end up with e.g. (waiting == -1 && sem.count == 1). When
255 * a new thread comes along, it will pass right throuhgh, having
256 * adjusted it to (waiting == 0 && sem.count == 0).
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000257 */
258
259 if (wait == WAIT_FAILED)
260 return -1;
261 /* return 0 on success, 1 on timeout */
262 return wait != WAIT_OBJECT_0;
263}
264
265Py_LOCAL_INLINE(int)
266PyCOND_WAIT(PyCOND_T *cv, PyMUTEX_T *cs)
267{
268 int result = _PyCOND_WAIT_MS(cv, cs, INFINITE);
269 return result >= 0 ? 0 : result;
270}
271
272Py_LOCAL_INLINE(int)
273PyCOND_TIMEDWAIT(PyCOND_T *cv, PyMUTEX_T *cs, long us)
274{
275 return _PyCOND_WAIT_MS(cv, cs, us/1000);
276}
277
278Py_LOCAL_INLINE(int)
279PyCOND_SIGNAL(PyCOND_T *cv)
280{
Kristjan Valur Jonsson16170772012-06-19 10:10:09 +0000281 /* this test allows PyCOND_SIGNAL to be a no-op unless required
282 * to wake someone up, thus preventing an unbounded increase of
283 * the semaphore's internal counter.
284 */
285 if (cv->waiting > 0) {
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000286 /* notifying thread decreases the cv->waiting count so that
Kristjan Valur Jonsson16170772012-06-19 10:10:09 +0000287 * a delay between notify and actual wakeup of the target thread
288 * doesn't cause a number of extra ReleaseSemaphore calls.
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000289 */
290 cv->waiting--;
291 return ReleaseSemaphore(cv->sem, 1, NULL) ? 0 : -1;
292 }
293 return 0;
294}
295
296Py_LOCAL_INLINE(int)
297PyCOND_BROADCAST(PyCOND_T *cv)
298{
Kristján Valur Jónsson32eccca2013-03-19 20:18:37 -0700299 int waiting = cv->waiting;
300 if (waiting > 0) {
301 cv->waiting = 0;
302 return ReleaseSemaphore(cv->sem, waiting, NULL) ? 0 : -1;
Kristján Valur Jónssone75ff352012-06-18 20:30:44 +0000303 }
304 return 0;
305}
306
307#else
308
309/* Use native Win7 primitives if build target is Win7 or higher */
310
311/* SRWLOCK is faster and better than CriticalSection */
312typedef SRWLOCK PyMUTEX_T;
313
314Py_LOCAL_INLINE(int)
315PyMUTEX_INIT(PyMUTEX_T *cs)
316{
317 InitializeSRWLock(cs);
318 return 0;
319}
320
321Py_LOCAL_INLINE(int)
322PyMUTEX_FINI(PyMUTEX_T *cs)
323{
324 return 0;
325}
326
327Py_LOCAL_INLINE(int)
328PyMUTEX_LOCK(PyMUTEX_T *cs)
329{
330 AcquireSRWLockExclusive(cs);
331 return 0;
332}
333
334Py_LOCAL_INLINE(int)
335PyMUTEX_UNLOCK(PyMUTEX_T *cs)
336{
337 ReleaseSRWLockExclusive(cs);
338 return 0;
339}
340
341
342typedef CONDITION_VARIABLE PyCOND_T;
343
344Py_LOCAL_INLINE(int)
345PyCOND_INIT(PyCOND_T *cv)
346{
347 InitializeConditionVariable(cv);
348 return 0;
349}
350Py_LOCAL_INLINE(int)
351PyCOND_FINI(PyCOND_T *cv)
352{
353 return 0;
354}
355
356Py_LOCAL_INLINE(int)
357PyCOND_WAIT(PyCOND_T *cv, PyMUTEX_T *cs)
358{
359 return SleepConditionVariableSRW(cv, cs, INFINITE, 0) ? 0 : -1;
360}
361
362/* This implementation makes no distinction about timeouts. Signal
363 * 2 to indicate that we don't know.
364 */
365Py_LOCAL_INLINE(int)
366PyCOND_TIMEDWAIT(PyCOND_T *cv, PyMUTEX_T *cs, long us)
367{
368 return SleepConditionVariableSRW(cv, cs, us/1000, 0) ? 2 : -1;
369}
370
371Py_LOCAL_INLINE(int)
372PyCOND_SIGNAL(PyCOND_T *cv)
373{
374 WakeConditionVariable(cv);
375 return 0;
376}
377
378Py_LOCAL_INLINE(int)
379PyCOND_BROADCAST(PyCOND_T *cv)
380{
381 WakeAllConditionVariable(cv);
382 return 0;
383}
384
385
386#endif /* _PY_EMULATED_WIN_CV */
387
388#endif /* _POSIX_THREADS, NT_THREADS */
389
390#endif /* _CONDVAR_H_ */