105  * detection. If an implementation provides such specialized semantics
 106  * then the implementation must document those semantics.
 107  *
 108  * <p>Note that {@code Lock} instances are just normal objects and can
 109  * themselves be used as the target in a {@code synchronized} statement.
 110  * Acquiring the
 111  * monitor lock of a {@code Lock} instance has no specified relationship
 112  * with invoking any of the {@link #lock} methods of that instance.
 113  * It is recommended that to avoid confusion you never use {@code Lock}
 114  * instances in this way, except within their own implementation.
 115  *
 116  * <p>Except where noted, passing a {@code null} value for any
 117  * parameter will result in a {@link NullPointerException} being
 118  * thrown.
 119  *
 120  * <h2>Memory Synchronization</h2>
 121  *
 122  * <p>All {@code Lock} implementations <em>must</em> enforce the same
 123  * memory synchronization semantics as provided by the built-in monitor
 124  * lock, as described in
 125  * <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-17.html#jls-17.4">
 126  * Chapter 17 of
 127  * <cite>The Java&trade; Language Specification</cite></a>:
 128  * <ul>
 129  * <li>A successful {@code lock} operation has the same memory
 130  * synchronization effects as a successful <em>Lock</em> action.
 131  * <li>A successful {@code unlock} operation has the same
 132  * memory synchronization effects as a successful <em>Unlock</em> action.
 133  * </ul>
 134  *
 135  * Unsuccessful locking and unlocking operations, and reentrant
 136  * locking/unlocking operations, do not require any memory
 137  * synchronization effects.
 138  *
 139  * <h2>Implementation Considerations</h2>
 140  *
 141  * <p>The three forms of lock acquisition (interruptible,
 142  * non-interruptible, and timed) may differ in their performance
 143  * characteristics, ordering guarantees, or other implementation
 144  * qualities.  Further, the ability to interrupt the <em>ongoing</em>
 145  * acquisition of a lock may not be available in a given {@code Lock}
 146  * class.  Consequently, an implementation is not required to define
 147  * exactly the same guarantees or semantics for all three forms of
 148  * lock acquisition, nor is it required to support interruption of an
 149  * ongoing lock acquisition.  An implementation is required to clearly
 150  * document the semantics and guarantees provided by each of the
 151  * locking methods. It must also obey the interruption semantics as
 152  * defined in this interface, to the extent that interruption of lock
 153  * acquisition is supported: which is either totally, or only on
 154  * method entry.
 155  *
 156  * <p>As interruption generally implies cancellation, and checks for
 157  * interruption are often infrequent, an implementation can favor responding
 158  * to an interrupt over normal method return. This is true even if it can be
 159  * shown that the interrupt occurred after another action may have unblocked
 160  * the thread. An implementation should document this behavior.
 161  *
 162  * @see ReentrantLock
 163  * @see Condition
 164  * @see ReadWriteLock

 165  *
 166  * @since 1.5
 167  * @author Doug Lea
 168  */
 169 public interface Lock {
 170 
 171     /**
 172      * Acquires the lock.
 173      *
 174      * <p>If the lock is not available then the current thread becomes
 175      * disabled for thread scheduling purposes and lies dormant until the
 176      * lock has been acquired.
 177      *
 178      * <p><b>Implementation Considerations</b>
 179      *
 180      * <p>A {@code Lock} implementation may be able to detect erroneous use
 181      * of the lock, such as an invocation that would cause deadlock, and
 182      * may throw an (unchecked) exception in such circumstances.  The
 183      * circumstances and the exception type must be documented by that
 184      * {@code Lock} implementation.

 105  * detection. If an implementation provides such specialized semantics
 106  * then the implementation must document those semantics.
 107  *
 108  * <p>Note that {@code Lock} instances are just normal objects and can
 109  * themselves be used as the target in a {@code synchronized} statement.
 110  * Acquiring the
 111  * monitor lock of a {@code Lock} instance has no specified relationship
 112  * with invoking any of the {@link #lock} methods of that instance.
 113  * It is recommended that to avoid confusion you never use {@code Lock}
 114  * instances in this way, except within their own implementation.
 115  *
 116  * <p>Except where noted, passing a {@code null} value for any
 117  * parameter will result in a {@link NullPointerException} being
 118  * thrown.
 119  *
 120  * <h2>Memory Synchronization</h2>
 121  *
 122  * <p>All {@code Lock} implementations <em>must</em> enforce the same
 123  * memory synchronization semantics as provided by the built-in monitor
 124  * lock, as described in

 125  * Chapter 17 of
 126  * <cite>The Java&trade; Language Specification</cite>:
 127  * <ul>
 128  * <li>A successful {@code lock} operation has the same memory
 129  * synchronization effects as a successful <em>Lock</em> action.
 130  * <li>A successful {@code unlock} operation has the same
 131  * memory synchronization effects as a successful <em>Unlock</em> action.
 132  * </ul>
 133  *
 134  * Unsuccessful locking and unlocking operations, and reentrant
 135  * locking/unlocking operations, do not require any memory
 136  * synchronization effects.
 137  *
 138  * <h2>Implementation Considerations</h2>
 139  *
 140  * <p>The three forms of lock acquisition (interruptible,
 141  * non-interruptible, and timed) may differ in their performance
 142  * characteristics, ordering guarantees, or other implementation
 143  * qualities.  Further, the ability to interrupt the <em>ongoing</em>
 144  * acquisition of a lock may not be available in a given {@code Lock}
 145  * class.  Consequently, an implementation is not required to define
 146  * exactly the same guarantees or semantics for all three forms of
 147  * lock acquisition, nor is it required to support interruption of an
 148  * ongoing lock acquisition.  An implementation is required to clearly
 149  * document the semantics and guarantees provided by each of the
 150  * locking methods. It must also obey the interruption semantics as
 151  * defined in this interface, to the extent that interruption of lock
 152  * acquisition is supported: which is either totally, or only on
 153  * method entry.
 154  *
 155  * <p>As interruption generally implies cancellation, and checks for
 156  * interruption are often infrequent, an implementation can favor responding
 157  * to an interrupt over normal method return. This is true even if it can be
 158  * shown that the interrupt occurred after another action may have unblocked
 159  * the thread. An implementation should document this behavior.
 160  *
 161  * @see ReentrantLock
 162  * @see Condition
 163  * @see ReadWriteLock
 164  * @jls 17.4 Memory Model
 165  *
 166  * @since 1.5
 167  * @author Doug Lea
 168  */
 169 public interface Lock {
 170 
 171     /**
 172      * Acquires the lock.
 173      *
 174      * <p>If the lock is not available then the current thread becomes
 175      * disabled for thread scheduling purposes and lies dormant until the
 176      * lock has been acquired.
 177      *
 178      * <p><b>Implementation Considerations</b>
 179      *
 180      * <p>A {@code Lock} implementation may be able to detect erroneous use
 181      * of the lock, such as an invocation that would cause deadlock, and
 182      * may throw an (unchecked) exception in such circumstances.  The
 183      * circumstances and the exception type must be documented by that
 184      * {@code Lock} implementation.