java.lang.ThreadGroupThread 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 classEvery 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.ThreadGroup{ publicThreadGroup(String name) throws SecurityException; publicThreadGroup(ThreadGroup parent, String name) throwsNullPointerExpression, SecurityException,IllegalThreadStateException; public StringtoString(); public final voidcheckAccess(); public final StringgetName(); public final ThreadGroupgetParent(); public final booleanparentOf(ThreadGroup g); public final voidstop() throwsSecurityException; public final voidsuspend() throwsSecurityException; public final voidresume() throwsSecurityException; public final voiddestroy() throwsSecurityException,IllegalThreadStateException; public final intgetMaxPriority(); public final voidsetMaxPriority(intnewMaxPriority) throwsSecurityException, IllegalArgumentException; public final booleanisDaemon(); public final voidsetDaemon(boolean daemon) throwsSecurityException; public intthreadsCount(); public intallThreadsCount() ; public intgroupsCount(); public intallGroupsCount(); public Thread[]threads(); public Thread[]allThreads(); public ThreadGroup[]groups(); public ThreadGroup[]allGroups(); public intactiveCount(); // deprecated public intactiveGroupCount(); // deprecated public intenumerate(Thread list[]); // deprecated public intenumerate(Thread list[], // deprecated boolean recurse); public intenumerate(ThreadGroup list[]); // deprecated public intenumerate(ThreadGroup list[], // deprecated boolean recurse); public voidlist(); public voiduncaughtException(Thread t, Throwable e); }
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:
"[name="
",maxpri="
"]"
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:
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