/*

 * Copyright (c) 1994, 2018, Oracle and/or its affiliates. All rights reserved.

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

 */

package java.lang;

import java.lang.ref.Reference;

import java.lang.ref.ReferenceQueue;

import java.lang.ref.WeakReference;

import java.security.AccessController;

import java.security.AccessControlContext;

import java.security.PrivilegedAction;

import java.util.Map;

import java.util.HashMap;

import java.util.concurrent.ConcurrentHashMap;

import java.util.concurrent.ConcurrentMap;

import java.util.concurrent.locks.LockSupport;

import sun.nio.ch.Interruptible;

import jdk.internal.reflect.CallerSensitive;

import jdk.internal.reflect.Reflection;

import sun.security.util.SecurityConstants;

import jdk.internal.HotSpotIntrinsicCandidate;

/**

 * A <i>thread</i> is a thread of execution in a program. The Java

 * Virtual Machine allows an application to have multiple threads of

 * execution running concurrently.

 * <p>

 * Every thread has a priority. Threads with higher priority are

 * executed in preference to threads with lower priority. Each thread

 * may or may not also be marked as a daemon. When code running in

 * some thread creates a new {@code Thread} object, the new

 * thread has its priority initially set equal to the priority of the

 * creating thread, and is a daemon thread if and only if the

 * creating thread is a daemon.

 * <p>

 * When a Java Virtual Machine starts up, there is usually a single

 * non-daemon thread (which typically calls the method named

 * {@code main} of some designated class). The Java Virtual

 * Machine continues to execute threads until either of the following

 * occurs:

 * <ul>

 * <li>The {@code exit} method of class {@code Runtime} has been

 *     called and the security manager has permitted the exit operation

 *     to take place.

 * <li>All threads that are not daemon threads have died, either by

 *     returning from the call to the {@code run} method or by

 *     throwing an exception that propagates beyond the {@code run}

 *     method.

 * </ul>

 * <p>

 * There are two ways to create a new thread of execution. One is to

 * declare a class to be a subclass of {@code Thread}. This

 * subclass should override the {@code run} method of class

 * {@code Thread}. An instance of the subclass can then be

 * allocated and started. For example, a thread that computes primes

 * larger than a stated value could be written as follows:

 * <hr><blockquote><pre>

 *     class PrimeThread extends Thread {

 *         long minPrime;

 *         PrimeThread(long minPrime) {

 *             this.minPrime = minPrime;

 *         }

 *

 *         public void run() {

 *             // compute primes larger than minPrime

 *              . . .

 *         }

 *     }

 * </pre></blockquote><hr>

 * <p>

 * The following code would then create a thread and start it running:

 * <blockquote><pre>

 *     PrimeThread p = new PrimeThread(143);

 *     p.start();

 * </pre></blockquote>

 * <p>

 * The other way to create a thread is to declare a class that

 * implements the {@code Runnable} interface. That class then

 * implements the {@code run} method. An instance of the class can

 * then be allocated, passed as an argument when creating

 * {@code Thread}, and started. The same example in this other

 * style looks like the following:

 * <hr><blockquote><pre>

 *     class PrimeRun implements Runnable {

 *         long minPrime;

 *         PrimeRun(long minPrime) {

 *             this.minPrime = minPrime;

 *         }

 *

 *         public void run() {

 *             // compute primes larger than minPrime

 *              . . .

 *         }

 *     }

 * </pre></blockquote><hr>

 * <p>

 * The following code would then create a thread and start it running:

 * <blockquote><pre>

 *     PrimeRun p = new PrimeRun(143);

 *     new Thread(p).start();

 * </pre></blockquote>

 * <p>

 * Every thread has a name for identification purposes. More than

 * one thread may have the same name. If a name is not specified when

 * a thread is created, a new name is generated for it.

 * <p>

 * Unless otherwise noted, passing a {@code null} argument to a constructor

 * or method in this class will cause a {@link NullPointerException} to be

 * thrown.

 *

 * @author  unascribed

 * @see     Runnable

 * @see     Runtime#exit(int)

 * @see     #run()

 * @see     #stop()

 * @since   1.0

 */

public

class Thread implements Runnable {

    /* Make sure registerNatives is the first thing <clinit> does. */

    private static native void registerNatives();

    static {

        registerNatives();

    }

    private volatile String name;

    private int priority;

    /* Whether or not the thread is a daemon thread. */

    private boolean daemon = false;

    /* Fields reserved for exclusive use by the JVM */

    private boolean stillborn = false;

    private long eetop;

    /* What will be run. */

    private Runnable target;

    /* The group of this thread */

    private ThreadGroup group;

    /* The context ClassLoader for this thread */

    private ClassLoader contextClassLoader;

    /* The inherited AccessControlContext of this thread */

    private AccessControlContext inheritedAccessControlContext;

    /* For autonumbering anonymous threads. */

    private static int threadInitNumber;

    private static synchronized int nextThreadNum() {

        return threadInitNumber++;

    }

    /* ThreadLocal values pertaining to this thread. This map is maintained

     * by the ThreadLocal class. */

    ThreadLocal.ThreadLocalMap threadLocals = null;

    /*

     * InheritableThreadLocal values pertaining to this thread. This map is

     * maintained by the InheritableThreadLocal class.

     */

    ThreadLocal.ThreadLocalMap inheritableThreadLocals = null;

    /*

     * The requested stack size for this thread, or 0 if the creator did

     * not specify a stack size.  It is up to the VM to do whatever it

     * likes with this number; some VMs will ignore it.

     */

    /*

     * JVM-private state that persists after native thread termination.

     */

    private long nativeParkEventPointer;

    /*

     * Thread ID

     */

    /* For generating thread ID */

    private static long threadSeqNumber;

    /*

     * Java thread status for tools, default indicates thread 'not yet started'

     */

    private volatile int threadStatus;

    /**

     * The argument supplied to the current call to

     * java.util.concurrent.locks.LockSupport.park.

     * Set by (private) java.util.concurrent.locks.LockSupport.setBlocker

     * Accessed using java.util.concurrent.locks.LockSupport.getBlocker

     */

    volatile Object parkBlocker;

    /* The object in which this thread is blocked in an interruptible I/O

     * operation, if any.  The blocker's interrupt method should be invoked

     * after setting this thread's interrupt status.

     */

    private volatile Interruptible blocker;

    private final Object blockerLock = new Object();

    /* Set the blocker field; invoked via jdk.internal.misc.SharedSecrets

     * from java.nio code

     */

    static void blockedOn(Interruptible b) {

        Thread me = Thread.currentThread();

        synchronized (me.blockerLock) {

            me.blocker = b;

        }

    }

    /**

     * The minimum priority that a thread can have.

     */

    public static final int MIN_PRIORITY = 1;

   /**

     * The default priority that is assigned to a thread.

     */

    public static final int NORM_PRIORITY = 5;

    /**

     * The maximum priority that a thread can have.

     */

    public static final int MAX_PRIORITY = 10;

    /**

     * Returns a reference to the currently executing thread object.

     *

     * @return  the currently executing thread.

     */

    @HotSpotIntrinsicCandidate

    public static native Thread currentThread();

    /**

     * A hint to the scheduler that the current thread is willing to yield

     * its current use of a processor. The scheduler is free to ignore this

     * hint.

     *

     * <p> Yield is a heuristic attempt to improve relative progression

     * between threads that would otherwise over-utilise a CPU. Its use

     * should be combined with detailed profiling and benchmarking to

     * ensure that it actually has the desired effect.

     *

     * <p> It is rarely appropriate to use this method. It may be useful

     * for debugging or testing purposes, where it may help to reproduce

     * bugs due to race conditions. It may also be useful when designing

     * concurrency control constructs such as the ones in the

     * {@link java.util.concurrent.locks} package.

     */

    public static native void yield();

    /**

     * Causes the currently executing thread to sleep (temporarily cease

     * execution) for the specified number of milliseconds, subject to

     * the precision and accuracy of system timers and schedulers. The thread

     * does not lose ownership of any monitors.

     *

     * @param  millis

     *         the length of time to sleep in milliseconds

     *

     * @throws  IllegalArgumentException

     *          if the value of {@code millis} is negative

     *

     * @throws  InterruptedException

     *          if any thread has interrupted the current thread. The

     *          <i>interrupted status</i> of the current thread is

     *          cleared when this exception is thrown.

     */

    public static native void sleep(long millis) throws InterruptedException;

    /**

     * Causes the currently executing thread to sleep (temporarily cease

     * execution) for the specified number of milliseconds plus the specified

     * number of nanoseconds, subject to the precision and accuracy of system

     * timers and schedulers. The thread does not lose ownership of any

     * monitors.

     *

     * @param  millis

     *         the length of time to sleep in milliseconds

     *

     * @param  nanos

     *         {@code 0-999999} additional nanoseconds to sleep

     *

     * @throws  IllegalArgumentException

     *          if the value of {@code millis} is negative, or the value of

     *          {@code nanos} is not in the range {@code 0-999999}

     *

     * @throws  InterruptedException

     *          if any thread has interrupted the current thread. The

     *          <i>interrupted status</i> of the current thread is

     *          cleared when this exception is thrown.

     */

    public static void sleep(long millis, int nanos)

    throws InterruptedException {

        if (millis < 0) {

            throw new IllegalArgumentException("timeout value is negative");

        }

        if (nanos < 0 || nanos > 999999) {

            throw new IllegalArgumentException(

                                "nanosecond timeout value out of range");

        }

        if (nanos >= 500000 || (nanos != 0 && millis == 0)) {

            millis++;

        }

        sleep(millis);

    }

    /**

     * Indicates that the caller is momentarily unable to progress, until the

     * occurrence of one or more actions on the part of other activities. By

     * invoking this method within each iteration of a spin-wait loop construct,

     * the calling thread indicates to the runtime that it is busy-waiting.

     * The runtime may take action to improve the performance of invoking

     * spin-wait loop constructions.

     *

     * @apiNote

     * As an example consider a method in a class that spins in a loop until

     * some flag is set outside of that method. A call to the {@code onSpinWait}

     * method should be placed inside the spin loop.

     * <pre>{@code

     *     class EventHandler {

     *         volatile boolean eventNotificationNotReceived;

     *         void waitForEventAndHandleIt() {

     *             while ( eventNotificationNotReceived ) {

     *                 java.lang.Thread.onSpinWait();

     *             }

     *             readAndProcessEvent();

     *         }

     *

     *         void readAndProcessEvent() {

     *             // Read event from some source and process it

     *              . . .

     *         }

     *     }

     * }</pre>

     * <p>

     * The code above would remain correct even if the {@code onSpinWait}

     * method was not called at all. However on some architectures the Java

     * Virtual Machine may issue the processor instructions to address such

     * code patterns in a more beneficial way.

     *

     * @since 9

     */

    @HotSpotIntrinsicCandidate

    public static void onSpinWait() {}

    /**

     * Initializes a Thread.

     *

     * @param g the Thread group

     * @param target the object whose run() method gets called

     * @param name the name of the new Thread

     * @param stackSize the desired stack size for the new thread, or

     *        zero to indicate that this parameter is to be ignored.

     * @param acc the AccessControlContext to inherit, or

     *            AccessController.getContext() if null

     * @param inheritThreadLocals if {@code true}, inherit initial values for

     *            inheritable thread-locals from the constructing thread

     */

        if (name == null) {

            throw new NullPointerException("name cannot be null");

        }

        this.name = name;

        Thread parent = currentThread();

        SecurityManager security = System.getSecurityManager();

        if (g == null) {

            /* Determine if it's an applet or not */

            /* If there is a security manager, ask the security manager

               what to do. */

            if (security != null) {

                g = security.getThreadGroup();

            }

            if (g == null) {

                g = parent.getThreadGroup();

            }

        }

        /* checkAccess regardless of whether or not threadgroup is

           explicitly passed in. */

        g.checkAccess();

        /*

         * Do we have the required permissions?

         */

        if (security != null) {

            if (isCCLOverridden(getClass())) {

                security.checkPermission(SUBCLASS_IMPLEMENTATION_PERMISSION);

            }

        }

        g.addUnstarted();

        this.group = g;

        this.daemon = parent.isDaemon();

        this.priority = parent.getPriority();

        if (security == null || isCCLOverridden(parent.getClass()))

            this.contextClassLoader = parent.getContextClassLoader();

        else

            this.contextClassLoader = parent.contextClassLoader;

        this.inheritedAccessControlContext =

                acc != null ? acc : AccessController.getContext();

        this.target = target;

        setPriority(priority);

        if (inheritThreadLocals && parent.inheritableThreadLocals != null)

            this.inheritableThreadLocals =

                ThreadLocal.createInheritedMap(parent.inheritableThreadLocals);

        /* Stash the specified stack size in case the VM cares */

        this.stackSize = stackSize;

        /* Set thread ID */

    }

    /**

     * Throws CloneNotSupportedException as a Thread can not be meaningfully

     * cloned. Construct a new Thread instead.

     *

     * @throws  CloneNotSupportedException

     *          always

     */

    @Override

    protected Object clone() throws CloneNotSupportedException {

        throw new CloneNotSupportedException();

    }

    /**

     * Allocates a new {@code Thread} object. This constructor has the same

     * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}

     * {@code (null, null, gname)}, where {@code gname} is a newly generated

     * name. Automatically generated names are of the form

     * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.

     */

    public Thread() {

    }

    /**

     * Allocates a new {@code Thread} object. This constructor has the same

     * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}

     * {@code (null, target, gname)}, where {@code gname} is a newly generated

     * name. Automatically generated names are of the form

     * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.

     *

     * @param  target

     *         the object whose {@code run} method is invoked when this thread

     *         is started. If {@code null}, this classes {@code run} method does

     *         nothing.

     */

    public Thread(Runnable target) {

    }

    /**

     * Creates a new Thread that inherits the given AccessControlContext

     * but thread-local variables are not inherited.

     * This is not a public constructor.

     */

    Thread(Runnable target, AccessControlContext acc) {

    }

    /**

     * Allocates a new {@code Thread} object. This constructor has the same

     * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}

     * {@code (group, target, gname)} ,where {@code gname} is a newly generated

     * name. Automatically generated names are of the form

     * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.

     *

     * @param  group