pr_cwait.rst (1951B)
1 PR_CWait 2 ======== 3 4 Wait for a notification that a monitor's state has changed. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prcmon.h> 13 14 PRStatus PR_CWait( 15 void *address, 16 PRIntervalTime timeout); 17 18 19 Parameters 20 ~~~~~~~~~~ 21 22 The function has the following parameters: 23 24 ``address`` 25 The address of the protected object--the same address previously 26 passed to :ref:`PR_CEnterMonitor`. 27 ``timeout`` 28 The amount of time (in :ref:`PRIntervalTime` units) that the thread is 29 willing to wait for an explicit notification before being 30 rescheduled. If you specify ``PR_INTERVAL_NO_TIMEOUT``, the function 31 returns if and only if the object is notified. 32 33 34 Returns 35 ~~~~~~~ 36 37 The function returns one of the following values: 38 39 - :ref:`PR_SUCCESS` indicates either that the monitored object has been 40 notified or that the interval specified in the timeout parameter has 41 been exceeded. 42 - :ref:`PR_FAILURE` indicates either that the monitor could not be located 43 in the cache or that the monitor was located and the calling thread 44 was not the thread that held the monitor's mutex. 45 46 47 Description 48 ----------- 49 50 Using the value specified in the ``address`` parameter to find a monitor 51 in the monitor cache, :ref:`PR_CWait` waits for a notification that the 52 monitor's state has changed. While the thread is waiting, it exits the 53 monitor (just as if it had called :ref:`PR_CExitMonitor` as many times as 54 it had called :ref:`PR_CEnterMonitor`). When the wait has finished, the 55 thread regains control of the monitor's lock with the same entry count 56 as before the wait began. 57 58 The thread waiting on the monitor resumes execution when the monitor is 59 notified (assuming the thread is the next in line to receive the notify) 60 or when the interval specified in the ``timeout`` parameter has been 61 exceeded. When the thread resumes execution, it is the caller's 62 responsibility to test the state of the monitored data to determine the 63 appropriate action.