sample/java.util.concurrent.locks.Lock.txt

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