/*

 * 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 sun.security.util.SecurityConstants;

/**

 * 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</code> 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</code> of some designated class). The Java Virtual

 * Machine continues to execute threads until either of the following

 * occurs:

 * <ul>

 * <li>The <code>exit</code> method of class <code>Runtime</code> 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</code> method or by

 *     throwing an exception that propagates beyond the <code>run</code>

 *     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</code>. This

 * subclass should override the <code>run</code> method of class

 * <code>Thread</code>. 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:

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

 * <p><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</code> interface. That class then

 * implements the <code>run</code> method. An instance of the class can

 * then be allocated, passed as an argument when creating

 * <code>Thread</code>, and started. The same example in this other

 * style looks like the following:

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

 * <p><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   JDK1.0

 */

public

class Thread implements Runnable {

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

    private static native void registerNatives();

    static {

        registerNatives();

    }

    private char        name[];

    private int         priority;

    private Thread      threadQ;

    private long        eetop;

    /* Whether or not to single_step this thread. */

    private boolean     single_step;

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

    private boolean     daemon = false;

    /* JVM state */

    private boolean     stillborn = false;

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

     */

    private long stackSize;

    /*

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

     */

    private long nativeParkEventPointer;

    /*

     * Thread ID

     */

    private long tid;

    /* For generating thread ID */

    private static long threadSeqNumber;

    /* Java thread status for tools,

     * initialized to indicate thread 'not yet started'

     */

    private volatile int threadStatus = 0;

    private static synchronized long nextThreadID() {

        return ++threadSeqNumber;

    }

    /**

     * 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 sun.misc.SharedSecrets from java.nio code

     */

    void blockedOn(Interruptible b) {

        synchronized (blockerLock) {

            blocker = b;

        }

    }

    /**

     * The minimum priority that a thread can have.

     */

    public final static int MIN_PRIORITY = 1;

   /**

     * The default priority that is assigned to a thread.

     */

    public final static int NORM_PRIORITY = 5;

    /**

     * The maximum priority that a thread can have.

     */

    public final static int MAX_PRIORITY = 10;

    /**

     * Returns a reference to the currently executing thread object.

     *

     * @return  the currently executing thread.

     */

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

    }

    /**

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

     */

    private void init(ThreadGroup g, Runnable target, String name,

                      long stackSize) {

        if (name == null) {

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

        }

        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 the security doesn't have a strong opinion of the matter

               use the parent thread group. */

            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();

        this.name = name.toCharArray();

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

            this.contextClassLoader = parent.getContextClassLoader();

        else

            this.contextClassLoader = parent.contextClassLoader;

        this.inheritedAccessControlContext = AccessController.getContext();

        this.target = target;

        setPriority(priority);

        if (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 */

        tid = nextThreadID();

    }

    /**

     * 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() {

        init(null, null, "Thread-" + nextThreadNum(), 0);

    }

    /**

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

        init(null, target, "Thread-" + nextThreadNum(), 0);

    }

    /**

     * 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

     *         the thread group. If {@code null} and there is a security

     *         manager, the group is determined by {@linkplain

     *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.

     *         If there is not a security manager or {@code

     *         SecurityManager.getThreadGroup()} returns {@code null}, the group

     *         is set to the current thread's thread group.

     *

     * @param  target

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

     *         is started. If {@code null}, this thread's run method is invoked.

     *

     * @throws  SecurityException

     *          if the current thread cannot create a thread in the specified

     *          thread group

     */

    public Thread(ThreadGroup group, Runnable target) {

        init(group, target, "Thread-" + nextThreadNum(), 0);

    }

    /**

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

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

     * {@code (null, null, name)}.

     *

     * @param   name

     *          the name of the new thread

     */

    public Thread(String name) {

        init(null, null, name, 0);

    }

    /**

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

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

     * {@code (group, null, name)}.

     *

     * @param  group

     *         the thread group. If {@code null} and there is a security

     *         manager, the group is determined by {@linkplain

     *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.

     *         If there is not a security manager or {@code

     *         SecurityManager.getThreadGroup()} returns {@code null}, the group

     *         is set to the current thread's thread group.

     *

     * @param  name

     *         the name of the new thread

     *

     * @throws  SecurityException

     *          if the current thread cannot create a thread in the specified

     *          thread group

     */

    public Thread(ThreadGroup group, String name) {

        init(group, null, name, 0);

    }

    /**

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

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

     * {@code (null, target, name)}.

     *

     * @param  target

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

     *         is started. If {@code null}, this thread's run method is invoked.