/*

 * Copyright 1994-2007 Sun Microsystems, Inc.  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.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.lang;

import java.security.AccessController;

import java.security.AccessControlContext;

import java.security.PrivilegedAction;

import java.util.Map;

import java.util.HashMap;

import java.util.Collections;

import java.util.concurrent.locks.LockSupport;

import sun.misc.SoftCache;

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.

 *

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

    /* If stop was called before start */

    private boolean stopBeforeStart;

    /* Remembered Throwable from stop before start */

    private Throwable throwableFromStop;

    /**

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

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

    }

   /**

     * Allocates a new <code>Thread</code> object. This constructor has

     * the same effect as <code>Thread(null, null,</code>

     * <i>gname</i><code>)</code>, where <b><i>gname</i></b> is

     * a newly generated name. Automatically generated names are of the

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

     *

     * @see     #Thread(ThreadGroup, Runnable, String)

     */

    public Thread() {

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

    }

    /**

     * Allocates a new <code>Thread</code> object. This constructor has

     * the same effect as <code>Thread(null, target,</code>

     * <i>gname</i><code>)</code>, where <i>gname</i> is

     * a newly generated name. Automatically generated names are of the

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

     *

     * @param   target   the object whose <code>run</code> method is called.

     * @see     #Thread(ThreadGroup, Runnable, String)

     */

    public Thread(Runnable target) {

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

    }

    /**

     * Allocates a new <code>Thread</code> object. This constructor has

     * the same effect as <code>Thread(group, target,</code>

     * <i>gname</i><code>)</code>, where <i>gname</i> is

     * a newly generated name. Automatically generated names are of the

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

     *

     * @param      group    the thread group.

     * @param      target   the object whose <code>run</code> method is called.

     * @exception  SecurityException  if the current thread cannot create a

     *             thread in the specified thread group.

     * @see        #Thread(ThreadGroup, Runnable, String)

     */

    public Thread(ThreadGroup group, Runnable target) {

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

    }

    /**

     * Allocates a new <code>Thread</code> object. This constructor has

     * the same effect as <code>Thread(null, null, name)</code>.

     *

     * @param   name   the name of the new thread.

     * @see     #Thread(ThreadGroup, Runnable, String)

     */

    public Thread(String name) {

        init(null, null, name, 0);

    }

    /**

     * Allocates a new <code>Thread</code> object. This constructor has

     * the same effect as <code>Thread(group, null, name)</code>

     *

     * @param      group   the thread group.

     * @param      name    the name of the new thread.

     * @exception  SecurityException  if the current thread cannot create a

     *               thread in the specified thread group.

     * @see        #Thread(ThreadGroup, Runnable, String)

     */

    public Thread(ThreadGroup group, String name) {

        init(group, null, name, 0);

    }

    /**

     * Allocates a new <code>Thread</code> object. This constructor has

     * the same effect as <code>Thread(null, target, name)</code>.

     *

     * @param   target   the object whose <code>run</code> method is called.

     * @param   name     the name of the new thread.

     * @see     #Thread(ThreadGroup, Runnable, String)

     */

    public Thread(Runnable target, String name) {

        init(null, target, name, 0);

    }

    /**

     * Allocates a new <code>Thread</code> object so that it has

     * <code>target</code> as its run object, has the specified

     * <code>name</code> as its name, and belongs to the thread group

     * referred to by <code>group</code>.

     * <p>

     * If <code>group</code> is <code>null</code> and there is a

     * security manager, the group is determined by the security manager's

     * <code>getThreadGroup</code> method. If <code>group</code> is

     * <code>null</code> and there is not a security manager, or the

     * security manager's <code>getThreadGroup</code> method returns

     * <code>null</code>, the group is set to be the same ThreadGroup

     * as the thread that is creating the new thread.

     *

     * <p>If there is a security manager, its <code>checkAccess</code>

     * method is called with the ThreadGroup as its argument.

     * <p>In addition, its <code>checkPermission</code>

     * method is called with the

     * <code>RuntimePermission("enableContextClassLoaderOverride")</code>

     * permission when invoked directly or indirectly by the constructor

     * of a subclass which overrides the <code>getContextClassLoader</code>

     * or <code>setContextClassLoader</code> methods.

     * This may result in a SecurityException.

     * <p>

     * If the <code>target</code> argument is not <code>null</code>, the

     * <code>run</code> method of the <code>target</code> is called when

     * this thread is started. If the target argument is

     * <code>null</code>, this thread's <code>run</code> method is called

     * when this thread is started.

     * <p>

     * The priority of the newly created thread is set equal to the

     * priority of the thread creating it, that is, the currently running

     * thread. The method <code>setPriority</code> may be used to

     * change the priority to a new value.

     * <p>

     * The newly created thread is initially marked as being a daemon

     * thread if and only if the thread creating it is currently marked

     * as a daemon thread. The method <code>setDaemon </code> may be used

     * to change whether or not a thread is a daemon.

     *

     * @param      group     the thread group.