1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3  *
   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.
   9  *
  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).
  15  *
  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.
  19  *
  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
  22  * questions.
  23  */
  24 
  25 /*
  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
  29  * file:
  30  *
  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/licenses/publicdomain
  34  */
  35 
  36 package java.util.concurrent.locks;
  37 import java.util.concurrent.*;
  38 import sun.misc.Unsafe;
  39 
  40 
  41 /**
  42  * Basic thread blocking primitives for creating locks and other
  43  * synchronization classes.
  44  *
  45  * <p>This class associates, with each thread that uses it, a permit
  46  * (in the sense of the {@link java.util.concurrent.Semaphore
  47  * Semaphore} class). A call to {@code park} will return immediately
  48  * if the permit is available, consuming it in the process; otherwise
  49  * it <em>may</em> block.  A call to {@code unpark} makes the permit
  50  * available, if it was not already available. (Unlike with Semaphores
  51  * though, permits do not accumulate. There is at most one.)
  52  *
  53  * <p>Methods {@code park} and {@code unpark} provide efficient
  54  * means of blocking and unblocking threads that do not encounter the
  55  * problems that cause the deprecated methods {@code Thread.suspend}
  56  * and {@code Thread.resume} to be unusable for such purposes: Races
  57  * between one thread invoking {@code park} and another thread trying
  58  * to {@code unpark} it will preserve liveness, due to the
  59  * permit. Additionally, {@code park} will return if the caller's
  60  * thread was interrupted, and timeout versions are supported. The
  61  * {@code park} method may also return at any other time, for "no
  62  * reason", so in general must be invoked within a loop that rechecks
  63  * conditions upon return. In this sense {@code park} serves as an
  64  * optimization of a "busy wait" that does not waste as much time
  65  * spinning, but must be paired with an {@code unpark} to be
  66  * effective.
  67  *
  68  * <p>The three forms of {@code park} each also support a
  69  * {@code blocker} object parameter. This object is recorded while
  70  * the thread is blocked to permit monitoring and diagnostic tools to
  71  * identify the reasons that threads are blocked. (Such tools may
  72  * access blockers using method {@link #getBlocker}.) The use of these
  73  * forms rather than the original forms without this parameter is
  74  * strongly encouraged. The normal argument to supply as a
  75  * {@code blocker} within a lock implementation is {@code this}.
  76  *
  77  * <p>These methods are designed to be used as tools for creating
  78  * higher-level synchronization utilities, and are not in themselves
  79  * useful for most concurrency control applications.  The {@code park}
  80  * method is designed for use only in constructions of the form:
  81  * <pre>while (!canProceed()) { ... LockSupport.park(this); }</pre>
  82  * where neither {@code canProceed} nor any other actions prior to the
  83  * call to {@code park} entail locking or blocking.  Because only one
  84  * permit is associated with each thread, any intermediary uses of
  85  * {@code park} could interfere with its intended effects.
  86  *
  87  * <p><b>Sample Usage.</b> Here is a sketch of a first-in-first-out
  88  * non-reentrant lock class:
  89  * <pre>{@code
  90  * class FIFOMutex {
  91  *   private final AtomicBoolean locked = new AtomicBoolean(false);
  92  *   private final Queue<Thread> waiters
  93  *     = new ConcurrentLinkedQueue<Thread>();
  94  *
  95  *   public void lock() {
  96  *     boolean wasInterrupted = false;
  97  *     Thread current = Thread.currentThread();
  98  *     waiters.add(current);
  99  *
 100  *     // Block while not first in queue or cannot acquire lock
 101  *     while (waiters.peek() != current ||
 102  *            !locked.compareAndSet(false, true)) {
 103  *        LockSupport.park(this);
 104  *        if (Thread.interrupted()) // ignore interrupts while waiting
 105  *          wasInterrupted = true;
 106  *     }
 107  *
 108  *     waiters.remove();
 109  *     if (wasInterrupted)          // reassert interrupt status on exit
 110  *        current.interrupt();
 111  *   }
 112  *
 113  *   public void unlock() {
 114  *     locked.set(false);
 115  *     LockSupport.unpark(waiters.peek());
 116  *   }
 117  * }}</pre>
 118  */
 119 
 120 public class LockSupport {
 121     private LockSupport() {} // Cannot be instantiated.
 122 
 123     // Hotspot implementation via intrinsics API
 124     private static final Unsafe unsafe = Unsafe.getUnsafe();
 125     private static final long parkBlockerOffset;
 126 
 127     static {
 128         try {
 129             parkBlockerOffset = unsafe.objectFieldOffset
 130                 (java.lang.Thread.class.getDeclaredField("parkBlocker"));
 131         } catch (Exception ex) { throw new Error(ex); }
 132     }
 133 
 134     private static void setBlocker(Thread t, Object arg) {
 135         // Even though volatile, hotspot doesn't need a write barrier here.
 136         unsafe.putObject(t, parkBlockerOffset, arg);
 137     }
 138 
 139     /**
 140      * Makes available the permit for the given thread, if it
 141      * was not already available.  If the thread was blocked on
 142      * {@code park} then it will unblock.  Otherwise, its next call
 143      * to {@code park} is guaranteed not to block. This operation
 144      * is not guaranteed to have any effect at all if the given
 145      * thread has not been started.
 146      *
 147      * @param thread the thread to unpark, or {@code null}, in which case
 148      *        this operation has no effect
 149      */
 150     public static void unpark(Thread thread) {
 151         if (thread != null)
 152             unsafe.unpark(thread);
 153     }
 154 
 155     /**
 156      * Disables the current thread for thread scheduling purposes unless the
 157      * permit is available.
 158      *
 159      * <p>If the permit is available then it is consumed and the call returns
 160      * immediately; otherwise
 161      * the current thread becomes disabled for thread scheduling
 162      * purposes and lies dormant until one of three things happens:
 163      *
 164      * <ul>
 165      * <li>Some other thread invokes {@link #unpark unpark} with the
 166      * current thread as the target; or
 167      *
 168      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
 169      * the current thread; or
 170      *
 171      * <li>The call spuriously (that is, for no reason) returns.
 172      * </ul>
 173      *
 174      * <p>This method does <em>not</em> report which of these caused the
 175      * method to return. Callers should re-check the conditions which caused
 176      * the thread to park in the first place. Callers may also determine,
 177      * for example, the interrupt status of the thread upon return.
 178      *
 179      * @param blocker the synchronization object responsible for this
 180      *        thread parking
 181      * @since 1.6
 182      */
 183     public static void park(Object blocker) {
 184         Thread t = Thread.currentThread();
 185         setBlocker(t, blocker);
 186         unsafe.park(false, 0L);
 187         setBlocker(t, null);
 188     }
 189 
 190     /**
 191      * Disables the current thread for thread scheduling purposes, for up to
 192      * the specified waiting time, unless the permit is available.
 193      *
 194      * <p>If the permit is available then it is consumed and the call
 195      * returns immediately; otherwise the current thread becomes disabled
 196      * for thread scheduling purposes and lies dormant until one of four
 197      * things happens:
 198      *
 199      * <ul>
 200      * <li>Some other thread invokes {@link #unpark unpark} with the
 201      * current thread as the target; or
 202      *
 203      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
 204      * the current thread; or
 205      *
 206      * <li>The specified waiting time elapses; or
 207      *
 208      * <li>The call spuriously (that is, for no reason) returns.
 209      * </ul>
 210      *
 211      * <p>This method does <em>not</em> report which of these caused the
 212      * method to return. Callers should re-check the conditions which caused
 213      * the thread to park in the first place. Callers may also determine,
 214      * for example, the interrupt status of the thread, or the elapsed time
 215      * upon return.
 216      *
 217      * @param blocker the synchronization object responsible for this
 218      *        thread parking
 219      * @param nanos the maximum number of nanoseconds to wait
 220      * @since 1.6
 221      */
 222     public static void parkNanos(Object blocker, long nanos) {
 223         if (nanos > 0) {
 224             Thread t = Thread.currentThread();
 225             setBlocker(t, blocker);
 226             unsafe.park(false, nanos);
 227             setBlocker(t, null);
 228         }
 229     }
 230 
 231     /**
 232      * Disables the current thread for thread scheduling purposes, until
 233      * the specified deadline, unless the permit is available.
 234      *
 235      * <p>If the permit is available then it is consumed and the call
 236      * returns immediately; otherwise the current thread becomes disabled
 237      * for thread scheduling purposes and lies dormant until one of four
 238      * things happens:
 239      *
 240      * <ul>
 241      * <li>Some other thread invokes {@link #unpark unpark} with the
 242      * current thread as the target; or
 243      *
 244      * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
 245      * current thread; or
 246      *
 247      * <li>The specified deadline passes; or
 248      *
 249      * <li>The call spuriously (that is, for no reason) returns.
 250      * </ul>
 251      *
 252      * <p>This method does <em>not</em> report which of these caused the
 253      * method to return. Callers should re-check the conditions which caused
 254      * the thread to park in the first place. Callers may also determine,
 255      * for example, the interrupt status of the thread, or the current time
 256      * upon return.
 257      *
 258      * @param blocker the synchronization object responsible for this
 259      *        thread parking
 260      * @param deadline the absolute time, in milliseconds from the Epoch,
 261      *        to wait until
 262      * @since 1.6
 263      */
 264     public static void parkUntil(Object blocker, long deadline) {
 265         Thread t = Thread.currentThread();
 266         setBlocker(t, blocker);
 267         unsafe.park(true, deadline);
 268         setBlocker(t, null);
 269     }
 270 
 271     /**
 272      * Returns the blocker object supplied to the most recent
 273      * invocation of a park method that has not yet unblocked, or null
 274      * if not blocked.  The value returned is just a momentary
 275      * snapshot -- the thread may have since unblocked or blocked on a
 276      * different blocker object.
 277      *
 278      * @return the blocker
 279      * @since 1.6
 280      */
 281     public static Object getBlocker(Thread t) {
 282         return unsafe.getObjectVolatile(t, parkBlockerOffset);
 283     }
 284 
 285     /**
 286      * Disables the current thread for thread scheduling purposes unless the
 287      * permit is available.
 288      *
 289      * <p>If the permit is available then it is consumed and the call
 290      * returns immediately; otherwise the current thread becomes disabled
 291      * for thread scheduling purposes and lies dormant until one of three
 292      * things happens:
 293      *
 294      * <ul>
 295      *
 296      * <li>Some other thread invokes {@link #unpark unpark} with the
 297      * current thread as the target; or
 298      *
 299      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
 300      * the current thread; or
 301      *
 302      * <li>The call spuriously (that is, for no reason) returns.
 303      * </ul>
 304      *
 305      * <p>This method does <em>not</em> report which of these caused the
 306      * method to return. Callers should re-check the conditions which caused
 307      * the thread to park in the first place. Callers may also determine,
 308      * for example, the interrupt status of the thread upon return.
 309      */
 310     public static void park() {
 311         unsafe.park(false, 0L);
 312     }
 313 
 314     /**
 315      * Disables the current thread for thread scheduling purposes, for up to
 316      * the specified waiting time, unless the permit is available.
 317      *
 318      * <p>If the permit is available then it is consumed and the call
 319      * returns immediately; otherwise the current thread becomes disabled
 320      * for thread scheduling purposes and lies dormant until one of four
 321      * things happens:
 322      *
 323      * <ul>
 324      * <li>Some other thread invokes {@link #unpark unpark} with the
 325      * current thread as the target; or
 326      *
 327      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
 328      * the current thread; or
 329      *
 330      * <li>The specified waiting time elapses; or
 331      *
 332      * <li>The call spuriously (that is, for no reason) returns.
 333      * </ul>
 334      *
 335      * <p>This method does <em>not</em> report which of these caused the
 336      * method to return. Callers should re-check the conditions which caused
 337      * the thread to park in the first place. Callers may also determine,
 338      * for example, the interrupt status of the thread, or the elapsed time
 339      * upon return.
 340      *
 341      * @param nanos the maximum number of nanoseconds to wait
 342      */
 343     public static void parkNanos(long nanos) {
 344         if (nanos > 0)
 345             unsafe.park(false, nanos);
 346     }
 347 
 348     /**
 349      * Disables the current thread for thread scheduling purposes, until
 350      * the specified deadline, unless the permit is available.
 351      *
 352      * <p>If the permit is available then it is consumed and the call
 353      * returns immediately; otherwise the current thread becomes disabled
 354      * for thread scheduling purposes and lies dormant until one of four
 355      * things happens:
 356      *
 357      * <ul>
 358      * <li>Some other thread invokes {@link #unpark unpark} with the
 359      * current thread as the target; or
 360      *
 361      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
 362      * the current thread; or
 363      *
 364      * <li>The specified deadline passes; or
 365      *
 366      * <li>The call spuriously (that is, for no reason) returns.
 367      * </ul>
 368      *
 369      * <p>This method does <em>not</em> report which of these caused the
 370      * method to return. Callers should re-check the conditions which caused
 371      * the thread to park in the first place. Callers may also determine,
 372      * for example, the interrupt status of the thread, or the current time
 373      * upon return.
 374      *
 375      * @param deadline the absolute time, in milliseconds from the Epoch,
 376      *        to wait until
 377      */
 378     public static void parkUntil(long deadline) {
 379         unsafe.park(true, deadline);
 380     }
 381 }