java.lang

Class ThreadGroup

java.lang.Object

java.lang.ThreadGroup

public class ThreadGroup
extends Object

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

Author:

John Keiser, Tom Tromey, Bryce McKinlay, Eric Blake

See Also:

Thread

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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 tg) 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 tg)

Check whether this ThreadGroup is an ancestor of the specified ThreadGroup, or if they are the same.

Parameters:

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

Parameters:

thread - the thread that exited

exception - the uncaught exception

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