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

   1 *java.util.concurrent.locks.LockSupport* *LockSupport* Basic thread blocking pri
   2
   3 public class LockSupport
   4   extends    |java.lang.Object|
   5
   6 |java.util.concurrent.locks.LockSupport_Description|
   7 |java.util.concurrent.locks.LockSupport_Fields|
   8 |java.util.concurrent.locks.LockSupport_Constructors|
   9 |java.util.concurrent.locks.LockSupport_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.concurrent.locks.LockSupport_Methods*
  14 |java.util.concurrent.locks.LockSupport.getBlocker(Thread)|Returns the blocker
  15 |java.util.concurrent.locks.LockSupport.park()|Disables the current thread for
  16 |java.util.concurrent.locks.LockSupport.park(Object)|Disables the current threa
  17 |java.util.concurrent.locks.LockSupport.parkNanos(long)|Disables the current th
  18 |java.util.concurrent.locks.LockSupport.parkNanos(Object,long)|Disables the cur
  19 |java.util.concurrent.locks.LockSupport.parkUntil(long)|Disables the current th
  20 |java.util.concurrent.locks.LockSupport.parkUntil(Object,long)|Disables the cur
  21 |java.util.concurrent.locks.LockSupport.unpark(Thread)|Makes available the perm
  22
  23 *java.util.concurrent.locks.LockSupport_Description*
  24
  25 Basic thread blocking primitives for creating locks and other synchronization
  26 classes.
  27
  28 This class associates, with each thread that uses it, a permit (in the sense of
  29 the Semaphore(|java.util.concurrent.Semaphore|) class). A call toparkwill
  30 return immediately if the permit is available, consuming it in the process;
  31 otherwise it may block. A call tounparkmakes the permit available, if it was
  32 not already available. (Unlike with Semaphores though, permits do not
  33 accumulate. There is at most one.)
  34
  35 Methodsparkandunparkprovide efficient means of blocking and unblocking threads
  36 that do not encounter the problems that cause the deprecated
  37 methodsThread.suspendandThread.resumeto be unusable for such purposes: Races
  38 between one thread invokingparkand another thread trying tounparkit will
  39 preserve liveness, due to the permit. Additionally,parkwill return if the
  40 caller's thread was interrupted, and timeout versions are supported.
  41 Theparkmethod may also return at any other time, for "no reason", so in general
  42 must be invoked within a loop that rechecks conditions upon return. In this
  43 senseparkserves as an optimization of a "busy wait" that does not waste as much
  44 time spinning, but must be paired with anunparkto be effective.
  45
  46 The three forms ofparkeach also support ablockerobject parameter. This object
  47 is recorded while the thread is blocked to permit monitoring and diagnostic
  48 tools to identify the reasons that threads are blocked. (Such tools may access
  49 blockers using method (|java.util.concurrent.locks.LockSupport|) .) The use of
  50 these forms rather than the original forms without this parameter is strongly
  51 encouraged. The normal argument to supply as ablockerwithin a lock
  52 implementation isthis.
  53
  54 These methods are designed to be used as tools for creating higher-level
  55 synchronization utilities, and are not in themselves useful for most
  56 concurrency control applications. Theparkmethod is designed for use only in
  57 constructions of the form:
  58
  59 while (!canProceed()) { ... LockSupport.park(this); }
  60
  61 where neithercanProceednor any other actions prior to the call toparkentail
  62 locking or blocking. Because only one permit is associated with each thread,
  63 any intermediary uses ofparkcould interfere with its intended effects.
  64
  65 Sample Usage. Here is a sketch of a first-in-first-out non-reentrant lock
  66 class:
  67
  68 class FIFOMutex { private final AtomicBoolean locked = new
  69 AtomicBoolean(false); private final Queue waiters = new
  70 ConcurrentLinkedQueue();
  71
  72 public void lock() { boolean wasInterrupted = false; Thread current =
  73 Thread.currentThread(); waiters.add(current);
  74
  75 // Block while not first in queue or cannot acquire lock while (waiters.peek()
  76 != current || !locked.compareAndSet(false, true)) { LockSupport.park(this); if
  77 (Thread.interrupted()) // ignore interrupts while waiting wasInterrupted =
  78 true; }
  79
  80 waiters.remove(); if (wasInterrupted) // reassert interrupt status on exit
  81 current.interrupt(); }
  82
  83 public void unlock() { locked.set(false); LockSupport.unpark(waiters.peek()); }
  84 }
  85
  86
  87
  88 *java.util.concurrent.locks.LockSupport.getBlocker(Thread)*
  89
  90 public static |java.lang.Object| getBlocker(java.lang.Thread t)
  91
  92 Returns the blocker object supplied to the most recent invocation of a park
  93 method that has not yet unblocked, or null if not blocked. The value returned
  94 is just a momentary snapshot -- the thread may have since unblocked or blocked
  95 on a different blocker object.
  96
  97
  98
  99     Returns:
 100
 101 *java.util.concurrent.locks.LockSupport.park()*
 102
 103 public static void park()
 104
 105 Disables the current thread for thread scheduling purposes unless the permit is
 106 available.
 107
 108 If the permit is available then it is consumed and the call returns
 109 immediately; otherwise the current thread becomes disabled for thread
 110 scheduling purposes and lies dormant until one of three things happens:
 111
 112
 113
 114 Some other thread invokes unpark(|java.util.concurrent.locks.LockSupport|) with
 115 the current thread as the target; or
 116
 117 Some other thread interrupts(|java.lang.Thread|) the current thread; or
 118
 119 The call spuriously (that is, for no reason) returns.
 120
 121 This method does not report which of these caused the method to return. Callers
 122 should re-check the conditions which caused the thread to park in the first
 123 place. Callers may also determine, for example, the interrupt status of the
 124 thread upon return.
 125
 126
 127
 128 *java.util.concurrent.locks.LockSupport.park(Object)*
 129
 130 public static void park(java.lang.Object blocker)
 131
 132 Disables the current thread for thread scheduling purposes unless the permit is
 133 available.
 134
 135 If the permit is available then it is consumed and the call returns
 136 immediately; otherwise the current thread becomes disabled for thread
 137 scheduling purposes and lies dormant until one of three things happens:
 138
 139 Some other thread invokes unpark(|java.util.concurrent.locks.LockSupport|) with
 140 the current thread as the target; or
 141
 142 Some other thread interrupts(|java.lang.Thread|) the current thread; or
 143
 144 The call spuriously (that is, for no reason) returns.
 145
 146 This method does not report which of these caused the method to return. Callers
 147 should re-check the conditions which caused the thread to park in the first
 148 place. Callers may also determine, for example, the interrupt status of the
 149 thread upon return.
 150
 151
 152     blocker - the synchronization object responsible for this thread parking
 153
 154 *java.util.concurrent.locks.LockSupport.parkNanos(long)*
 155
 156 public static void parkNanos(long nanos)
 157
 158 Disables the current thread for thread scheduling purposes, for up to the
 159 specified waiting time, unless the permit is available.
 160
 161 If the permit is available then it is consumed and the call returns
 162 immediately; otherwise the current thread becomes disabled for thread
 163 scheduling purposes and lies dormant until one of four things happens:
 164
 165 Some other thread invokes unpark(|java.util.concurrent.locks.LockSupport|) with
 166 the current thread as the target; or
 167
 168 Some other thread interrupts(|java.lang.Thread|) the current thread; or
 169
 170 The specified waiting time elapses; or
 171
 172 The call spuriously (that is, for no reason) returns.
 173
 174 This method does not report which of these caused the method to return. Callers
 175 should re-check the conditions which caused the thread to park in the first
 176 place. Callers may also determine, for example, the interrupt status of the
 177 thread, or the elapsed time upon return.
 178
 179
 180     nanos - the maximum number of nanoseconds to wait
 181
 182 *java.util.concurrent.locks.LockSupport.parkNanos(Object,long)*
 183
 184 public static void parkNanos(
 185   java.lang.Object blocker,
 186   long nanos)
 187
 188 Disables the current thread for thread scheduling purposes, for up to the
 189 specified waiting time, unless the permit is available.
 190
 191 If the permit is available then it is consumed and the call returns
 192 immediately; otherwise the current thread becomes disabled for thread
 193 scheduling purposes and lies dormant until one of four things happens:
 194
 195 Some other thread invokes unpark(|java.util.concurrent.locks.LockSupport|) with
 196 the current thread as the target; or
 197
 198 Some other thread interrupts(|java.lang.Thread|) the current thread; or
 199
 200 The specified waiting time elapses; or
 201
 202 The call spuriously (that is, for no reason) returns.
 203
 204 This method does not report which of these caused the method to return. Callers
 205 should re-check the conditions which caused the thread to park in the first
 206 place. Callers may also determine, for example, the interrupt status of the
 207 thread, or the elapsed time upon return.
 208
 209
 210     blocker - the synchronization object responsible for this thread parking
 211     nanos - the maximum number of nanoseconds to wait
 212
 213 *java.util.concurrent.locks.LockSupport.parkUntil(long)*
 214
 215 public static void parkUntil(long deadline)
 216
 217 Disables the current thread for thread scheduling purposes, until the specified
 218 deadline, unless the permit is available.
 219
 220 If the permit is available then it is consumed and the call returns
 221 immediately; otherwise the current thread becomes disabled for thread
 222 scheduling purposes and lies dormant until one of four things happens:
 223
 224 Some other thread invokes unpark(|java.util.concurrent.locks.LockSupport|) with
 225 the current thread as the target; or
 226
 227 Some other thread interrupts(|java.lang.Thread|) the current thread; or
 228
 229 The specified deadline passes; or
 230
 231 The call spuriously (that is, for no reason) returns.
 232
 233 This method does not report which of these caused the method to return. Callers
 234 should re-check the conditions which caused the thread to park in the first
 235 place. Callers may also determine, for example, the interrupt status of the
 236 thread, or the current time upon return.
 237
 238
 239     deadline - the absolute time, in milliseconds from the Epoch, to wait until
 240
 241 *java.util.concurrent.locks.LockSupport.parkUntil(Object,long)*
 242
 243 public static void parkUntil(
 244   java.lang.Object blocker,
 245   long deadline)
 246
 247 Disables the current thread for thread scheduling purposes, until the specified
 248 deadline, unless the permit is available.
 249
 250 If the permit is available then it is consumed and the call returns
 251 immediately; otherwise the current thread becomes disabled for thread
 252 scheduling purposes and lies dormant until one of four things happens:
 253
 254 Some other thread invokes unpark(|java.util.concurrent.locks.LockSupport|) with
 255 the current thread as the target; or
 256
 257 Some other thread interrupts(|java.lang.Thread|) the current thread; or
 258
 259 The specified deadline passes; or
 260
 261 The call spuriously (that is, for no reason) returns.
 262
 263 This method does not report which of these caused the method to return. Callers
 264 should re-check the conditions which caused the thread to park in the first
 265 place. Callers may also determine, for example, the interrupt status of the
 266 thread, or the current time upon return.
 267
 268
 269     blocker - the synchronization object responsible for this thread parking
 270     deadline - the absolute time, in milliseconds from the Epoch, to wait until
 271
 272 *java.util.concurrent.locks.LockSupport.unpark(Thread)*
 273
 274 public static void unpark(java.lang.Thread thread)
 275
 276 Makes available the permit for the given thread, if it was not already
 277 available. If the thread was blocked onparkthen it will unblock. Otherwise, its
 278 next call toparkis guaranteed not to block. This operation is not guaranteed to
 279 have any effect at all if the given thread has not been started.
 280
 281
 282     thread - the thread to unpark, or {@code null}, in which case this operation has no
 283        effect
 284
 285