java.lang.Thread Class Reference

List of all members.


Detailed Description

This class must be implemented by the VM vendor.

The documented methods must be implemented to support other provided class implementations in this package. A Thread is a unit of concurrent execution in Java. It has its own call stack for methods being called and their parameters. Threads in the same VM interact and synchronize by the use of shared Objects and monitors associated with these objects. Synchronized methods and part of the API in Object also allow Threads to cooperate. When a Java program starts executing there is an implicit Thread (called "main") which is automatically created by the VM. This Thread belongs to a ThreadGroup (also called "main") which is automatically created by the bootstrap sequence by the VM as well.

See also:
java.lang.Object

java.lang.ThreadGroup


Public Types

enum  State
 A representation of a thread's state. More...

Public Member Functions

 Thread ()
 Constructs a new Thread with no runnable object and a newly generated name.
 Thread (Runnable runnable)
 Constructs a new Thread with a runnable object and a newly generated name.
 Thread (Runnable runnable, String threadName)
 Constructs a new Thread with a runnable object and name provided.
 Thread (String threadName)
 Constructs a new Thread with no runnable object and the name provided.
 Thread (ThreadGroup group, Runnable runnable)
 Constructs a new Thread with a runnable object and a newly generated name.
 Thread (ThreadGroup group, Runnable runnable, String threadName, long stack)
 Constructs a new Thread with a runnable object, the given name and belonging to the ThreadGroup passed as parameter.
 Thread (ThreadGroup group, Runnable runnable, String threadName)
 Constructs a new Thread with a runnable object, the given name and belonging to the ThreadGroup passed as parameter.
 Thread (ThreadGroup group, String threadName)
 Constructs a new Thread with no runnable object, the given name and belonging to the ThreadGroup passed as parameter.
final void checkAccess ()
 This method is used for operations that require approval from a SecurityManager.
int countStackFrames ()
 Returns the number of stack frames in this thread.
void destroy ()
 Destroys the receiver without any monitor cleanup.
ClassLoader getContextClassLoader ()
 Returns the context ClassLoader for the receiver.
long getId ()
final String getName ()
 Answers the name of the receiver.
final int getPriority ()
 Answers the priority of the receiver.
StackTraceElement[] getStackTrace ()
State getState ()
final ThreadGroup getThreadGroup ()
 Answers the ThreadGroup to which the receiver belongs.
UncaughtExceptionHandler getUncaughtExceptionHandler ()
void interrupt ()
 Posts an interrupt request to the receiver.
final boolean isAlive ()
 Answers true if the receiver has already been started and still runs code (hasn't died yet).
final boolean isDaemon ()
 Answers a boolean indicating whether the receiver is a daemon Thread (true) or not (false) A daemon Thread only runs as long as there are non-daemon Threads running.
boolean isInterrupted ()
 Answers a boolean indicating whether the receiver has a pending interrupt request (true) or not ( false).
final void join () throws InterruptedException
 Blocks the current Thread (Thread.currentThread()) until the receiver finishes its execution and dies.
final void join (long timeoutInMilliseconds) throws InterruptedException
 Blocks the current Thread (Thread.currentThread()) until the receiver finishes its execution and dies or the specified timeout expires, whatever happens first.
final void join (long timeoutInMilliseconds, int nanos) throws InterruptedException
 Blocks the current Thread (Thread.currentThread()) until the receiver finishes its execution and dies or the specified timeout expires, whatever happens first.
final void resume ()
 This is a no-op if the receiver was never suspended, or suspended and already resumed.
void run ()
 Calls the run() method of the Runnable object the receiver holds.
void setContextClassLoader (ClassLoader cl)
 Set the context ClassLoader for the receiver.
final void setDaemon (boolean isDaemon)
 Set if the receiver is a daemon Thread or not.
final void setName (String threadName)
 Sets the name of the receiver.
final void setPriority (int priority)
 Sets the priority of the receiver.
void setUncaughtExceptionHandler (UncaughtExceptionHandler handler)
void start ()
 Starts the new Thread of execution.
final void stop ()
 Requests the receiver Thread to stop and throw ThreadDeath.
final void stop (Throwable throwable)
 Requests the receiver Thread to stop and throw the throwable().
final void suspend ()
 This is a no-op if the receiver is suspended.
String toString ()
 Answers a string containing a concise, human-readable description of the receiver.

Static Public Member Functions

static int activeCount ()
 Returns the number of active threads in the running thread's ThreadGroup.
static Thread currentThread ()
 Answers the instance of Thread that corresponds to the running Thread which calls this method.
static void dumpStack ()
 Prints a text representation of the stack for this Thread.
static int enumerate (Thread[] threads)
 Copies an array with all Threads which are in the same ThreadGroup as the receiver - and subgroups - into the array threads passed as parameter.
static Map< Thread,
StackTraceElement[]> 
getAllStackTraces ()
static UncaughtExceptionHandler getDefaultUncaughtExceptionHandler ()
static boolean interrupted ()
 Answers a boolean indicating whether the current Thread ( currentThread()) has a pending interrupt request ( true) or not (false).
static void setDefaultUncaughtExceptionHandler (UncaughtExceptionHandler handler)
static void sleep (long time) throws InterruptedException
 Causes the thread which sent this message to sleep an interval of time (given in milliseconds).
static void sleep (long time, int nanos) throws InterruptedException
 Causes the thread which sent this message to sleep an interval of time (given in milliseconds).
static void yield ()
 Causes the thread which sent this message to yield execution to another Thread that is ready to run.
static boolean holdsLock (Object object)
 Returns whether the current thread has a monitor lock on the specified object.

Static Public Attributes

static final int MAX_PRIORITY = 10
static final int MIN_PRIORITY = 1
static final int NORM_PRIORITY = 5

Package Functions

Object getThreadLocal (ThreadLocal<?> local)
 A sample implementation of this method is provided by the reference implementation.
void setThreadLocal (ThreadLocal<?> local, Object value)
 A sample implementation of this method is provided by the reference implementation.

Package Attributes

Object slot1
Object slot2
Object slot3

Private Member Functions

void setInterruptAction (Runnable action)
 Set the action to be executed when interruption, which is probably be used to implement the interruptible channel.

Private Attributes

Runnable action

Classes

interface  UncaughtExceptionHandler
 Implemented by objects that want to handle cases where a thread is being terminated by an uncaught exception. More...

Member Enumeration Documentation

enum java::lang::Thread::State

A representation of a thread's state.

A given thread may only be in one state at a time.

Since:
1.5


Constructor & Destructor Documentation

java.lang.Thread.Thread (  ) 

Constructs a new Thread with no runnable object and a newly generated name.

The new Thread will belong to the same ThreadGroup as the Thread calling this constructor.

See also:
java.lang.ThreadGroup

java.lang.Thread.Thread ( Runnable  runnable  ) 

Constructs a new Thread with a runnable object and a newly generated name.

The new Thread will belong to the same ThreadGroup as the Thread calling this constructor.

Parameters:
runnable a java.lang.Runnable whose method run will be executed by the new Thread
See also:
java.lang.ThreadGroup

java.lang.Runnable

java.lang.Thread.Thread ( Runnable  runnable,
String  threadName 
)

Constructs a new Thread with a runnable object and name provided.

The new Thread will belong to the same ThreadGroup as the Thread calling this constructor.

Parameters:
runnable a java.lang.Runnable whose method run will be executed by the new Thread
threadName Name for the Thread being created
See also:
java.lang.ThreadGroup

java.lang.Runnable

java.lang.Thread.Thread ( String  threadName  ) 

Constructs a new Thread with no runnable object and the name provided.

The new Thread will belong to the same ThreadGroup as the Thread calling this constructor.

Parameters:
threadName Name for the Thread being created
See also:
java.lang.ThreadGroup

java.lang.Runnable

java.lang.Thread.Thread ( ThreadGroup  group,
Runnable  runnable 
)

Constructs a new Thread with a runnable object and a newly generated name.

The new Thread will belong to the ThreadGroup passed as parameter.

Parameters:
group ThreadGroup to which the new Thread will belong
runnable a java.lang.Runnable whose method run will be executed by the new Thread
Exceptions:
SecurityException if group.checkAccess() fails with a SecurityException
IllegalThreadStateException if group.destroy() has already been done
See also:
java.lang.ThreadGroup

java.lang.Runnable

java.lang.SecurityException

java.lang.SecurityManager

java.lang.Thread.Thread ( ThreadGroup  group,
Runnable  runnable,
String  threadName,
long  stack 
)

Constructs a new Thread with a runnable object, the given name and belonging to the ThreadGroup passed as parameter.

Parameters:
group ThreadGroup to which the new Thread will belong
runnable a java.lang.Runnable whose method run will be executed by the new Thread
threadName Name for the Thread being created
stack Platform dependent stack size
Exceptions:
SecurityException if group.checkAccess() fails with a SecurityException
IllegalThreadStateException if group.destroy() has already been done
See also:
java.lang.ThreadGroup

java.lang.Runnable

java.lang.SecurityException

java.lang.SecurityManager

java.lang.Thread.Thread ( ThreadGroup  group,
Runnable  runnable,
String  threadName 
)

Constructs a new Thread with a runnable object, the given name and belonging to the ThreadGroup passed as parameter.

Parameters:
group ThreadGroup to which the new Thread will belong
runnable a java.lang.Runnable whose method run will be executed by the new Thread
threadName Name for the Thread being created
Exceptions:
SecurityException if group.checkAccess() fails with a SecurityException
IllegalThreadStateException if group.destroy() has already been done
See also:
java.lang.ThreadGroup

java.lang.Runnable

java.lang.SecurityException

java.lang.SecurityManager

java.lang.Thread.Thread ( ThreadGroup  group,
String  threadName 
)

Constructs a new Thread with no runnable object, the given name and belonging to the ThreadGroup passed as parameter.

Parameters:
group ThreadGroup to which the new Thread will belong
threadName Name for the Thread being created
Exceptions:
SecurityException if group.checkAccess() fails with a SecurityException
IllegalThreadStateException if group.destroy() has already been done
See also:
java.lang.ThreadGroup

java.lang.SecurityException

java.lang.SecurityManager


Member Function Documentation

void java.lang.Thread.setInterruptAction ( Runnable  action  )  [private]

Set the action to be executed when interruption, which is probably be used to implement the interruptible channel.

The action is null by default. And if this method is invoked by passing in a non-null value, this action's run() method will be invoked in interrupt().

Parameters:
action the action to be executed when interruption

static int java.lang.Thread.activeCount (  )  [static]

Returns the number of active threads in the running thread's ThreadGroup.

Returns:
Number of Threads

final void java.lang.Thread.checkAccess (  ) 

This method is used for operations that require approval from a SecurityManager.

If there's none installed, this method is a no-op. If there's a SecurityManager installed , SecurityManager#checkAccess(Thread) is called for that SecurityManager.

See also:
java.lang.SecurityException

java.lang.SecurityManager

int java.lang.Thread.countStackFrames (  ) 

Returns the number of stack frames in this thread.

Returns:
Number of stack frames
Deprecated:
The results of this call were never well defined. To make things worse, it would depend if the Thread was suspended or not, and suspend was deprecated too.

static Thread java.lang.Thread.currentThread (  )  [static]

Answers the instance of Thread that corresponds to the running Thread which calls this method.

Returns:
a java.lang.Thread corresponding to the code that called currentThread()

void java.lang.Thread.destroy (  ) 

Destroys the receiver without any monitor cleanup.

Not implemented.

Deprecated:
Not implemented.

static void java.lang.Thread.dumpStack (  )  [static]

Prints a text representation of the stack for this Thread.

static int java.lang.Thread.enumerate ( Thread[]  threads  )  [static]

Copies an array with all Threads which are in the same ThreadGroup as the receiver - and subgroups - into the array threads passed as parameter.

If the array passed as parameter is too small no exception is thrown - the extra elements are simply not copied.

Parameters:
threads array into which the Threads will be copied
Returns:
How many Threads were copied over
Exceptions:
SecurityException if the installed SecurityManager fails SecurityManager#checkAccess(Thread)
See also:
java.lang.SecurityException

java.lang.SecurityManager

static Map<Thread, StackTraceElement[]> java.lang.Thread.getAllStackTraces (  )  [static]

Returns the stack traces of all the currently live threads.

The RuntimePermission("getStackTrace") and RuntimePermission("modifyThreadGroup") are checked before returning a result.

Returns:
A Map of current Threads to StackTraceElement arrays.
Exceptions:
SecurityException if the current SecurityManager fails the SecurityManager#checkPermission(java.security.Permission) call.
Since:
1.5

ClassLoader java.lang.Thread.getContextClassLoader (  ) 

Returns the context ClassLoader for the receiver.

Returns:
ClassLoader The context ClassLoader
See also:
java.lang.ClassLoader

getContextClassLoader()

static UncaughtExceptionHandler java.lang.Thread.getDefaultUncaughtExceptionHandler (  )  [static]

Returns the default exception handler that's executed when uncaught exception terminates a thread.

Returns:
An UncaughtExceptionHandler or null if none exists.
Since:
1.5

long java.lang.Thread.getId (  ) 

Returns the thread's identifier. The ID is a positive long generated on thread creation, is unique to the thread and doesn't change during the life of the thread; the ID may be reused after the thread has been terminated.

Returns:
The thread's ID.
Since:
1.5

final String java.lang.Thread.getName (  ) 

Answers the name of the receiver.

Returns:
the receiver's name (a java.lang.String)

final int java.lang.Thread.getPriority (  ) 

Answers the priority of the receiver.

Returns:
the receiver's priority (an int)
See also:
Thread.setPriority

StackTraceElement [] java.lang.Thread.getStackTrace (  ) 

Returns the current stack trace of the thread.

The RuntimePermission("getStackTrace") is checked before returning a result.

Returns:
An array of StackTraceElements.
Exceptions:
SecurityException if the current SecurityManager fails the SecurityManager#checkPermission(java.security.Permission) call.
Since:
1.5

State java.lang.Thread.getState (  ) 

Returns the current state of the thread for monitoring purposes.

Returns:
A State value.
Since:
1.5

final ThreadGroup java.lang.Thread.getThreadGroup (  ) 

Answers the ThreadGroup to which the receiver belongs.

Returns:
the receiver's ThreadGroup

Object java.lang.Thread.getThreadLocal ( ThreadLocal<?>  local  )  [package]

A sample implementation of this method is provided by the reference implementation.

It must be included, as it is called by ThreadLocal.get() and InheritableThreadLocal.get(). Return the value associated with the ThreadLocal in the receiver

Parameters:
local ThreadLocal to perform the lookup
Returns:
the value of the ThreadLocal
See also:
setThreadLocal

UncaughtExceptionHandler java.lang.Thread.getUncaughtExceptionHandler (  ) 

Returns the thread's uncaught exception handler. If not explicitly set, then the ThreadGroup's handler is returned. If the thread is terminated, then null is returned.

Returns:
An UncaughtExceptionHandler instance or null.
Since:
1.5

void java.lang.Thread.interrupt (  ) 

Posts an interrupt request to the receiver.

Exceptions:
SecurityException if group.checkAccess() fails with a SecurityException
See also:
java.lang.SecurityException

java.lang.SecurityManager

Thread.interrupted

Thread.isInterrupted

static boolean java.lang.Thread.interrupted (  )  [static]

Answers a boolean indicating whether the current Thread ( currentThread()) has a pending interrupt request ( true) or not (false).

It also has the side-effect of clearing the flag.

Returns:
a boolean
See also:
Thread.currentThread

Thread.interrupt

Thread.isInterrupted

final boolean java.lang.Thread.isAlive (  ) 

Answers true if the receiver has already been started and still runs code (hasn't died yet).

Answers false either if the receiver hasn't been started yet or if it has already started and run to completion and died.

Returns:
a boolean
See also:
Thread.start

final boolean java.lang.Thread.isDaemon (  ) 

Answers a boolean indicating whether the receiver is a daemon Thread (true) or not (false) A daemon Thread only runs as long as there are non-daemon Threads running.

When the last non-daemon Thread ends, the whole program ends no matter if it had daemon Threads still running or not.

Returns:
a boolean
See also:
Thread.setDaemon

boolean java.lang.Thread.isInterrupted (  ) 

Answers a boolean indicating whether the receiver has a pending interrupt request (true) or not ( false).

Returns:
a boolean
See also:
Thread.interrupt

Thread.interrupted

final void java.lang.Thread.join (  )  throws InterruptedException

Blocks the current Thread (Thread.currentThread()) until the receiver finishes its execution and dies.

Exceptions:
InterruptedException if interrupt() was called for the receiver while it was in the join() call
See also:
Object.notifyAll

java.lang.ThreadDeath

final void java.lang.Thread.join ( long  timeoutInMilliseconds  )  throws InterruptedException

Blocks the current Thread (Thread.currentThread()) until the receiver finishes its execution and dies or the specified timeout expires, whatever happens first.

Parameters:
timeoutInMilliseconds The maximum time to wait (in milliseconds).
Exceptions:
InterruptedException if interrupt() was called for the receiver while it was in the join() call
See also:
Object.notifyAll

java.lang.ThreadDeath

final void java.lang.Thread.join ( long  timeoutInMilliseconds,
int  nanos 
) throws InterruptedException

Blocks the current Thread (Thread.currentThread()) until the receiver finishes its execution and dies or the specified timeout expires, whatever happens first.

Parameters:
timeoutInMilliseconds The maximum time to wait (in milliseconds).
nanos Extra nanosecond precision
Exceptions:
InterruptedException if interrupt() was called for the receiver while it was in the join() call
See also:
Object.notifyAll

java.lang.ThreadDeath

final void java.lang.Thread.resume (  ) 

This is a no-op if the receiver was never suspended, or suspended and already resumed.

If the receiver is suspended, however, makes it resume to the point where it was when it was suspended.

Exceptions:
SecurityException if checkAccess() fails with a SecurityException
See also:
Thread.suspend()
Deprecated:
Used with deprecated method Thread.suspend().

void java.lang.Thread.run (  ) 

Calls the run() method of the Runnable object the receiver holds.

If no Runnable is set, does nothing.

See also:
Thread.start

void java.lang.Thread.setContextClassLoader ( ClassLoader  cl  ) 

Set the context ClassLoader for the receiver.

Parameters:
cl The context ClassLoader
See also:
java.lang.ClassLoader

getContextClassLoader()

final void java.lang.Thread.setDaemon ( boolean  isDaemon  ) 

Set if the receiver is a daemon Thread or not.

This can only be done before the Thread starts running.

Parameters:
isDaemon A boolean indicating if the Thread should be daemon or not
Exceptions:
SecurityException if checkAccess() fails with a SecurityException
See also:
Thread.isDaemon

static void java.lang.Thread.setDefaultUncaughtExceptionHandler ( UncaughtExceptionHandler  handler  )  [static]

Sets the default uncaught exception handler.

The RuntimePermission("setDefaultUncaughtExceptionHandler") is checked prior to setting the handler.

Parameters:
handler The handler to set or null.
Exceptions:
SecurityException if the current SecurityManager fails the checkPermission call.
Since:
1.5

final void java.lang.Thread.setName ( String  threadName  ) 

Sets the name of the receiver.

Parameters:
threadName new name for the Thread
Exceptions:
SecurityException if checkAccess() fails with a SecurityException
See also:
Thread.getName

final void java.lang.Thread.setPriority ( int  priority  ) 

Sets the priority of the receiver.

Note that the final priority set may not be the parameter that was passed - it will depend on the receiver's ThreadGroup. The priority cannot be set to be higher than the receiver's ThreadGroup's maxPriority().

Parameters:
priority new priority for the Thread
Exceptions:
SecurityException if checkAccess() fails with a SecurityException
IllegalArgumentException if the new priority is greater than Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY
See also:
Thread.getPriority

void java.lang.Thread.setThreadLocal ( ThreadLocal<?>  local,
Object  value 
) [package]

A sample implementation of this method is provided by the reference implementation.

It must be included, as it is called by ThreadLocal.set() and InheritableThreadLocal.set(). Set the value associated with the ThreadLocal in the receiver to be value.

Parameters:
local ThreadLocal to set
value new value for the ThreadLocal
See also:
getThreadLocal

void java.lang.Thread.setUncaughtExceptionHandler ( UncaughtExceptionHandler  handler  ) 

Sets the default uncaught exception handler.

Parameters:
handler The handler to set or null.
Exceptions:
SecurityException if the current SecurityManager fails the checkAccess call.
Since:
1.5

static void java.lang.Thread.sleep ( long  time  )  throws InterruptedException [static]

Causes the thread which sent this message to sleep an interval of time (given in milliseconds).

The precision is not guaranteed - the Thread may sleep more or less than requested.

Parameters:
time The time to sleep in milliseconds.
Exceptions:
InterruptedException if interrupt() was called for this Thread while it was sleeping
See also:
Thread.interrupt()

static void java.lang.Thread.sleep ( long  time,
int  nanos 
) throws InterruptedException [static]

Causes the thread which sent this message to sleep an interval of time (given in milliseconds).

The precision is not guaranteed - the Thread may sleep more or less than requested.

Parameters:
time The time to sleep in milliseconds.
nanos Extra nanosecond precision
Exceptions:
InterruptedException if interrupt() was called for this Thread while it was sleeping
See also:
Thread.interrupt()

void java.lang.Thread.start (  ) 

Starts the new Thread of execution.

The run() method of the receiver will be called by the receiver Thread itself (and not the Thread calling start()).

Exceptions:
IllegalThreadStateException Unspecified in the Java language specification
See also:
Thread.run

final void java.lang.Thread.stop (  ) 

Requests the receiver Thread to stop and throw ThreadDeath.

The Thread is resumed if it was suspended and awakened if it was sleeping, so that it can proceed to throw ThreadDeath.

Exceptions:
SecurityException if checkAccess() fails with a SecurityException
Deprecated:

final void java.lang.Thread.stop ( Throwable  throwable  ) 

Requests the receiver Thread to stop and throw the throwable().

The Thread is resumed if it was suspended and awakened if it was sleeping, so that it can proceed to throw the throwable().

Parameters:
throwable Throwable object to be thrown by the Thread
Exceptions:
SecurityException if checkAccess() fails with a SecurityException
NullPointerException if throwable() is null
Deprecated:

final void java.lang.Thread.suspend (  ) 

This is a no-op if the receiver is suspended.

If the receiver isAlive() however, suspended it until resume() is sent to it. Suspend requests are not queued, which means that N requests are equivalent to just one - only one resume request is needed in this case.

Exceptions:
SecurityException if checkAccess() fails with a SecurityException
See also:
Thread.resume()
Deprecated:
May cause deadlocks.

String java.lang.Thread.toString (  ) 

Answers a string containing a concise, human-readable description of the receiver.

Returns:
a printable representation for the receiver.

static void java.lang.Thread.yield (  )  [static]

Causes the thread which sent this message to yield execution to another Thread that is ready to run.

The actual scheduling is implementation-dependent.

static boolean java.lang.Thread.holdsLock ( Object  object  )  [static]

Returns whether the current thread has a monitor lock on the specified object.

Parameters:
object the object to test for the monitor lock
Returns:
true when the current thread has a monitor lock on the specified object


Member Data Documentation

final int java.lang.Thread.MAX_PRIORITY = 10 [static]

The maximum priority value allowed for a thread.

final int java.lang.Thread.MIN_PRIORITY = 1 [static]

The minimum priority value allowed for a thread.

final int java.lang.Thread.NORM_PRIORITY = 5 [static]

The normal (default) priority value assigned to threads.


The documentation for this class was generated from the following file:

Genereated on Tue Dec 9 14:09:48 2008 by Doxygen.

(c) Copyright 2005, 2008 The Apache Software Foundation or its licensors, as applicable.