/*

 * Copyright (c) 1994, 2011, 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 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.

     *

     * @param  name

     *         the name of the new thread

     */

    public Thread(Runnable target, String name) {

        init(null, target, name, 0);

    }

    /**

     * Allocates a new {@code Thread} object so that it has {@code target}

     * as its run object, has the specified {@code name} as its name,

     * and belongs to the thread group referred to by {@code group}.

     *

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

     * {@link SecurityManager#checkAccess(ThreadGroup) checkAccess}

     * method is invoked with the ThreadGroup as its argument.

     *

     * <p>In addition, its {@code checkPermission} method is invoked with

     * the {@code RuntimePermission("enableContextClassLoaderOverride")}

     * permission when invoked directly or indirectly by the constructor

     * of a subclass which overrides the {@code getContextClassLoader}

     * or {@code setContextClassLoader} methods.

     *

     * <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 {@linkplain #setPriority setPriority} 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 {@linkplain #setDaemon setDaemon}

     * may be used to change whether or not a thread is a daemon.

     *

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

     *

     * @param  name

     *         the name of the new thread

     *

     * @throws  SecurityException

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

     *          thread group or cannot override the context class loader methods.

     */

    public Thread(ThreadGroup group, Runnable target, String name) {

        init(group, target, name, 0);

    }

    /**

     * Allocates a new {@code Thread} object so that it has {@code target}

     * as its run object, has the specified {@code name} as its name,

     * and belongs to the thread group referred to by {@code group}, and has

     * the specified <i>stack size</i>.

     *

     * <p>This constructor is identical to {@link

     * #Thread(ThreadGroup,Runnable,String)} with the exception of the fact

     * that it allows the thread stack size to be specified.  The stack size

     * is the approximate number of bytes of address space that the virtual

     * machine is to allocate for this thread's stack.  <b>The effect of the

     * {@code stackSize} parameter, if any, is highly platform dependent.</b>

     *

     * <p>On some platforms, specifying a higher value for the

     * {@code stackSize} parameter may allow a thread to achieve greater

     * recursion depth before throwing a {@link StackOverflowError}.

     * Similarly, specifying a lower value may allow a greater number of

     * threads to exist concurrently without throwing an {@link

     * OutOfMemoryError} (or other internal error).  The details of

     * the relationship between the value of the <tt>stackSize</tt> parameter

     * and the maximum recursion depth and concurrency level are

     * platform-dependent.  <b>On some platforms, the value of the

     * {@code stackSize} parameter may have no effect whatsoever.</b>

     *

     * <p>The virtual machine is free to treat the {@code stackSize}

     * parameter as a suggestion.  If the specified value is unreasonably low

     * for the platform, the virtual machine may instead use some

     * platform-specific minimum value; if the specified value is unreasonably

     * high, the virtual machine may instead use some platform-specific

     * maximum.  Likewise, the virtual machine is free to round the specified

     * value up or down as it sees fit (or to ignore it completely).

     *

     * <p>Specifying a value of zero for the {@code stackSize} parameter will

     * cause this constructor to behave exactly like the

     * {@code Thread(ThreadGroup, Runnable, String)} constructor.

     *

     * <p><i>Due to the platform-dependent nature of the behavior of this

     * constructor, extreme care should be exercised in its use.

     * The thread stack size necessary to perform a given computation will

     * likely vary from one JRE implementation to another.  In light of this

     * variation, careful tuning of the stack size parameter may be required,

     * and the tuning may need to be repeated for each JRE implementation on

     * which an application is to run.</i>

     *

     * <p>Implementation note: Java platform implementers are encouraged to

     * document their implementation's behavior with respect to the

     * {@code stackSize} parameter.

     *

     *

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

     *

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

     *

     * @throws  SecurityException

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

     *          thread group

     *

     * @since 1.4

     */

    public Thread(ThreadGroup group, Runnable target, String name,

                  long stackSize) {

        init(group, target, name, stackSize);

    }

    /**

     * Causes this thread to begin execution; the Java Virtual Machine

     * calls the <code>run</code> method of this thread.

     * <p>

     * The result is that two threads are running concurrently: the

     * current thread (which returns from the call to the

     * <code>start</code> method) and the other thread (which executes its

     * <code>run</code> method).

     * <p>

     * It is never legal to start a thread more than once.

     * In particular, a thread may not be restarted once it has completed

     * execution.

     *

     * @exception  IllegalThreadStateException  if the thread was already

     *               started.

     * @see        #run()

     * @see        #stop()

     */

    public synchronized void start() {

        /**

         * This method is not invoked for the main method thread or "system"

         * group threads created/set up by the VM. Any new functionality added

         * to this method in the future may have to also be added to the VM.

         *

         * A zero status value corresponds to state "NEW".

         */

        if (threadStatus != 0)

            throw new IllegalThreadStateException();

        /* Notify the group that this thread is about to be started

         * so that it can be added to the group's list of threads

         * and the group's unstarted count can be decremented. */

        group.add(this);

        boolean started = false;

        try {

            start0();

            started = true;

        } finally {

            try {

                if (!started) {

                    group.threadStartFailed(this);

                }

            } catch (Throwable ignore) {

                /* do nothing. If start0 threw a Throwable then

                  it will be passed up the call stack */

            }

        }

    }

    private native void start0();

    /**

     * If this thread was constructed using a separate

     * <code>Runnable</code> run object, then that

     * <code>Runnable</code> object's <code>run</code> method is called;

     * otherwise, this method does nothing and returns.

     * <p>

     * Subclasses of <code>Thread</code> should override this method.

     *

     * @see     #start()

     * @see     #stop()

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

     */

    @Override

    public void run() {

        if (target != null) {

            target.run();

        }

    }

    /**

     * This method is called by the system to give a Thread

     * a chance to clean up before it actually exits.

     */

    private void exit() {

        if (group != null) {

            group.threadTerminated(this);

            group = null;

        }

        /* Aggressively null out all reference fields: see bug 4006245 */

        target = null;

        /* Speed the release of some of these resources */

        threadLocals = null;

        inheritableThreadLocals = null;

        inheritedAccessControlContext = null;

        blocker = null;

        uncaughtExceptionHandler = null;

    }

    /**

     * Forces the thread to stop executing.

     * <p>

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

     * method is called with <code>this</code>

     * as its argument. This may result in a

     * <code>SecurityException</code> being raised (in the current thread).

     * <p>

     * If this thread is different from the current thread (that is, the current

     * thread is trying to stop a thread other than itself), the

     * security manager's <code>checkPermission</code> method (with a

     * <code>RuntimePermission("stopThread")</code> argument) is called in

     * addition.

     * Again, this may result in throwing a

     * <code>SecurityException</code> (in the current thread).

     * <p>

     * The thread represented by this thread is forced to stop whatever

     * it is doing abnormally and to throw a newly created

     * <code>ThreadDeath</code> object as an exception.

     * <p>

     * It is permitted to stop a thread that has not yet been started.

     * If the thread is eventually started, it immediately terminates.

     * <p>

     * An application should not normally try to catch

     * <code>ThreadDeath</code> unless it must do some extraordinary

     * cleanup operation (note that the throwing of

     * <code>ThreadDeath</code> causes <code>finally</code> clauses of

     * <code>try</code> statements to be executed before the thread

     * officially dies).  If a <code>catch</code> clause catches a

     * <code>ThreadDeath</code> object, it is important to rethrow the

     * object so that the thread actually dies.

     * <p>

     * The top-level error handler that reacts to otherwise uncaught

     * exceptions does not print out a message or otherwise notify the

     * application if the uncaught exception is an instance of

     * <code>ThreadDeath</code>.

     *

     * @exception  SecurityException  if the current thread cannot

     *               modify this thread.

     * @see        #interrupt()

     * @see        #checkAccess()

     * @see        #run()

     * @see        #start()

     * @see        ThreadDeath

     * @see        ThreadGroup#uncaughtException(Thread,Throwable)

     * @see        SecurityManager#checkAccess(Thread)

     * @see        SecurityManager#checkPermission

     * @deprecated This method is inherently unsafe.  Stopping a thread with

     *       Thread.stop causes it to unlock all of the monitors that it

     *       has locked (as a natural consequence of the unchecked

     *       <code>ThreadDeath</code> exception propagating up the stack).  If

     *       any of the objects previously protected by these monitors were in

     *       an inconsistent state, the damaged objects become visible to

     *       other threads, potentially resulting in arbitrary behavior.  Many

     *       uses of <code>stop</code> should be replaced by code that simply

     *       modifies some variable to indicate that the target thread should

     *       stop running.  The target thread should check this variable

     *       regularly, and return from its run method in an orderly fashion

     *       if the variable indicates that it is to stop running.  If the

     *       target thread waits for long periods (on a condition variable,

     *       for example), the <code>interrupt</code> method should be used to

     *       interrupt the wait.

     *       For more information, see

     *       <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why

     *       are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.

     */

    @Deprecated

    public final void stop() {

        stop(new ThreadDeath());

    }

    /**

     * Forces the thread to stop executing.

     * <p>

     * If there is a security manager installed, the <code>checkAccess</code>

     * method of this thread is called, which may result in a

     * <code>SecurityException</code> being raised (in the current thread).

     * <p>

     * If this thread is different from the current thread (that is, the current

     * thread is trying to stop a thread other than itself) or

     * <code>obj</code> is not an instance of <code>ThreadDeath</code>, the

     * security manager's <code>checkPermission</code> method (with the

     * <code>RuntimePermission("stopThread")</code> argument) is called in

     * addition.

     * Again, this may result in throwing a

     * <code>SecurityException</code> (in the current thread).

     * <p>

     * If the argument <code>obj</code> is null, a

     * <code>NullPointerException</code> is thrown (in the current thread).

     * <p>

     * The thread represented by this thread is forced to stop

     * whatever it is doing abnormally and to throw the

     * <code>Throwable</code> object <code>obj</code> as an exception. This

     * is an unusual action to take; normally, the <code>stop</code> method

     * that takes no arguments should be used.

     * <p>

     * It is permitted to stop a thread that has not yet been started.

     * If the thread is eventually started, it immediately terminates.

     *

     * @param      obj   the Throwable object to be thrown.

     * @exception  SecurityException  if the current thread cannot modify

     *               this thread.

     * @throws     NullPointerException if obj is <tt>null</tt>.

     * @see        #interrupt()

     * @see        #checkAccess()

     * @see        #run()

     * @see        #start()

     * @see        #stop()

     * @see        SecurityManager#checkAccess(Thread)

     * @see        SecurityManager#checkPermission

     * @deprecated This method is inherently unsafe.  See {@link #stop()}

     *        for details.  An additional danger of this

     *        method is that it may be used to generate exceptions that the

     *        target thread is unprepared to handle (including checked

     *        exceptions that the thread could not possibly throw, were it

     *        not for this method).

     *        For more information, see

     *        <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why

     *        are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.

     */

    @Deprecated

    public final synchronized void stop(Throwable obj) {

        if (obj == null)

            throw new NullPointerException();

        SecurityManager security = System.getSecurityManager();

        if (security != null) {

            checkAccess();

            if ((this != Thread.currentThread()) ||

                (!(obj instanceof ThreadDeath))) {

                security.checkPermission(SecurityConstants.STOP_THREAD_PERMISSION);

            }

        }

        // A zero status value corresponds to "NEW", it can't change to

        // not-NEW because we hold the lock.

        if (threadStatus != 0) {

            resume(); // Wake up thread if it was suspended; no-op otherwise

        }

        // The VM can handle all thread states

        stop0(obj);

    }

    /**

     * Interrupts this thread.

     *

     * <p> Unless the current thread is interrupting itself, which is

     * always permitted, the {@link #checkAccess() checkAccess} method

     * of this thread is invoked, which may cause a {@link

     * SecurityException} to be thrown.

     *

     * <p> If this thread is blocked in an invocation of the {@link

     * Object#wait() wait()}, {@link Object#wait(long) wait(long)}, or {@link

     * Object#wait(long, int) wait(long, int)} methods of the {@link Object}

     * class, or of the {@link #join()}, {@link #join(long)}, {@link

     * #join(long, int)}, {@link #sleep(long)}, or {@link #sleep(long, int)},

     * methods of this class, then its interrupt status will be cleared and it

     * will receive an {@link InterruptedException}.

     *

     * <p> If this thread is blocked in an I/O operation upon an {@link

     * java.nio.channels.InterruptibleChannel </code>interruptible

     * channel<code>} then the channel will be closed, the thread's interrupt

     * status will be set, and the thread will receive a {@link

     * java.nio.channels.ClosedByInterruptException}.

     *

     * <p> If this thread is blocked in a {@link java.nio.channels.Selector}

     * then the thread's interrupt status will be set and it will return

     * immediately from the selection operation, possibly with a non-zero

     * value, just as if the selector's {@link

     * java.nio.channels.Selector#wakeup wakeup} method were invoked.

     *

     * <p> If none of the previous conditions hold then this thread's interrupt

     * status will be set. </p>

     *

     * <p> Interrupting a thread that is not alive need not have any effect.

     *

     * @throws  SecurityException

     *          if the current thread cannot modify this thread

     *

     * @revised 6.0

     * @spec JSR-51

     */

    public void interrupt() {

        if (this != Thread.currentThread())

            checkAccess();

        synchronized (blockerLock) {

            Interruptible b = blocker;

            if (b != null) {

                interrupt0();           // Just to set the interrupt flag

                b.interrupt(this);

                return;

            }

        }

        interrupt0();

    }

    /**

     * Tests whether the current thread has been interrupted.  The

     * <i>interrupted status</i> of the thread is cleared by this method.  In

     * other words, if this method were to be called twice in succession, the

     * second call would return false (unless the current thread were

     * interrupted again, after the first call had cleared its interrupted

     * status and before the second call had examined it).

     *

     * <p>A thread interruption ignored because a thread was not alive

     * at the time of the interrupt will be reflected by this method

     * returning false.

     *

     * @return  <code>true</code> if the current thread has been interrupted;

     *          <code>false</code> otherwise.

     * @see #isInterrupted()

     * @revised 6.0

     */

    public static boolean interrupted() {

        return currentThread().isInterrupted(true);

    }

    /**

     * Tests whether this thread has been interrupted.  The <i>interrupted

     * status</i> of the thread is unaffected by this method.

     *

     * <p>A thread interruption ignored because a thread was not alive

     * at the time of the interrupt will be reflected by this method

     * returning false.

     *

     * @return  <code>true</code> if this thread has been interrupted;

     *          <code>false</code> otherwise.

     * @see     #interrupted()

     * @revised 6.0

     */

    public boolean isInterrupted() {

        return isInterrupted(false);

    }

    /**

     * Tests if some Thread has been interrupted.  The interrupted state

     * is reset or not based on the value of ClearInterrupted that is

     * passed.

     */

    private native boolean isInterrupted(boolean ClearInterrupted);

    /**

     * Throws {@link NoSuchMethodError}.

     *

     * @deprecated This method was originally designed to destroy this

     *     thread without any cleanup. Any monitors it held would have

     *     remained locked. However, the method was never implemented.

     *     If if were to be implemented, it would be deadlock-prone in

     *     much the manner of {@link #suspend}. If the target thread held