public class

ThreadGroup

extends Object
implements Thread.UncaughtExceptionHandler
java.lang.Object
   ↳ java.lang.ThreadGroup

Class Overview

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.

See Also

Summary

Public Constructors
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.
Public Methods
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.
boolean allowThreadSuspension(boolean b)
This method is deprecated. Required deprecated method suspend().
final void checkAccess()
Checks the accessibility of the ThreadGroup from the perspective of the caller.
final void destroy()
Destroys the receiver and recursively all its subgroups.
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 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(Thread[] threads)
Iterates over all active threads in this group (and its sub-groups) and stores the threads in the given array.
final int getMaxPriority()
Returns the maximum allowed priority for a Thread in the receiver.
final String getName()
Returns the name of the receiver.
final ThreadGroup getParent()
Returns the receiver's parent ThreadGroup.
final void interrupt()
Interrupts every Thread in the receiver and recursively in all its subgroups.
final boolean isDaemon()
Checks whether the receiver is a daemon ThreadGroup.
synchronized 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).
final boolean parentOf(ThreadGroup g)
Checks whether the receiver is a direct or indirect parent group of a given ThreadGroup.
final void resume()
This method is deprecated. Requires deprecated method Thread.resume().
final void setDaemon(boolean isDaemon)
Configures the receiver to be a daemon ThreadGroup or not.
final void setMaxPriority(int newMax)
Configures the maximum allowed priority for a Thread in the receiver and recursively in all its subgroups.
final void stop()
This method is deprecated. Requires deprecated method Thread.stop().
final void suspend()
This method is 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.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.Thread.UncaughtExceptionHandler

Public Constructors

public ThreadGroup (String name)

Since: API Level 1

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

public ThreadGroup (ThreadGroup parent, String name)

Since: API Level 1

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

Public Methods

public int activeCount ()

Since: API Level 1

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

Returns
  • the number of children Threads

public int activeGroupCount ()

Since: API Level 1

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

Returns
  • the number of children ThreadGroups

public boolean allowThreadSuspension (boolean b)

Since: API Level 1

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

public final void checkAccess ()

Since: API Level 1

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.

public final void destroy ()

Since: API Level 1

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

public int enumerate (ThreadGroup[] groups)

Since: API Level 1

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

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

Since: API Level 1

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

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

Since: API Level 1

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

public int enumerate (Thread[] threads)

Since: API Level 1

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

public final int getMaxPriority ()

Since: API Level 1

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

Returns
  • the maximum priority
See Also

public final String getName ()

Since: API Level 1

Returns the name of the receiver.

Returns
  • the receiver's name

public final ThreadGroup getParent ()

Since: API Level 1

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

Returns
  • the parent ThreadGroup

public final void interrupt ()

Since: API Level 1

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

Throws
SecurityException if this.checkAccess() fails with a SecurityException
See Also

public final boolean isDaemon ()

Since: API Level 1

Checks whether the receiver is a daemon ThreadGroup.

Returns
  • true if (and only if) the receiver is a daemon ThreadGroup
See Also

public synchronized boolean isDestroyed ()

Since: API Level 1

Checks whether the receiver has already been destroyed.

Returns
  • true if (and only if) the receiver has already been destroyed
See Also

public void list ()

Since: API Level 1

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.

public final boolean parentOf (ThreadGroup g)

Since: API Level 1

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

public final void resume ()

Since: API Level 1

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

public final void setDaemon (boolean isDaemon)

Since: API Level 1

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

public final void setMaxPriority (int newMax)

Since: API Level 1

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

public final void stop ()

Since: API Level 1

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

public final void suspend ()

Since: API Level 1

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

public String toString ()

Since: API Level 1

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

Returns
  • a printable representation of the ThreadGroup

public void uncaughtException (Thread t, Throwable e)

Since: API Level 1

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

Parameters
t the Thread that terminated with an uncaught exception
e the uncaught exception itself
See Also