Adding upstream version 115.7.0esr.upstream/115.7.0esrupstream

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

1 files changed, 82 insertions, 0 deletions

diff --git a/docs/nspr/reference/pr_wait.rst b/docs/nspr/reference/pr_wait.rst
new file mode 100644
index 0000000000..3eb6e16f30
--- /dev/null
+++ b/docs/nspr/reference/pr_wait.rst
@@ -0,0 +1,82 @@
+PR_Wait
+=======
+
+Waits for an application-defined state of the monitored data to exist.
+
+
+Syntax
+------
+
+.. code::
+
+   #include <prmon.h>
+
+   PRStatus PR_Wait(
+     PRMonitor *mon,
+     PRIntervalTime ticks);
+
+
+Parameters
+~~~~~~~~~~
+
+The function has the following parameter:
+
+``mon``
+   A reference to an existing structure of type :ref:`PRMonitor`. The
+   monitor object referenced must be one for which the calling thread
+   currently holds the lock.
+``ticks``
+   The amount of time (in :ref:`PRIntervalTime` units) that the thread is
+   willing to wait for an explicit notification before being
+   rescheduled.
+
+
+Returns
+~~~~~~~
+
+The function returns one of the following values:
+
+ - :ref:`PR_SUCCESS`` means the thread is being resumed from the ``PR_Wait`
+   call either because it was explicitly notified or because the time
+   specified by the parameter ``ticks`` has expired.
+ - :ref:`PR_FAILURE` means ``PR_Wait`` encountered a system error (such as
+   an invalid monitor reference) or the thread was interrupted by
+   another thread.
+
+
+Description
+-----------
+
+A call to :ref:`PR_Wait` causes the thread to release the monitor's lock,
+just as if it had called :ref:`PR_ExitMonitor` as many times as it had
+called :ref:`PR_EnterMonitor`. This has the effect of making the monitor
+available to other threads. When the wait is over, the thread regains
+control of the monitor's lock with the same entry count it had before
+the wait began.
+
+A thread waiting on the monitor resumes when the monitor is notified or
+when the timeout specified by the ``ticks`` parameter elapses. The
+resumption from the wait is merely a hint that a change of state has
+occurred. It is the responsibility of the programmer to evaluate the
+data and act accordingly. This is usually done by evaluating a Boolean
+expression involving the monitored data. While the Boolean expression is
+false, the thread should wait. The thread should act on the data only
+when the expression is true. The boolean expression must be evaluated
+while in the monitor and within a loop.
+
+In pseudo-code, the sequence is as follows:
+
+| ``PR_EnterMonitor(&ml);``
+| ``while (!expression) wait;``
+| ``... act on the state change ...``
+| ``PR_ExitMonitor(&ml);``
+
+A thread can be resumed from a wait for a variety of reasons. The most
+obvious is that it was notified by another thread. If the value of
+timeout is not ``PR_INTERVAL_NO_TIMEOUT``, :ref:`PR_Wait` resumes execution
+after the specified interval has expired. If a timeout value is used,
+the Boolean expression must include elapsed time as part of the
+monitored data.
+
+Resuming from the wait is merely an opportunity to evaluate the
+expression, not an assertion that the expression is true.