pr_waitcondvar.rst (2201B)
1 PR_WaitCondVar 2 ============== 3 4 Waits on a condition. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prcvar.h> 13 14 PRStatus PR_WaitCondVar( 15 PRCondVar *cvar, 16 PRIntervalTime timeout); 17 18 19 Parameters 20 ~~~~~~~~~~ 21 22 :ref:`PR_WaitCondVar` has the following parameters: 23 24 ``cvar`` 25 The condition variable on which to wait. 26 ``timeout`` 27 The value ``PR_INTERVAL_NO_TIMEOUT`` requires that a condition be 28 notified (or the thread interrupted) before it will resume from the 29 wait. The value ``PR_INTERVAL_NO_WAIT`` causes the thread to release 30 the lock, possibly causing a rescheduling within the runtime, then 31 immediately attempt to reacquire the lock and resume. 32 33 34 Returns 35 ~~~~~~~ 36 37 The function returns one of the following values: 38 39 - If successful, ``PR_SUCCESS``. 40 - If unsuccessful (for example, if the caller has not locked the lock 41 associated with the condition variable or the thread was interrupted 42 with :ref:`PR_Interrupt`), ``PR_FAILURE``. The details can be determined 43 with :ref:`PR_GetError`. 44 45 46 Description 47 ----------- 48 49 Before the call to :ref:`PR_WaitCondVar`, the lock associated with the 50 condition variable must be held by the calling thread. After a call to 51 :ref:`PR_WaitCondVar`, the lock is released and the thread is blocked in a 52 "waiting on condition" state until another thread notifies the condition 53 or a caller-specified amount of time expires. 54 55 When the condition variable is notified, a thread waiting on that 56 condition moves from the "waiting on condition" state to the "ready" 57 state. When scheduled, the thread attempts to reacquire the lock that it 58 held when :ref:`PR_WaitCondVar` was called. 59 60 Any value other than ``PR_INTERVAL_NO_TIMEOUT`` or 61 ``PR_INTERVAL_NO_WAIT`` for the timeout parameter will cause the thread 62 to be rescheduled due to either explicit notification or the expiration 63 of the specified interval. The latter must be determined by treating 64 time as one part of the monitored data being protected by the lock and 65 tested explicitly for an expired interval. To detect the expiration of 66 the specified interval, call :ref:`PR_IntervalNow` before and after the 67 call to :ref:`PR_WaitCondVar` and compare the elapsed time with the 68 specified interval.