Class 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()

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:

parent - the ThreadGroup to use as a parent

name - the name to use for the ThreadGroup

Throws:

NullPointerException - if parent is null

SecurityException - if the current thread cannot create a group

IllegalThreadStateException - if the parent is destroyed

See Also:

checkAccess()

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

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

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

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)

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

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)

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

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)

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

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

public final String getName()

Get the name of this ThreadGroup.

Returns:

the name of this ThreadGroup

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

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

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

public boolean isDestroyed()

Tell whether this ThreadGroup has been destroyed or not.

Returns:

whether this ThreadGroup has been destroyed or not

Since:

1.1

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.

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

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

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

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

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)

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

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 interface Object

Returns:

a human-readable String representing this ThreadGroup

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