java.lang
Class Thread

java.lang.Object
  extended by java.lang.Thread
All Implemented Interfaces:
Runnable

public class Thread
extends Object
implements Runnable

Thread represents a single thread of execution in the VM. When an application VM starts up, it creates a non-daemon Thread which calls the main() method of a particular class. There may be other Threads running, such as the garbage collection thread.

Threads have names to identify them. These names are not necessarily unique. Every Thread has a priority, as well, which tells the VM which Threads should get more running time. New threads inherit the priority and daemon status of the parent thread, by default.

There are two methods of creating a Thread: you may subclass Thread and implement the run() method, at which point you may start the Thread by calling its start() method, or you may implement Runnable in the class you want to use and then call new Thread(your_obj).start().

The virtual machine runs until all non-daemon threads have died (either by returning from the run() method as invoked by start(), or by throwing an uncaught exception); or until System.exit is called with adequate permissions.

It is unclear at what point a Thread should be added to a ThreadGroup, and at what point it should be removed. Should it be inserted when it starts, or when it is created? Should it be removed when it is suspended or interrupted? The only thing that is clear is that the Thread should be removed when it is stopped.

Since:
1.0
See Also:
Runnable, Runtime.exit(int), run(), start(), ThreadLocal

Field Summary
static int MAX_PRIORITY
          The maximum priority for a Thread.
static int MIN_PRIORITY
          The minimum priority for a Thread.
static int NORM_PRIORITY
          The priority a Thread gets by default.
 
Constructor Summary
Thread()
          Allocates a new Thread object.
Thread(Runnable target)
          Allocates a new Thread object.
Thread(Runnable target, String name)
          Allocates a new Thread object.
Thread(String name)
          Allocates a new Thread object.
 
Method Summary
static Thread currentThread()
          Get the currently executing Thread.
 String getName()
          Get this Thread's name.
 int getPriority()
          Get this Thread's priority.
 boolean isAlive()
          Determine whether this Thread is alive.
 void run()
          The method of Thread that will be run if there is no Runnable object associated with the Thread.
 void setName(String name)
          Set this Thread's name.
 void setPriority(int newPriority)
          Set this Thread's priority.
static void sleep(long ms)
          Suspend the current Thread's execution for the specified amount of time.
static void sleep(long timeout, int nanos)
          Suspend the current Thread's execution for the specified amount of time.
 void start()
          Start this Thread, calling the run() method of the Runnable this Thread was created with, or else the run() method of the Thread itself.
 String toString()
          Returns a string representation of this thread, including the thread's name, priority, and thread group.
static void yield()
          Causes the currently executing thread object to temporarily pause and allow other threads to execute.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MIN_PRIORITY

public static final int MIN_PRIORITY
The minimum priority for a Thread.

See Also:
Constant Field Values

NORM_PRIORITY

public static final int NORM_PRIORITY
The priority a Thread gets by default.

See Also:
Constant Field Values

MAX_PRIORITY

public static final int MAX_PRIORITY
The maximum priority for a Thread.

See Also:
Constant Field Values
Constructor Detail

Thread

public Thread()
Allocates a new Thread object. This constructor has the same effect as Thread(null, null, gname), where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n, where n is an integer.

Threads created this way must have overridden their run() method to actually do anything. An example illustrating this method being used follows:

     import java.lang.*;

     class plain01 implements Runnable {
         String name;
         plain01() {
             name = null;
         }
         plain01(String s) {
             name = s;
         }
         public void run() {
             if (name == null)
                 System.out.println("A new thread created");
             else
                 System.out.println("A new thread with name " + name +
                                    " created");
         }
     }
     class threadtest01 {
         public static void main(String args[] ) {
             int failed = 0 ;

             Thread t1 = new Thread();
             if (t1 != null)
                 System.out.println("new Thread() succeed");
             else {
                 System.out.println("new Thread() failed");
                 failed++;
             }
         }
     }
 

See Also:
java.lang.Thread#Thread(java.lang.ThreadGroup, java.lang.Runnable, java.lang.String)

Thread

public Thread(Runnable target)
Allocates a new Thread object. This constructor has the same effect as Thread(null, target, gname), where gname is a newly generated name. Automatically generated names are of the form "Thread-"+n, where n is an integer.

Parameters:
target - the object whose run method is called.
See Also:
java.lang.Thread#Thread(java.lang.ThreadGroup, java.lang.Runnable, java.lang.String)

Thread

public Thread(String name)
Allocates a new Thread object. This constructor has the same effect as Thread(null, null, name).

Parameters:
name - the name of the new thread.
See Also:
java.lang.Thread#Thread(java.lang.ThreadGroup, java.lang.Runnable, java.lang.String)

Thread

public Thread(Runnable target,
              String name)
Allocates a new Thread object. This constructor has the same effect as Thread(null, target, name).

Parameters:
target - the Runnable object to execute
name - the name for the Thread
Throws:
NullPointerException - if name is null
See Also:
#Thread(ThreadGroup, Runnable, String)
Method Detail

currentThread

public static Thread currentThread()
Get the currently executing Thread.

Returns:
the currently executing Thread

getName

public final String getName()
Get this Thread's name.

Returns:
this Thread's name

getPriority

public final int getPriority()
Get this Thread's priority.

Returns:
the Thread's priority

isAlive

public final boolean isAlive()
Determine whether this Thread is alive. A thread which is alive has started and not yet died.

Returns:
whether this Thread is alive

run

public void run()
The method of Thread that will be run if there is no Runnable object associated with the Thread. Thread's implementation does nothing at all.

Specified by:
run in interface Runnable
See Also:
start(), #Thread(ThreadGroup, Runnable, String)

setName

public final void setName(String name)
Set this Thread's name. There may be a security check, checkAccess.

Parameters:
name - the new name for this Thread
Throws:
NullPointerException - if name is null
java.lang.SecurityException - if you cannot modify this Thread

yield

public static void yield()
Causes the currently executing thread object to temporarily pause and allow other threads to execute.


sleep

public static void sleep(long ms)
                  throws InterruptedException
Suspend the current Thread's execution for the specified amount of time. The Thread will not lose any locks it has during this time. There are no guarantees which thread will be next to run, but most VMs will choose the highest priority thread that has been waiting longest.

Parameters:
ms - the number of milliseconds to sleep, or 0 for forever
Throws:
InterruptedException - if the Thread is interrupted; it's interrupted status will be cleared
See Also:
Object.notify(), Object.wait(long)

sleep

public static void sleep(long timeout,
                         int nanos)
                  throws InterruptedException
Suspend the current Thread's execution for the specified amount of time. The Thread will not lose any locks it has during this time. There are no guarantees which thread will be next to run, but most VMs will choose the highest priority thread that has been waiting longest.

Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs do not offer that fine a grain of timing resolution. Besides, there is no guarantee that this thread can start up immediately when time expires, because some other thread may be active. So don't expect real-time performance.

Parameters:
ms - the number of milliseconds to sleep, or 0 for forever
ns - the number of extra nanoseconds to sleep (0-999999)
Throws:
InterruptedException - if the Thread is interrupted; it's interrupted status will be cleared
IllegalArgumentException - if ns is invalid
See Also:
Object.notify(), Object.wait(long, int)

start

public void start()
Start this Thread, calling the run() method of the Runnable this Thread was created with, or else the run() method of the Thread itself. This is the only way to start a new thread; calling run by yourself will just stay in the same thread. The virtual machine will remove the thread from its thread group when the run() method completes.

Throws:
IllegalThreadStateException - if the thread has already started
See Also:
run()

setPriority

public final void setPriority(int newPriority)
Set this Thread's priority. There may be a security check, checkAccess, then the priority is set to the smaller of priority and the ThreadGroup maximum priority.

Parameters:
priority - the new priority for this Thread
Throws:
IllegalArgumentException - if priority exceeds MIN_PRIORITY or MAX_PRIORITY
java.lang.SecurityException - if you cannot modify this Thread
See Also:
getPriority(), #checkAccess(), ThreadGroup.getMaxPriority(), MIN_PRIORITY, MAX_PRIORITY

toString

public String toString()
Returns a string representation of this thread, including the thread's name, priority, and thread group.

Overrides:
toString in class Object
Returns:
a human-readable String representing this Thread
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)