GNU Classpath (0.98) | |
Frames | No Frames |
1: /* 2: * Written by Doug Lea with assistance from members of JCP JSR-166 3: * Expert Group and released to the public domain, as explained at 4: * http://creativecommons.org/licenses/publicdomain 5: */ 6: 7: package java.util.concurrent.locks; 8: import java.util.concurrent.TimeUnit; 9: 10: /** 11: * {@code Lock} implementations provide more extensive locking 12: * operations than can be obtained using {@code synchronized} methods 13: * and statements. They allow more flexible structuring, may have 14: * quite different properties, and may support multiple associated 15: * {@link Condition} objects. 16: * 17: * <p>A lock is a tool for controlling access to a shared resource by 18: * multiple threads. Commonly, a lock provides exclusive access to a 19: * shared resource: only one thread at a time can acquire the lock and 20: * all access to the shared resource requires that the lock be 21: * acquired first. However, some locks may allow concurrent access to 22: * a shared resource, such as the read lock of a {@link ReadWriteLock}. 23: * 24: * <p>The use of {@code synchronized} methods or statements provides 25: * access to the implicit monitor lock associated with every object, but 26: * forces all lock acquisition and release to occur in a block-structured way: 27: * when multiple locks are acquired they must be released in the opposite 28: * order, and all locks must be released in the same lexical scope in which 29: * they were acquired. 30: * 31: * <p>While the scoping mechanism for {@code synchronized} methods 32: * and statements makes it much easier to program with monitor locks, 33: * and helps avoid many common programming errors involving locks, 34: * there are occasions where you need to work with locks in a more 35: * flexible way. For example, some algorithms for traversing 36: * concurrently accessed data structures require the use of 37: * "hand-over-hand" or "chain locking": you 38: * acquire the lock of node A, then node B, then release A and acquire 39: * C, then release B and acquire D and so on. Implementations of the 40: * {@code Lock} interface enable the use of such techniques by 41: * allowing a lock to be acquired and released in different scopes, 42: * and allowing multiple locks to be acquired and released in any 43: * order. 44: * 45: * <p>With this increased flexibility comes additional 46: * responsibility. The absence of block-structured locking removes the 47: * automatic release of locks that occurs with {@code synchronized} 48: * methods and statements. In most cases, the following idiom 49: * should be used: 50: * 51: * <pre><tt> Lock l = ...; 52: * l.lock(); 53: * try { 54: * // access the resource protected by this lock 55: * } finally { 56: * l.unlock(); 57: * } 58: * </tt></pre> 59: * 60: * When locking and unlocking occur in different scopes, care must be 61: * taken to ensure that all code that is executed while the lock is 62: * held is protected by try-finally or try-catch to ensure that the 63: * lock is released when necessary. 64: * 65: * <p>{@code Lock} implementations provide additional functionality 66: * over the use of {@code synchronized} methods and statements by 67: * providing a non-blocking attempt to acquire a lock ({@link 68: * #tryLock()}), an attempt to acquire the lock that can be 69: * interrupted ({@link #lockInterruptibly}, and an attempt to acquire 70: * the lock that can timeout ({@link #tryLock(long, TimeUnit)}). 71: * 72: * <p>A {@code Lock} class can also provide behavior and semantics 73: * that is quite different from that of the implicit monitor lock, 74: * such as guaranteed ordering, non-reentrant usage, or deadlock 75: * detection. If an implementation provides such specialized semantics 76: * then the implementation must document those semantics. 77: * 78: * <p>Note that {@code Lock} instances are just normal objects and can 79: * themselves be used as the target in a {@code synchronized} statement. 80: * Acquiring the 81: * monitor lock of a {@code Lock} instance has no specified relationship 82: * with invoking any of the {@link #lock} methods of that instance. 83: * It is recommended that to avoid confusion you never use {@code Lock} 84: * instances in this way, except within their own implementation. 85: * 86: * <p>Except where noted, passing a {@code null} value for any 87: * parameter will result in a {@link NullPointerException} being 88: * thrown. 89: * 90: * <h3>Memory Synchronization</h3> 91: * 92: * <p>All {@code Lock} implementations <em>must</em> enforce the same 93: * memory synchronization semantics as provided by the built-in monitor 94: * lock, as described in <a href="http://java.sun.com/docs/books/jls/"> 95: * The Java Language Specification, Third Edition (17.4 Memory Model)</a>: 96: * <ul> 97: * <li>A successful {@code lock} operation has the same memory 98: * synchronization effects as a successful <em>Lock</em> action. 99: * <li>A successful {@code unlock} operation has the same 100: * memory synchronization effects as a successful <em>Unlock</em> action. 101: * </ul> 102: * 103: * Unsuccessful locking and unlocking operations, and reentrant 104: * locking/unlocking operations, do not require any memory 105: * synchronization effects. 106: * 107: * <h3>Implementation Considerations</h3> 108: * 109: * <p> The three forms of lock acquisition (interruptible, 110: * non-interruptible, and timed) may differ in their performance 111: * characteristics, ordering guarantees, or other implementation 112: * qualities. Further, the ability to interrupt the <em>ongoing</em> 113: * acquisition of a lock may not be available in a given {@code Lock} 114: * class. Consequently, an implementation is not required to define 115: * exactly the same guarantees or semantics for all three forms of 116: * lock acquisition, nor is it required to support interruption of an 117: * ongoing lock acquisition. An implementation is required to clearly 118: * document the semantics and guarantees provided by each of the 119: * locking methods. It must also obey the interruption semantics as 120: * defined in this interface, to the extent that interruption of lock 121: * acquisition is supported: which is either totally, or only on 122: * method entry. 123: * 124: * <p>As interruption generally implies cancellation, and checks for 125: * interruption are often infrequent, an implementation can favor responding 126: * to an interrupt over normal method return. This is true even if it can be 127: * shown that the interrupt occurred after another action may have unblocked 128: * the thread. An implementation should document this behavior. 129: * 130: * @see ReentrantLock 131: * @see Condition 132: * @see ReadWriteLock 133: * 134: * @since 1.5 135: * @author Doug Lea 136: */ 137: public interface Lock { 138: 139: /** 140: * Acquires the lock. 141: * 142: * <p>If the lock is not available then the current thread becomes 143: * disabled for thread scheduling purposes and lies dormant until the 144: * lock has been acquired. 145: * 146: * <p><b>Implementation Considerations</b> 147: * 148: * <p>A {@code Lock} implementation may be able to detect erroneous use 149: * of the lock, such as an invocation that would cause deadlock, and 150: * may throw an (unchecked) exception in such circumstances. The 151: * circumstances and the exception type must be documented by that 152: * {@code Lock} implementation. 153: */ 154: void lock(); 155: 156: /** 157: * Acquires the lock unless the current thread is 158: * {@linkplain Thread#interrupt interrupted}. 159: * 160: * <p>Acquires the lock if it is available and returns immediately. 161: * 162: * <p>If the lock is not available then the current thread becomes 163: * disabled for thread scheduling purposes and lies dormant until 164: * one of two things happens: 165: * 166: * <ul> 167: * <li>The lock is acquired by the current thread; or 168: * <li>Some other thread {@linkplain Thread#interrupt interrupts} the 169: * current thread, and interruption of lock acquisition is supported. 170: * </ul> 171: * 172: * <p>If the current thread: 173: * <ul> 174: * <li>has its interrupted status set on entry to this method; or 175: * <li>is {@linkplain Thread#interrupt interrupted} while acquiring the 176: * lock, and interruption of lock acquisition is supported, 177: * </ul> 178: * then {@link InterruptedException} is thrown and the current thread's 179: * interrupted status is cleared. 180: * 181: * <p><b>Implementation Considerations</b> 182: * 183: * <p>The ability to interrupt a lock acquisition in some 184: * implementations may not be possible, and if possible may be an 185: * expensive operation. The programmer should be aware that this 186: * may be the case. An implementation should document when this is 187: * the case. 188: * 189: * <p>An implementation can favor responding to an interrupt over 190: * normal method return. 191: * 192: * <p>A {@code Lock} implementation may be able to detect 193: * erroneous use of the lock, such as an invocation that would 194: * cause deadlock, and may throw an (unchecked) exception in such 195: * circumstances. The circumstances and the exception type must 196: * be documented by that {@code Lock} implementation. 197: * 198: * @throws InterruptedException if the current thread is 199: * interrupted while acquiring the lock (and interruption 200: * of lock acquisition is supported). 201: */ 202: void lockInterruptibly() throws InterruptedException; 203: 204: /** 205: * Acquires the lock only if it is free at the time of invocation. 206: * 207: * <p>Acquires the lock if it is available and returns immediately 208: * with the value {@code true}. 209: * If the lock is not available then this method will return 210: * immediately with the value {@code false}. 211: * 212: * <p>A typical usage idiom for this method would be: 213: * <pre> 214: * Lock lock = ...; 215: * if (lock.tryLock()) { 216: * try { 217: * // manipulate protected state 218: * } finally { 219: * lock.unlock(); 220: * } 221: * } else { 222: * // perform alternative actions 223: * } 224: * </pre> 225: * This usage ensures that the lock is unlocked if it was acquired, and 226: * doesn't try to unlock if the lock was not acquired. 227: * 228: * @return {@code true} if the lock was acquired and 229: * {@code false} otherwise 230: */ 231: boolean tryLock(); 232: 233: /** 234: * Acquires the lock if it is free within the given waiting time and the 235: * current thread has not been {@linkplain Thread#interrupt interrupted}. 236: * 237: * <p>If the lock is available this method returns immediately 238: * with the value {@code true}. 239: * If the lock is not available then 240: * the current thread becomes disabled for thread scheduling 241: * purposes and lies dormant until one of three things happens: 242: * <ul> 243: * <li>The lock is acquired by the current thread; or 244: * <li>Some other thread {@linkplain Thread#interrupt interrupts} the 245: * current thread, and interruption of lock acquisition is supported; or 246: * <li>The specified waiting time elapses 247: * </ul> 248: * 249: * <p>If the lock is acquired then the value {@code true} is returned. 250: * 251: * <p>If the current thread: 252: * <ul> 253: * <li>has its interrupted status set on entry to this method; or 254: * <li>is {@linkplain Thread#interrupt interrupted} while acquiring 255: * the lock, and interruption of lock acquisition is supported, 256: * </ul> 257: * then {@link InterruptedException} is thrown and the current thread's 258: * interrupted status is cleared. 259: * 260: * <p>If the specified waiting time elapses then the value {@code false} 261: * is returned. 262: * If the time is 263: * less than or equal to zero, the method will not wait at all. 264: * 265: * <p><b>Implementation Considerations</b> 266: * 267: * <p>The ability to interrupt a lock acquisition in some implementations 268: * may not be possible, and if possible may 269: * be an expensive operation. 270: * The programmer should be aware that this may be the case. An 271: * implementation should document when this is the case. 272: * 273: * <p>An implementation can favor responding to an interrupt over normal 274: * method return, or reporting a timeout. 275: * 276: * <p>A {@code Lock} implementation may be able to detect 277: * erroneous use of the lock, such as an invocation that would cause 278: * deadlock, and may throw an (unchecked) exception in such circumstances. 279: * The circumstances and the exception type must be documented by that 280: * {@code Lock} implementation. 281: * 282: * @param time the maximum time to wait for the lock 283: * @param unit the time unit of the {@code time} argument 284: * @return {@code true} if the lock was acquired and {@code false} 285: * if the waiting time elapsed before the lock was acquired 286: * 287: * @throws InterruptedException if the current thread is interrupted 288: * while acquiring the lock (and interruption of lock 289: * acquisition is supported) 290: */ 291: boolean tryLock(long time, TimeUnit unit) throws InterruptedException; 292: 293: /** 294: * Releases the lock. 295: * 296: * <p><b>Implementation Considerations</b> 297: * 298: * <p>A {@code Lock} implementation will usually impose 299: * restrictions on which thread can release a lock (typically only the 300: * holder of the lock can release it) and may throw 301: * an (unchecked) exception if the restriction is violated. 302: * Any restrictions and the exception 303: * type must be documented by that {@code Lock} implementation. 304: */ 305: void unlock(); 306: 307: /** 308: * Returns a new {@link Condition} instance that is bound to this 309: * {@code Lock} instance. 310: * 311: * <p>Before waiting on the condition the lock must be held by the 312: * current thread. 313: * A call to {@link Condition#await()} will atomically release the lock 314: * before waiting and re-acquire the lock before the wait returns. 315: * 316: * <p><b>Implementation Considerations</b> 317: * 318: * <p>The exact operation of the {@link Condition} instance depends on 319: * the {@code Lock} implementation and must be documented by that 320: * implementation. 321: * 322: * @return A new {@link Condition} instance for this {@code Lock} instance 323: * @throws UnsupportedOperationException if this {@code Lock} 324: * implementation does not support conditions 325: */ 326: Condition newCondition(); 327: }
GNU Classpath (0.98) |