Module java.base
Package java.lang

Class ThreadGroup

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

public class ThreadGroup extends Object implements Thread.UncaughtExceptionHandler
ThreadGroups are containers of Threads and ThreadGroups, therefore providing a tree-like structure to organize Threads. The root ThreadGroup name is "system" and it has no parent ThreadGroup. All other ThreadGroups have exactly one parent ThreadGroup. All Threads belong to exactly one ThreadGroup.
See Also:
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a new ThreadGroup with the name provided.
    Constructs a new ThreadGroup with the name provided, as child of the ThreadGroup parent
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    Returns the number of Threads which are children of the receiver, directly or indirectly.
    int
    Returns the number of ThreadGroups which are children of the receiver, directly or indirectly.
    boolean
    Deprecated, for removal: This API element is subject to removal in a future version.
    Required deprecated method suspend().
    final void
    Deprecated, for removal: This API element is subject to removal in a future version.
    final void
    Deprecated, for removal: This API element is subject to removal in a future version. 
    int
    enumerate(Thread[] threads)
    Copies an array with all Threads which are children of the receiver (directly or indirectly) into the array threads passed as parameters.
    int
    enumerate(Thread[] threads, boolean recurse)
    Copies an array with all Threads which are children of the receiver into the array threads passed as parameter.
    int
    Copies an array with all ThreadGroups which are children of the receiver (directly or indirectly) into the array groups passed as parameters.
    int
    enumerate(ThreadGroup[] groups, boolean recurse)
    Copies an array with all ThreadGroups which are children of the receiver into the array groups passed as parameter.
    final int
    Answers the maximum allowed priority for a Thread in the receiver.
    final String
    Answers the name of the receiver.
    Answers the receiver's parent ThreadGroup.
    final void
    Interrupts every Thread in the receiver and recursively in all its subgroups.
    final boolean
    Deprecated, for removal: This API element is subject to removal in a future version. 
    boolean
    Deprecated, for removal: This API element is subject to removal in a future version. 
    void
    Outputs to System.out a text representation of the hierarchy of Threads and ThreadGroups in the receiver (and recursively).
    final boolean
    Answers true if the receiver is a direct or indirect parent group of ThreadGroup g, false otherwise.
    final void
    Deprecated, for removal: This API element is subject to removal in a future version.
    Requires deprecated method Thread.resume().
    final void
    setDaemon(boolean isDaemon)
    Deprecated, for removal: This API element is subject to removal in a future version. 
    final void
    setMaxPriority(int newMax)
    Configures the maximum allowed priority for a Thread in the receiver and recursively in all its subgroups.
    final void
    Deprecated, for removal: This API element is subject to removal in a future version.
    Requires deprecated method Thread.stop().
    final void
    Deprecated, for removal: This API element is subject to removal in a future version.
    Requires deprecated method Thread.suspend().
    Answers a string containing a concise, human-readable description of the receiver.
    void
    Any uncaught exception in any Thread has to be forwarded (by the VM) to the Thread's ThreadGroup by sending this message (uncaughtException).

    Methods declared in class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Constructor Details

    • ThreadGroup

      public ThreadGroup(String name)
      Constructs a new ThreadGroup with the name provided. The new ThreadGroup will be child of the ThreadGroup to which the Thread.currentThread() belongs.
      Parameters:
      name - Name for the ThreadGroup being created
      Throws:
      SecurityException - if checkAccess() for the parent group fails with a SecurityException
      See Also:
    • ThreadGroup

      public ThreadGroup(ThreadGroup parent, String name)
      Constructs a new ThreadGroup with the name provided, as child of the ThreadGroup parent
      Parameters:
      parent - Parent ThreadGroup
      name - Name for the ThreadGroup being created
      Throws:
      NullPointerException - if parent is null
      SecurityException - if checkAccess() for the parent group fails with a SecurityException
      IllegalThreadStateException - if parent has been destroyed already
  • Method Details

    • activeCount

      public int activeCount()
      Returns the number of Threads which are children of the receiver, directly or indirectly.
      Returns:
      Number of children Threads
    • activeGroupCount

      public int activeGroupCount()
      Returns the number of ThreadGroups which are children of the receiver, directly or indirectly.
      Returns:
      Number of children ThreadGroups
    • allowThreadSuspension

      @Deprecated(forRemoval=true, since="1.2") public boolean allowThreadSuspension(boolean b)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Required deprecated method suspend().
      The definition of this method depends on the deprecated method suspend(). The behavior of this call was never specified.
      Parameters:
      b - Used to control low memory implicit suspension
      Returns:
      always returns true
    • checkAccess

      @Deprecated(since="17", forRemoval=true) public final void checkAccess()
      Deprecated, for removal: This API element is subject to removal in a future version.
      If there is a SecurityManager installed, call checkAccess in it passing the receiver as parameter, otherwise do nothing.
    • destroy

      @Deprecated(forRemoval=true, since="16") public final void destroy()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Destroys the receiver and recursively all its subgroups. It is only legal to destroy a ThreadGroup that has no Threads. Any daemon ThreadGroup is destroyed automatically when it becomes empty (no Threads and no ThreadGroups in it).
      Throws:
      IllegalThreadStateException - if the receiver or any of its subgroups has been destroyed already
      SecurityException - if this.checkAccess() fails with a SecurityException
    • enumerate

      public int enumerate(Thread[] threads)
      Copies an array with all Threads which are children of the receiver (directly or indirectly) into the array threads passed as parameters. If the array passed as parameter is too small no exception is thrown - the extra elements are simply not copied.
      Parameters:
      threads - Thread array into which the Threads will be copied
      Returns:
      How many Threads were copied over
    • enumerate

      public int enumerate(Thread[] threads, boolean recurse)
      Copies an array with all Threads which are children of the receiver into the array threads passed as parameter. Children Threads of subgroups are recursively copied as well if parameter recurse is true. If the array passed as parameter is too small no exception is thrown - the extra elements are simply not copied.
      Parameters:
      threads - array into which the Threads will be copied
      recurse - Indicates whether Threads in subgroups should be recursively copied as well or not
      Returns:
      How many Threads were copied over
    • enumerate

      public int enumerate(ThreadGroup[] groups)
      Copies an array with all ThreadGroups which are children of the receiver (directly or indirectly) into the array groups passed as parameters. If the array passed as parameter is too small no exception is thrown - the extra elements are simply not copied.
      Parameters:
      groups - array into which the ThreadGroups will be copied
      Returns:
      How many ThreadGroups were copied over
    • enumerate

      public int enumerate(ThreadGroup[] groups, boolean recurse)
      Copies an array with all ThreadGroups which are children of the receiver into the array groups passed as parameter. Children ThreadGroups of subgroups are recursively copied as well if parameter recurse is true. If the array passed as parameter is too small no exception is thrown - the extra elements are simply not copied.
      Parameters:
      groups - array into which the ThreadGroups will be copied
      recurse - Indicates whether ThreadGroups in subgroups should be recursively copied as well or not
      Returns:
      How many ThreadGroups were copied over
    • getMaxPriority

      public final int getMaxPriority()
      Answers the maximum allowed priority for a Thread in the receiver.
      Returns:
      the maximum priority (an int)
      See Also:
    • getName

      public final String getName()
      Answers the name of the receiver.
      Returns:
      the receiver's name (a java.lang.String)
    • getParent

      public final ThreadGroup getParent()
      Answers the receiver's parent ThreadGroup. It can be null if the receiver is the root ThreadGroup.
      Returns:
      the parent ThreadGroup
    • interrupt

      public final void interrupt()
      Interrupts every Thread in the receiver and recursively in all its subgroups.
      Throws:
      SecurityException - if this.checkAccess() fails with a SecurityException
      See Also:
    • isDaemon

      @Deprecated(forRemoval=true, since="16") public final boolean isDaemon()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Answers true if the receiver is a daemon ThreadGroup, false otherwise.
      Returns:
      if the receiver is a daemon ThreadGroup
      See Also:
    • isDestroyed

      @Deprecated(forRemoval=true, since="16") public boolean isDestroyed()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Answers true if the receiver has been destroyed already, false otherwise.
      Returns:
      if the receiver has been destroyed already
      See Also:
    • list

      public void list()
      Outputs to System.out a text representation of the hierarchy of Threads and ThreadGroups in the receiver (and recursively). Proper indentation is done to suggest the nesting of groups inside groups and threads inside groups.
    • parentOf

      public final boolean parentOf(ThreadGroup g)
      Answers true if the receiver is a direct or indirect parent group of ThreadGroup g, false otherwise.
      Parameters:
      g - ThreadGroup to test
      Returns:
      if the receiver is parent of the ThreadGroup passed as parameter
    • resume

      @Deprecated(forRemoval=true, since="1.2") public final void resume()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Requires deprecated method Thread.resume().
      Resumes every Thread in the receiver and recursively in all its subgroups.
      Throws:
      SecurityException - if this.checkAccess() fails with a SecurityException
      See Also:
    • setDaemon

      @Deprecated(forRemoval=true, since="16") public final void setDaemon(boolean isDaemon)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Configures the receiver to be a daemon ThreadGroup or not. Daemon ThreadGroups are automatically destroyed when they become empty.
      Parameters:
      isDaemon - new value defining if receiver should be daemon or not
      Throws:
      SecurityException - if checkAccess() for the parent group fails with a SecurityException
      See Also:
    • setMaxPriority

      public final void setMaxPriority(int newMax)
      Configures the maximum allowed priority for a Thread in the receiver and recursively in all its subgroups. One can never change the maximum priority of a ThreadGroup to be higher than it was. Such an attempt will not result in an exception, it will simply leave the ThreadGroup with its current maximum priority.
      Parameters:
      newMax - the new maximum priority to be set
      Throws:
      SecurityException - if checkAccess() fails with a SecurityException
      IllegalArgumentException - if the new priority is greater than Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY
      See Also:
    • stop

      @Deprecated(forRemoval=true, since="1.2") public final void stop()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Requires deprecated method Thread.stop().
      Stops every Thread in the receiver and recursively in all its subgroups.
      Throws:
      SecurityException - if this.checkAccess() fails with a SecurityException
      See Also:
    • suspend

      @Deprecated(forRemoval=true, since="1.2") public final void suspend()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Requires deprecated method Thread.suspend().
      Suspends every Thread in the receiver and recursively in all its subgroups.
      Throws:
      SecurityException - if this.checkAccess() fails with a SecurityException
      See Also:
    • toString

      public String toString()
      Answers a string containing a concise, human-readable description of the receiver.
      Overrides:
      toString in class Object
      Returns:
      a printable representation for the receiver.
    • uncaughtException

      public void uncaughtException(Thread t, Throwable e)
      Any uncaught exception in any Thread has to be forwarded (by the VM) to the Thread's ThreadGroup by sending this message (uncaughtException). This allows users to define custom ThreadGroup classes and custom behavior for when a Thread has an uncaughtException or when it does (ThreadDeath).
      Specified by:
      uncaughtException in interface Thread.UncaughtExceptionHandler
      Parameters:
      t - Thread with an uncaught exception
      e - The uncaught exception itself
      See Also: