java.lang
Class ThreadGroup

java.lang.Object
  java.lang.ThreadGroup

All Implemented Interfaces:

Thread.UncaughtExceptionHandler

public class ThreadGroup
extends Object
implements Thread.UncaughtExceptionHandler

A ThreadGroup is a means of organizing Threads into a hierarchical structure. A ThreadGroup can contain zero or more Threads and zero or more other ThreadGroups. Each Thread and each ThreadGroup (except the root group) has a unique parent ThreadGroup. The result is a tree whose inner nodes are ThreadGroups and whose leaf nodes are Threads. The unique root of the tree is a ThreadGroup that is created at VM startup and has the name "system". The benefit of using ThreadGroups, in addition to the mere housekeeping aspect, is that all Threads in a ThreadGroup can be manipulated together, that is, the ThreadGroup has methods that delegate to all its all Threads.

Since:

Android 1.0

See Also:

Thread, SecurityManager

Field Summary

(package private) static ThreadGroup	mMain
(package private) static ThreadGroup	mSystem
(package private) int	numGroups
(package private) int	numThreads
(package private) ThreadGroup	parent

Constructor Summary

ThreadGroup()
Initialize the special "system" ThreadGroup.

ThreadGroup(String name)
Constructs a new ThreadGroup with the name provided.

ThreadGroup(ThreadGroup parent, String name)
Constructs a new ThreadGroup with the name provided, as child of the ThreadGroup parent.

Method Summary

int	activeCount() Returns the number of Threads which are children of the receiver, directly or indirectly and are running.
int	activeGroupCount() Returns the number of ThreadGroups which are children of the receiver, directly or indirectly.
(package private) void	add(Thread thread) Adds a Thread to the receiver.
(package private) void	addThread(Thread thread) Non-standard method for adding a thread to a group, required by Dalvik.
boolean	allowThreadSuspension(boolean b) Deprecated. Required deprecated method suspend().
void	checkAccess() Checks the accessibility of the ThreadGroup from the perspective of the caller.
void	destroy() Destroys the receiver and recursively all its subgroups.
int	enumerate(Thread[] threads) Iterates over all active threads in this group (and its sub-groups) and stores the threads in the given array.
int	enumerate(Thread[] threads, boolean recurse) Iterates over all active threads in this group (and, optionally, its sub-groups) and stores the threads in the given array.
int	enumerate(ThreadGroup[] groups) Iterates over all thread groups in this group (and its sub-groups) and and stores the groups in the given array.
int	enumerate(ThreadGroup[] groups, boolean recurse) Iterates over all thread groups in this group (and, optionally, its sub-groups) and and stores the groups in the given array.
int	getMaxPriority() Returns the maximum allowed priority for a Thread in the receiver.
String	getName() Returns the name of the receiver.
ThreadGroup	getParent() Returns the receiver's parent ThreadGroup.
void	interrupt() Interrupts every Thread in the receiver and recursively in all its subgroups.
boolean	isDaemon() Checks whether the receiver is a daemon ThreadGroup.
boolean	isDestroyed() Checks whether the receiver has already been destroyed.
void	list() Outputs to System.out a text representation of the hierarchy of Threads and ThreadGroups in the receiver (and recursively).
boolean	parentOf(ThreadGroup g) Checks whether the receiver is a direct or indirect parent group of a given ThreadGroup.
(package private) void	remove(Thread thread) Removes a Thread from the receiver.
(package private) void	removeThread(Thread thread) Non-standard method for adding a thread to a group, required by Dalvik.
void	resume() Deprecated. Requires deprecated method Thread.resume().
void	setDaemon(boolean isDaemon) Configures the receiver to be a daemon ThreadGroup or not.
void	setMaxPriority(int newMax) Configures the maximum allowed priority for a Thread in the receiver and recursively in all its subgroups.
void	stop() Deprecated. Requires deprecated method Thread.stop().
void	suspend() Deprecated. Requires deprecated method Thread.suspend().
String	toString() Returns a string containing a concise, human-readable description of the receiver.
void	uncaughtException(Thread t, Throwable e) Handles uncaught exceptions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

parent

ThreadGroup parent

numThreads

int numThreads

numGroups

int numGroups

mSystem

static ThreadGroup mSystem

mMain

static ThreadGroup mMain

Constructor Detail

ThreadGroup

public ThreadGroup(String name)

Constructs a new ThreadGroup with the name provided. The new ThreadGroup will be child of the ThreadGroup to which the Thread.currentThread() belongs.

Parameters:

name - the name for the ThreadGroup being created

Throws:

SecurityException - if checkAccess() for the parent group fails with a SecurityException

See Also:

Thread.currentThread()

ThreadGroup

public ThreadGroup(ThreadGroup parent,
                   String name)

Constructs a new ThreadGroup with the name provided, as child of the ThreadGroup parent.

Parameters:

parent - the parent ThreadGroup

name - the name for the ThreadGroup being created

Throws:

NullPointerException - if parent is null

SecurityException - if checkAccess() for the parent group fails with a SecurityException

IllegalThreadStateException - if parent has been destroyed already

ThreadGroup

ThreadGroup()

Initialize the special "system" ThreadGroup. Was "main" in Harmony, but we have an additional group above that in Android.

Method Detail

activeCount

public int activeCount()

Returns the number of Threads which are children of the receiver, directly or indirectly and are running.

Returns:

the number of children Threads

activeGroupCount

public int activeGroupCount()

Returns the number of ThreadGroups which are children of the receiver, directly or indirectly.

Returns:

the number of children ThreadGroups

add

final void add(Thread thread)
        throws IllegalThreadStateException

Adds a Thread to the receiver. This should only be visible to class java.lang.Thread, and should only be called when a new Thread is created and initialized by the constructor.

Parameters:

thread - Thread to add to the receiver

Throws:

IllegalThreadStateException - if the receiver has been destroyed already

See Also:

remove(java.lang.Thread)

allowThreadSuspension

@Deprecated
public boolean allowThreadSuspension(boolean b)

Deprecated. Required deprecated method suspend().

Does nothing. The definition of this method depends on the deprecated method suspend(). The exact behavior of this call was never specified.

Parameters:

b - Used to control low memory implicit suspension

Returns:

true (always)

checkAccess

public final void checkAccess()

Checks the accessibility of the ThreadGroup from the perspective of the caller. If there is a SecurityManager installed, calls checkAccess with the receiver as a parameter, otherwise does nothing.

destroy

public final void destroy()

Destroys the receiver and recursively all its subgroups. It is only legal to destroy a ThreadGroup that has no Threads in it. Any daemon ThreadGroup is destroyed automatically when it becomes empty (no Threads and no ThreadGroups in it).

Throws:

IllegalThreadStateException - if the receiver or any of its subgroups has been destroyed already or if it still contains threads.

SecurityException - if this.checkAccess() fails with a SecurityException

enumerate

public int enumerate(Thread[] threads)

Iterates over all active threads in this group (and its sub-groups) and stores the threads in the given array. Returns when the array is full or no more threads remain, whichever happens first.

Parameters:

threads - the array into which the Threads will be copied

Returns:

the number of Threads that were copied

enumerate

public int enumerate(Thread[] threads,
                     boolean recurse)

Iterates over all active threads in this group (and, optionally, its sub-groups) and stores the threads in the given array. Returns when the array is full or no more threads remain, whichever happens first.

Parameters:

threads - the array into which the Threads will be copied

recurse - indicates whether Threads in subgroups should be recursively copied as well

Returns:

the number of Threads that were copied

enumerate

public int enumerate(ThreadGroup[] groups)

Iterates over all thread groups in this group (and its sub-groups) and and stores the groups in the given array. Returns when the array is full or no more groups remain, whichever happens first.

Parameters:

groups - the array into which the ThreadGroups will be copied

Returns:

the number of ThreadGroups that were copied

enumerate

public int enumerate(ThreadGroup[] groups,
                     boolean recurse)

Iterates over all thread groups in this group (and, optionally, its sub-groups) and and stores the groups in the given array. Returns when the array is full or no more groups remain, whichever happens first.

Parameters:

groups - the array into which the ThreadGroups will be copied

recurse - indicates whether ThreadGroups in subgroups should be recursively copied as well or not

Returns:

the number of ThreadGroups that were copied

getMaxPriority

public final int getMaxPriority()

Returns the maximum allowed priority for a Thread in the receiver.

Returns:

the maximum priority

See Also:

setMaxPriority(int)

getName

public final String getName()

Returns the name of the receiver.

Returns:

the receiver's name

getParent

public final ThreadGroup getParent()

Returns the receiver's parent ThreadGroup. It can be null if the receiver is the the root ThreadGroup.

Returns:

the parent ThreadGroup

interrupt

public final void interrupt()

Interrupts every Thread in the receiver and recursively in all its subgroups.

Throws:

SecurityException - if this.checkAccess() fails with a SecurityException

See Also:

Thread.interrupt()

isDaemon

public final boolean isDaemon()

Checks whether the receiver is a daemon ThreadGroup.

Returns:

true if (and only if) the receiver is a daemon ThreadGroup

See Also:

setDaemon(boolean), destroy()

isDestroyed

public boolean isDestroyed()

Checks whether the receiver has already been destroyed.

Returns:

true if (and only if) the receiver has already been destroyed

See Also:

destroy()

list

public void list()

Outputs to System.out a text representation of the hierarchy of Threads and ThreadGroups in the receiver (and recursively). Proper indentation is done to suggest the nesting of groups inside groups and threads inside groups.

parentOf

public final boolean parentOf(ThreadGroup g)

Checks whether the receiver is a direct or indirect parent group of a given ThreadGroup.

Parameters:

g - the potential child ThreadGroup

Returns:

true if (and only if) the receiver is parent of g

remove

final void remove(Thread thread)

Removes a Thread from the receiver. This should only be visible to class java.lang.Thread, and should only be called when a Thread dies.

Parameters:

thread - Thread to remove from the receiver

See Also:

add(Thread)

resume

@Deprecated
public final void resume()

Deprecated. Requires deprecated method Thread.resume().

Resumes every Thread in the receiver and recursively in all its subgroups.

Throws:

SecurityException - if this.checkAccess() fails with a SecurityException

See Also:

Thread.resume(), suspend()

setDaemon

public final void setDaemon(boolean isDaemon)

Configures the receiver to be a daemon ThreadGroup or not. Daemon ThreadGroups are automatically destroyed when they become empty.

Parameters:

isDaemon - the new value defining if receiver should be daemon or not

Throws:

SecurityException - if checkAccess() for the parent group fails with a SecurityException

See Also:

isDaemon, destroy()

setMaxPriority

public final void setMaxPriority(int newMax)

Configures the maximum allowed priority for a Thread in the receiver and recursively in all its subgroups. One can never change the maximum priority of a ThreadGroup to be higher than it was. Such an attempt will not result in an exception, it will simply leave the ThreadGroup with its current maximum priority.

Parameters:

newMax - the new maximum priority to be set

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:

getMaxPriority()

stop

@Deprecated
public final void stop()

Deprecated. Requires deprecated method Thread.stop().

Stops every Thread in the receiver and recursively in all its subgroups.

Throws:

SecurityException - if this.checkAccess() fails with a SecurityException

See Also:

Thread.stop(), Thread.stop(Throwable), ThreadDeath

suspend

@Deprecated
public final void suspend()

Deprecated. Requires deprecated method Thread.suspend().

Suspends every Thread in the receiver and recursively in all its subgroups.

Throws:

SecurityException - if this.checkAccess() fails with a SecurityException

See Also:

Thread.suspend(), resume()

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

a printable representation of the ThreadGroup

uncaughtException

public void uncaughtException(Thread t,
                              Throwable e)

Handles uncaught exceptions. Any uncaught exception in any Thread is forwarded (by the VM) to the Thread's ThreadGroup by sending this message (uncaughtException). This allows users to define custom ThreadGroup classes and custom behavior for when a Thread has an uncaughtException or when it does (ThreadDeath).

Specified by:

uncaughtException in interface Thread.UncaughtExceptionHandler

Parameters:

t - the Thread that terminated with an uncaught exception

e - the uncaught exception itself

See Also:

Thread.stop(), Thread.stop(Throwable), ThreadDeath

addThread

void addThread(Thread thread)
         throws IllegalThreadStateException

Non-standard method for adding a thread to a group, required by Dalvik.

Parameters:

thread - Thread to add to the receiver

Throws:

IllegalThreadStateException - if the receiver has been destroyed already

See Also:

add(java.lang.Thread), removeThread(java.lang.Thread)

removeThread

void removeThread(Thread thread)
            throws IllegalThreadStateException

Non-standard method for adding a thread to a group, required by Dalvik.

Parameters:

thread - Thread to add to the receiver

Throws:

IllegalThreadStateException - if the receiver has been destroyed already

See Also:

remove(java.lang.Thread), addThread(java.lang.Thread)