pr_wait.rst (2706B)
1 PR_Wait 2 ======= 3 4 Waits for an application-defined state of the monitored data to exist. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prmon.h> 13 14 PRStatus PR_Wait( 15 PRMonitor *mon, 16 PRIntervalTime ticks); 17 18 19 Parameters 20 ~~~~~~~~~~ 21 22 The function has the following parameter: 23 24 ``mon`` 25 A reference to an existing structure of type :ref:`PRMonitor`. The 26 monitor object referenced must be one for which the calling thread 27 currently holds the lock. 28 ``ticks`` 29 The amount of time (in :ref:`PRIntervalTime` units) that the thread is 30 willing to wait for an explicit notification before being 31 rescheduled. 32 33 34 Returns 35 ~~~~~~~ 36 37 The function returns one of the following values: 38 39 - :ref:`PR_SUCCESS`` means the thread is being resumed from the ``PR_Wait` 40 call either because it was explicitly notified or because the time 41 specified by the parameter ``ticks`` has expired. 42 - :ref:`PR_FAILURE` means ``PR_Wait`` encountered a system error (such as 43 an invalid monitor reference) or the thread was interrupted by 44 another thread. 45 46 47 Description 48 ----------- 49 50 A call to :ref:`PR_Wait` causes the thread to release the monitor's lock, 51 just as if it had called :ref:`PR_ExitMonitor` as many times as it had 52 called :ref:`PR_EnterMonitor`. This has the effect of making the monitor 53 available to other threads. When the wait is over, the thread regains 54 control of the monitor's lock with the same entry count it had before 55 the wait began. 56 57 A thread waiting on the monitor resumes when the monitor is notified or 58 when the timeout specified by the ``ticks`` parameter elapses. The 59 resumption from the wait is merely a hint that a change of state has 60 occurred. It is the responsibility of the programmer to evaluate the 61 data and act accordingly. This is usually done by evaluating a Boolean 62 expression involving the monitored data. While the Boolean expression is 63 false, the thread should wait. The thread should act on the data only 64 when the expression is true. The boolean expression must be evaluated 65 while in the monitor and within a loop. 66 67 In pseudo-code, the sequence is as follows: 68 69 | ``PR_EnterMonitor(&ml);`` 70 | ``while (!expression) wait;`` 71 | ``... act on the state change ...`` 72 | ``PR_ExitMonitor(&ml);`` 73 74 A thread can be resumed from a wait for a variety of reasons. The most 75 obvious is that it was notified by another thread. If the value of 76 timeout is not ``PR_INTERVAL_NO_TIMEOUT``, :ref:`PR_Wait` resumes execution 77 after the specified interval has expired. If a timeout value is used, 78 the Boolean expression must include elapsed time as part of the 79 monitored data. 80 81 Resuming from the wait is merely an opportunity to evaluate the 82 expression, not an assertion that the expression is true.