to top
Android APIs
public class

Thread

extends Object
implements Runnable
java.lang.Object
   ↳ java.lang.Thread
Known Direct Subclasses

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 Threads in the running Thread's group and its subgroups.
final void checkAccess()
Does nothing.
int countStackFrames()
This method was deprecated in API level 1. 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 was deprecated in API level 1. 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<ThreadStackTraceElement[]> getAllStackTraces()
Returns a map of all the currently live threads to their stack traces.
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 an array of StackTraceElement representing the current thread's stack.
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 was deprecated in API level 1. 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 was deprecated in API level 1. 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 was deprecated in API level 1. 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 was deprecated in API level 1. 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
From interface java.lang.Runnable

Constants

public static final int MAX_PRIORITY

Added in API level 1

The maximum priority value allowed for a thread.

Constant Value: 10 (0x0000000a)

public static final int MIN_PRIORITY

Added in API level 1

The minimum priority value allowed for a thread.

Constant Value: 1 (0x00000001)

public static final int NORM_PRIORITY

Added in API level 1

The normal (default) priority value assigned to threads.

Constant Value: 5 (0x00000005)

Public Constructors

public Thread ()

Added in 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)

Added in 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)

Added in 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)

Added in 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)

Added in 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
IllegalThreadStateException if group.destroy() has already been done

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

Added in 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
IllegalThreadStateException if group.destroy() has already been done

public Thread (ThreadGroup group, String threadName)

Added in 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
IllegalThreadStateException if group.destroy() has already been done

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

Added in 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
IllegalThreadStateException if group.destroy() has already been done

Public Methods

public static int activeCount ()

Added in 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 ()

Added in API level 1

Does nothing.

public int countStackFrames ()

Added in API level 1

This method was deprecated in API level 1.
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 ()

Added in API level 1

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

Returns
  • the current Thread.

public void destroy ()

Added in API level 1

This method was deprecated in API level 1.
Not implemented.

Destroys the receiver without any monitor cleanup.

public static void dumpStack ()

Added in 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)

Added in 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

public static Map<ThreadStackTraceElement[]> getAllStackTraces ()

Added in API level 1

Returns a map of all the currently live threads to their stack traces.

public ClassLoader getContextClassLoader ()

Added in API level 1

Returns the context ClassLoader for this Thread.

Returns
  • ClassLoader The context ClassLoader

public static Thread.UncaughtExceptionHandler getDefaultUncaughtExceptionHandler ()

Added in API level 1

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

Returns

public long getId ()

Added in 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 ()

Added in API level 1

Returns the name of the Thread.

Returns
  • the Thread's name

public final int getPriority ()

Added in API level 1

Returns the priority of the Thread.

Returns
  • the Thread's priority
See Also

public StackTraceElement[] getStackTrace ()

Added in API level 1

Returns an array of StackTraceElement representing the current thread's stack.

public Thread.State getState ()

Added in API level 1

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

Returns

public final ThreadGroup getThreadGroup ()

Added in API level 1

Returns the ThreadGroup to which this Thread belongs.

Returns
  • the Thread's ThreadGroup

public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler ()

Added in 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

public static boolean holdsLock (Object object)

Added in 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 ()

Added in API level 1

Posts an interrupt request to this Thread. The 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.

public static boolean interrupted ()

Added in 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 ()

Added in 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
See Also

public final boolean isDaemon ()

Added in 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 ()

Added in 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 ()

Added in 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)

Added in 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)

Added in 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 ()

Added in API level 1

This method was deprecated in API level 1.
Used with deprecated method suspend()

Throws UnsupportedOperationException.

See Also

public void run ()

Added in API level 1

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

See Also

public void setContextClassLoader (ClassLoader cl)

Added in API level 1

Set the context ClassLoader for the receiver.

Parameters
cl The context ClassLoader

public final void setDaemon (boolean isDaemon)

Added in 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
See Also

public static void setDefaultUncaughtExceptionHandler (Thread.UncaughtExceptionHandler handler)

Added in API level 1

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

Parameters
handler The handler to set or null.

public final void setName (String threadName)

Added in API level 1

Sets the name of the Thread.

Parameters
threadName the new name for the Thread
See Also

public final void setPriority (int priority)

Added in 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
IllegalArgumentException if the new priority is greater than Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY
See Also

public void setUncaughtExceptionHandler (Thread.UncaughtExceptionHandler handler)

Added in 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.

public static void sleep (long millis, int nanos)

Added in 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
See Also

public static void sleep (long time)

Added in 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
See Also

public synchronized void start ()

Added in 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
See Also

public final synchronized void stop (Throwable throwable)

Added in API level 1

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

Throws UnsupportedOperationException.

Throws
NullPointerException if throwable() is null

public final void stop ()

Added in API level 1

This method was deprecated in API level 1.
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.

public final void suspend ()

Added in API level 1

This method was deprecated in API level 1.
May cause deadlocks.

Throws UnsupportedOperationException.

See Also

public String toString ()

Added in 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 ()

Added in 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.