Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.