summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/pr_cwait.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/nspr/reference/pr_cwait.rst63
1 files changed, 63 insertions, 0 deletions
diff --git a/docs/nspr/reference/pr_cwait.rst b/docs/nspr/reference/pr_cwait.rst
new file mode 100644
index 0000000000..9af79c42c3
--- /dev/null
+++ b/docs/nspr/reference/pr_cwait.rst
@@ -0,0 +1,63 @@
+PR_CWait
+========
+
+Wait for a notification that a monitor's state has changed.
+
+
+Syntax
+------
+
+.. code::
+
+ #include <prcmon.h>
+
+ PRStatus PR_CWait(
+ void *address,
+ PRIntervalTime timeout);
+
+
+Parameters
+~~~~~~~~~~
+
+The function has the following parameters:
+
+``address``
+ The address of the protected object--the same address previously
+ passed to :ref:`PR_CEnterMonitor`.
+``timeout``
+ The amount of time (in :ref:`PRIntervalTime` units) that the thread is
+ willing to wait for an explicit notification before being
+ rescheduled. If you specify ``PR_INTERVAL_NO_TIMEOUT``, the function
+ returns if and only if the object is notified.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+ - :ref:`PR_SUCCESS` indicates either that the monitored object has been
+ notified or that the interval specified in the timeout parameter has
+ been exceeded.
+ - :ref:`PR_FAILURE` indicates either that the monitor could not be located
+ in the cache or that the monitor was located and the calling thread
+ was not the thread that held the monitor's mutex.
+
+
+Description
+-----------
+
+Using the value specified in the ``address`` parameter to find a monitor
+in the monitor cache, :ref:`PR_CWait` waits for a notification that the
+monitor's state has changed. While the thread is waiting, it exits the
+monitor (just as if it had called :ref:`PR_CExitMonitor` as many times as
+it had called :ref:`PR_CEnterMonitor`). When the wait has finished, the
+thread regains control of the monitor's lock with the same entry count
+as before the wait began.
+
+The thread waiting on the monitor resumes execution when the monitor is
+notified (assuming the thread is the next in line to receive the notify)
+or when the interval specified in the ``timeout`` parameter has been
+exceeded. When the thread resumes execution, it is the caller's
+responsibility to test the state of the monitored data to determine the
+appropriate action.