Since: API Level 1

public class

Thread

extends Object
implements Runnable

java.lang.Object
↳	java.lang.Thread

Known Direct Subclasses

HandlerThread

Class Overview

A Thread is a concurrent unit of execution. It has its own call stack for methods being invoked, their arguments and local variables. Each virtual machine instance has at least one main Thread running when it is started; typically, there are several others for housekeeping. The application might decide to launch additional Threads for specific purposes.

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.

There are basically two main ways of having a Thread execute application code. One is providing a new class that extends Thread and overriding its run() method. The other is providing a new Thread instance with a Runnable object during its creation. In both cases, the start() method must be called to actually execute the new Thread.

Each Thread has an integer priority that basically determines the amount of CPU time the Thread gets. It can be set using the setPriority(int) method. A Thread can also be made a daemon, which makes it run in the background. The latter also affects VM termination behavior: the VM does not terminate automatically as long as there are non-daemon threads running.

Summary

Nested Classes
enum	Thread.State	A representation of a thread's state.
interface	Thread.UncaughtExceptionHandler	Implemented by objects that want to handle cases where a thread is being terminated by an uncaught exception.

Constants
int	MAX_PRIORITY	The maximum priority value allowed for a thread.
int	MIN_PRIORITY	The minimum priority value allowed for a thread.
int	NORM_PRIORITY	The normal (default) priority value assigned to threads.

Public Constructors
	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) 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.
	Thread(ThreadGroup group, Runnable runnable, String threadName, long stackSize) Constructs a new `Thread` with a `Runnable` object, the given name and belonging to the `ThreadGroup` passed as parameter.

Public Methods
static int	activeCount() Returns the number of active `Thread`s in the running `Thread`'s group and its subgroups.
final void	checkAccess() Is used for operations that require approval from a SecurityManager.
int	countStackFrames() This method is deprecated. The results of this call were never well defined. To make things worse, it would depend on whether the Thread was suspended or not, and suspend was deprecated too.
static Thread	currentThread() Returns the Thread of the caller, that is, the current Thread.
void	destroy() This method is deprecated. Not implemented.
static void	dumpStack() Prints to the standard error stream a text representation of the current 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() Returns the stack traces of all the currently live threads and puts them into the given map.
ClassLoader	getContextClassLoader() Returns the context ClassLoader for this Thread.
static Thread.UncaughtExceptionHandler	getDefaultUncaughtExceptionHandler() Returns the default exception handler that's executed when uncaught exception terminates a thread.
long	getId() Returns the thread's identifier.
final String	getName() Returns the name of the Thread.
final int	getPriority() Returns the priority of the Thread.
StackTraceElement[]	getStackTrace() Returns the a stack trace representing the current execution state of this Thread.
Thread.State	getState() Returns the current state of the Thread.
final ThreadGroup	getThreadGroup() Returns the ThreadGroup to which this Thread belongs.
Thread.UncaughtExceptionHandler	getUncaughtExceptionHandler() Returns the thread's uncaught exception handler.
static boolean	holdsLock(Object object) Indicates whether the current Thread has a monitor lock on the specified object.
void	interrupt() Posts an interrupt request to this `Thread`.
static boolean	interrupted() Returns a `boolean` indicating whether the current Thread ( `currentThread()`) has a pending interrupt request (`true`) or not (`false`).
final boolean	isAlive() Returns `true` if the receiver has already been started and still runs code (hasn't died yet).
final boolean	isDaemon() Returns 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() Returns a `boolean` indicating whether the receiver has a pending interrupt request (`true`) or not ( `false`)
final void	join() Blocks the current Thread (`Thread.currentThread()`) until the receiver finishes its execution and dies.
final void	join(long millis, int nanos) 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 millis) 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 method is deprecated. Used with deprecated method `suspend()`
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.
static void	setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler handler) Sets the default uncaught exception handler.
final void	setName(String threadName) Sets the name of the Thread.
final void	setPriority(int priority) Sets the priority of the Thread.
void	setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler handler) Sets the uncaught exception handler.
static void	sleep(long millis, int nanos) Causes the thread which sent this message to sleep for the given interval of time (given in milliseconds and nanoseconds).
static void	sleep(long time) Causes the thread which sent this message to sleep for the given interval of time (given in milliseconds).
synchronized void	start() Starts the new Thread of execution.
synchronized final void	stop(Throwable throwable) This method is deprecated. because stopping a thread in this manner is unsafe and can leave your application and the VM in an unpredictable state.
final void	stop() This method is deprecated. because stopping a thread in this manner is unsafe and can leave your application and the VM in an unpredictable state.
final void	suspend() This method is deprecated. May cause deadlocks.
String	toString() Returns a string containing a concise, human-readable description of the Thread.
static void	yield() Causes the calling Thread to yield execution time to another Thread that is ready to run.

[Expand]

Inherited Methods

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Called before the object's memory is reclaimed by the VM.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

From interface java.lang.Runnable

Constants

public static final int MAX_PRIORITY

Since: API Level 1

The maximum priority value allowed for a thread.

Constant Value: 10 (0x0000000a)

public static final int MIN_PRIORITY

Since: API Level 1

The minimum priority value allowed for a thread.

Constant Value: 1 (0x00000001)

public static final int NORM_PRIORITY

Since: API Level 1

The normal (default) priority value assigned to threads.

Constant Value: 5 (0x00000005)

Public Constructors

public Thread ()

Since: API Level 1

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.

public Thread (Runnable runnable)

Since: API Level 1

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 `Runnable` whose method `run` will be executed by the new `Thread`

public Thread (Runnable runnable, String threadName)

Since: API Level 1

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 `Runnable` whose method `run` will be executed by the new `Thread`
threadName	the name for the `Thread` being created

public Thread (String threadName)

Since: API Level 1

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	the name for the `Thread` being created

public Thread (ThreadGroup group, Runnable runnable)

Since: API Level 1

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 `Runnable` whose method `run` will be executed by the new `Thread`

Throws

SecurityException	if `group.checkAccess()` fails with a SecurityException
IllegalThreadStateException	if `group.destroy()` has already been done

public Thread (ThreadGroup group, Runnable runnable, String threadName)

Since: API Level 1

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 `Runnable` whose method `run` will be executed by the new `Thread`
threadName	the name for the `Thread` being created

Throws

SecurityException	if `group.checkAccess()` fails with a SecurityException
IllegalThreadStateException	if `group.destroy()` has already been done

public Thread (ThreadGroup group, String threadName)

Since: API Level 1

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	the name for the `Thread` being created

Throws

SecurityException	if `group.checkAccess()` fails with a SecurityException
IllegalThreadStateException	if `group.destroy()` has already been done

public Thread (ThreadGroup group, Runnable runnable, String threadName, long stackSize)

Since: API Level 1

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 `Runnable` whose method `run` will be executed by the new `Thread`
threadName	the name for the `Thread` being created
stackSize	a stack size for the new `Thread`. This has a highly platform-dependent interpretation. It may even be ignored completely.

Throws

SecurityException	if `group.checkAccess()` fails with a SecurityException
IllegalThreadStateException	if `group.destroy()` has already been done

Public Methods

public static int activeCount ()

Since: API Level 1

Returns the number of active Threads in the running Thread's group and its subgroups.

Returns

the number of Threads

public final void checkAccess ()

Since: API Level 1

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, checkAccess(Thread) is called for that SecurityManager.

Throws

SecurityException	if a SecurityManager is installed and it does not allow access to the Thread.

public int countStackFrames ()

Since: API Level 1

This method is deprecated.
The results of this call were never well defined. To make things worse, it would depend on whether the Thread was suspended or not, and suspend was deprecated too.

Returns the number of stack frames in this thread.

Returns

Number of stack frames

public static Thread currentThread ()

Since: API Level 1

Returns the Thread of the caller, that is, the current Thread.

Returns

the current Thread.

public void destroy ()

Since: API Level 1

This method is deprecated.
Not implemented.

Destroys the receiver without any monitor cleanup.

public static void dumpStack ()

Since: API Level 1

Prints to the standard error stream a text representation of the current stack for this Thread.

public static int enumerate (Thread[] threads)

Since: API Level 1

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

Throws

SecurityException	if the installed SecurityManager fails `checkAccess(Thread)`

public static Map<Thread, StackTraceElement[]> getAllStackTraces ()

Since: API Level 1

Returns the stack traces of all the currently live threads and puts them into the given map.

Returns

A Map of current Threads to StackTraceElement arrays.

Throws

SecurityException	if the current SecurityManager fails the `checkPermission(java.security.Permission)` call.

public ClassLoader getContextClassLoader ()

Since: API Level 1

Returns the context ClassLoader for this Thread.

If the conditions

there is a security manager
the caller's class loader is not null
the caller's class loader is not the same as the requested context class loader and not an ancestor thereof

are satisfied, a security check for RuntimePermission("getClassLoader") is performed first.

Returns

ClassLoader The context ClassLoader

Throws

SecurityException	if the aforementioned security check fails.

public static Thread.UncaughtExceptionHandler getDefaultUncaughtExceptionHandler ()

Since: API Level 1

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

Returns

an Thread.UncaughtExceptionHandler or null if none exists.

public long getId ()

Since: API Level 1

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 lifetime of the thread; the ID may be reused after the thread has been terminated.

Returns

the thread's ID.

public final String getName ()

Since: API Level 1

Returns the name of the Thread.

Returns

the Thread's name

public final int getPriority ()

Since: API Level 1

Returns the priority of the Thread.

Returns

the Thread's priority

public StackTraceElement[] getStackTrace ()

Since: API Level 1

Returns the a stack trace representing the current execution state of this Thread.

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

Returns

an array of StackTraceElements.

Throws

SecurityException	if the current SecurityManager fails the `checkPermission(java.security.Permission)` call.

public Thread.State getState ()

Since: API Level 1

Returns the current state of the Thread. This method is useful for monitoring purposes.

Returns

a Thread.State value.

public final ThreadGroup getThreadGroup ()

Since: API Level 1

Returns the ThreadGroup to which this Thread belongs.

Returns

the Thread's ThreadGroup

public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler ()

Since: API Level 1

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 Thread.UncaughtExceptionHandler instance or null.

public static boolean holdsLock (Object object)

Since: API Level 1

Indicates whether the current Thread has a monitor lock on the specified object.

Parameters

object	the object to test for the monitor lock

Returns

true if the current thread has a monitor lock on the specified object; false otherwise

public void interrupt ()

Since: API Level 1

Posts an interrupt request to this Thread. Unless the caller is the currentThread(), the method checkAccess() is called for the installed SecurityManager, if any. This may result in a SecurityException being thrown. The further behavior depends on the state of this Thread:

Threads blocked in one of Object's wait() methods or one of Thread's join() or sleep() methods will be woken up, their interrupt status will be cleared, and they receive an InterruptedException.
Threads blocked in an I/O operation of an InterruptibleChannel will have their interrupt status set and receive an ClosedByInterruptException. Also, the channel will be closed.
Threads blocked in a Selector will have their interrupt status set and return immediately. They don't receive an exception in this case.

Throws

SecurityException	if `checkAccess()` fails with a SecurityException

public static boolean interrupted ()

Since: API Level 1

Returns 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 indicating the interrupt status

public final boolean isAlive ()

Since: API Level 1

Returns true if the receiver has already been started and still runs code (hasn't died yet). Returns 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 indicating the liveness of the Thread

public final boolean isDaemon ()

Since: API Level 1

Returns 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 indicating whether the Thread is a daemon

public boolean isInterrupted ()

Since: API Level 1

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

Returns

a boolean indicating the interrupt status

public final void join ()

Since: API Level 1

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

Throws

InterruptedException	if `interrupt()` was called for the receiver while it was in the `join()` call

public final void join (long millis, int nanos)

Since: API Level 1

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

Parameters

millis	The maximum time to wait (in milliseconds).
nanos	Extra nanosecond precision

Throws

InterruptedException	if `interrupt()` was called for the receiver while it was in the `join()` call

public final void join (long millis)

Since: API Level 1

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

Parameters

millis	The maximum time to wait (in milliseconds).

Throws

InterruptedException	if `interrupt()` was called for the receiver while it was in the `join()` call

public final void resume ()

Since: API Level 1

This method is deprecated.
Used with deprecated method suspend()

Resumes a suspended Thread. 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.

Throws

SecurityException	if `checkAccess()` fails with a SecurityException

public void run ()

Since: API Level 1

Calls the run() method of the Runnable object the receiver holds. If no Runnable is set, does nothing.

public void setContextClassLoader (ClassLoader cl)

Since: API Level 1

Set the context ClassLoader for the receiver.

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

Parameters

cl	The context ClassLoader

Throws

SecurityException	if the current SecurityManager fails the checkPermission call.

public final void setDaemon (boolean isDaemon)

Since: API Level 1

Set if the receiver is a daemon Thread or not. This can only be done before the Thread starts running.

Parameters

isDaemon	indicates whether the Thread should be daemon or not

Throws

SecurityException	if `checkAccess()` fails with a SecurityException

public static void setDefaultUncaughtExceptionHandler (Thread.UncaughtExceptionHandler handler)

Since: API Level 1

Sets the default uncaught exception handler. This handler is invoked in case any Thread dies due to an unhandled exception.

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

Parameters

handler	The handler to set or `null`.

Throws

SecurityException	if the current SecurityManager fails the checkPermission call.

public final void setName (String threadName)

Since: API Level 1

Sets the name of the Thread.

Parameters

threadName	the new name for the Thread

Throws

SecurityException	if `checkAccess()` fails with a SecurityException

public final void setPriority (int priority)

Since: API Level 1

Sets the priority of the Thread. 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

Throws

SecurityException	if `checkAccess()` fails with a SecurityException
IllegalArgumentException	if the new priority is greater than Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY

public void setUncaughtExceptionHandler (Thread.UncaughtExceptionHandler handler)

Since: API Level 1

Sets the uncaught exception handler. This handler is invoked in case this Thread dies due to an unhandled exception.

Parameters

handler	The handler to set or `null`.

Throws

SecurityException	if the current SecurityManager fails the checkAccess call.

public static void sleep (long millis, int nanos)

Since: API Level 1

Causes the thread which sent this message to sleep for the given interval of time (given in milliseconds and nanoseconds). The precision is not guaranteed - the Thread may sleep more or less than requested.

Parameters

millis	The time to sleep in milliseconds.
nanos	Extra nanosecond precision

Throws

InterruptedException	if `interrupt()` was called for this Thread while it was sleeping

public static void sleep (long time)

Since: API Level 1

Causes the thread which sent this message to sleep for the given 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.

Throws

InterruptedException	if `interrupt()` was called for this Thread while it was sleeping

public synchronized void start ()

Since: API Level 1

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

Throws

IllegalThreadStateException	if the Thread has been started before

public final synchronized void stop (Throwable throwable)

Since: API Level 1

This method is deprecated.
because stopping a thread in this manner is unsafe and can leave your application and the VM in an unpredictable state.

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

Throws

SecurityException	if `checkAccess()` fails with a SecurityException
NullPointerException	if `throwable()` is `null`

public final void stop ()

Since: API Level 1

This method is deprecated.
because stopping a thread in this manner is unsafe and can leave your application and the VM in an unpredictable state.

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.

Throws

SecurityException	if `checkAccess()` fails with a SecurityException

public final void suspend ()

Since: API Level 1

This method is deprecated.
May cause deadlocks.

Suspends this Thread. 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.

Throws

SecurityException	if `checkAccess()` fails with a SecurityException

public String toString ()

Since: API Level 1

Returns a string containing a concise, human-readable description of the Thread. It includes the Thread's name, priority, and group name.

Returns

a printable representation for the receiver.

public static void yield ()

Since: API Level 1

Causes the calling Thread to yield execution time to another Thread that is ready to run. The actual scheduling is implementation-dependent.

Interfaces

Classes

Enums

Exceptions

Errors

Thread

Class Overview

See Also

Summary

Constants

public static final int MAX_PRIORITY

public static final int MIN_PRIORITY

public static final int NORM_PRIORITY

Public Constructors

public Thread ()

See Also

public Thread (Runnable runnable)

Parameters

See Also

public Thread (Runnable runnable, String threadName)

Parameters

See Also

public Thread (String threadName)

Parameters

See Also

public Thread (ThreadGroup group, Runnable runnable)

Parameters

Throws

See Also

public Thread (ThreadGroup group, Runnable runnable, String threadName)

Parameters

Throws

See Also

public Thread (ThreadGroup group, String threadName)

Parameters

Throws

See Also

public Thread (ThreadGroup group, Runnable runnable, String threadName, long stackSize)

Parameters

Throws

See Also

Public Methods

public static int activeCount ()

Returns

public final void checkAccess ()

Throws

See Also

public int countStackFrames ()

Returns

public static Thread currentThread ()

Returns

public void destroy ()

public static void dumpStack ()

See Also

public static int enumerate (Thread[] threads)

Parameters

Returns

Throws

See Also

public static Map<Thread, StackTraceElement[]> getAllStackTraces ()

Returns

Throws

public ClassLoader getContextClassLoader ()

Returns

Throws

See Also

public static Thread.UncaughtExceptionHandler getDefaultUncaughtExceptionHandler ()

Returns

public long getId ()

Returns

public final String getName ()

Returns

public final int getPriority ()

Returns

See Also

public StackTraceElement[] getStackTrace ()

Returns

Throws

public Thread.State getState ()

Returns