Top Description Fields Constructors Methods
java.lang

public Class ThreadGroup

extends Object
implements UncaughtExceptionHandler
Class Inheritance
All Implemented Interfaces
java.lang.Thread.UncaughtExceptionHandler
Imports
java.io.PrintStream, java.lang.ref.WeakReference, java.util.ArrayList, .Arrays, .HashMap, .List, .Map, .Objects, jdk.internal.misc.VM
A thread group represents a set of threads. In addition, a thread group can also include other thread groups. The thread groups form a tree in which every thread group except the initial thread group has a parent.

A thread group has a name and maximum priority. The name is specified when creating the group and cannot be changed. The group's maximum priority is the maximum priority for threads created in the group. It is initially inherited from the parent thread group but may be changed using the setMaxPriority method.

A thread group is weakly reachable from its parent group so that it is eligible for garbage collection when there are no live threads in the group and the thread group is otherwise unreachable.

Unless otherwise specified, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

Thread groups and virtual threads

The Java runtime creates a special thread group for virtual threads. This group is returned by the Thread.getThreadGroup method when invoked on a virtual thread. The thread group differs to other thread groups in that its maximum priority is fixed and cannot be changed with the setMaxPriority method. Virtual threads are not included in the estimated thread count returned by the activeCount method, are not enumerated by the enumerate method, and are not interrupted by the interrupt method.

API Note

Thread groups provided a way in early Java releases to group threads and provide a form of job control for threads. Thread groups supported the isolation of applets and defined methods intended for diagnostic purposes. It should be rare for new applications to create ThreadGroups and interact with this API.

Since
1.0

Field Summary

Modifier and TypeField and Description
private volatile boolean
daemon

private ThreadGroup[]
groups

private volatile int
maxPriority

private final String
name

private int
ngroups

private int
nweaks

private final ThreadGroup
parent

All fields are accessed directly by the VM and from JVMTI functions.

private WeakReference<ThreadGroup>[]
weaks

Constructor Summary

AccessConstructor and Description
private
ThreadGroup()

Creates the top-level "system" ThreadGroup.

pack-priv
ThreadGroup(ThreadGroup parent, String name, int maxPriority, boolean daemon)

Creates a ThreadGroup without any permission or other checks.

private
ThreadGroup(Void unused, ThreadGroup parent, String name)

public
ThreadGroup(String
the name of the new thread group, can be null
name)

Constructs a new thread group.

public
ThreadGroup(ThreadGroup
the parent thread group.
parent, String
the name of the new thread group, can be null
name)

Creates a new thread group.

Method Summary

Modifier and TypeMethod and Description
public int

Returns:

an estimate of the number of live threads in this thread group and in any other thread group that has this thread group as an ancestor
activeCount()

Returns an estimate of the number of live platform threads in this thread group and its subgroups.

public int

Returns:

the number of thread groups with this thread group as an ancestor
activeGroupCount()

Returns an estimate of the number of groups in this thread group and its subgroups.

public final void
checkAccess()
Deprecated for removal since 17. This method is only useful in conjunction with the Security Manager, which is deprecated and subject to removal in a future release.

Determines if the currently running thread has permission to modify this thread group.

private static Void
checkParentAccess(ThreadGroup parent)

public final void
destroy()
Deprecated for removal since 16. This method was originally specified to destroy an empty thread group.

Does nothing.

public int

Returns:

the number of threads put into the array
enumerate(Thread[]
an array into which to put the list of threads
list)

Copies into the specified array every live platform thread in this thread group and its subgroups.

public int

Returns:

the number of threads put into the array
enumerate(Thread[]
an array into which to put the list of threads
list, boolean
if true, recursively enumerate all subgroups of this thread group
recurse)

Copies into the specified array every live platform thread in this thread group.

public int

Returns:

the number of thread groups put into the array
enumerate(ThreadGroup[]
an array into which to put the list of thread groups
list)

Copies into the specified array references to every subgroup in this thread group and its subgroups.

public int

Returns:

the number of thread groups put into the array
enumerate(ThreadGroup[]
an array into which to put the list of thread groups
list, boolean
if true, recursively enumerate all subgroups
recurse)

Copies into the specified array references to every subgroup in this thread group.

private int
enumerate(ThreadGroup[] list, int i, boolean recurse)

Add a reference to each subgroup to the given array, starting at the given index.

public final int

Returns:

the maximum priority for new threads created in the thread group
getMaxPriority()

Returns the maximum priority of this thread group.

public final String

Returns:

the name of this thread group, may be null
getName()

Returns the name of this thread group.

public final ThreadGroup

Returns:

the parent of this thread group. The top-level thread group is the only thread group whose parent is null.
getParent()

Returns the parent of this thread group.

public final void
interrupt()

Interrupts all live platform threads in this thread group and its subgroups.

public final boolean

Returns:

the daemon status of this thread group
isDaemon()
Deprecated for removal since 16. This method originally indicated if the thread group is a daemon thread group that is automatically destroyed when its last thread terminates.

Returns the daemon status of this thread group.

public boolean

Returns:

false
isDestroyed()
Deprecated for removal since 16. This method originally indicated if the thread group is destroyed.

Returns false.

public void
list()

Prints information about this thread group to the standard output.

private void
list(Map<ThreadGroup, List<Thread>> map, PrintStream out, int indent)

public final boolean

Returns:

true if this thread group is the thread group argument or one of its ancestor thread groups; false otherwise.
parentOf(ThreadGroup
a thread group, can be null
g)

Tests if this thread group is either the thread group argument or one of its ancestor thread groups.

private void
removeWeak(int index)

Remove the weakly reachable group at the given index of the weaks array.

public final void
setDaemon(boolean
the daemon status
daemon)
Deprecated for removal since 16. This method originally configured whether the thread group is a daemon thread group that is automatically destroyed when its last thread terminates.

Sets the daemon status of this thread group.

public final void
setMaxPriority(int
the new priority of the thread group.
pri)

Sets the maximum priority of the group.

private List<ThreadGroup>
subgroups()

Returns a snapshot of the subgroups.

private ThreadGroup[]
subgroupsAsArray()

Returns a snapshot of the subgroups as an array, used by JVMTI.

private void
synchronizedAddStrong(ThreadGroup group)

Add a strongly reachable subgroup.

private void
synchronizedAddWeak(ThreadGroup group)

Add a weakly reachable subgroup.

private List<ThreadGroup>
synchronizedSubgroups()

Returns a snapshot of the subgroups.

public String

Returns:

a string representation of this thread group.
toString()

Overrides java.lang.Object.toString.

Returns a string representation of this Thread group.

public void
uncaughtException(Thread
the thread that is about to exit.
t, Throwable
the uncaught exception.
e)

Implements java.lang.Thread.UncaughtExceptionHandler.uncaughtException.

Called by the Java Virtual Machine when a thread in this thread group stops because of an uncaught exception, and the thread does not have a specific Thread.UncaughtExceptionHandler installed.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

daemonback to summary
private volatile boolean daemon
groupsback to summary
private ThreadGroup[] groups
maxPriorityback to summary
private volatile int maxPriority
nameback to summary
private final String name
ngroupsback to summary
private int ngroups
nweaksback to summary
private int nweaks
parentback to summary
private final ThreadGroup parent

All fields are accessed directly by the VM and from JVMTI functions. Operations that require synchronization on more than one group in the tree should synchronize on the parent group before synchronizing on the child group.

weaksback to summary
private WeakReference<ThreadGroup>[] weaks

Constructor Detail

ThreadGroupback to summary
private ThreadGroup()

Creates the top-level "system" ThreadGroup.

API Note

This method is invoked by the VM early startup.

ThreadGroupback to summary
pack-priv ThreadGroup(ThreadGroup parent, String name, int maxPriority, boolean daemon)

Creates a ThreadGroup without any permission or other checks.

ThreadGroupback to summary
private ThreadGroup(Void unused, ThreadGroup parent, String name)
ThreadGroupback to summary
public ThreadGroup(String name)

Constructs a new thread group. The parent of this new group is the thread group of the currently running thread.

The checkAccess method of the parent thread group is called with no arguments; this may result in a security exception.

Parameters
name:String

the name of the new thread group, can be null

Exceptions
SecurityException:
if the current thread cannot create a thread in the specified thread group.
See Also
java.lang.ThreadGroup#checkAccess()
ThreadGroupback to summary
public ThreadGroup(ThreadGroup parent, String name)

Creates a new thread group. The parent of this new group is the specified thread group.

The checkAccess method of the parent thread group is called with no arguments; this may result in a security exception.

Parameters
parent:ThreadGroup

the parent thread group.

name:String

the name of the new thread group, can be null

Annotations
@SuppressWarnings:this-escape
Exceptions
SecurityException:
if the current thread cannot create a thread in the specified thread group.
See Also
java.lang.ThreadGroup#checkAccess()

Method Detail

activeCountback to summary
public int activeCount()

Returns an estimate of the number of live platform threads in this thread group and its subgroups. Virtual threads are not included in the estimate. This method recursively iterates over all subgroups in this thread group.

The value returned is only an estimate because the number of threads may change dynamically while this method traverses internal data structures, and might be affected by the presence of certain system threads. This method is intended primarily for debugging and monitoring purposes.

Returns:int

an estimate of the number of live threads in this thread group and in any other thread group that has this thread group as an ancestor

activeGroupCountback to summary
public int activeGroupCount()

Returns an estimate of the number of groups in this thread group and its subgroups. Recursively iterates over all subgroups in this thread group.

The value returned is only an estimate because the number of thread groups may change dynamically while this method traverses internal data structures. This method is intended primarily for debugging and monitoring purposes.

Returns:int

the number of thread groups with this thread group as an ancestor

checkAccessback to summary
public final void checkAccess()

Deprecated

for removal since 17.

This method is only useful in conjunction with the Security Manager, which is deprecated and subject to removal in a future release. Consequently, this method is also deprecated and subject to removal. There is no replacement for the Security Manager or this method.

Determines if the currently running thread has permission to modify this thread group.

If there is a security manager, its checkAccess method is called with this thread group as its argument. This may result in throwing a SecurityException.

Annotations
@Deprecated
since:17
forRemoval:true
Exceptions
SecurityException:
if the current thread is not allowed to access this thread group.
See Also
java.lang.SecurityManager#checkAccess(java.lang.ThreadGroup)
checkParentAccessback to summary
private static Void checkParentAccess(ThreadGroup parent)
destroyback to summary
public final void destroy()

Deprecated

for removal since 16.

This method was originally specified to destroy an empty thread group. The ability to explicitly destroy a thread group no longer exists. A thread group is eligible to be GC'ed when there are no live threads in the group and it is otherwise unreachable.

Does nothing.

Annotations
@Deprecated
since:16
forRemoval:true
enumerateback to summary
public int enumerate(Thread[] list)

Copies into the specified array every live platform thread in this thread group and its subgroups. Virtual threads are not enumerated by this method.

An invocation of this method behaves in exactly the same way as the invocation

enumerate(list, true)
Parameters
list:Thread[]

an array into which to put the list of threads

Returns:int

the number of threads put into the array

Exceptions
SecurityException:
if checkAccess determines that the current thread cannot access this thread group
enumerateback to summary
public int enumerate(Thread[] list, boolean recurse)

Copies into the specified array every live platform thread in this thread group. Virtual threads are not enumerated by this method. If recurse is true, this method recursively enumerates all subgroups of this thread group and references to every live platform thread in these subgroups are also included. If the array is too short to hold all the threads, the extra threads are silently ignored.

An application might use the activeCount method to get an estimate of how big the array should be, however if the array is too short to hold all the threads, the extra threads are silently ignored. If it is critical to obtain every live thread in this thread group, the caller should verify that the returned int value is strictly less than the length of list.

Due to the inherent race condition in this method, it is recommended that the method only be used for debugging and monitoring purposes.

Parameters
list:Thread[]

an array into which to put the list of threads

recurse:boolean

if true, recursively enumerate all subgroups of this thread group

Returns:int

the number of threads put into the array

Exceptions
SecurityException:
if checkAccess determines that the current thread cannot access this thread group
enumerateback to summary
public int enumerate(ThreadGroup[] list)

Copies into the specified array references to every subgroup in this thread group and its subgroups.

An invocation of this method behaves in exactly the same way as the invocation

enumerate(list, true)
Parameters
list:ThreadGroup[]

an array into which to put the list of thread groups

Returns:int

the number of thread groups put into the array

Exceptions
SecurityException:
if checkAccess determines that the current thread cannot access this thread group
enumerateback to summary
public int enumerate(ThreadGroup[] list, boolean recurse)

Copies into the specified array references to every subgroup in this thread group. If recurse is true, this method recursively enumerates all subgroups of this thread group and references to every thread group in these subgroups are also included.

An application might use the activeGroupCount method to get an estimate of how big the array should be, however if the array is too short to hold all the thread groups, the extra thread groups are silently ignored. If it is critical to obtain every subgroup in this thread group, the caller should verify that the returned int value is strictly less than the length of list.

Due to the inherent race condition in this method, it is recommended that the method only be used for debugging and monitoring purposes.

Parameters
list:ThreadGroup[]

an array into which to put the list of thread groups

recurse:boolean

if true, recursively enumerate all subgroups

Returns:int

the number of thread groups put into the array

Exceptions
SecurityException:
if checkAccess determines that the current thread cannot access this thread group
enumerateback to summary
private int enumerate(ThreadGroup[] list, int i, boolean recurse)

Add a reference to each subgroup to the given array, starting at the given index. Returns the new index.

getMaxPriorityback to summary
public final int getMaxPriority()

Returns the maximum priority of this thread group. This is the maximum priority for new threads created in the thread group.

Returns:int

the maximum priority for new threads created in the thread group

See Also
setMaxPriority
getNameback to summary
public final String getName()

Returns the name of this thread group.

Returns:String

the name of this thread group, may be null

getParentback to summary
public final ThreadGroup getParent()

Returns the parent of this thread group.

First, if the parent is not null, the checkAccess method of the parent thread group is called with no arguments; this may result in a security exception.

Returns:ThreadGroup

the parent of this thread group. The top-level thread group is the only thread group whose parent is null.

Exceptions
SecurityException:
if the current thread cannot modify this thread group.
See Also
java.lang.ThreadGroup#checkAccess(), java.lang.SecurityException, java.lang.RuntimePermission
interruptback to summary
public final void interrupt()

Interrupts all live platform threads in this thread group and its subgroups.

Exceptions
SecurityException:
if the current thread is not allowed to access this thread group or any of the threads in the thread group.
Since
1.2
See Also
java.lang.Thread#interrupt(), java.lang.SecurityException, java.lang.ThreadGroup#checkAccess()
isDaemonback to summary
public final boolean isDaemon()

Deprecated

for removal since 16.

This method originally indicated if the thread group is a daemon thread group that is automatically destroyed when its last thread terminates. The concept of daemon thread group no longer exists. A thread group is eligible to be GC'ed when there are no live threads in the group and it is otherwise unreachable.

Returns the daemon status of this thread group. The daemon status is not used for anything.

Returns:boolean

the daemon status of this thread group

Annotations
@Deprecated
since:16
forRemoval:true
isDestroyedback to summary
public boolean isDestroyed()

Deprecated

for removal since 16.

This method originally indicated if the thread group is destroyed. The ability to destroy a thread group and the concept of a destroyed thread group no longer exists. A thread group is eligible to be GC'ed when there are no live threads in the group and it is otherwise unreachable.

Returns false.

Returns:boolean

false

Annotations
@Deprecated
since:16
forRemoval:true
Since
1.1
listback to summary
public void list()

Prints information about this thread group to the standard output. This method is useful only for debugging.

listback to summary
private void list(Map<ThreadGroup, List<Thread>> map, PrintStream out, int indent)
parentOfback to summary
public final boolean parentOf(ThreadGroup g)

Tests if this thread group is either the thread group argument or one of its ancestor thread groups.

Parameters
g:ThreadGroup

a thread group, can be null

Returns:boolean

true if this thread group is the thread group argument or one of its ancestor thread groups; false otherwise.

removeWeakback to summary
private void removeWeak(int index)

Remove the weakly reachable group at the given index of the weaks array.

setDaemonback to summary
public final void setDaemon(boolean daemon)

Deprecated

for removal since 16.

This method originally configured whether the thread group is a daemon thread group that is automatically destroyed when its last thread terminates. The concept of daemon thread group no longer exists. A thread group is eligible to be GC'ed when there are no live threads in the group and it is otherwise unreachable.

Sets the daemon status of this thread group. The daemon status is not used for anything.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

Parameters
daemon:boolean

the daemon status

Annotations
@Deprecated
since:16
forRemoval:true
Exceptions
SecurityException:
if the current thread cannot modify this thread group.
See Also
java.lang.SecurityException, java.lang.ThreadGroup#checkAccess()
setMaxPriorityback to summary
public final void setMaxPriority(int pri)

Sets the maximum priority of the group. The maximum priority of the ThreadGroup for virtual threads is not changed by this method (the new priority is ignored). Threads in the thread group (or subgroups) that already have a higher priority are not affected by this method.

First, the checkAccess method of this thread group is called with no arguments; this may result in a security exception.

If the pri argument is less than Thread#MIN_PRIORITY or greater than Thread#MAX_PRIORITY, the maximum priority of the group remains unchanged.

Otherwise, the priority of this ThreadGroup object is set to the smaller of the specified pri and the maximum permitted priority of the parent of this thread group. (If this thread group is the system thread group, which has no parent, then its maximum priority is simply set to pri.) Then this method is called recursively, with pri as its argument, for every thread group that belongs to this thread group.

Parameters
pri:int

the new priority of the thread group.

Exceptions
SecurityException:
if the current thread cannot modify this thread group.
See Also
getMaxPriority, java.lang.SecurityException, java.lang.ThreadGroup#checkAccess()
subgroupsback to summary
private List<ThreadGroup> subgroups()

Returns a snapshot of the subgroups.

subgroupsAsArrayback to summary
private ThreadGroup[] subgroupsAsArray()

Returns a snapshot of the subgroups as an array, used by JVMTI.

synchronizedAddStrongback to summary
private void synchronizedAddStrong(ThreadGroup group)

Add a strongly reachable subgroup.

synchronizedAddWeakback to summary
private void synchronizedAddWeak(ThreadGroup group)

Add a weakly reachable subgroup.

synchronizedSubgroupsback to summary
private List<ThreadGroup> synchronizedSubgroups()

Returns a snapshot of the subgroups.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a string representation of this Thread group.

Returns:String

a string representation of this thread group.

uncaughtExceptionback to summary
public void uncaughtException(Thread t, Throwable e)

Implements java.lang.Thread.UncaughtExceptionHandler.uncaughtException.

Called by the Java Virtual Machine when a thread in this thread group stops because of an uncaught exception, and the thread does not have a specific Thread.UncaughtExceptionHandler installed.

The uncaughtException method of ThreadGroup does the following:

  • If this thread group has a parent thread group, the uncaughtException method of that parent is called with the same two arguments.
  • Otherwise, this method checks to see if there is a default uncaught exception handler installed, and if so, its uncaughtException method is called with the same two arguments.
  • Otherwise, a message containing the thread's name, as returned from the thread's getName method, and a stack backtrace, using the Throwable's printStackTrace method, is printed to the standard error stream.

Applications can override this method in subclasses of ThreadGroup to provide alternative handling of uncaught exceptions.

Parameters
t:Thread

the thread that is about to exit.

e:Throwable

the uncaught exception.