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