/home/mdboom/Work/builds/cpython/Python/condvar.h
Line | Count | Source (jump to first uncovered line) |
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) { Branch (74:9): [True: 123k, False: 171k]
|
75 | return 1; |
76 | } |
77 | if (ret) { Branch (77:9): [True: 0, False: 171k]
|
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_ */ |