Source Code Cross Referenced for Condition.java in  » 6.0-JDK-Core » Collections-Jar-Zip-Logging-regex » java » util » concurrent » locks » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Home
Java Source Code / Java Documentation
1.6.0 JDK Core
2.6.0 JDK Modules
3.6.0 JDK Modules com.sun
4.6.0 JDK Modules com.sun.java
5.6.0 JDK Modules sun
6.6.0 JDK Platform
7.Ajax
8.Apache Harmony Java SE
9.Aspect oriented
10.Authentication Authorization
11.Blogger System
12.Build
13.Byte Code
14.Cache
15.Chart
16.Chat
17.Code Analyzer
18.Collaboration
19.Content Management System
20.Database Client
21.Database DBMS
22.Database JDBC Connection Pool
23.Database ORM
24.Development
25.EJB Server
26.ERP CRM Financial
27.ESB
28.Forum
29.Game
30.GIS
31.Graphic 3D
32.Graphic Library
33.Groupware
34.HTML Parser
35.IDE
36.IDE Eclipse
37.IDE Netbeans
38.Installer
39.Internationalization Localization
40.Inversion of Control
41.Issue Tracking
42.J2EE
43.J2ME
44.JBoss
45.JMS
46.JMX
47.Library
48.Mail Clients
49.Music
50.Net
51.Parser
52.PDF
53.Portal
54.Profiler
55.Project Management
56.Report
57.RSS RDF
58.Rule Engine
59.Science
60.Scripting
61.Search Engine
62.Security
63.Sevlet Container
64.Source Control
65.Swing Library
66.Template Engine
67.Test Coverage
68.Testing
69.UML
70.Web Crawler
71.Web Framework
72.Web Mail
73.Web Server
74.Web Services
75.Web Services apache cxf 2.2.6
76.Web Services AXIS2
77.Wiki Engine
78.Workflow Engines
79.XML
80.XML UI
Java Source Code / Java Documentation » 6.0 JDK Core » Collections Jar Zip Logging regex » java.util.concurrent.locks 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001        /*
002         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003         *
004         * This code is free software; you can redistribute it and/or modify it
005         * under the terms of the GNU General Public License version 2 only, as
006         * published by the Free Software Foundation.  Sun designates this
007         * particular file as subject to the "Classpath" exception as provided
008         * by Sun in the LICENSE file that accompanied this code.
009         *
010         * This code is distributed in the hope that it will be useful, but WITHOUT
011         * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012         * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
013         * version 2 for more details (a copy is included in the LICENSE file that
014         * accompanied this code).
015         *
016         * You should have received a copy of the GNU General Public License version
017         * 2 along with this work; if not, write to the Free Software Foundation,
018         * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019         *
020         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021         * CA 95054 USA or visit www.sun.com if you need additional information or
022         * have any questions.
023         */
024
025        /*
026         * This file is available under and governed by the GNU General Public
027         * License version 2 only, as published by the Free Software Foundation.
028         * However, the following notice accompanied the original version of this
029         * file:
030         *
031         * Written by Doug Lea with assistance from members of JCP JSR-166
032         * Expert Group and released to the public domain, as explained at
033         * http://creativecommons.org/licenses/publicdomain
034         */
035
036        package java.util.concurrent.locks;
037
038        import java.util.concurrent.*;
039        import java.util.Date;
040
041        /**
042         * {@code Condition} factors out the {@code Object} monitor
043         * methods ({@link Object#wait() wait}, {@link Object#notify notify}
044         * and {@link Object#notifyAll notifyAll}) into distinct objects to
045         * give the effect of having multiple wait-sets per object, by
046         * combining them with the use of arbitrary {@link Lock} implementations.
047         * Where a {@code Lock} replaces the use of {@code synchronized} methods
048         * and statements, a {@code Condition} replaces the use of the Object
049         * monitor methods.
050         *
051         * <p>Conditions (also known as <em>condition queues</em> or
052         * <em>condition variables</em>) provide a means for one thread to
053         * suspend execution (to &quot;wait&quot;) until notified by another
054         * thread that some state condition may now be true.  Because access
055         * to this shared state information occurs in different threads, it
056         * must be protected, so a lock of some form is associated with the
057         * condition. The key property that waiting for a condition provides
058         * is that it <em>atomically</em> releases the associated lock and
059         * suspends the current thread, just like {@code Object.wait}.
060         *
061         * <p>A {@code Condition} instance is intrinsically bound to a lock.
062         * To obtain a {@code Condition} instance for a particular {@link Lock}
063         * instance use its {@link Lock#newCondition newCondition()} method.
064         *
065         * <p>As an example, suppose we have a bounded buffer which supports
066         * {@code put} and {@code take} methods.  If a
067         * {@code take} is attempted on an empty buffer, then the thread will block
068         * until an item becomes available; if a {@code put} is attempted on a
069         * full buffer, then the thread will block until a space becomes available.
070         * We would like to keep waiting {@code put} threads and {@code take}
071         * threads in separate wait-sets so that we can use the optimization of
072         * only notifying a single thread at a time when items or spaces become
073         * available in the buffer. This can be achieved using two
074         * {@link Condition} instances.
075         * <pre>
076         * class BoundedBuffer {
077         *   <b>final Lock lock = new ReentrantLock();</b>
078         *   final Condition notFull  = <b>lock.newCondition(); </b>
079         *   final Condition notEmpty = <b>lock.newCondition(); </b>
080         *
081         *   final Object[] items = new Object[100];
082         *   int putptr, takeptr, count;
083         *
084         *   public void put(Object x) throws InterruptedException {
085         *     <b>lock.lock();
086         *     try {</b>
087         *       while (count == items.length)
088         *         <b>notFull.await();</b>
089         *       items[putptr] = x;
090         *       if (++putptr == items.length) putptr = 0;
091         *       ++count;
092         *       <b>notEmpty.signal();</b>
093         *     <b>} finally {
094         *       lock.unlock();
095         *     }</b>
096         *   }
097         *
098         *   public Object take() throws InterruptedException {
099         *     <b>lock.lock();
100         *     try {</b>
101         *       while (count == 0)
102         *         <b>notEmpty.await();</b>
103         *       Object x = items[takeptr];
104         *       if (++takeptr == items.length) takeptr = 0;
105         *       --count;
106         *       <b>notFull.signal();</b>
107         *       return x;
108         *     <b>} finally {
109         *       lock.unlock();
110         *     }</b>
111         *   }
112         * }
113         * </pre>
114         *
115         * (The {@link java.util.concurrent.ArrayBlockingQueue} class provides
116         * this functionality, so there is no reason to implement this
117         * sample usage class.)
118         *
119         * <p>A {@code Condition} implementation can provide behavior and semantics
120         * that is
121         * different from that of the {@code Object} monitor methods, such as
122         * guaranteed ordering for notifications, or not requiring a lock to be held
123         * when performing notifications.
124         * If an implementation provides such specialized semantics then the
125         * implementation must document those semantics.
126         *
127         * <p>Note that {@code Condition} instances are just normal objects and can
128         * themselves be used as the target in a {@code synchronized} statement,
129         * and can have their own monitor {@link Object#wait wait} and
130         * {@link Object#notify notification} methods invoked.
131         * Acquiring the monitor lock of a {@code Condition} instance, or using its
132         * monitor methods, has no specified relationship with acquiring the
133         * {@link Lock} associated with that {@code Condition} or the use of its
134         * {@linkplain #await waiting} and {@linkplain #signal signalling} methods.
135         * It is recommended that to avoid confusion you never use {@code Condition}
136         * instances in this way, except perhaps within their own implementation.
137         *
138         * <p>Except where noted, passing a {@code null} value for any parameter
139         * will result in a {@link NullPointerException} being thrown.
140         *
141         * <h3>Implementation Considerations</h3>
142         *
143         * <p>When waiting upon a {@code Condition}, a &quot;<em>spurious
144         * wakeup</em>&quot; is permitted to occur, in
145         * general, as a concession to the underlying platform semantics.
146         * This has little practical impact on most application programs as a
147         * {@code Condition} should always be waited upon in a loop, testing
148         * the state predicate that is being waited for.  An implementation is
149         * free to remove the possibility of spurious wakeups but it is
150         * recommended that applications programmers always assume that they can
151         * occur and so always wait in a loop.
152         *
153         * <p>The three forms of condition waiting
154         * (interruptible, non-interruptible, and timed) may differ in their ease of
155         * implementation on some platforms and in their performance characteristics.
156         * In particular, it may be difficult to provide these features and maintain
157         * specific semantics such as ordering guarantees.
158         * Further, the ability to interrupt the actual suspension of the thread may
159         * not always be feasible to implement on all platforms.
160         *
161         * <p>Consequently, an implementation is not required to define exactly the
162         * same guarantees or semantics for all three forms of waiting, nor is it
163         * required to support interruption of the actual suspension of the thread.
164         *
165         * <p>An implementation is required to
166         * clearly document the semantics and guarantees provided by each of the
167         * waiting methods, and when an implementation does support interruption of
168         * thread suspension then it must obey the interruption semantics as defined
169         * in this interface.
170         *
171         * <p>As interruption generally implies cancellation, and checks for
172         * interruption are often infrequent, an implementation can favor responding
173         * to an interrupt over normal method return. This is true even if it can be
174         * shown that the interrupt occurred after another action may have unblocked
175         * the thread. An implementation should document this behavior.
176         *
177         * @since 1.5
178         * @author Doug Lea
179         */
180        public interface Condition {
181
182            /**
183             * Causes the current thread to wait until it is signalled or
184             * {@linkplain Thread#interrupt interrupted}.
185             *
186             * <p>The lock associated with this {@code Condition} is atomically
187             * released and the current thread becomes disabled for thread scheduling
188             * purposes and lies dormant until <em>one</em> of four things happens:
189             * <ul>
190             * <li>Some other thread invokes the {@link #signal} method for this
191             * {@code Condition} and the current thread happens to be chosen as the
192             * thread to be awakened; or
193             * <li>Some other thread invokes the {@link #signalAll} method for this
194             * {@code Condition}; or
195             * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
196             * current thread, and interruption of thread suspension is supported; or
197             * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
198             * </ul>
199             *
200             * <p>In all cases, before this method can return the current thread must
201             * re-acquire the lock associated with this condition. When the
202             * thread returns it is <em>guaranteed</em> to hold this lock.
203             *
204             * <p>If the current thread:
205             * <ul>
206             * <li>has its interrupted status set on entry to this method; or
207             * <li>is {@linkplain Thread#interrupt interrupted} while waiting
208             * and interruption of thread suspension is supported,
209             * </ul>
210             * then {@link InterruptedException} is thrown and the current thread's
211             * interrupted status is cleared. It is not specified, in the first
212             * case, whether or not the test for interruption occurs before the lock
213             * is released.
214             *
215             * <p><b>Implementation Considerations</b>
216             *
217             * <p>The current thread is assumed to hold the lock associated with this
218             * {@code Condition} when this method is called.
219             * It is up to the implementation to determine if this is
220             * the case and if not, how to respond. Typically, an exception will be
221             * thrown (such as {@link IllegalMonitorStateException}) and the
222             * implementation must document that fact.
223             *
224             * <p>An implementation can favor responding to an interrupt over normal
225             * method return in response to a signal. In that case the implementation
226             * must ensure that the signal is redirected to another waiting thread, if
227             * there is one.
228             *
229             * @throws InterruptedException if the current thread is interrupted
230             *         (and interruption of thread suspension is supported)
231             */
232            void await() throws InterruptedException;
233
234            /**
235             * Causes the current thread to wait until it is signalled.
236             *
237             * <p>The lock associated with this condition is atomically
238             * released and the current thread becomes disabled for thread scheduling
239             * purposes and lies dormant until <em>one</em> of three things happens:
240             * <ul>
241             * <li>Some other thread invokes the {@link #signal} method for this
242             * {@code Condition} and the current thread happens to be chosen as the
243             * thread to be awakened; or
244             * <li>Some other thread invokes the {@link #signalAll} method for this
245             * {@code Condition}; or
246             * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
247             * </ul>
248             *
249             * <p>In all cases, before this method can return the current thread must
250             * re-acquire the lock associated with this condition. When the
251             * thread returns it is <em>guaranteed</em> to hold this lock.
252             *
253             * <p>If the current thread's interrupted status is set when it enters
254             * this method, or it is {@linkplain Thread#interrupt interrupted}
255             * while waiting, it will continue to wait until signalled. When it finally
256             * returns from this method its interrupted status will still
257             * be set.
258             *
259             * <p><b>Implementation Considerations</b>
260             *
261             * <p>The current thread is assumed to hold the lock associated with this
262             * {@code Condition} when this method is called.
263             * It is up to the implementation to determine if this is
264             * the case and if not, how to respond. Typically, an exception will be
265             * thrown (such as {@link IllegalMonitorStateException}) and the
266             * implementation must document that fact.
267             */
268            void awaitUninterruptibly();
269
270            /**
271             * Causes the current thread to wait until it is signalled or interrupted,
272             * or the specified waiting time elapses.
273             *
274             * <p>The lock associated with this condition is atomically
275             * released and the current thread becomes disabled for thread scheduling
276             * purposes and lies dormant until <em>one</em> of five things happens:
277             * <ul>
278             * <li>Some other thread invokes the {@link #signal} method for this
279             * {@code Condition} and the current thread happens to be chosen as the
280             * thread to be awakened; or
281             * <li>Some other thread invokes the {@link #signalAll} method for this
282             * {@code Condition}; or
283             * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
284             * current thread, and interruption of thread suspension is supported; or
285             * <li>The specified waiting time elapses; or
286             * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
287             * </ul>
288             *
289             * <p>In all cases, before this method can return the current thread must
290             * re-acquire the lock associated with this condition. When the
291             * thread returns it is <em>guaranteed</em> to hold this lock.
292             *
293             * <p>If the current thread:
294             * <ul>
295             * <li>has its interrupted status set on entry to this method; or
296             * <li>is {@linkplain Thread#interrupt interrupted} while waiting
297             * and interruption of thread suspension is supported,
298             * </ul>
299             * then {@link InterruptedException} is thrown and the current thread's
300             * interrupted status is cleared. It is not specified, in the first
301             * case, whether or not the test for interruption occurs before the lock
302             * is released.
303             *
304             * <p>The method returns an estimate of the number of nanoseconds
305             * remaining to wait given the supplied {@code nanosTimeout}
306             * value upon return, or a value less than or equal to zero if it
307             * timed out. This value can be used to determine whether and how
308             * long to re-wait in cases where the wait returns but an awaited
309             * condition still does not hold. Typical uses of this method take
310             * the following form:
311             *
312             * <pre>
313             * synchronized boolean aMethod(long timeout, TimeUnit unit) {
314             *   long nanosTimeout = unit.toNanos(timeout);
315             *   while (!conditionBeingWaitedFor) {
316             *     if (nanosTimeout &gt; 0)
317             *         nanosTimeout = theCondition.awaitNanos(nanosTimeout);
318             *      else
319             *        return false;
320             *   }
321             *   // ...
322             * }
323             * </pre>
324             *
325             * <p> Design note: This method requires a nanosecond argument so
326             * as to avoid truncation errors in reporting remaining times.
327             * Such precision loss would make it difficult for programmers to
328             * ensure that total waiting times are not systematically shorter
329             * than specified when re-waits occur.
330             *
331             * <p><b>Implementation Considerations</b>
332             *
333             * <p>The current thread is assumed to hold the lock associated with this
334             * {@code Condition} when this method is called.
335             * It is up to the implementation to determine if this is
336             * the case and if not, how to respond. Typically, an exception will be
337             * thrown (such as {@link IllegalMonitorStateException}) and the
338             * implementation must document that fact.
339             *
340             * <p>An implementation can favor responding to an interrupt over normal
341             * method return in response to a signal, or over indicating the elapse
342             * of the specified waiting time. In either case the implementation
343             * must ensure that the signal is redirected to another waiting thread, if
344             * there is one.
345             *
346             * @param nanosTimeout the maximum time to wait, in nanoseconds
347             * @return an estimate of the {@code nanosTimeout} value minus
348             *         the time spent waiting upon return from this method.
349             *         A positive value may be used as the argument to a
350             *         subsequent call to this method to finish waiting out
351             *         the desired time.  A value less than or equal to zero
352             *         indicates that no time remains.
353             * @throws InterruptedException if the current thread is interrupted
354             *         (and interruption of thread suspension is supported)
355             */
356            long awaitNanos(long nanosTimeout) throws InterruptedException;
357
358            /**
359             * Causes the current thread to wait until it is signalled or interrupted,
360             * or the specified waiting time elapses. This method is behaviorally
361             * equivalent to:<br>
362             * <pre>
363             *   awaitNanos(unit.toNanos(time)) &gt; 0
364             * </pre>
365             * @param time the maximum time to wait
366             * @param unit the time unit of the {@code time} argument
367             * @return {@code false} if the waiting time detectably elapsed
368             *         before return from the method, else {@code true}
369             * @throws InterruptedException if the current thread is interrupted
370             *         (and interruption of thread suspension is supported)
371             */
372            boolean await(long time, TimeUnit unit) throws InterruptedException;
373
374            /**
375             * Causes the current thread to wait until it is signalled or interrupted,
376             * or the specified deadline elapses.
377             *
378             * <p>The lock associated with this condition is atomically
379             * released and the current thread becomes disabled for thread scheduling
380             * purposes and lies dormant until <em>one</em> of five things happens:
381             * <ul>
382             * <li>Some other thread invokes the {@link #signal} method for this
383             * {@code Condition} and the current thread happens to be chosen as the
384             * thread to be awakened; or
385             * <li>Some other thread invokes the {@link #signalAll} method for this
386             * {@code Condition}; or
387             * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
388             * current thread, and interruption of thread suspension is supported; or
389             * <li>The specified deadline elapses; or
390             * <li>A &quot;<em>spurious wakeup</em>&quot; occurs.
391             * </ul>
392             *
393             * <p>In all cases, before this method can return the current thread must
394             * re-acquire the lock associated with this condition. When the
395             * thread returns it is <em>guaranteed</em> to hold this lock.
396             *
397             *
398             * <p>If the current thread:
399             * <ul>
400             * <li>has its interrupted status set on entry to this method; or
401             * <li>is {@linkplain Thread#interrupt interrupted} while waiting
402             * and interruption of thread suspension is supported,
403             * </ul>
404             * then {@link InterruptedException} is thrown and the current thread's
405             * interrupted status is cleared. It is not specified, in the first
406             * case, whether or not the test for interruption occurs before the lock
407             * is released.
408             *
409             *
410             * <p>The return value indicates whether the deadline has elapsed,
411             * which can be used as follows:
412             * <pre>
413             * synchronized boolean aMethod(Date deadline) {
414             *   boolean stillWaiting = true;
415             *   while (!conditionBeingWaitedFor) {
416             *     if (stillWaiting)
417             *         stillWaiting = theCondition.awaitUntil(deadline);
418             *      else
419             *        return false;
420             *   }
421             *   // ...
422             * }
423             * </pre>
424             *
425             * <p><b>Implementation Considerations</b>
426             *
427             * <p>The current thread is assumed to hold the lock associated with this
428             * {@code Condition} when this method is called.
429             * It is up to the implementation to determine if this is
430             * the case and if not, how to respond. Typically, an exception will be
431             * thrown (such as {@link IllegalMonitorStateException}) and the
432             * implementation must document that fact.
433             *
434             * <p>An implementation can favor responding to an interrupt over normal
435             * method return in response to a signal, or over indicating the passing
436             * of the specified deadline. In either case the implementation
437             * must ensure that the signal is redirected to another waiting thread, if
438             * there is one.
439             *
440             * @param deadline the absolute time to wait until
441             * @return {@code false} if the deadline has elapsed upon return, else
442             *         {@code true}
443             * @throws InterruptedException if the current thread is interrupted
444             *         (and interruption of thread suspension is supported)
445             */
446            boolean awaitUntil(Date deadline) throws InterruptedException;
447
448            /**
449             * Wakes up one waiting thread.
450             *
451             * <p>If any threads are waiting on this condition then one
452             * is selected for waking up. That thread must then re-acquire the
453             * lock before returning from {@code await}.
454             */
455            void signal();
456
457            /**
458             * Wakes up all waiting threads.
459             *
460             * <p>If any threads are waiting on this condition then they are
461             * all woken up. Each thread must re-acquire the lock before it can
462             * return from {@code await}.
463             */
464            void signalAll();
465        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.