1PR_CWait 2======== 3 4Wait for a notification that a monitor's state has changed. 5 6 7Syntax 8------ 9 10.. code:: eval 11 12 #include <prcmon.h> 13 14 PRStatus PR_CWait( 15 void *address, 16 PRIntervalTime timeout); 17 18 19Parameters 20~~~~~~~~~~ 21 22The 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 34Returns 35~~~~~~~ 36 37The 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 47Description 48----------- 49 50Using the value specified in the ``address`` parameter to find a monitor 51in the monitor cache, :ref:`PR_CWait` waits for a notification that the 52monitor's state has changed. While the thread is waiting, it exits the 53monitor (just as if it had called :ref:`PR_CExitMonitor` as many times as 54it had called :ref:`PR_CEnterMonitor`). When the wait has finished, the 55thread regains control of the monitor's lock with the same entry count 56as before the wait began. 57 58The thread waiting on the monitor resumes execution when the monitor is 59notified (assuming the thread is the next in line to receive the notify) 60or when the interval specified in the ``timeout`` parameter has been 61exceeded. When the thread resumes execution, it is the caller's 62responsibility to test the state of the monitored data to determine the 63appropriate action. 64