/*

 * 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;

import jdk.internal.misc.Unsafe;

/**

 * 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>

 *

 * @since 1.5

 */

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;

    }

    /**

     * Returns the thread id for the given thread.  We must access

     * this directly rather than via method Thread.getId() because

     */

    static final long getThreadId(Thread thread) {

    }

    // Hotspot implementation via intrinsics API

    private static final Unsafe U = Unsafe.getUnsafe();

    private static final long PARKBLOCKER = U.objectFieldOffset

            (Thread.class, "parkBlocker");

    private static final long SECONDARY = U.objectFieldOffset

            (Thread.class, "threadLocalRandomSecondarySeed");

    private static final long TID = U.objectFieldOffset

            (Thread.class, "tid");

}