LCOV - code coverage report
Current view: | top level - Python - condvar.h (source / functions) |  |  | Hit | Total | Coverage
Test: | CPython 3.12 LCOV report [commit 5e6661bce9] |  | Lines: | 0 | 8 | 0.0 %
Date: | 2023-03-20 08:15:36 |  | Functions: | 0 | 1 | 0.0 %
|  |  | Branches: | 0 | 4 | 0.0 %

               Branch data     Line data    Source code
           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                 :          0 : PyCOND_TIMEDWAIT(PyCOND_T *cond, PyMUTEX_T *mut, long long us)
          70                 :            : {
          71                 :            :     struct timespec abs_timeout;
          72                 :          0 :     _PyThread_cond_after(us, &abs_timeout);
          73                 :          0 :     int ret = pthread_cond_timedwait(cond, mut, &abs_timeout);
          74         [ #  # ]:          0 :     if (ret == ETIMEDOUT) {
          75                 :          0 :         return 1;
          76                 :            :     }
          77         [ #  # ]:          0 :     if (ret) {
          78                 :          0 :         return -1;
          79                 :            :     }
          80                 :          0 :     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_ */

Generated by: LCOV version 1.14