Android
java.lang
public class

java.lang.Thread

java.lang.Object
java.lang.Thread Runnable

A Thread is a unit of concurrent execution. 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.

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

See Also

Summary

Constants

      Value  
int  MAX_PRIORITY 

The maximum priority value allowed for a thread. 

10  0x0000000a 
int  MIN_PRIORITY 

The minimum priority value allowed for a thread. 

0x00000001 
int  NORM_PRIORITY 

The normal (default) priority value assigned to threads. 

0x00000005 

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 ThreadGroup and its subgroups.
    final      void  checkAccess()
This method 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 if the Thread was suspended or not, and suspend was deprecated too.
      static    Thread  currentThread()
Returns the instance of Thread that corresponds to the running Thread which calls this method.
          void  destroy()
This method is deprecated. Not implemented.
      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<ThreadStackTraceElement[] 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 the receiver.
      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 receiver.
    final      int  getPriority()
Returns the priority of the receiver.
          StackTraceElement[]  getStackTrace()

Returns the current stack trace of the thread.

          Thread.State  getState()

Returns the current state of the thread for monitoring purposes.

    final      ThreadGroup  getThreadGroup()
Returns the ThreadGroup to which the receiver belongs
          Thread.UncaughtExceptionHandler  getUncaughtExceptionHandler()

Returns the thread's uncaught exception handler.

      static    boolean  holdsLock(Object object)
Returns whether the current thread has a monitor lock on the specified object.
          void  interrupt()
Posts an interrupt request to the receiver.
      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 receiver.
    final      void  setPriority(int priority)
Sets the priority of the receiver.
          void  setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler handler)

Sets the default uncaught exception handler.

      static    void  sleep(long time, int nanos)
Causes the thread which sent this message to sleep an interval of time (given in milliseconds).
      static    void  sleep(long time)
Causes the thread which sent this message to sleep an interval of time (given in milliseconds).
  synchronized        void  start()
Starts the new Thread of execution.
    final      void  stop()
Requests the receiver Thread to stop and throw ThreadDeath.
  synchronized  final      void  stop(Throwable throwable)
Requests the receiver Thread to stop and throw the throwable().
    final      void  suspend()
This method is deprecated. May cause deadlocks.
          String  toString()
Returns a string containing a concise, human-readable description of the receiver.
      static    void  yield()
Causes the thread which sent this message to yield execution to another Thread that is ready to run.
Methods inherited from class java.lang.Object
Methods inherited from interface java.lang.Runnable

Details

Constants

public static final int MAX_PRIORITY

The maximum priority value allowed for a thread.

Constant Value: 10 (0x0000000a)

public static final int MIN_PRIORITY

The minimum priority value allowed for a thread.

Constant Value: 1 (0x00000001)

public static final int NORM_PRIORITY

The normal (default) priority value assigned to threads.

Constant Value: 5 (0x00000005)

Public Constructors

public 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

public 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

public 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

public 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

public 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

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)

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

Throws

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

public 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

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)

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
stackSize Platform dependent stack size

Throws

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

Public Methods

public static int activeCount()

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

Returns

  • Number of Threads

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

public int countStackFrames()

This method is 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.

Returns the number of stack frames in this thread.

Returns

  • Number of stack frames

public static Thread currentThread()

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

public void destroy()

This method is deprecated. Not implemented.

Destroys the receiver without any monitor cleanup.

public static void dumpStack()

Prints a text representation of the stack for this Thread.

public 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. 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<ThreadStackTraceElement[]> getAllStackTraces()

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

Returns the context ClassLoader for the receiver.

If the conditions

  1. there is a security manager
  2. the caller's class loader is not null
  3. the caller's class loader is not the same as or an ancestor of contextClassLoader
are satisfied, a security check for RuntimePermission("getClassLoader") is performed first.

Returns

  • ClassLoader The context ClassLoader

Throws

SecurityException If aforementioned security check fails.

public static Thread.UncaughtExceptionHandler getDefaultUncaughtExceptionHandler()

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

Returns

public long 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.

public final String getName()

Returns the name of the receiver.

Returns

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

public final int getPriority()

Returns the priority of the receiver.

Returns

  • the receiver's priority (an int)

See Also

public StackTraceElement[] getStackTrace()

Returns the current stack trace of the 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()

Returns the current state of the thread for monitoring purposes.

Returns

  • A State value.

public final ThreadGroup getThreadGroup()

Returns the ThreadGroup to which the receiver belongs

Returns

  • the receiver's ThreadGroup

public Thread.UncaughtExceptionHandler 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.

public static boolean holdsLock(Object object)

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

public void interrupt()

Posts an interrupt request to the receiver.

Throws

SecurityException if checkAccess() fails with a SecurityException

public static boolean interrupted()

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

public final boolean isAlive()

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

See Also

public 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. 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

public boolean isInterrupted()

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

Returns

  • a boolean

public final void join()

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)

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)

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

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

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

See Also

public void run()

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)

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)

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

Throws

SecurityException if checkAccess() fails with a SecurityException

See Also

public static void setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler handler)

Sets the default uncaught exception handler.

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)

Sets the name of the receiver.

Parameters

threadName new name for the Thread

Throws

SecurityException if checkAccess() fails with a SecurityException

See Also

public final void 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

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

See Also

public void setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler handler)

Sets the default uncaught exception handler.

Parameters

handler The handler to set or null.

Throws

SecurityException if the current SecurityManager fails the checkAccess call.

public static void sleep(long time, int nanos)

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

Throws

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

See Also

public static void sleep(long time)

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.

Throws

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

See Also

public synchronized void 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()).

Throws

IllegalThreadStateException Unspecified in the Java language specification

See Also

public final void 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.

Throws

SecurityException if checkAccess() fails with a SecurityException

public final synchronized void 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

Throws

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

public final void suspend()

This method is deprecated. May cause deadlocks.

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

See Also

public String toString()

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

Returns

  • a printable representation for the receiver.

public static void yield()

Causes the thread which sent this message to yield execution to another Thread that is ready to run. The actual scheduling is implementation-dependent.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48