This class associates, with each thread that uses it, a permit jaroslav@1890: * (in the sense of the {@link java.util.concurrent.Semaphore jaroslav@1890: * Semaphore} class). A call to {@code park} will return immediately jaroslav@1890: * if the permit is available, consuming it in the process; otherwise jaroslav@1890: * it may block. A call to {@code unpark} makes the permit jaroslav@1890: * available, if it was not already available. (Unlike with Semaphores jaroslav@1890: * though, permits do not accumulate. There is at most one.) jaroslav@1890: * jaroslav@1890: *
Methods {@code park} and {@code unpark} provide efficient jaroslav@1890: * means of blocking and unblocking threads that do not encounter the jaroslav@1890: * problems that cause the deprecated methods {@code Thread.suspend} jaroslav@1890: * and {@code Thread.resume} to be unusable for such purposes: Races jaroslav@1890: * between one thread invoking {@code park} and another thread trying jaroslav@1890: * to {@code unpark} it will preserve liveness, due to the jaroslav@1890: * permit. Additionally, {@code park} will return if the caller's jaroslav@1890: * thread was interrupted, and timeout versions are supported. The jaroslav@1890: * {@code park} method may also return at any other time, for "no jaroslav@1890: * reason", so in general must be invoked within a loop that rechecks jaroslav@1890: * conditions upon return. In this sense {@code park} serves as an jaroslav@1890: * optimization of a "busy wait" that does not waste as much time jaroslav@1890: * spinning, but must be paired with an {@code unpark} to be jaroslav@1890: * effective. jaroslav@1890: * jaroslav@1890: *
The three forms of {@code park} each also support a jaroslav@1890: * {@code blocker} object parameter. This object is recorded while jaroslav@1890: * the thread is blocked to permit monitoring and diagnostic tools to jaroslav@1890: * identify the reasons that threads are blocked. (Such tools may jaroslav@1890: * access blockers using method {@link #getBlocker}.) The use of these jaroslav@1890: * forms rather than the original forms without this parameter is jaroslav@1890: * strongly encouraged. The normal argument to supply as a jaroslav@1890: * {@code blocker} within a lock implementation is {@code this}. jaroslav@1890: * jaroslav@1890: *
These methods are designed to be used as tools for creating jaroslav@1890: * higher-level synchronization utilities, and are not in themselves jaroslav@1890: * useful for most concurrency control applications. The {@code park} jaroslav@1890: * method is designed for use only in constructions of the form: jaroslav@1890: *
while (!canProceed()) { ... LockSupport.park(this); }
jaroslav@1890: * where neither {@code canProceed} nor any other actions prior to the
jaroslav@1890: * call to {@code park} entail locking or blocking. Because only one
jaroslav@1890: * permit is associated with each thread, any intermediary uses of
jaroslav@1890: * {@code park} could interfere with its intended effects.
jaroslav@1890: *
jaroslav@1890: * Sample Usage. Here is a sketch of a first-in-first-out jaroslav@1890: * non-reentrant lock class: jaroslav@1890: *
{@code
jaroslav@1890: * class FIFOMutex {
jaroslav@1890: * private final AtomicBoolean locked = new AtomicBoolean(false);
jaroslav@1890: * private final Queue waiters
jaroslav@1890: * = new ConcurrentLinkedQueue();
jaroslav@1890: *
jaroslav@1890: * public void lock() {
jaroslav@1890: * boolean wasInterrupted = false;
jaroslav@1890: * Thread current = Thread.currentThread();
jaroslav@1890: * waiters.add(current);
jaroslav@1890: *
jaroslav@1890: * // Block while not first in queue or cannot acquire lock
jaroslav@1890: * while (waiters.peek() != current ||
jaroslav@1890: * !locked.compareAndSet(false, true)) {
jaroslav@1890: * LockSupport.park(this);
jaroslav@1890: * if (Thread.interrupted()) // ignore interrupts while waiting
jaroslav@1890: * wasInterrupted = true;
jaroslav@1890: * }
jaroslav@1890: *
jaroslav@1890: * waiters.remove();
jaroslav@1890: * if (wasInterrupted) // reassert interrupt status on exit
jaroslav@1890: * current.interrupt();
jaroslav@1890: * }
jaroslav@1890: *
jaroslav@1890: * public void unlock() {
jaroslav@1890: * locked.set(false);
jaroslav@1890: * LockSupport.unpark(waiters.peek());
jaroslav@1890: * }
jaroslav@1890: * }}
jaroslav@1890: */
jaroslav@1890:
jaroslav@1890: public class LockSupport {
jaroslav@1890: private LockSupport() {} // Cannot be instantiated.
jaroslav@1890:
jaroslav@1890: // Hotspot implementation via intrinsics API
jaroslav@1890: private static final Unsafe unsafe = Unsafe.getUnsafe();
jaroslav@1890: private static final long parkBlockerOffset;
jaroslav@1890:
jaroslav@1890: static {
jaroslav@1890: try {
jaroslav@1890: parkBlockerOffset = unsafe.objectFieldOffset
jaroslav@1890: (java.lang.Thread.class.getDeclaredField("parkBlocker"));
jaroslav@1890: } catch (Exception ex) { throw new Error(ex); }
jaroslav@1890: }
jaroslav@1890:
jaroslav@1890: private static void setBlocker(Thread t, Object arg) {
jaroslav@1890: // Even though volatile, hotspot doesn't need a write barrier here.
jaroslav@1890: unsafe.putObject(t, parkBlockerOffset, arg);
jaroslav@1890: }
jaroslav@1890:
jaroslav@1890: /**
jaroslav@1890: * Makes available the permit for the given thread, if it
jaroslav@1890: * was not already available. If the thread was blocked on
jaroslav@1890: * {@code park} then it will unblock. Otherwise, its next call
jaroslav@1890: * to {@code park} is guaranteed not to block. This operation
jaroslav@1890: * is not guaranteed to have any effect at all if the given
jaroslav@1890: * thread has not been started.
jaroslav@1890: *
jaroslav@1890: * @param thread the thread to unpark, or {@code null}, in which case
jaroslav@1890: * this operation has no effect
jaroslav@1890: */
jaroslav@1890: public static void unpark(Thread thread) {
jaroslav@1890: if (thread != null)
jaroslav@1890: unsafe.unpark(thread);
jaroslav@1890: }
jaroslav@1890:
jaroslav@1890: /**
jaroslav@1890: * Disables the current thread for thread scheduling purposes unless the
jaroslav@1890: * permit is available.
jaroslav@1890: *
jaroslav@1890: * If the permit is available then it is consumed and the call returns jaroslav@1890: * immediately; otherwise jaroslav@1890: * the current thread becomes disabled for thread scheduling jaroslav@1890: * purposes and lies dormant until one of three things happens: jaroslav@1890: * jaroslav@1890: *
This method does not report which of these caused the jaroslav@1890: * method to return. Callers should re-check the conditions which caused jaroslav@1890: * the thread to park in the first place. Callers may also determine, jaroslav@1890: * for example, the interrupt status of the thread upon return. jaroslav@1890: * jaroslav@1890: * @param blocker the synchronization object responsible for this jaroslav@1890: * thread parking jaroslav@1890: * @since 1.6 jaroslav@1890: */ jaroslav@1890: public static void park(Object blocker) { jaroslav@1890: Thread t = Thread.currentThread(); jaroslav@1890: setBlocker(t, blocker); jaroslav@1890: unsafe.park(false, 0L); jaroslav@1890: setBlocker(t, null); jaroslav@1890: } jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Disables the current thread for thread scheduling purposes, for up to jaroslav@1890: * the specified waiting time, unless the permit is available. jaroslav@1890: * jaroslav@1890: *
If the permit is available then it is consumed and the call jaroslav@1890: * returns immediately; otherwise the current thread becomes disabled jaroslav@1890: * for thread scheduling purposes and lies dormant until one of four jaroslav@1890: * things happens: jaroslav@1890: * jaroslav@1890: *
This method does not report which of these caused the jaroslav@1890: * method to return. Callers should re-check the conditions which caused jaroslav@1890: * the thread to park in the first place. Callers may also determine, jaroslav@1890: * for example, the interrupt status of the thread, or the elapsed time jaroslav@1890: * upon return. jaroslav@1890: * jaroslav@1890: * @param blocker the synchronization object responsible for this jaroslav@1890: * thread parking jaroslav@1890: * @param nanos the maximum number of nanoseconds to wait jaroslav@1890: * @since 1.6 jaroslav@1890: */ jaroslav@1890: public static void parkNanos(Object blocker, long nanos) { jaroslav@1890: if (nanos > 0) { jaroslav@1890: Thread t = Thread.currentThread(); jaroslav@1890: setBlocker(t, blocker); jaroslav@1890: unsafe.park(false, nanos); jaroslav@1890: setBlocker(t, null); jaroslav@1890: } jaroslav@1890: } jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Disables the current thread for thread scheduling purposes, until jaroslav@1890: * the specified deadline, unless the permit is available. jaroslav@1890: * jaroslav@1890: *
If the permit is available then it is consumed and the call jaroslav@1890: * returns immediately; otherwise the current thread becomes disabled jaroslav@1890: * for thread scheduling purposes and lies dormant until one of four jaroslav@1890: * things happens: jaroslav@1890: * jaroslav@1890: *
This method does not report which of these caused the jaroslav@1890: * method to return. Callers should re-check the conditions which caused jaroslav@1890: * the thread to park in the first place. Callers may also determine, jaroslav@1890: * for example, the interrupt status of the thread, or the current time jaroslav@1890: * upon return. jaroslav@1890: * jaroslav@1890: * @param blocker the synchronization object responsible for this jaroslav@1890: * thread parking jaroslav@1890: * @param deadline the absolute time, in milliseconds from the Epoch, jaroslav@1890: * to wait until jaroslav@1890: * @since 1.6 jaroslav@1890: */ jaroslav@1890: public static void parkUntil(Object blocker, long deadline) { jaroslav@1890: Thread t = Thread.currentThread(); jaroslav@1890: setBlocker(t, blocker); jaroslav@1890: unsafe.park(true, deadline); jaroslav@1890: setBlocker(t, null); jaroslav@1890: } jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Returns the blocker object supplied to the most recent jaroslav@1890: * invocation of a park method that has not yet unblocked, or null jaroslav@1890: * if not blocked. The value returned is just a momentary jaroslav@1890: * snapshot -- the thread may have since unblocked or blocked on a jaroslav@1890: * different blocker object. jaroslav@1890: * jaroslav@1890: * @param t the thread jaroslav@1890: * @return the blocker jaroslav@1890: * @throws NullPointerException if argument is null jaroslav@1890: * @since 1.6 jaroslav@1890: */ jaroslav@1890: public static Object getBlocker(Thread t) { jaroslav@1890: if (t == null) jaroslav@1890: throw new NullPointerException(); jaroslav@1890: return unsafe.getObjectVolatile(t, parkBlockerOffset); jaroslav@1890: } jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Disables the current thread for thread scheduling purposes unless the jaroslav@1890: * permit is available. jaroslav@1890: * jaroslav@1890: *
If the permit is available then it is consumed and the call jaroslav@1890: * returns immediately; otherwise the current thread becomes disabled jaroslav@1890: * for thread scheduling purposes and lies dormant until one of three jaroslav@1890: * things happens: jaroslav@1890: * jaroslav@1890: *
This method does not report which of these caused the jaroslav@1890: * method to return. Callers should re-check the conditions which caused jaroslav@1890: * the thread to park in the first place. Callers may also determine, jaroslav@1890: * for example, the interrupt status of the thread upon return. jaroslav@1890: */ jaroslav@1890: public static void park() { jaroslav@1890: unsafe.park(false, 0L); jaroslav@1890: } jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Disables the current thread for thread scheduling purposes, for up to jaroslav@1890: * the specified waiting time, unless the permit is available. jaroslav@1890: * jaroslav@1890: *
If the permit is available then it is consumed and the call jaroslav@1890: * returns immediately; otherwise the current thread becomes disabled jaroslav@1890: * for thread scheduling purposes and lies dormant until one of four jaroslav@1890: * things happens: jaroslav@1890: * jaroslav@1890: *
This method does not report which of these caused the jaroslav@1890: * method to return. Callers should re-check the conditions which caused jaroslav@1890: * the thread to park in the first place. Callers may also determine, jaroslav@1890: * for example, the interrupt status of the thread, or the elapsed time jaroslav@1890: * upon return. jaroslav@1890: * jaroslav@1890: * @param nanos the maximum number of nanoseconds to wait jaroslav@1890: */ jaroslav@1890: public static void parkNanos(long nanos) { jaroslav@1890: if (nanos > 0) jaroslav@1890: unsafe.park(false, nanos); jaroslav@1890: } jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * Disables the current thread for thread scheduling purposes, until jaroslav@1890: * the specified deadline, unless the permit is available. jaroslav@1890: * jaroslav@1890: *
If the permit is available then it is consumed and the call jaroslav@1890: * returns immediately; otherwise the current thread becomes disabled jaroslav@1890: * for thread scheduling purposes and lies dormant until one of four jaroslav@1890: * things happens: jaroslav@1890: * jaroslav@1890: *
This method does not report which of these caused the jaroslav@1890: * method to return. Callers should re-check the conditions which caused jaroslav@1890: * the thread to park in the first place. Callers may also determine, jaroslav@1890: * for example, the interrupt status of the thread, or the current time jaroslav@1890: * upon return. jaroslav@1890: * jaroslav@1890: * @param deadline the absolute time, in milliseconds from the Epoch, jaroslav@1890: * to wait until jaroslav@1890: */ jaroslav@1890: public static void parkUntil(long deadline) { jaroslav@1890: unsafe.park(true, deadline); jaroslav@1890: } jaroslav@1890: }