java.lang
Class ThreadGroup

java.lang.Object
  extended by java.lang.ThreadGroup
All Implemented Interfaces:
Thread.UncaughtExceptionHandler

public class ThreadGroup
extends Object
implements Thread.UncaughtExceptionHandler

ThreadGroup allows you to group Threads together. There is a hierarchy of ThreadGroups, and only the initial ThreadGroup has no parent. A Thread may access information about its own ThreadGroup, but not its parents or others outside the tree.

Since:
1.0
See Also:
Thread

Constructor Summary
ThreadGroup(String name)
          Create a new ThreadGroup using the given name and the current thread's ThreadGroup as a parent.
ThreadGroup(ThreadGroup parent, String name)
          Create a new ThreadGroup using the given name and parent group.
 
Method Summary
 int activeCount()
          Return an estimate of the total number of active threads in this ThreadGroup and all its descendants.
 int activeGroupCount()
          Get the number of active groups in this ThreadGroup.
 boolean allowThreadSuspension(boolean allow)
          Deprecated. pointless, since suspend is deprecated
 void checkAccess()
          Find out if the current Thread can modify this ThreadGroup.
 void destroy()
          Destroy this ThreadGroup.
 int enumerate(Thread[] array)
          Copy all of the active Threads from this ThreadGroup and its descendants into the specified array.
 int enumerate(Thread[] array, boolean recurse)
          Copy all of the active Threads from this ThreadGroup and, if desired, from its descendants, into the specified array.
 int enumerate(ThreadGroup[] array)
          Copy all active ThreadGroups that are descendants of this ThreadGroup into the specified array.
 int enumerate(ThreadGroup[] array, boolean recurse)
          Copy all active ThreadGroups that are children of this ThreadGroup into the specified array, and if desired, also all descendents.
 int getMaxPriority()
          Get the maximum priority of Threads in this ThreadGroup.
 String getName()
          Get the name of this ThreadGroup.
 ThreadGroup getParent()
          Get the parent of this ThreadGroup.
 void interrupt()
          Interrupt all Threads in this ThreadGroup and its sub-groups.
 boolean isDaemon()
          Tell whether this ThreadGroup is a daemon group.
 boolean isDestroyed()
          Tell whether this ThreadGroup has been destroyed or not.
 void list()
          Print out information about this ThreadGroup to System.out.
 boolean parentOf(ThreadGroup group)
          Check whether this ThreadGroup is an ancestor of the specified ThreadGroup, or if they are the same.
 void resume()
          Deprecated. pointless, since suspend is deprecated
 void setDaemon(boolean daemon)
          Set whether this ThreadGroup is a daemon group.
 void setMaxPriority(int maxpri)
          Set the maximum priority for Threads in this ThreadGroup. setMaxPriority can only be used to reduce the current maximum.
 void stop()
          Deprecated. unsafe operation, try not to use
 void suspend()
          Deprecated. unsafe operation, try not to use
 String toString()
          Return a human-readable String representing this ThreadGroup.
 void uncaughtException(Thread thread, Throwable t)
          When a Thread in this ThreadGroup does not catch an exception, the virtual machine calls this method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ThreadGroup

public ThreadGroup(String name)
Create a new ThreadGroup using the given name and the current thread's ThreadGroup as a parent. There may be a security check, checkAccess.

Parameters:
name - the name to use for the ThreadGroup
Throws:
SecurityException - if the current thread cannot create a group
See Also:
checkAccess()

ThreadGroup

public ThreadGroup(ThreadGroup parent,
                   String name)
Create a new ThreadGroup using the given name and parent group. The new group inherits the maximum priority and daemon status of its parent group. There may be a security check, checkAccess.

Parameters:
name - the name to use for the ThreadGroup
parent - the ThreadGroup to use as a parent
Throws:
NullPointerException - if parent is null
SecurityException - if the current thread cannot create a group
IllegalThreadStateException - if the parent is destroyed
See Also:
checkAccess()
Method Detail

getName

public final String getName()
Get the name of this ThreadGroup.

Returns:
the name of this ThreadGroup

getParent

public final ThreadGroup getParent()
Get the parent of this ThreadGroup. If the parent is not null, there may be a security check, checkAccess.

Returns:
the parent of this ThreadGroup
Throws:
SecurityException - if permission is denied

getMaxPriority

public final int getMaxPriority()
Get the maximum priority of Threads in this ThreadGroup. Threads created after this call in this group may not exceed this priority.

Returns:
the maximum priority of Threads in this ThreadGroup

isDaemon

public final boolean isDaemon()
Tell whether this ThreadGroup is a daemon group. A daemon group will be automatically destroyed when its last thread is stopped and its last thread group is destroyed.

Returns:
whether this ThreadGroup is a daemon group

isDestroyed

public boolean isDestroyed()
Tell whether this ThreadGroup has been destroyed or not.

Returns:
whether this ThreadGroup has been destroyed or not
Since:
1.1

setDaemon

public final void setDaemon(boolean daemon)
Set whether this ThreadGroup is a daemon group. A daemon group will be destroyed when its last thread is stopped and its last thread group is destroyed. There may be a security check, checkAccess.

Parameters:
daemon - whether this ThreadGroup should be a daemon group
Throws:
SecurityException - if you cannot modify this ThreadGroup
See Also:
checkAccess()

setMaxPriority

public final void setMaxPriority(int maxpri)
Set the maximum priority for Threads in this ThreadGroup. setMaxPriority can only be used to reduce the current maximum. If maxpri is greater than the current Maximum of the parent group, the current value is not changed. Otherwise, all groups which belong to this have their priority adjusted as well. Calling this does not affect threads already in this ThreadGroup. There may be a security check, checkAccess.

Parameters:
maxpri - the new maximum priority for this ThreadGroup
Throws:
SecurityException - if you cannot modify this ThreadGroup
See Also:
getMaxPriority(), checkAccess()

parentOf

public final boolean parentOf(ThreadGroup group)
Check whether this ThreadGroup is an ancestor of the specified ThreadGroup, or if they are the same.

Parameters:
group - the group to test on
Returns:
whether this ThreadGroup is a parent of the specified group

checkAccess

public final void checkAccess()
Find out if the current Thread can modify this ThreadGroup. This passes the check on to SecurityManager.checkAccess(this).

Throws:
SecurityException - if the current Thread cannot modify this ThreadGroup
See Also:
SecurityManager.checkAccess(ThreadGroup)

activeCount

public int activeCount()
Return an estimate of the total number of active threads in this ThreadGroup and all its descendants. This cannot return an exact number, since the status of threads may change after they were counted; but it should be pretty close. Based on a JDC bug, 4089701, we take active to mean isAlive().

Returns:
count of active threads in this ThreadGroup and its descendants

enumerate

public int enumerate(Thread[] array)
Copy all of the active Threads from this ThreadGroup and its descendants into the specified array. If the array is not big enough to hold all the Threads, extra Threads will simply not be copied. There may be a security check, checkAccess.

Parameters:
array - the array to put the threads into
Returns:
the number of threads put into the array
Throws:
SecurityException - if permission was denied
NullPointerException - if array is null
ArrayStoreException - if a thread does not fit in the array
See Also:
activeCount(), checkAccess(), enumerate(Thread[], boolean)

enumerate

public int enumerate(Thread[] array,
                     boolean recurse)
Copy all of the active Threads from this ThreadGroup and, if desired, from its descendants, into the specified array. If the array is not big enough to hold all the Threads, extra Threads will simply not be copied. There may be a security check, checkAccess.

Parameters:
array - the array to put the threads into
recurse - whether to recurse into descendent ThreadGroups
Returns:
the number of threads put into the array
Throws:
SecurityException - if permission was denied
NullPointerException - if array is null
ArrayStoreException - if a thread does not fit in the array
See Also:
activeCount(), checkAccess()

activeGroupCount

public int activeGroupCount()
Get the number of active groups in this ThreadGroup. This group itself is not included in the count. A sub-group is active if it has not been destroyed. This cannot return an exact number, since the status of threads may change after they were counted; but it should be pretty close.

Returns:
the number of active groups in this ThreadGroup

enumerate

public int enumerate(ThreadGroup[] array)
Copy all active ThreadGroups that are descendants of this ThreadGroup into the specified array. If the array is not large enough to hold all active ThreadGroups, extra ThreadGroups simply will not be copied. There may be a security check, checkAccess.

Parameters:
array - the array to put the ThreadGroups into
Returns:
the number of ThreadGroups copied into the array
Throws:
SecurityException - if permission was denied
NullPointerException - if array is null
ArrayStoreException - if a group does not fit in the array
See Also:
activeCount(), checkAccess(), enumerate(ThreadGroup[], boolean)

enumerate

public int enumerate(ThreadGroup[] array,
                     boolean recurse)
Copy all active ThreadGroups that are children of this ThreadGroup into the specified array, and if desired, also all descendents. If the array is not large enough to hold all active ThreadGroups, extra ThreadGroups simply will not be copied. There may be a security check, checkAccess.

Parameters:
array - the array to put the ThreadGroups into
recurse - whether to recurse into descendent ThreadGroups
Returns:
the number of ThreadGroups copied into the array
Throws:
SecurityException - if permission was denied
NullPointerException - if array is null
ArrayStoreException - if a group does not fit in the array
See Also:
activeCount(), checkAccess()

stop

public final void stop()
Deprecated. unsafe operation, try not to use

Stop all Threads in this ThreadGroup and its descendants.

This is inherently unsafe, as it can interrupt synchronized blocks and leave data in bad states. Hence, there is a security check: checkAccess(), followed by further checks on each thread being stopped.

Throws:
SecurityException - if permission is denied
See Also:
checkAccess(), Thread.stop(Throwable)

interrupt

public final void interrupt()
Interrupt all Threads in this ThreadGroup and its sub-groups. There may be a security check, checkAccess.

Throws:
SecurityException - if permission is denied
Since:
1.2
See Also:
checkAccess(), Thread.interrupt()

suspend

public final void suspend()
Deprecated. unsafe operation, try not to use

Suspend all Threads in this ThreadGroup and its descendants.

This is inherently unsafe, as suspended threads still hold locks, which can lead to deadlock. Hence, there is a security check: checkAccess(), followed by further checks on each thread being suspended.

Throws:
SecurityException - if permission is denied
See Also:
checkAccess(), Thread.suspend()

resume

public final void resume()
Deprecated. pointless, since suspend is deprecated

Resume all suspended Threads in this ThreadGroup and its descendants. To mirror suspend(), there is a security check: checkAccess(), followed by further checks on each thread being resumed.

Throws:
SecurityException - if permission is denied
See Also:
checkAccess(), Thread.suspend()

destroy

public final void destroy()
Destroy this ThreadGroup. The group must be empty, meaning that all threads and sub-groups have completed execution. Daemon groups are destroyed automatically. There may be a security check, checkAccess.

Throws:
IllegalThreadStateException - if the ThreadGroup is not empty, or was previously destroyed
SecurityException - if permission is denied
See Also:
checkAccess()

list

public void list()
Print out information about this ThreadGroup to System.out. This is meant for debugging purposes. WARNING: This method is not secure, and can print the name of threads to standard out even when you cannot otherwise get at such threads.


uncaughtException

public void uncaughtException(Thread thread,
                              Throwable t)
When a Thread in this ThreadGroup does not catch an exception, the virtual machine calls this method. The default implementation simply passes the call to the parent; then in top ThreadGroup, it will ignore ThreadDeath and print the stack trace of any other throwable. Override this method if you want to handle the exception in a different manner.

Specified by:
uncaughtException in interface Thread.UncaughtExceptionHandler
Parameters:
thread - the thread that exited
t - the uncaught throwable
Throws:
NullPointerException - if t is null
See Also:
ThreadDeath, System.err, Throwable.printStackTrace()

allowThreadSuspension

public boolean allowThreadSuspension(boolean allow)
Deprecated. pointless, since suspend is deprecated

Originally intended to tell the VM whether it may suspend Threads in low memory situations, this method was never implemented by Sun, and is hence a no-op.

Parameters:
allow - whether to allow low-memory thread suspension; ignored
Returns:
false
Since:
1.1

toString

public String toString()
Return a human-readable String representing this ThreadGroup. The format of the string is:
getClass().getName() + "[name=" + getName() + ",maxpri=" + getMaxPriority() + ']'.

Overrides:
toString in class Object
Returns:
a human-readable String representing this ThreadGroup
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)