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™ 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
|
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 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
|