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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
The class tt(std::condition_variable)hi(condition_variable) merely offers a
default constructor. No copy constructor or overloaded assignment operator is
provided.
Before using the class tt(condition_variable) the tthi(condition_variable)
header file must be included.
The class's destructor requires that no thread is blocked by the thread
destroying the tt(condition_variable). So all threads waiting on a
tt(condition_variable) must be notified before a tt(condition_variable)
object's lifetime ends. Calling tt(notify_all) (see below) before a
tt(condition_variable's) lifetime ends takes care of that, as the
tt(condition_variable's) thread releases its lock of the tt(mutex) variable,
allowing one of the notified threads to lock the mutex.
In the following member-descriptions a type tt(Predicate) indicates that a
provided tt(Predicate) argument can be called as a function without arguments,
returning a tt(bool). Also, other member functions are frequently referred
to. It is tacitly assumed that all member referred to below were called using
the same condition variable object.
The class tt(condition_variable) supports several tt(wait) members, which
block the thread until notified by another thread (or after a configurable
waiting time). However, tt(wait) members may also spuriously unblock, without
having reacquired the lock. Therefore, returning from tt(wait) members threads
should verify that the required condition is actually true. If not,
again calling tt(wait) may be appropriate. The next piece of pseudo code
illustrates this scheme:
verb( while (conditionNotTrue())
condVariable.wait(&uniqueLock);)
The class tt(condition_variable)'s members are:
itemization(
ithtq(notify_one)(void notify_one() noexcept)
(one tt(wait) member called by other threads returns. Which one
actually returns cannot be predicted.)
ithtq(notify_all)(void notify_all() noexcept)
(all tt(wait) members called by other threads unblock their wait
states. Of course, only one of them will subsequently succeed in
reacquiring the condition variable's lock object.)
ithtq(wait)(void wait(unique_lock<mutex>& uniqueLock))
(before calling tt(wait) the current thread must have acquired the lock
of tt(uniqueLock). Calling tt(wait) releases the lock, and the current
thread is blocked until it has received a notification from another
thread, and has reacquired the lock.)
ittq(void wait(unique_lock<mutex>& uniqueLock, Predicate pred))
(this is a member template, using the template header tt(template
<typename Predicate>).
The template's type is automatically derived from the function's
argument type and does not have to be specified explicitly.
Before calling tt(wait) the current thread must have acquired the lock
of tt(uniqueLock). As long as `tt(pred)' returns tt(false)
tt(wait(lock)) is called.)
ithtq(wait_for)(cv_status wait_for(unique_lock<mutex> &uniqueLock,
std::chrono::duration<Rep, Period> const &relTime))
(this member is defined as a member template, using the template header
tt(template <typename Rep, typename Period>).
The template's types are automatically derived from the types of the
function's arguments and do not have to be specified explicitly.
E.g., to wait for at most 5 seconds tt(wait_for) can be called like
this:
verb(cond.wait_for(&unique_lock, std::chrono::seconds(5));)
This member returns when being notified or when the time interval
specified by tt(relTime) has passed.
When returning due to a timeout, tt(std::cv_status::timeout) is
returned, otherwise tt(std::cv_status::no_timeout) is
returned.
Threads should verify that the required data condition has been met
after tt(wait_for) has returned.)
ittq(bool wait_for(unique_lock<mutex> &uniqueLock,
chrono::duration<Rep, Period> const &relTime, Predicate
pred))
(this member is defined as a member template, using the template
header tt(template <typename Rep, typename Period, typename
Predicate>).
The template's types are automatically derived from the types of the
function's arguments and do not have to be specified explicitly.
As long as tt(pred) returns false, the previous tt(wait_for) member is
called. If the previous member returns tt(cv_status::timeout), then
tt(pred) is returned, otherwise tt(true).)
ithtq(wait_until)(cv_status wait_until(unique_lock<mutex>& uniqueLock,
chrono::time_point<Clock, Duration> const &absTime))
(this member is defined as a member template, using the template
header tt(template <typename Clock, typename Duration>).
The template's types are automatically derived from the types of the
function's arguments and do not have to be specified explicitly.
E.g., to wait until 5 minutes after the current time tt(wait_until) can
be called like this:
verb(cond.wait_until(&unique_lock, chrono::system_clock::now() +
std::chrono::minutes(5));)
This function acts identically to the tt(wait_for(unique_lock<mutex>
&uniqueLock, chrono::duration<Rep, Period> const &relTime)) member
described earlier, but uses an absolute point in time, rather than a
relative time specification.
This member returns when being notified or when the time interval
specified by tt(relTime) has passed.linebreak()
When returning due to a timeout, tt(std::cv_status::timeout) is
returned, otherwise tt(std::cv_status::no_timeout) is
returned.)
ittq(bool wait_until(unique_lock<mutex> &lock,
chrono::time_point<Clock, Duration> const &absTime,
Predicate pred))
(this member is defined as a member template, using the template header
tt(template <typename Clock, typename Duration, typename Predicate>).
The template's types are automatically derived from the types of the
function's arguments and do not have to be specified explicitly.
As long as tt(pred) returns false, the previous tt(wait_until) member
is called. If the previous member returns tt(cv_status::timeout), then
tt(pred) is returned, otherwise tt(true).)
)
Threads should verify that the required condition is tt(true) when
wait-members of condition variables return.
|
