content: /*
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  /*
   * This file is available under and governed by the GNU General Public
   * License version 2 only, as published by the Free Software Foundation.
   * However, the following notice accompanied the original version of this
   * file:
   *
   * Written by Doug Lea with assistance from members of JCP JSR-166
   * Expert Group and released to the public domain, as explained at
   * http://creativecommons.org/publicdomain/zero/1.0/
   */
  
  package java.util.concurrent.locks;
  
  /**
   * Basic thread blocking primitives for creating locks and other
   * synchronization classes.
   *
   * <p>This class associates, with each thread that uses it, a permit
   * (in the sense of the {@link java.util.concurrent.Semaphore
   * Semaphore} class). A call to {@code park} will return immediately
   * if the permit is available, consuming it in the process; otherwise
   * it <em>may</em> block.  A call to {@code unpark} makes the permit
   * available, if it was not already available. (Unlike with Semaphores
   * though, permits do not accumulate. There is at most one.)
   * Reliable usage requires the use of volatile (or atomic) variables
   * to control when to park or unpark.  Orderings of calls to these
   * methods are maintained with respect to volatile variable accesses,
   * but not necessarily non-volatile variable accesses.
   *
   * <p>Methods {@code park} and {@code unpark} provide efficient
   * means of blocking and unblocking threads that do not encounter the
   * problems that cause the deprecated methods {@code Thread.suspend}
   * and {@code Thread.resume} to be unusable for such purposes: Races
   * between one thread invoking {@code park} and another thread trying
   * to {@code unpark} it will preserve liveness, due to the
   * permit. Additionally, {@code park} will return if the caller's
   * thread was interrupted, and timeout versions are supported. The
   * {@code park} method may also return at any other time, for "no
   * reason", so in general must be invoked within a loop that rechecks
   * conditions upon return. In this sense {@code park} serves as an
   * optimization of a "busy wait" that does not waste as much time
   * spinning, but must be paired with an {@code unpark} to be
   * effective.
   *
   * <p>The three forms of {@code park} each also support a
   * {@code blocker} object parameter. This object is recorded while
   * the thread is blocked to permit monitoring and diagnostic tools to
   * identify the reasons that threads are blocked. (Such tools may
   * access blockers using method {@link #getBlocker(Thread)}.)
   * The use of these forms rather than the original forms without this
   * parameter is strongly encouraged. The normal argument to supply as
   * a {@code blocker} within a lock implementation is {@code this}.
   *
   * <p>These methods are designed to be used as tools for creating
   * higher-level synchronization utilities, and are not in themselves
   * useful for most concurrency control applications.  The {@code park}
   * method is designed for use only in constructions of the form:
   *
   * <pre> {@code
   * while (!canProceed()) {
   *   // ensure request to unpark is visible to other threads
   *   ...
   *   LockSupport.park(this);
   * }}</pre>
   *
   * where no actions by the thread publishing a request to unpark,
   * prior to the call to {@code park}, entail locking or blocking.
   * Because only one permit is associated with each thread, any
   * intermediary uses of {@code park}, including implicitly via class
   * loading, could lead to an unresponsive thread (a "lost unpark").
   *
   * <p><b>Sample Usage.</b> Here is a sketch of a first-in-first-out
   * non-reentrant lock class:
   * <pre> {@code
   * class FIFOMutex {
   *   private final AtomicBoolean locked = new AtomicBoolean(false);
   *   private final Queue<Thread> waiters
   *     = new ConcurrentLinkedQueue<>();
   *
   *   public void lock() {
   *     boolean wasInterrupted = false;
   *     // publish current thread for unparkers
   *     waiters.add(Thread.currentThread());
   *
   *     // Block while not first in queue or cannot acquire lock
   *     while (waiters.peek() != Thread.currentThread() ||
   *            !locked.compareAndSet(false, true)) {
   *       LockSupport.park(this);
   *       // ignore interrupts while waiting
   *       if (Thread.interrupted())
   *         wasInterrupted = true;
   *     }
   *
   *     waiters.remove();
   *     // ensure correct interrupt status on return
   *     if (wasInterrupted)
   *       Thread.currentThread().interrupt();
   *   }
   *
   *   public void unlock() {
   *     locked.set(false);
   *     LockSupport.unpark(waiters.peek());
   *   }
   *
   *   static {
   *     // Reduce the risk of "lost unpark" due to classloading
   *     Class<?> ensureLoaded = LockSupport.class;
   *   }
   * }}</pre>
   */
  public class LockSupport {
      private LockSupport() {} // Cannot be instantiated.
  
      private static void setBlocker(Thread t, Object arg) {
          // Even though volatile, hotspot doesn't need a write barrier here.
          U.putObject(t, PARKBLOCKER, arg);
      }
  
      /**
       * Makes available the permit for the given thread, if it
       * was not already available.  If the thread was blocked on
       * {@code park} then it will unblock.  Otherwise, its next call
       * to {@code park} is guaranteed not to block. This operation
       * is not guaranteed to have any effect at all if the given
       * thread has not been started.
       *
       * @param thread the thread to unpark, or {@code null}, in which case
       *        this operation has no effect
       */
      public static void unpark(Thread thread) {
          if (thread != null)
              U.unpark(thread);
      }
  
      /**
       * Disables the current thread for thread scheduling purposes unless the
       * permit is available.
       *
       * <p>If the permit is available then it is consumed and the call returns
       * immediately; otherwise
       * the current thread becomes disabled for thread scheduling
       * purposes and lies dormant until one of three things happens:
       *
       * <ul>
       * <li>Some other thread invokes {@link #unpark unpark} with the
       * current thread as the target; or
       *
       * <li>Some other thread {@linkplain Thread#interrupt interrupts}
       * the current thread; or
       *
       * <li>The call spuriously (that is, for no reason) returns.
       * </ul>
       *
       * <p>This method does <em>not</em> report which of these caused the
       * method to return. Callers should re-check the conditions which caused
       * the thread to park in the first place. Callers may also determine,
       * for example, the interrupt status of the thread upon return.
       *
       * @param blocker the synchronization object responsible for this
       *        thread parking
       * @since 1.6
       */
      public static void park(Object blocker) {
          Thread t = Thread.currentThread();
          setBlocker(t, blocker);
          U.park(false, 0L);
          setBlocker(t, null);
      }
  
      /**
       * Disables the current thread for thread scheduling purposes, for up to
       * the specified waiting time, unless the permit is available.
       *
       * <p>If the permit is available then it is consumed and the call
       * returns immediately; otherwise the current thread becomes disabled
       * for thread scheduling purposes and lies dormant until one of four
       * things happens:
       *
       * <ul>
       * <li>Some other thread invokes {@link #unpark unpark} with the
       * current thread as the target; or
       *
       * <li>Some other thread {@linkplain Thread#interrupt interrupts}
       * the current thread; or
       *
       * <li>The specified waiting time elapses; or
       *
       * <li>The call spuriously (that is, for no reason) returns.
       * </ul>
       *
       * <p>This method does <em>not</em> report which of these caused the
       * method to return. Callers should re-check the conditions which caused
       * the thread to park in the first place. Callers may also determine,
       * for example, the interrupt status of the thread, or the elapsed time
       * upon return.
       *
       * @param blocker the synchronization object responsible for this
       *        thread parking
       * @param nanos the maximum number of nanoseconds to wait
       * @since 1.6
       */
      public static void parkNanos(Object blocker, long nanos) {
          if (nanos > 0) {
              Thread t = Thread.currentThread();
              setBlocker(t, blocker);
              U.park(false, nanos);
              setBlocker(t, null);
          }
      }
  
      /**
       * Disables the current thread for thread scheduling purposes, until
       * the specified deadline, unless the permit is available.
       *
       * <p>If the permit is available then it is consumed and the call
       * returns immediately; otherwise the current thread becomes disabled
       * for thread scheduling purposes and lies dormant until one of four
       * things happens:
       *
       * <ul>
       * <li>Some other thread invokes {@link #unpark unpark} with the
       * current thread as the target; or
       *
       * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
       * current thread; or
       *
       * <li>The specified deadline passes; or
       *
       * <li>The call spuriously (that is, for no reason) returns.
       * </ul>
       *
       * <p>This method does <em>not</em> report which of these caused the
       * method to return. Callers should re-check the conditions which caused
       * the thread to park in the first place. Callers may also determine,
       * for example, the interrupt status of the thread, or the current time
       * upon return.
       *
       * @param blocker the synchronization object responsible for this
       *        thread parking
       * @param deadline the absolute time, in milliseconds from the Epoch,
       *        to wait until
       * @since 1.6
       */
      public static void parkUntil(Object blocker, long deadline) {
          Thread t = Thread.currentThread();
          setBlocker(t, blocker);
          U.park(true, deadline);
          setBlocker(t, null);
      }
  
      /**
       * Returns the blocker object supplied to the most recent
       * invocation of a park method that has not yet unblocked, or null
       * if not blocked.  The value returned is just a momentary
       * snapshot -- the thread may have since unblocked or blocked on a
       * different blocker object.
       *
       * @param t the thread
       * @return the blocker
       * @throws NullPointerException if argument is null
       * @since 1.6
       */
      public static Object getBlocker(Thread t) {
          if (t == null)
              throw new NullPointerException();
          return U.getObjectVolatile(t, PARKBLOCKER);
      }
  
      /**
       * Disables the current thread for thread scheduling purposes unless the
       * permit is available.
       *
       * <p>If the permit is available then it is consumed and the call
       * returns immediately; otherwise the current thread becomes disabled
       * for thread scheduling purposes and lies dormant until one of three
       * things happens:
       *
       * <ul>
       *
       * <li>Some other thread invokes {@link #unpark unpark} with the
       * current thread as the target; or
       *
       * <li>Some other thread {@linkplain Thread#interrupt interrupts}
       * the current thread; or
       *
       * <li>The call spuriously (that is, for no reason) returns.
       * </ul>
       *
       * <p>This method does <em>not</em> report which of these caused the
       * method to return. Callers should re-check the conditions which caused
       * the thread to park in the first place. Callers may also determine,
       * for example, the interrupt status of the thread upon return.
       */
      public static void park() {
          U.park(false, 0L);
      }
  
      /**
       * Disables the current thread for thread scheduling purposes, for up to
       * the specified waiting time, unless the permit is available.
       *
       * <p>If the permit is available then it is consumed and the call
       * returns immediately; otherwise the current thread becomes disabled
       * for thread scheduling purposes and lies dormant until one of four
       * things happens:
       *
       * <ul>
       * <li>Some other thread invokes {@link #unpark unpark} with the
       * current thread as the target; or
       *
       * <li>Some other thread {@linkplain Thread#interrupt interrupts}
       * the current thread; or
       *
       * <li>The specified waiting time elapses; or
       *
       * <li>The call spuriously (that is, for no reason) returns.
       * </ul>
       *
       * <p>This method does <em>not</em> report which of these caused the
       * method to return. Callers should re-check the conditions which caused
       * the thread to park in the first place. Callers may also determine,
       * for example, the interrupt status of the thread, or the elapsed time
       * upon return.
       *
       * @param nanos the maximum number of nanoseconds to wait
       */
      public static void parkNanos(long nanos) {
          if (nanos > 0)
              U.park(false, nanos);
      }
  
      /**
       * Disables the current thread for thread scheduling purposes, until
       * the specified deadline, unless the permit is available.
       *
       * <p>If the permit is available then it is consumed and the call
       * returns immediately; otherwise the current thread becomes disabled
       * for thread scheduling purposes and lies dormant until one of four
       * things happens:
       *
       * <ul>
       * <li>Some other thread invokes {@link #unpark unpark} with the
       * current thread as the target; or
       *
       * <li>Some other thread {@linkplain Thread#interrupt interrupts}
       * the current thread; or
       *
       * <li>The specified deadline passes; or
       *
       * <li>The call spuriously (that is, for no reason) returns.
       * </ul>
       *
       * <p>This method does <em>not</em> report which of these caused the
       * method to return. Callers should re-check the conditions which caused
       * the thread to park in the first place. Callers may also determine,
       * for example, the interrupt status of the thread, or the current time
       * upon return.
       *
       * @param deadline the absolute time, in milliseconds from the Epoch,
       *        to wait until
       */
      public static void parkUntil(long deadline) {
          U.park(true, deadline);
      }
  
      /**
       * Returns the pseudo-randomly initialized or updated secondary seed.
       * Copied from ThreadLocalRandom due to package access restrictions.
       */
      static final int nextSecondarySeed() {
          int r;
          Thread t = Thread.currentThread();
          if ((r = U.getInt(t, SECONDARY)) != 0) {
              r ^= r << 13;   // xorshift
              r ^= r >>> 17;
              r ^= r << 5;
          }
          else if ((r = java.util.concurrent.ThreadLocalRandom.current().nextInt()) == 0)
              r = 1; // avoid zero
          U.putInt(t, SECONDARY, r);
          return r;
      }
  
      // Hotspot implementation via intrinsics API
      private static final sun.misc.Unsafe U = sun.misc.Unsafe.getUnsafe();
      private static final long PARKBLOCKER;
      private static final long SECONDARY;
      static {
          try {
              PARKBLOCKER = U.objectFieldOffset
                  (Thread.class.getDeclaredField("parkBlocker"));
              SECONDARY = U.objectFieldOffset
                  (Thread.class.getDeclaredField("threadLocalRandomSecondarySeed"));
          } catch (ReflectiveOperationException e) {
              throw new Error(e);
          }
      }
  
  }
  