2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
36 package java.util.concurrent.locks;
40 * Basic thread blocking primitives for creating locks and other
41 * synchronization classes.
43 * <p>This class associates, with each thread that uses it, a permit
44 * (in the sense of the {@link java.util.concurrent.Semaphore
45 * Semaphore} class). A call to {@code park} will return immediately
46 * if the permit is available, consuming it in the process; otherwise
47 * it <em>may</em> block. A call to {@code unpark} makes the permit
48 * available, if it was not already available. (Unlike with Semaphores
49 * though, permits do not accumulate. There is at most one.)
51 * <p>Methods {@code park} and {@code unpark} provide efficient
52 * means of blocking and unblocking threads that do not encounter the
53 * problems that cause the deprecated methods {@code Thread.suspend}
54 * and {@code Thread.resume} to be unusable for such purposes: Races
55 * between one thread invoking {@code park} and another thread trying
56 * to {@code unpark} it will preserve liveness, due to the
57 * permit. Additionally, {@code park} will return if the caller's
58 * thread was interrupted, and timeout versions are supported. The
59 * {@code park} method may also return at any other time, for "no
60 * reason", so in general must be invoked within a loop that rechecks
61 * conditions upon return. In this sense {@code park} serves as an
62 * optimization of a "busy wait" that does not waste as much time
63 * spinning, but must be paired with an {@code unpark} to be
66 * <p>The three forms of {@code park} each also support a
67 * {@code blocker} object parameter. This object is recorded while
68 * the thread is blocked to permit monitoring and diagnostic tools to
69 * identify the reasons that threads are blocked. (Such tools may
70 * access blockers using method {@link #getBlocker}.) The use of these
71 * forms rather than the original forms without this parameter is
72 * strongly encouraged. The normal argument to supply as a
73 * {@code blocker} within a lock implementation is {@code this}.
75 * <p>These methods are designed to be used as tools for creating
76 * higher-level synchronization utilities, and are not in themselves
77 * useful for most concurrency control applications. The {@code park}
78 * method is designed for use only in constructions of the form:
79 * <pre>while (!canProceed()) { ... LockSupport.park(this); }</pre>
80 * where neither {@code canProceed} nor any other actions prior to the
81 * call to {@code park} entail locking or blocking. Because only one
82 * permit is associated with each thread, any intermediary uses of
83 * {@code park} could interfere with its intended effects.
85 * <p><b>Sample Usage.</b> Here is a sketch of a first-in-first-out
86 * non-reentrant lock class:
89 * private final AtomicBoolean locked = new AtomicBoolean(false);
90 * private final Queue<Thread> waiters
91 * = new ConcurrentLinkedQueue<Thread>();
93 * public void lock() {
94 * boolean wasInterrupted = false;
95 * Thread current = Thread.currentThread();
96 * waiters.add(current);
98 * // Block while not first in queue or cannot acquire lock
99 * while (waiters.peek() != current ||
100 * !locked.compareAndSet(false, true)) {
101 * LockSupport.park(this);
102 * if (Thread.interrupted()) // ignore interrupts while waiting
103 * wasInterrupted = true;
107 * if (wasInterrupted) // reassert interrupt status on exit
108 * current.interrupt();
111 * public void unlock() {
113 * LockSupport.unpark(waiters.peek());
118 public class LockSupport {
119 private LockSupport() {} // Cannot be instantiated.
122 * Makes available the permit for the given thread, if it
123 * was not already available. If the thread was blocked on
124 * {@code park} then it will unblock. Otherwise, its next call
125 * to {@code park} is guaranteed not to block. This operation
126 * is not guaranteed to have any effect at all if the given
127 * thread has not been started.
129 * @param thread the thread to unpark, or {@code null}, in which case
130 * this operation has no effect
132 public static void unpark(Thread thread) {
136 * Disables the current thread for thread scheduling purposes unless the
137 * permit is available.
139 * <p>If the permit is available then it is consumed and the call returns
140 * immediately; otherwise
141 * the current thread becomes disabled for thread scheduling
142 * purposes and lies dormant until one of three things happens:
145 * <li>Some other thread invokes {@link #unpark unpark} with the
146 * current thread as the target; or
148 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
149 * the current thread; or
151 * <li>The call spuriously (that is, for no reason) returns.
154 * <p>This method does <em>not</em> report which of these caused the
155 * method to return. Callers should re-check the conditions which caused
156 * the thread to park in the first place. Callers may also determine,
157 * for example, the interrupt status of the thread upon return.
159 * @param blocker the synchronization object responsible for this
163 public static void park(Object blocker) {
167 * Disables the current thread for thread scheduling purposes, for up to
168 * the specified waiting time, unless the permit is available.
170 * <p>If the permit is available then it is consumed and the call
171 * returns immediately; otherwise the current thread becomes disabled
172 * for thread scheduling purposes and lies dormant until one of four
176 * <li>Some other thread invokes {@link #unpark unpark} with the
177 * current thread as the target; or
179 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
180 * the current thread; or
182 * <li>The specified waiting time elapses; or
184 * <li>The call spuriously (that is, for no reason) returns.
187 * <p>This method does <em>not</em> report which of these caused the
188 * method to return. Callers should re-check the conditions which caused
189 * the thread to park in the first place. Callers may also determine,
190 * for example, the interrupt status of the thread, or the elapsed time
193 * @param blocker the synchronization object responsible for this
195 * @param nanos the maximum number of nanoseconds to wait
198 public static void parkNanos(Object blocker, long nanos) {
202 * Disables the current thread for thread scheduling purposes, until
203 * the specified deadline, unless the permit is available.
205 * <p>If the permit is available then it is consumed and the call
206 * returns immediately; otherwise the current thread becomes disabled
207 * for thread scheduling purposes and lies dormant until one of four
211 * <li>Some other thread invokes {@link #unpark unpark} with the
212 * current thread as the target; or
214 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
217 * <li>The specified deadline passes; or
219 * <li>The call spuriously (that is, for no reason) returns.
222 * <p>This method does <em>not</em> report which of these caused the
223 * method to return. Callers should re-check the conditions which caused
224 * the thread to park in the first place. Callers may also determine,
225 * for example, the interrupt status of the thread, or the current time
228 * @param blocker the synchronization object responsible for this
230 * @param deadline the absolute time, in milliseconds from the Epoch,
234 public static void parkUntil(Object blocker, long deadline) {
238 * Returns the blocker object supplied to the most recent
239 * invocation of a park method that has not yet unblocked, or null
240 * if not blocked. The value returned is just a momentary
241 * snapshot -- the thread may have since unblocked or blocked on a
242 * different blocker object.
244 * @param t the thread
245 * @return the blocker
246 * @throws NullPointerException if argument is null
249 public static Object getBlocker(Thread t) {
254 * Disables the current thread for thread scheduling purposes unless the
255 * permit is available.
257 * <p>If the permit is available then it is consumed and the call
258 * returns immediately; otherwise the current thread becomes disabled
259 * for thread scheduling purposes and lies dormant until one of three
264 * <li>Some other thread invokes {@link #unpark unpark} with the
265 * current thread as the target; or
267 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
268 * the current thread; or
270 * <li>The call spuriously (that is, for no reason) returns.
273 * <p>This method does <em>not</em> report which of these caused the
274 * method to return. Callers should re-check the conditions which caused
275 * the thread to park in the first place. Callers may also determine,
276 * for example, the interrupt status of the thread upon return.
278 public static void park() {
282 * Disables the current thread for thread scheduling purposes, for up to
283 * the specified waiting time, unless the permit is available.
285 * <p>If the permit is available then it is consumed and the call
286 * returns immediately; otherwise the current thread becomes disabled
287 * for thread scheduling purposes and lies dormant until one of four
291 * <li>Some other thread invokes {@link #unpark unpark} with the
292 * current thread as the target; or
294 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
295 * the current thread; or
297 * <li>The specified waiting time elapses; or
299 * <li>The call spuriously (that is, for no reason) returns.
302 * <p>This method does <em>not</em> report which of these caused the
303 * method to return. Callers should re-check the conditions which caused
304 * the thread to park in the first place. Callers may also determine,
305 * for example, the interrupt status of the thread, or the elapsed time
308 * @param nanos the maximum number of nanoseconds to wait
310 public static void parkNanos(long nanos) {
314 * Disables the current thread for thread scheduling purposes, until
315 * the specified deadline, unless the permit is available.
317 * <p>If the permit is available then it is consumed and the call
318 * returns immediately; otherwise the current thread becomes disabled
319 * for thread scheduling purposes and lies dormant until one of four
323 * <li>Some other thread invokes {@link #unpark unpark} with the
324 * current thread as the target; or
326 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
327 * the current thread; or
329 * <li>The specified deadline passes; or
331 * <li>The call spuriously (that is, for no reason) returns.
334 * <p>This method does <em>not</em> report which of these caused the
335 * method to return. Callers should re-check the conditions which caused
336 * the thread to park in the first place. Callers may also determine,
337 * for example, the interrupt status of the thread, or the current time
340 * @param deadline the absolute time, in milliseconds from the Epoch,
343 public static void parkUntil(long deadline) {