lib/classpath/external/jsr166/java/util/concurrent/locks/Lock.java

   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  * &quot;hand-over-hand&quot; or &quot;chain locking&quot;: 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 }