public member function
<condition_variable>
| unconditional (1) | template <class Lock, class Rep, class Period> cv_status wait_for (Lock& lck, const chrono::duration<Rep,Period>& rel_time); |
|---|
| predicate (2) | template <class Lock, class Rep, class Period, class Predicate> bool wait_for (Lock& lck, const chrono::duration<Rep,Period>& rel_time, Predicate pred); |
|---|
Wait for timeout or until notified
The execution of the current thread (which shall currently lock lck) is blocked during rel_time, or until notified (if the latter happens first).
At the moment of blocking the thread, the function automatically calls lck.unlock(), allowing other locked threads to continue.
Once notified or once rel_time has passed, the function unblocks and calls lck.lock(), leaving lck in the same state as when the function was called. Then the function returns (notice that this last mutex locking may block again the thread before returning).
Generally, the function is notified to wake up by a call in another thread either to member notify_one or to member notify_one. But certain implementations may produce spurious wake-up calls without any of these functions being called. Therefore, users of this function shall ensure their condition for resumption is met.
If pred is specified (2), the function only blocks if pred returns false, and notifications can only unblock the thread when it becomes true (which is especially useful to check against spurious wake-up calls). It behaves as if implemented as:
1
|
return wait_until (lck, chrono::steady_clock::now() + rel_time, std::move(pred));
|
Parameters
- lck
- A lockable object currently locked by this thread.
All concurrent calls to wait member functions of this object shall use the same underlying mutex object.
Lock shall be a lockable type.
- rel_time
- The maximum time span during which the thread will block waiting to be notified.
duration is an object that represents a specific relative time.
- pred
- A callable object or function that takes no arguments and returns a value that can be evaluated as a
bool.
This is called repeatedly until it evaluates to true.
Return value
The unconditional version (1) returns cv_status::timeout if the function returns because rel_time has passed, or cv_status::no_timeout otherwise.
The predicate version (2) returns pred(), regardless of whether the timeout was triggered (although it can only be false if triggered).
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
|
// condition_variable_any::wait_for example
#include <iostream> // std::cout
#include <thread> // std::thread
#include <chrono> // std::chrono::seconds
#include <mutex> // std::mutex
#include <condition_variable> // std::condition_variable_any, std::cv_status
std::condition_variable_any cv;
int value;
void read_value() {
std::cin >> value;
cv.notify_one();
}
int main ()
{
std::cout << "Please, enter an integer (I'll be printing dots): ";
std::thread th (read_value);
std::mutex mtx;
mtx.lock();
while (cv.wait_for(mtx,std::chrono::seconds(1))==std::cv_status::timeout) {
std::cout << '.';
}
std::cout << "You entered: " << value << '\n';
mtx.unlock();
th.join();
return 0;
}
|
Possible output:
Please, enter an integer (I'll be priniting dots): .....20
You entered: 20
|
Data races
The function performs three atomic operations:
- The initial unlocking of lck and simultaneous entry into the waiting state.
- The unblocking of the waiting state.
- The locking of lck before returning.
Atomic operations on the object are ordered according to a single total order, with the three atomic operations in this function happening in the same relative as above.
Exception safety
If any parameter has a value that is not valid for this function (such as if lck's mutex object is not locked by the calling thread), it causes undefined behavior.
Otherwise, if an exception is thrown, both the condition_variable_any object and the arguments are in a valid state (basic guarantee).
It may throw
system_error in case of failure (transmitting any error condition from the respective call to
lock or
unlock).
The
predicate version (2) may also throw any exception thrown by
pred.
On exception, the state of
lck is attempted to be restored before exiting the function scope (by calling
lck.lock()).
It may throw if an operation related to
rel_time throws (note that operations on
duration types provided in
<chrono>, such as
seconds, never throw).
The
predicate version (2) may also throw exceptions thrown by
pred.
If the function is not able to restore the lock and return at some point (such as if some attempt to lock or unlock throws),
std::terminate is called.