1 *java.util.concurrent.locks.Condition* *Condition* Condition factors out the Obj
3 public interface interface Condition
6 |java.util.concurrent.locks.Condition_Description|
7 |java.util.concurrent.locks.Condition_Fields|
8 |java.util.concurrent.locks.Condition_Constructors|
9 |java.util.concurrent.locks.Condition_Methods|
11 ================================================================================
13 *java.util.concurrent.locks.Condition_Methods*
14 |java.util.concurrent.locks.Condition.await()|Causes the current thread to wait
15 |java.util.concurrent.locks.Condition.await(long,TimeUnit)|Causes the current t
16 |java.util.concurrent.locks.Condition.awaitNanos(long)|Causes the current threa
17 |java.util.concurrent.locks.Condition.awaitUninterruptibly()|Causes the current
18 |java.util.concurrent.locks.Condition.awaitUntil(Date)|Causes the current threa
19 |java.util.concurrent.locks.Condition.signal()|Wakes up one waiting thread.
20 |java.util.concurrent.locks.Condition.signalAll()|Wakes up all waiting threads.
22 *java.util.concurrent.locks.Condition_Description*
24 Condition factors out the Object monitor methods ( wait(|java.lang.Object|) ,
25 notify(|java.lang.Object|) and notifyAll(|java.lang.Object|) ) into distinct
26 objects to give the effect of having multiple wait-sets per object, by
27 combining them with the use of arbitrary (|java.util.concurrent.locks.Lock|)
28 implementations. Where a Lock replaces the use of synchronized methods and
29 statements, a Condition replaces the use of the Object monitor methods.
31 Conditions (also known as condition queues or condition variables) provide a
32 means for one thread to suspend execution (to wait) until notified by another
33 thread that some state condition may now be true. Because access to this shared
34 state information occurs in different threads, it must be protected, so a lock
35 of some form is associated with the condition. The key property that waiting
36 for a condition provides is that it atomically releases the associated lock and
37 suspends the current thread, just like Object.wait.
39 A Condition instance is intrinsically bound to a lock. To obtain a Condition
40 instance for a particular (|java.util.concurrent.locks.Lock|) instance use its
41 newCondition()(|java.util.concurrent.locks.Lock|) method.
43 As an example, suppose we have a bounded buffer which supports put and take
44 methods. If a take is attempted on an empty buffer, then the thread will block
45 until an item becomes available; if a put is attempted on a full buffer, then
46 the thread will block until a space becomes available. We would like to keep
47 waiting put threads and take threads in separate wait-sets so that we can use
48 the optimization of only notifying a single thread at a time when items or
49 spaces become available in the buffer. This can be achieved using two
50 (|java.util.concurrent.locks.Condition|) instances.
52 class BoundedBuffer { final Lock lock = new ReentrantLock(); final Condition
53 notFull = lock.newCondition(); final Condition notEmpty = lock.newCondition();
55 final Object[] items = new Object[100]; int putptr, takeptr, count;
57 public void put(Object x) throws InterruptedException { lock.lock(); try {
58 while (count == items.length) notFull.await(); items[putptr] = x; if (++putptr
59 == items.length) putptr = 0; ++count; notEmpty.signal(); } finally {
62 public Object take() throws InterruptedException { lock.lock(); try { while
63 (count == 0) notEmpty.await(); Object x = items[takeptr]; if (++takeptr ==
64 items.length) takeptr = 0; --count; notFull.signal(); return x; } finally {
67 (The (|java.util.concurrent.ArrayBlockingQueue|) class provides this
68 functionality, so there is no reason to implement this sample usage class.)
70 A Condition implementation can provide behavior and semantics that is different
71 from that of the Object monitor methods, such as guaranteed ordering for
72 notifications, or not requiring a lock to be held when performing
73 notifications. If an implementation provides such specialized semantics then
74 the implementation must document those semantics.
76 Note that Condition instances are just normal objects and can themselves be
77 used as the target in a synchronized statement, and can have their own monitor
78 wait(|java.lang.Object|) and notification(|java.lang.Object|) methods invoked.
79 Acquiring the monitor lock of a Condition instance, or using its monitor
80 methods, has no specified relationship with acquiring the
81 (|java.util.concurrent.locks.Lock|) associated with that Condition or the use
82 of its waiting(|java.util.concurrent.locks.Condition|) and
83 signalling(|java.util.concurrent.locks.Condition|) methods. It is recommended
84 that to avoid confusion you never use Condition instances in this way, except
85 perhaps within their own implementation.
87 Except where noted, passing a null value for any parameter will result in a
88 (|java.lang.NullPointerException|) being thrown.
90 Implementation Considerations
92 When waiting upon a Condition, a spurious wakeup is permitted to occur, in
93 general, as a concession to the underlying platform semantics. This has little
94 practical impact on most application programs as a Condition should always be
95 waited upon in a loop, testing the state predicate that is being waited for. An
96 implementation is free to remove the possibility of spurious wakeups but it is
97 recommended that applications programmers always assume that they can occur and
98 so always wait in a loop.
100 The three forms of condition waiting (interruptible, non-interruptible, and
101 timed) may differ in their ease of implementation on some platforms and in
102 their performance characteristics. In particular, it may be difficult to
103 provide these features and maintain specific semantics such as ordering
104 guarantees. Further, the ability to interrupt the actual suspension of the
105 thread may not always be feasible to implement on all platforms. Consequently,
106 an implementation is not required to define exactly the same guarantees or
107 semantics for all three forms of waiting, nor is it required to support
108 interruption of the actual suspension of the thread. An implementation is
109 required to clearly document the semantics and guarantees provided by each of
110 the waiting methods, and when an implementation does support interruption of
111 thread suspension then it must obey the interruption semantics as defined in
112 this interface. As interruption generally implies cancellation, and checks for
113 interruption are often infrequent, an implementation can favor responding to an
114 interrupt over normal method return. This is true even if it can be shown that
115 the interrupt occurred after another action may have unblocked the thread. An
116 implementation should document this behavior.
119 *java.util.concurrent.locks.Condition.await()*
122 throws |java.lang.InterruptedException|
124 Causes the current thread to wait until it is signalled or
125 interrupted(|java.lang.Thread|) .
127 The lock associated with this Condition is atomically released and the current
128 thread becomes disabled for thread scheduling purposes and lies dormant until
129 one of four things happens:
131 Some other thread invokes the (|java.util.concurrent.locks.Condition|) method
132 for this Condition and the current thread happens to be chosen as the thread to
133 be awakened; or Some other thread invokes the
134 (|java.util.concurrent.locks.Condition|) method for this Condition; or Some
135 other thread interrupts(|java.lang.Thread|) the current thread, and
136 interruption of thread suspension is supported; or A spurious wakeup occurs
138 In all cases, before this method can return the current thread must re-acquire
139 the lock associated with this condition. When the thread returns it is
140 guaranteed to hold this lock.
142 If the current thread:
144 has its interrupted status set on entry to this method; or is
145 interrupted(|java.lang.Thread|) while waiting and interruption of thread
146 suspension is supported,
148 then (|java.lang.InterruptedException|) is thrown and the current thread's
149 interrupted status is cleared. It is not specified, in the first case, whether
150 or not the test for interruption occurs before the lock is released.
152 Implementation Considerations The current thread is assumed to hold the lock
153 associated with this Condition when this method is called. It is up to the
154 implementation to determine if this is the case and if not, how to respond.
155 Typically, an exception will be thrown (such as
156 (|java.lang.IllegalMonitorStateException|) ) and the implementation must
159 An implementation can favor responding to an interrupt over normal method
160 return in response to a signal. In that case the implementation must ensure
161 that the signal is redirected to another waiting thread, if there is one.
164 *java.util.concurrent.locks.Condition.await(long,TimeUnit)*
166 public boolean await(
168 java.util.concurrent.TimeUnit unit)
169 throws |java.lang.InterruptedException|
171 Causes the current thread to wait until it is signalled or interrupted, or the
172 specified waiting time elapses. This method is behaviorally equivalent to:
174 awaitNanos(unit.toNanos(time)) > 0
176 time - the maximum time to wait
177 unit - the time unit of the time argument.
179 Returns: false if the waiting time detectably elapsed before return from the method,
181 *java.util.concurrent.locks.Condition.awaitNanos(long)*
183 public long awaitNanos(long nanosTimeout)
184 throws |java.lang.InterruptedException|
186 Causes the current thread to wait until it is signalled or interrupted, or the
187 specified waiting time elapses.
189 The lock associated with this condition is atomically released and the current
190 thread becomes disabled for thread scheduling purposes and lies dormant until
191 one of five things happens:
193 Some other thread invokes the (|java.util.concurrent.locks.Condition|) method
194 for this Condition and the current thread happens to be chosen as the thread to
195 be awakened; or Some other thread invokes the
196 (|java.util.concurrent.locks.Condition|) method for this Condition; or Some
197 other thread interrupts(|java.lang.Thread|) the current thread, and
198 interruption of thread suspension is supported; or The specified waiting time
199 elapses; or A spurious wakeup occurs.
201 In all cases, before this method can return the current thread must re-acquire
202 the lock associated with this condition. When the thread returns it is
203 guaranteed to hold this lock.
205 If the current thread:
207 has its interrupted status set on entry to this method; or is
208 interrupted(|java.lang.Thread|) while waiting and interruption of thread
209 suspension is supported,
211 then (|java.lang.InterruptedException|) is thrown and the current thread's
212 interrupted status is cleared. It is not specified, in the first case, whether
213 or not the test for interruption occurs before the lock is released.
215 The method returns an estimate of the number of nanoseconds remaining to wait
216 given the supplied nanosTimeout value upon return, or a value less than or
217 equal to zero if it timed out. This value can be used to determine whether and
218 how long to re-wait in cases where the wait returns but an awaited condition
219 still does not hold. Typical uses of this method take the following form:
223 synchronized boolean aMethod(long timeout, TimeUnit unit) { long nanosTimeout =
224 unit.toNanos(timeout); while (!conditionBeingWaitedFor) { if (nanosTimeout > 0)
225 nanosTimeout = theCondition.awaitNanos(nanosTimeout); else return false; } //
228 Design note: This method requires a nanosecond argument so as to avoid
229 truncation errors in reporting remaining times. Such precision loss would make
230 it difficult for programmers to ensure that total waiting times are not
231 systematically shorter than specified when re-waits occur.
233 Implementation Considerations The current thread is assumed to hold the lock
234 associated with this Condition when this method is called. It is up to the
235 implementation to determine if this is the case and if not, how to respond.
236 Typically, an exception will be thrown (such as
237 (|java.lang.IllegalMonitorStateException|) ) and the implementation must
240 An implementation can favor responding to an interrupt over normal method
241 return in response to a signal, or over indicating the elapse of the specified
242 waiting time. In either case the implementation must ensure that the signal is
243 redirected to another waiting thread, if there is one.
245 nanosTimeout - the maximum time to wait, in nanoseconds
247 Returns: A value less than or equal to zero if the wait has timed out; otherwise an
248 estimate, that is strictly less than the nanosTimeout argument, of
249 the time still remaining when this method returned.
250 *java.util.concurrent.locks.Condition.awaitUninterruptibly()*
252 public void awaitUninterruptibly()
254 Causes the current thread to wait until it is signalled.
256 The lock associated with this condition is atomically released and the current
257 thread becomes disabled for thread scheduling purposes and lies dormant until
258 one of three things happens:
260 Some other thread invokes the (|java.util.concurrent.locks.Condition|) method
261 for this Condition and the current thread happens to be chosen as the thread to
262 be awakened; or Some other thread invokes the
263 (|java.util.concurrent.locks.Condition|) method for this Condition; or A
264 spurious wakeup occurs
266 In all cases, before this method can return the current thread must re-acquire
267 the lock associated with this condition. When the thread returns it is
268 guaranteed to hold this lock.
270 If the current thread's interrupted status is set when it enters this method,
271 or it is interrupted(|java.lang.Thread|) while waiting, it will continue to
272 wait until signalled. When it finally returns from this method its interrupted
273 status will still be set.
275 Implementation Considerations The current thread is assumed to hold the lock
276 associated with this Condition when this method is called. It is up to the
277 implementation to determine if this is the case and if not, how to respond.
278 Typically, an exception will be thrown (such as
279 (|java.lang.IllegalMonitorStateException|) ) and the implementation must
283 *java.util.concurrent.locks.Condition.awaitUntil(Date)*
285 public boolean awaitUntil(java.util.Date deadline)
286 throws |java.lang.InterruptedException|
288 Causes the current thread to wait until it is signalled or interrupted, or the
289 specified deadline elapses.
291 The lock associated with this condition is atomically released and the current
292 thread becomes disabled for thread scheduling purposes and lies dormant until
293 one of five things happens:
295 Some other thread invokes the (|java.util.concurrent.locks.Condition|) method
296 for this Condition and the current thread happens to be chosen as the thread to
297 be awakened; or Some other thread invokes the
298 (|java.util.concurrent.locks.Condition|) method for this Condition; or Some
299 other thread interrupts(|java.lang.Thread|) the current thread, and
300 interruption of thread suspension is supported; or The specified deadline
301 elapses; or A spurious wakeup occurs.
303 In all cases, before this method can return the current thread must re-acquire
304 the lock associated with this condition. When the thread returns it is
305 guaranteed to hold this lock.
307 If the current thread:
309 has its interrupted status set on entry to this method; or is
310 interrupted(|java.lang.Thread|) while waiting and interruption of thread
311 suspension is supported,
313 then (|java.lang.InterruptedException|) is thrown and the current thread's
314 interrupted status is cleared. It is not specified, in the first case, whether
315 or not the test for interruption occurs before the lock is released.
317 The return value indicates whether the deadline has elapsed, which can be used
320 synchronized boolean aMethod(Date deadline) { boolean stillWaiting = true;
321 while (!conditionBeingWaitedFor) { if (stillwaiting) stillWaiting =
322 theCondition.awaitUntil(deadline); else return false; } // ... }
324 Implementation Considerations The current thread is assumed to hold the lock
325 associated with this Condition when this method is called. It is up to the
326 implementation to determine if this is the case and if not, how to respond.
327 Typically, an exception will be thrown (such as
328 (|java.lang.IllegalMonitorStateException|) ) and the implementation must
331 An implementation can favor responding to an interrupt over normal method
332 return in response to a signal, or over indicating the passing of the specified
333 deadline. In either case the implementation must ensure that the signal is
334 redirected to another waiting thread, if there is one.
336 deadline - the absolute time to wait until
338 Returns: false if the deadline has elapsed upon return, else true.
339 *java.util.concurrent.locks.Condition.signal()*
343 Wakes up one waiting thread.
345 If any threads are waiting on this condition then one is selected for waking
346 up. That thread must then re-acquire the lock before returning from await.
349 *java.util.concurrent.locks.Condition.signalAll()*
351 public void signalAll()
353 Wakes up all waiting threads.
355 If any threads are waiting on this condition then they are all woken up. Each
356 thread must re-acquire the lock before it can return from await.