diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 19:33:14 +0000 |
commit | 36d22d82aa202bb199967e9512281e9a53db42c9 (patch) | |
tree | 105e8c98ddea1c1e4784a60a5a6410fa416be2de /docs/nspr/reference/pr_wait.rst | |
parent | Initial commit. (diff) | |
download | firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.tar.xz firefox-esr-36d22d82aa202bb199967e9512281e9a53db42c9.zip |
Adding upstream version 115.7.0esr.upstream/115.7.0esr
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/nspr/reference/pr_wait.rst')
-rw-r--r-- | docs/nspr/reference/pr_wait.rst | 82 |
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. |