java.lang

Class ThreadGroup

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

UNKNOWN: updated to 1.4

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) 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.
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() Resume all suspended Threads in this ThreadGroup and its descendants.
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() Stop all Threads in this ThreadGroup and its descendants.
void	suspend() Suspend all Threads in this ThreadGroup and its descendants.
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.

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

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

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

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

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: checkAccess

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

toString

public String toString()

Return a human-readable String representing this ThreadGroup. The format of the string is:

getClass().getName() + "[name=" + getName() + ",maxpri="
 + getMaxPriority() + ']'

Returns: a human-readable String representing this ThreadGroup

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.

Parameters: thread the thread that exited t the uncaught throwable

Throws: NullPointerException if t is null