Source Code Cross Referenced for Lock.java in  » Apache-Harmony-Java-SE » java-package » java » util » concurrent » locks » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Apache Harmony Java SE » java package » java.util.concurrent.locks 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * Written by Doug Lea with assistance from members of JCP JSR-166
003:         * Expert Group and released to the public domain, as explained at
004:         * http://creativecommons.org/licenses/publicdomain
005:         */
006:
007:        package java.util.concurrent.locks;
008:
009:        import java.util.concurrent.TimeUnit;
010:
011:        /**
012:         * <tt>Lock</tt> implementations provide more extensive locking
013:         * operations than can be obtained using <tt>synchronized</tt> methods
014:         * and statements.  They allow more flexible structuring, may have
015:         * quite different properties, and may support multiple associated
016:         * {@link Condition} objects.
017:         *
018:         * <p>A lock is a tool for controlling access to a shared resource by
019:         * multiple threads. Commonly, a lock provides exclusive access to a
020:         * shared resource: only one thread at a time can acquire the lock and
021:         * all access to the shared resource requires that the lock be
022:         * acquired first. However, some locks may allow concurrent access to
023:         * a shared resource, such as the read lock of a {@link
024:         * ReadWriteLock}.
025:         *
026:         * <p>The use of <tt>synchronized</tt> methods or statements provides 
027:         * access to the implicit monitor lock associated with every object, but
028:         * forces all lock acquisition and release to occur in a block-structured way:
029:         * when multiple locks are acquired they must be released in the opposite
030:         * order, and all locks must be released in the same lexical scope in which
031:         * they were acquired.
032:         *
033:         * <p>While the scoping mechanism for <tt>synchronized</tt> methods
034:         * and statements makes it much easier to program with monitor locks,
035:         * and helps avoid many common programming errors involving locks,
036:         * there are occasions where you need to work with locks in a more
037:         * flexible way. For example, some algorithms for traversing
038:         * concurrently accessed data structures require the use of
039:         * &quot;hand-over-hand&quot; or &quot;chain locking&quot;: you
040:         * acquire the lock of node A, then node B, then release A and acquire
041:         * C, then release B and acquire D and so on.  Implementations of the
042:         * <tt>Lock</tt> interface enable the use of such techniques by
043:         * allowing a lock to be acquired and released in different scopes,
044:         * and allowing multiple locks to be acquired and released in any
045:         * order.
046:         *
047:         * <p>With this increased flexibility comes additional
048:         * responsibility. The absence of block-structured locking removes the
049:         * automatic release of locks that occurs with <tt>synchronized</tt>
050:         * methods and statements. In most cases, the following idiom
051:         * should be used:
052:         *
053:         * <pre><tt>     Lock l = ...; 
054:         *     l.lock();
055:         *     try {
056:         *         // access the resource protected by this lock
057:         *     } finally {
058:         *         l.unlock();
059:         *     }
060:         * </tt></pre>
061:         *
062:         * When locking and unlocking occur in different scopes, care must be
063:         * taken to ensure that all code that is executed while the lock is
064:         * held is protected by try-finally or try-catch to ensure that the
065:         * lock is released when necessary.
066:         *
067:         * <p><tt>Lock</tt> implementations provide additional functionality
068:         * over the use of <tt>synchronized</tt> methods and statements by
069:         * providing a non-blocking attempt to acquire a lock ({@link
070:         * #tryLock()}), an attempt to acquire the lock that can be
071:         * interrupted ({@link #lockInterruptibly}, and an attempt to acquire
072:         * the lock that can timeout ({@link #tryLock(long, TimeUnit)}).
073:         *
074:         * <p>A <tt>Lock</tt> class can also provide behavior and semantics
075:         * that is quite different from that of the implicit monitor lock,
076:         * such as guaranteed ordering, non-reentrant usage, or deadlock
077:         * detection. If an implementation provides such specialized semantics
078:         * then the implementation must document those semantics.
079:         *
080:         * <p>Note that <tt>Lock</tt> instances are just normal objects and can 
081:         * themselves be used as the target in a <tt>synchronized</tt> statement.
082:         * Acquiring the
083:         * monitor lock of a <tt>Lock</tt> instance has no specified relationship
084:         * with invoking any of the {@link #lock} methods of that instance. 
085:         * It is recommended that to avoid confusion you never use <tt>Lock</tt>
086:         * instances in this way, except within their own implementation.
087:         *
088:         * <p>Except where noted, passing a <tt>null</tt> value for any
089:         * parameter will result in a {@link NullPointerException} being
090:         * thrown.
091:         *
092:         * <h3>Memory Synchronization</h3>
093:         * <p>All <tt>Lock</tt> implementations <em>must</em> enforce the same
094:         * memory synchronization semantics as provided by the built-in monitor lock:
095:         * <ul>
096:         * <li>A successful lock operation acts like a successful 
097:         * <tt>monitorEnter</tt> action
098:         * <li>A successful <tt>unlock</tt> operation acts like a successful
099:         * <tt>monitorExit</tt> action
100:         * </ul>
101:         *
102:         * Unsuccessful locking and unlocking operations, and reentrant
103:         * locking/unlocking operations, do not require any memory
104:         * synchronization effects.
105:         *
106:         * <h3>Implementation Considerations</h3>
107:         *
108:         * <p> The three forms of lock acquisition (interruptible,
109:         * non-interruptible, and timed) may differ in their performance
110:         * characteristics, ordering guarantees, or other implementation
111:         * qualities.  Further, the ability to interrupt the <em>ongoing</em>
112:         * acquisition of a lock may not be available in a given <tt>Lock</tt>
113:         * class.  Consequently, an implementation is not required to define
114:         * exactly the same guarantees or semantics for all three forms of
115:         * lock acquisition, nor is it required to support interruption of an
116:         * ongoing lock acquisition.  An implementation is required to clearly
117:         * document the semantics and guarantees provided by each of the
118:         * locking methods. It must also obey the interruption semantics as
119:         * defined in this interface, to the extent that interruption of lock
120:         * acquisition is supported: which is either totally, or only on
121:         * method entry.
122:         *
123:         * <p>As interruption generally implies cancellation, and checks for 
124:         * interruption are often infrequent, an implementation can favor responding
125:         * to an interrupt over normal method return. This is true even if it can be
126:         * shown that the interrupt occurred after another action may have unblocked
127:         * the thread. An implementation should document this behavior. 
128:         *
129:         *
130:         * @see ReentrantLock
131:         * @see Condition
132:         * @see ReadWriteLock
133:         *
134:         * @since 1.5
135:         * @author Doug Lea
136:         *
137:         **/
138:        public interface Lock {
139:
140:            /**
141:             * Acquires the lock.
142:             * <p>If the lock is not available then
143:             * the current thread becomes disabled for thread scheduling 
144:             * purposes and lies dormant until the lock has been acquired.
145:             * <p><b>Implementation Considerations</b>
146:             * <p>A <tt>Lock</tt> implementation may be able to detect 
147:             * erroneous use of the lock, such as an invocation that would cause 
148:             * deadlock, and may throw an (unchecked) exception in such circumstances. 
149:             * The circumstances and the exception type must be documented by that 
150:             * <tt>Lock</tt> implementation.
151:             *
152:             **/
153:            void lock();
154:
155:            /**
156:             * Acquires the lock unless the current thread is  
157:             * {@link Thread#interrupt interrupted}. 
158:             * <p>Acquires the lock if it is available and returns immediately.
159:             * <p>If the lock is not available then
160:             * the current thread becomes disabled for thread scheduling 
161:             * purposes and lies dormant until one of two things happens:
162:             * <ul>
163:             * <li>The lock is acquired by the current thread; or
164:             * <li>Some other thread {@link Thread#interrupt interrupts} the current
165:             * thread, and interruption of lock acquisition is supported.
166:             * </ul>
167:             * <p>If the current thread:
168:             * <ul>
169:             * <li>has its interrupted status set on entry to this method; or 
170:             * <li>is {@link Thread#interrupt interrupted} while acquiring 
171:             * the lock, and interruption of lock acquisition is supported, 
172:             * </ul>
173:             * then {@link InterruptedException} is thrown and the current thread's 
174:             * interrupted status is cleared. 
175:             *
176:             * <p><b>Implementation Considerations</b>
177:             *
178:             * <p>The ability to interrupt a lock acquisition in some
179:             * implementations may not be possible, and if possible may be an
180:             * expensive operation.  The programmer should be aware that this
181:             * may be the case. An implementation should document when this is
182:             * the case.
183:             *
184:             * <p>An implementation can favor responding to an interrupt over
185:             * normal method return.
186:             *
187:             * <p>A <tt>Lock</tt> implementation may be able to detect
188:             * erroneous use of the lock, such as an invocation that would
189:             * cause deadlock, and may throw an (unchecked) exception in such
190:             * circumstances.  The circumstances and the exception type must
191:             * be documented by that <tt>Lock</tt> implementation.
192:             *
193:             * @throws InterruptedException if the current thread is interrupted
194:             * while acquiring the lock (and interruption of lock acquisition is 
195:             * supported).
196:             *
197:             * @see Thread#interrupt
198:             *
199:             **/
200:            void lockInterruptibly() throws InterruptedException;
201:
202:            /**
203:             * Acquires the lock only if it is free at the time of invocation.
204:             * <p>Acquires the lock if it is available and returns immediately
205:             * with the value <tt>true</tt>.
206:             * If the lock is not available then this method will return 
207:             * immediately with the value <tt>false</tt>.
208:             * <p>A typical usage idiom for this method would be:
209:             * <pre>
210:             *      Lock lock = ...;
211:             *      if (lock.tryLock()) {
212:             *          try {
213:             *              // manipulate protected state
214:             *          } finally {
215:             *              lock.unlock();
216:             *          }
217:             *      } else {
218:             *          // perform alternative actions
219:             *      }
220:             * </pre>
221:             * This usage ensures that the lock is unlocked if it was acquired, and
222:             * doesn't try to unlock if the lock was not acquired.
223:             *
224:             * @return <tt>true</tt> if the lock was acquired and <tt>false</tt>
225:             * otherwise.
226:             **/
227:            boolean tryLock();
228:
229:            /**
230:             * Acquires the lock if it is free within the given waiting time and the
231:             * current thread has not been {@link Thread#interrupt interrupted}.
232:             *
233:             * <p>If the lock is available this method returns immediately
234:             * with the value <tt>true</tt>.
235:             * If the lock is not available then
236:             * the current thread becomes disabled for thread scheduling 
237:             * purposes and lies dormant until one of three things happens:
238:             * <ul>
239:             * <li>The lock is acquired by the current thread; or
240:             * <li>Some other thread {@link Thread#interrupt interrupts} the current
241:             * thread, and interruption of lock acquisition is supported; or
242:             * <li>The specified waiting time elapses
243:             * </ul>
244:             * <p>If the lock is acquired then the value <tt>true</tt> is returned.
245:             * <p>If the current thread:
246:             * <ul>
247:             * <li>has its interrupted status set on entry to this method; or 
248:             * <li>is {@link Thread#interrupt interrupted} while acquiring 
249:             * the lock, and interruption of lock acquisition is supported, 
250:             * </ul>
251:             * then {@link InterruptedException} is thrown and the current thread's 
252:             * interrupted status is cleared. 
253:             * <p>If the specified waiting time elapses then the value <tt>false</tt>
254:             * is returned.
255:             * If the time is 
256:             * less than or equal to zero, the method will not wait at all.
257:             *
258:             * <p><b>Implementation Considerations</b>
259:             * <p>The ability to interrupt a lock acquisition in some implementations
260:             * may not be possible, and if possible may 
261:             * be an expensive operation. 
262:             * The programmer should be aware that this may be the case. An
263:             * implementation should document when this is the case.
264:             * <p>An implementation can favor responding to an interrupt over normal 
265:             * method return, or reporting a timeout.
266:             * <p>A <tt>Lock</tt> implementation may be able to detect 
267:             * erroneous use of the lock, such as an invocation that would cause 
268:             * deadlock, and may throw an (unchecked) exception in such circumstances. 
269:             * The circumstances and the exception type must be documented by that 
270:             * <tt>Lock</tt> implementation.
271:             *
272:             * @param time the maximum time to wait for the lock
273:             * @param unit the time unit of the <tt>time</tt> argument.
274:             * @return <tt>true</tt> if the lock was acquired and <tt>false</tt>
275:             * if the waiting time elapsed before the lock was acquired.
276:             *
277:             * @throws InterruptedException if the current thread is interrupted
278:             * while acquiring the lock (and interruption of lock acquisition is 
279:             * supported).
280:             *
281:             * @see Thread#interrupt
282:             *
283:             **/
284:            boolean tryLock(long time, TimeUnit unit)
285:                    throws InterruptedException;
286:
287:            /**
288:             * Releases the lock.
289:             * <p><b>Implementation Considerations</b>
290:             * <p>A <tt>Lock</tt> implementation will usually impose
291:             * restrictions on which thread can release a lock (typically only the
292:             * holder of the lock can release it) and may throw
293:             * an (unchecked) exception if the restriction is violated.
294:             * Any restrictions and the exception
295:             * type must be documented by that <tt>Lock</tt> implementation.
296:             **/
297:            void unlock();
298:
299:            /**
300:             * Returns a new {@link Condition} instance that is bound to this 
301:             * <tt>Lock</tt> instance.
302:             * <p>Before waiting on the condition the lock must be held by the 
303:             * current thread. 
304:             * A call to {@link Condition#await()} will atomically release the lock 
305:             * before waiting and re-acquire the lock before the wait returns.
306:             * <p><b>Implementation Considerations</b>
307:             * <p>The exact operation of the {@link Condition} instance depends on the
308:             * <tt>Lock</tt> implementation and must be documented by that
309:             * implementation.
310:             * 
311:             * @return A new {@link Condition} instance for this <tt>Lock</tt> 
312:             * instance.
313:             * @throws UnsupportedOperationException if this <tt>Lock</tt> 
314:             * implementation does not support conditions.
315:             **/
316:            Condition newCondition();
317:
318:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.