Contents | Prev | Next | Index

20.21 The Class `java.lang.ThreadGroup`

A thread group is a set of threads and thread groups. Every thread belongs to exactly one thread group, and every thread group but one (called the "system thread group") belongs to some other thread group. Thus thread groups form a tree with the system thread group at the root.

Thread groups provide a way to manage threads and to impose security boundaries; for example, a thread may always create a new thread within its own thread group, but creating a thread in another thread group requires the approval of the security manager (§20.17), as does the creation of a new thread group.

public class ThreadGroup {
	public ThreadGroup(String name)
		throws SecurityException;
	public ThreadGroup(ThreadGroup parent, String name)
		throws NullPointerExpression, SecurityException,
			IllegalThreadStateException;
	public String toString();
	public final void checkAccess();
	public final String getName();
	public final ThreadGroup getParent();
	public final boolean parentOf(ThreadGroup g);
	public final void stop()
		throws SecurityException;
	public final void suspend()
		throws SecurityException;
	public final void resume()
		throws SecurityException;
	public final void destroy()
		throws SecurityException, IllegalThreadStateException;
	public final int getMaxPriority();
	public final void setMaxPriority(int newMaxPriority)
		throws SecurityException, IllegalArgumentException;
	public final boolean isDaemon();
	public final void setDaemon(boolean daemon)
		throws SecurityException;
	public 	int threadsCount();
	public int allThreadsCount()		;
	public int groupsCount();
	public int allGroupsCount();
	public Thread[] threads();
	public 	Thread[] allThreads();
	public ThreadGroup[] groups();
	public 	ThreadGroup[] allGroups();
	public int activeCount();															// deprecated
	public int activeGroupCount();															// deprecated
	public int enumerate(Thread list[]);															// deprecated
	public int enumerate(Thread list[],															// deprecated
			boolean recurse);
	public int enumerate(ThreadGroup list[]);															// deprecated
	public int enumerate(ThreadGroup list[],															// deprecated
			boolean recurse);
	public void list();
	public void uncaughtException(Thread t, Throwable e);
}

Every thread group has a maximum priority. The priority of a thread cannot be set (§20.20.23) higher than the maximum priority of its thread group.

Each thread group may or may not be marked as a daemon. When a new ThreadGroup object is created, the newly created thread group is marked as a daemon thread group if and only if the thread group to which it belongs is currently a daemon thread group. But the daemonhood of a thread group G may be changed at any time by calling the setDaemon method of the ThreadGroup object that represents G (provided that the security manager (§20.17.12) approves execution of the setDaemon operation).

Every thread group has a name, which is a String, for identification purposes. More than one thread group may have the same name.

Creation of a thread group requires the approval of the checkAccess method (§20.21.4) of its proposed parent thread group, which forwards the decision to the security manager (§20.17.11).

20.21.1 public ThreadGroup(String name) throws SecurityException

First, the checkAccess method (§20.21.4) of the thread group to which the current thread belongs is called with no arguments.

This constructor initializes a newly created ThreadGroup object so that it has the specified name as its name and belongs to the same thread group as the thread that is creating the new thread group.

This constructor has exactly the same effect as the explicit constructor call this(Thread.currentThread().getThreadGroup(), name) (§20.21.2).

20.21.2 public ThreadGroup(ThreadGroup parent, String name) throws NullPointerExpression, SecurityException, IllegalThreadStateException

First, the checkAccess method (§20.21.4) of the parent thread group is called with no arguments.

If parent is null, then a NullPointerExpression is thrown. If parent is a ThreadGroup that has been destroyed by method destroy (§20.21.11), then an IllegalThreadStateException is thrown.

This constructor initializes a newly created ThreadGroup object so that it has the specified name as its name and belongs to the thread group represented by parent.

The maximum priority for the newly created thread group is set equal to the maximum priority of parent. The method setMaxPriority (§20.21.13) may be used to change the maximum priority to a lower value.

The newly created thread group is initially marked as being a daemon thread group if and only parent is a daemon thread group. The method setDaemon (§20.21.15) may be used to change whether or not a thread group is a daemon thread group.

20.21.3 public String toString()

The returned value is a concatenation of the following six strings:

The name of the class of this thread group object
"[name="
The name (§20.21.5) of this thread group
",maxpri="
The current maximum priority (§20.21.12) for this thread group, as a decimal numeral
"]"

All literal characters mentioned above are from the ASCII subset of Unicode.

Overrides the toString method of Object (§20.1.3).

20.21.4 public final void checkAccess()

If there is a security manager, its checkAccess method (§20.17.12) is called with this ThreadGroup object as its argument. This may result in throwing, in the current thread, a SecurityException.

This method is called by methods stop (§20.21.8), suspend (§20.21.9), resume (§20.21.10), destroy (§20.21.11), setMaxPriority (§20.21.13), and setDaemon (§20.21.15).

20.21.5 public final String getName()

The current name of this ThreadGroup object is returned as a String.

20.21.6 public final ThreadGroup getParent()

This method returns the ThreadGroup object that represents the thread group to which this thread group belongs. If this thread group is the system thread group, which is at the root of the thread group hierarchy, then null is returned.

20.21.7 public final boolean parentOf(ThreadGroup g)

This method returns true if and only if either this thread group is g or this method is true when applied to the parent of g. In other words, this method says whether this thread group is an ancestor of g or perhaps g itself.

(This method arguably is misnamed; a more accurate, if clumsy and abstruse, name would be parentOfReflexiveTransitiveClosure.)

20.21.8 public final void stop() throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

Every thread in this thread group or any of its subgroups is stopped. More precisely, the method stop is called for every ThreadGroup and every Thread (§20.20.15) that belongs to this ThreadGroup.

20.21.9 public final void suspend() throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

Every thread in this thread group or any of its subgroups is suspended. More precisely, the method suspend is called for every ThreadGroup and every Thread (§20.20.17) that belongs to this ThreadGroup.

20.21.10 public final void resume() throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

Every thread in this thread group or any of its subgroups is resumed. More precisely, the method resume is called for every ThreadGroup and every Thread (§20.20.18) that belongs to this ThreadGroup.

20.21.11 public final void destroy() throws SecurityException, IllegalThreadStateException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

This thread group is destroyed. If it has already been destroyed, or if any threads belong to it directly, then an IllegalThreadStateException is thrown. Otherwise, this method is called recursively for every thread group that belongs to this thread group, and this thread group is removed from its parent thread group.

A thread group that is currently marked as a daemon thread group is destroyed automatically if both of the following conditions are true:

A thread or thread group has just been removed from it (because the thread has died or the thread group has been destroyed).
The thread group now contains no more threads or thread groups.

20.21.12 public final int getMaxPriority()

The current maximum priority of this ThreadGroup object is returned.

20.21.13 public final void setMaxPriority(int newMaxPriority) throws SecurityException, IllegalArgumentException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

If the newMaxPriority argument is less than MIN_PRIORITY (§20.20.1) or greater than MAX_PRIORITY (§20.20.2), then an IllegalArgumentException is thrown.

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

20.21.14 public final boolean isDaemon()

The result is true if and only if this thread group is currently marked as a daemon thread group.

20.21.15 public final void setDaemon(boolean daemon) throws SecurityException

First, the checkAccess method (§20.21.4) of this ThreadGroup object is called with no arguments. This may result in a SecurityException being thrown (in the current thread).

This thread group is marked as being a daemon thread group if the argument is true, and as not being a daemon thread group if the argument is false.

20.21.16 public int threadsCount()

This method returns the number of threads that directly belong to this thread group.

20.21.17 public int allThreadsCount()

This method returns the number of threads that belong to this thread group or to any of its subgroups.

20.21.18 public int groupsCount()

This method returns the number of thread groups that directly belong to this thread group.

20.21.19 public int allGroupsCount()

This method returns the number of thread groups that belong to this thread group or to any of its subgroups.

20.21.20 public Thread[] threads()

This method returns a newly created array containing the Thread objects for all threads that directly belong to this thread group.

20.21.21 public Thread[] allThreads()

This method returns a newly created array containing the Thread objects for all threads that belong to this thread group or to any of its subgroups.

20.21.22 public ThreadGroup[] groups()

This method returns a newly created array containing the ThreadGroup objects for all thread groups that directly belong to this thread group.

20.21.23 public ThreadGroup[] allGroups()

This method returns a newly created array containing the ThreadGroup objects for all thread groups that belong to this thread group or to any of its subgroups.

20.21.24 public int activeCount()

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the equivalent method allThreadsCount instead.]

20.21.25 public int activeGroupCount()

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the equivalent method allGroupsCount instead.]

20.21.26 public int enumerate(Thread list[])

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method allThreads instead.]

20.21.27 public int enumerate(Thread list[], boolean recurse)

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method threads or allThreads instead.]

20.21.28 public int enumerate(ThreadGroup list[])

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method allGroups instead.]

20.21.29 public int enumerate(ThreadGroup list[], boolean recurse)

[This method is deprecated for use in new code after Java version 1.1 becomes available. Use the method groups or allGroups instead.]

20.21.30 public void list()

This method prints a detailed description of this thread group to the output stream System.out (§20.18.2). It is intended as a convenient utility for debugging.

The output is a series of lines; each line contains some space characters (for indentation) followed by the toString representation of one thread (§20.20.11) or one thread group (§20.21.3).

The first line gives the toString representation for this thread group, with no indentation spaces. Following lines are then generated by a recursive rule: whenever a line is printed for a thread group G with n leading spaces, it is immediately followed by one line for each thread that directly belongs to G, with spaces of indentation; then one line is printed for each thread group that directly belongs to G, with spaces of indentation, using the recursive case.

20.21.31 public void uncaughtException(Thread t, Throwable e)

The general contract of uncaughtException is that it is called whenever a thread that belongs directly to this thread group dies because an exception was thrown in that thread and not caught. The arguments are the Thread object for the thread in question and the Throwable object that was thrown. The uncaughtException method may then take any appropriate action.

The call to uncaughtException is performed by the thread that failed to catch the exception, so t is the current thread. The call to uncaughtException is the last action of the thread before it dies. If the call to uncaughtException itself results in an (uncaught) exception, this fact is ignored and the thread merely goes on to die.

The method uncaughtException defined by class ThreadGroup takes one of two actions. If this thread group has a parent thread group, then this method is invoked for that parent thread group, with the same arguments. If this thread group is the system thread group (which has no parent), then if the exception e is not an instance of ThreadDeath (§20.22), a stack trace (§20.22.6) for e is printed on the error output stream that is the value of the field System.err (§20.18.3).

Subclasses of ThreadGroup may override the uncaughtException method.

Contents | Prev | Next | Index

Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc. All rights reserved
Please send any comments or corrections to doug.kramer@sun.com

20.21 The Class java.lang.ThreadGroup

20.21 The Class `java.lang.ThreadGroup`