Adding upstream version 115.7.0esr.upstream/115.7.0esr

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

1 files changed, 68 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_waitcondvar.rst b/docs/nspr/reference/pr_waitcondvar.rst
new file mode 100644
index 0000000000..f915464f7b
--- /dev/null
+++ b/docs/nspr/reference/pr_waitcondvar.rst
@@ -0,0 +1,68 @@
+PR_WaitCondVar
+==============
+
+Waits on a condition.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prcvar.h>
+
+   PRStatus PR_WaitCondVar(
+     PRCondVar *cvar,
+     PRIntervalTime timeout);
+
+
+Parameters
+~~~~~~~~~~
+
+:ref:`PR_WaitCondVar` has the following parameters:
+
+``cvar``
+   The condition variable on which to wait.
+``timeout``
+   The value ``PR_INTERVAL_NO_TIMEOUT`` requires that a condition be
+   notified (or the thread interrupted) before it will resume from the
+   wait. The value ``PR_INTERVAL_NO_WAIT`` causes the thread to release
+   the lock, possibly causing a rescheduling within the runtime, then
+   immediately attempt to reacquire the lock and resume.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+-  If successful, ``PR_SUCCESS``.
+-  If unsuccessful (for example, if the caller has not locked the lock
+   associated with the condition variable or the thread was interrupted
+   with :ref:`PR_Interrupt`), ``PR_FAILURE``. The details can be determined
+   with :ref:`PR_GetError`.
+
+
+Description
+-----------
+
+Before the call to :ref:`PR_WaitCondVar`, the lock associated with the
+condition variable must be held by the calling thread. After a call to
+:ref:`PR_WaitCondVar`, the lock is released and the thread is blocked in a
+"waiting on condition" state until another thread notifies the condition
+or a caller-specified amount of time expires.
+
+When the condition variable is notified, a thread waiting on that
+condition moves from the "waiting on condition" state to the "ready"
+state. When scheduled, the thread attempts to reacquire the lock that it
+held when :ref:`PR_WaitCondVar` was called.
+
+Any value other than ``PR_INTERVAL_NO_TIMEOUT`` or
+``PR_INTERVAL_NO_WAIT`` for the timeout parameter will cause the thread
+to be rescheduled due to either explicit notification or the expiration
+of the specified interval. The latter must be determined by treating
+time as one part of the monitored data being protected by the lock and
+tested explicitly for an expired interval. To detect the expiration of
+the specified interval, call :ref:`PR_IntervalNow` before and after the
+call to :ref:`PR_WaitCondVar` and compare the elapsed time with the
+specified interval.