Waits for an application-defined state of the monitored data to exist.
#include <prmon.h> PRStatus PR_Wait( PRMonitor *mon, PRIntervalTime ticks);
The function has the following parameter:
- A reference to an existing structure of type
PRMonitor. The monitor object referenced must be one for which the calling thread currently holds the lock.
- The amount of time (in
PRIntervalTimeunits) that the thread is willing to wait for an explicit notification before being rescheduled.
The function returns one of the following values:
PR_SUCCESSmeans the thread is being resumed from the
PR_Waitcall either because it was explicitly notified or because the time specified by the parameter
PR_Waitencountered a system error (such as an invalid monitor reference) or the thread was interrupted by another thread.
A call to
PR_Wait causes the thread to release the monitor's lock, just as if it had called
PR_ExitMonitor as many times as it had called
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:
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_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.