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