104  * detection. If an implementation provides such specialized semantics
 105  * then the implementation must document those semantics.
 106  *
 107  * <p>Note that {@code Lock} instances are just normal objects and can
 108  * themselves be used as the target in a {@code synchronized} statement.
 109  * Acquiring the
 110  * monitor lock of a {@code Lock} instance has no specified relationship
 111  * with invoking any of the {@link #lock} methods of that instance.
 112  * It is recommended that to avoid confusion you never use {@code Lock}
 113  * instances in this way, except within their own implementation.
 114  *
 115  * <p>Except where noted, passing a {@code null} value for any
 116  * parameter will result in a {@link NullPointerException} being
 117  * thrown.
 118  *
 119  * <h3>Memory Synchronization</h3>
 120  *
 121  * <p>All {@code Lock} implementations <em>must</em> enforce the same
 122  * memory synchronization semantics as provided by the built-in monitor
 123  * lock, as described in
 124  * <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4">
 125  * The Java Language Specification (17.4 Memory Model)</a>:
 126  * <ul>
 127  * <li>A successful {@code lock} operation has the same memory
 128  * synchronization effects as a successful <em>Lock</em> action.
 129  * <li>A successful {@code unlock} operation has the same
 130  * memory synchronization effects as a successful <em>Unlock</em> action.
 131  * </ul>
 132  *
 133  * Unsuccessful locking and unlocking operations, and reentrant
 134  * locking/unlocking operations, do not require any memory
 135  * synchronization effects.
 136  *
 137  * <h3>Implementation Considerations</h3>
 138  *
 139  * <p>The three forms of lock acquisition (interruptible,
 140  * non-interruptible, and timed) may differ in their performance
 141  * characteristics, ordering guarantees, or other implementation
 142  * qualities.  Further, the ability to interrupt the <em>ongoing</em>
 143  * acquisition of a lock may not be available in a given {@code Lock}
 144  * class.  Consequently, an implementation is not required to define

 104  * detection. If an implementation provides such specialized semantics
 105  * then the implementation must document those semantics.
 106  *
 107  * <p>Note that {@code Lock} instances are just normal objects and can
 108  * themselves be used as the target in a {@code synchronized} statement.
 109  * Acquiring the
 110  * monitor lock of a {@code Lock} instance has no specified relationship
 111  * with invoking any of the {@link #lock} methods of that instance.
 112  * It is recommended that to avoid confusion you never use {@code Lock}
 113  * instances in this way, except within their own implementation.
 114  *
 115  * <p>Except where noted, passing a {@code null} value for any
 116  * parameter will result in a {@link NullPointerException} being
 117  * thrown.
 118  *
 119  * <h3>Memory Synchronization</h3>
 120  *
 121  * <p>All {@code Lock} implementations <em>must</em> enforce the same
 122  * memory synchronization semantics as provided by the built-in monitor
 123  * lock, as described in
 124  * <a href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4">
 125  * The Java Language Specification (17.4 Memory Model)</a>:
 126  * <ul>
 127  * <li>A successful {@code lock} operation has the same memory
 128  * synchronization effects as a successful <em>Lock</em> action.
 129  * <li>A successful {@code unlock} operation has the same
 130  * memory synchronization effects as a successful <em>Unlock</em> action.
 131  * </ul>
 132  *
 133  * Unsuccessful locking and unlocking operations, and reentrant
 134  * locking/unlocking operations, do not require any memory
 135  * synchronization effects.
 136  *
 137  * <h3>Implementation Considerations</h3>
 138  *
 139  * <p>The three forms of lock acquisition (interruptible,
 140  * non-interruptible, and timed) may differ in their performance
 141  * characteristics, ordering guarantees, or other implementation
 142  * qualities.  Further, the ability to interrupt the <em>ongoing</em>
 143  * acquisition of a lock may not be available in a given {@code Lock}
 144  * class.  Consequently, an implementation is not required to define