• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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_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) \
63 do { /* TODO: add overflow and truncation checks */ \
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 */
91 Py_LOCAL_INLINE(int)
PyCOND_TIMEDWAIT(PyCOND_T * cond,PyMUTEX_T * mut,long long us)92 PyCOND_TIMEDWAIT(PyCOND_T *cond, PyMUTEX_T *mut, long 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 
159    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 
164    Generic emulations of the pthread_cond_* API using
165    earlier Win32 functions can be found on the Web.
166    The following read can be give background information to these issues,
167    but the implementations are all broken in some way.
168    http://www.cse.wustl.edu/~schmidt/win32-cv-1.html
169 */
170 
171 typedef CRITICAL_SECTION PyMUTEX_T;
172 
173 Py_LOCAL_INLINE(int)
PyMUTEX_INIT(PyMUTEX_T * cs)174 PyMUTEX_INIT(PyMUTEX_T *cs)
175 {
176     InitializeCriticalSection(cs);
177     return 0;
178 }
179 
180 Py_LOCAL_INLINE(int)
PyMUTEX_FINI(PyMUTEX_T * cs)181 PyMUTEX_FINI(PyMUTEX_T *cs)
182 {
183     DeleteCriticalSection(cs);
184     return 0;
185 }
186 
187 Py_LOCAL_INLINE(int)
PyMUTEX_LOCK(PyMUTEX_T * cs)188 PyMUTEX_LOCK(PyMUTEX_T *cs)
189 {
190     EnterCriticalSection(cs);
191     return 0;
192 }
193 
194 Py_LOCAL_INLINE(int)
PyMUTEX_UNLOCK(PyMUTEX_T * cs)195 PyMUTEX_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 
205 typedef struct _PyCOND_T
206 {
207     HANDLE sem;
208     int waiting; /* to allow PyCOND_SIGNAL to be a no-op */
209 } PyCOND_T;
210 
211 Py_LOCAL_INLINE(int)
PyCOND_INIT(PyCOND_T * cv)212 PyCOND_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 
225 Py_LOCAL_INLINE(int)
PyCOND_FINI(PyCOND_T * cv)226 PyCOND_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  */
234 Py_LOCAL_INLINE(int)
_PyCOND_WAIT_MS(PyCOND_T * cv,PyMUTEX_T * cs,DWORD ms)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 which has an internal
242      * count.
243      */
244     wait = WaitForSingleObjectEx(cv->sem, ms, FALSE);
245     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.
253          * ('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).
257          */
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 
265 Py_LOCAL_INLINE(int)
PyCOND_WAIT(PyCOND_T * cv,PyMUTEX_T * cs)266 PyCOND_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 
272 Py_LOCAL_INLINE(int)
PyCOND_TIMEDWAIT(PyCOND_T * cv,PyMUTEX_T * cs,long long us)273 PyCOND_TIMEDWAIT(PyCOND_T *cv, PyMUTEX_T *cs, long long us)
274 {
275     return _PyCOND_WAIT_MS(cv, cs, (DWORD)(us/1000));
276 }
277 
278 Py_LOCAL_INLINE(int)
PyCOND_SIGNAL(PyCOND_T * cv)279 PyCOND_SIGNAL(PyCOND_T *cv)
280 {
281     /* 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) {
286         /* notifying thread decreases the cv->waiting count so that
287          * a delay between notify and actual wakeup of the target thread
288          * doesn't cause a number of extra ReleaseSemaphore calls.
289          */
290         cv->waiting--;
291         return ReleaseSemaphore(cv->sem, 1, NULL) ? 0 : -1;
292     }
293     return 0;
294 }
295 
296 Py_LOCAL_INLINE(int)
PyCOND_BROADCAST(PyCOND_T * cv)297 PyCOND_BROADCAST(PyCOND_T *cv)
298 {
299     int waiting = cv->waiting;
300     if (waiting > 0) {
301         cv->waiting = 0;
302         return ReleaseSemaphore(cv->sem, waiting, NULL) ? 0 : -1;
303     }
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 */
312 typedef SRWLOCK PyMUTEX_T;
313 
314 Py_LOCAL_INLINE(int)
PyMUTEX_INIT(PyMUTEX_T * cs)315 PyMUTEX_INIT(PyMUTEX_T *cs)
316 {
317     InitializeSRWLock(cs);
318     return 0;
319 }
320 
321 Py_LOCAL_INLINE(int)
PyMUTEX_FINI(PyMUTEX_T * cs)322 PyMUTEX_FINI(PyMUTEX_T *cs)
323 {
324     return 0;
325 }
326 
327 Py_LOCAL_INLINE(int)
PyMUTEX_LOCK(PyMUTEX_T * cs)328 PyMUTEX_LOCK(PyMUTEX_T *cs)
329 {
330     AcquireSRWLockExclusive(cs);
331     return 0;
332 }
333 
334 Py_LOCAL_INLINE(int)
PyMUTEX_UNLOCK(PyMUTEX_T * cs)335 PyMUTEX_UNLOCK(PyMUTEX_T *cs)
336 {
337     ReleaseSRWLockExclusive(cs);
338     return 0;
339 }
340 
341 
342 typedef CONDITION_VARIABLE  PyCOND_T;
343 
344 Py_LOCAL_INLINE(int)
PyCOND_INIT(PyCOND_T * cv)345 PyCOND_INIT(PyCOND_T *cv)
346 {
347     InitializeConditionVariable(cv);
348     return 0;
349 }
350 Py_LOCAL_INLINE(int)
PyCOND_FINI(PyCOND_T * cv)351 PyCOND_FINI(PyCOND_T *cv)
352 {
353     return 0;
354 }
355 
356 Py_LOCAL_INLINE(int)
PyCOND_WAIT(PyCOND_T * cv,PyMUTEX_T * cs)357 PyCOND_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  */
365 Py_LOCAL_INLINE(int)
PyCOND_TIMEDWAIT(PyCOND_T * cv,PyMUTEX_T * cs,long long us)366 PyCOND_TIMEDWAIT(PyCOND_T *cv, PyMUTEX_T *cs, long long us)
367 {
368     return SleepConditionVariableSRW(cv, cs, (DWORD)(us/1000), 0) ? 2 : -1;
369 }
370 
371 Py_LOCAL_INLINE(int)
PyCOND_SIGNAL(PyCOND_T * cv)372 PyCOND_SIGNAL(PyCOND_T *cv)
373 {
374      WakeConditionVariable(cv);
375      return 0;
376 }
377 
378 Py_LOCAL_INLINE(int)
PyCOND_BROADCAST(PyCOND_T * cv)379 PyCOND_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_ */
391