java.lang
Class ThreadGroup

java.lang.Object
  java.lang.ThreadGroup

All Implemented Interfaces:

Thread.UncaughtExceptionHandler

public class ThreadGroup
extends Object
implements Thread.UncaughtExceptionHandler

ThreadGroup enables grouping of threads and modifying a whole group of threads.

Thread groups form a hierarchy, i.e., a thread group A can contain another thread group B, in which case B may has A as parent.

Since:

1.0

Constructor Summary

ThreadGroup(String name)
Constructor that creates a new ThreadGroup with the given name using theThreadGroup of the current thread as parent.

ThreadGroup(ThreadGroup parent, String name)
Creates a new ThreadGroup with the given parent and the given name.

Method Summary

int	activeCount() activeCount returns an estimation of the threads that are currently running in this thread group.
int	activeGroupCount() activeGroupCount returns an estimation of the number of thread groups that are children of this thread group.
boolean	allowThreadSuspension(boolean b) Deprecated. the behavior of this method was never specified.
void	checkAccess() checkAccess checks if access to this ThreadGroup is permitted.
void	destroy() destroy destroys this thread group and all of its children.
int	enumerate(Thread[] array) enumerate enumerates all the threads in this thread group and any sub groups and stores the threads in the given array.
int	enumerate(Thread[] array, boolean recursive) enumerate copies into the specified array every active thread in this thread group.
int	enumerate(ThreadGroup[] list) enumerate enumerates all the thread groups that are children of this thread group and any sub groups and stores the thread groups in the given array.
int	enumerate(ThreadGroup[] array, boolean recursive) enumerate enumerates all the thread groups that are children of this thread group and any sub groups and stores the thread groups in the given array.
int	getMaxPriority() getMaxPriority returns the maximum priority allowed for threads of this thread group.
String	getName() getName returns the name of this thread group.
ThreadGroup	getParent() getParent returns the parent of this thread group.
void	interrupt() interrupt interrupts all threads in this thread group and all of its subgroups.
boolean	isDaemon() isDaemon returns true if this is a daemon thread group, i.e., this thread group is removed automatically when the last thread running in this thread group terminates or the last child is removed.
boolean	isDestroyed() isDestroyed returns true iff this thread group has been destroyed.
void	list() list prints information about this thread group to System.out.
boolean	parentOf(ThreadGroup g) parentOf tests if this is equal to a given thread group or a (grand-) parent of a given thread group .
void	resume() Deprecated. suspend/resume is deadlock-prone since all locks held by the suspended thread will be held until the thread will be resumed. If the thread that performs the resume() locks on one of these monitors, a deadlock occurs.
void	setDaemon(boolean daemon) setDaemon sets the daemon state of this thread group.
void	setMaxPriority(int pri) setMaxPriority sets the maximum priority of this thread group and of all its children.
void	stop() Deprecated. this is inherently unsafe. Use AsynchronouslyInterruptedException instead.
void	suspend() Deprecated. suspend/resume is deadlock-prone since all locks held by the suspended thread will be held until the thread will be resumed. If the thread that performs the resume() locks on one of these monitors, a deadlock occurs.
String	toString() toString returns a string representation of this
void	uncaughtException(Thread t, Throwable e) uncaughtException is called by the virtual machine if one thread of this thread group is terminated by an unhandled exception and this thread did not set its own uncaught exception handler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ThreadGroup

public ThreadGroup(String name)
            throws SecurityException

Constructor that creates a new ThreadGroup with the given name using theThreadGroup of the current thread as parent.

ensure

   (   (getName  () == name)
    && (getParent() == Thread.currentThread().getThreadGroup()));
 

Parameters:

name - of the new ThreadGroup

Throws:

SecurityException - if the current thread's ThreadGroup's checkAccess() function causes this exception.

NullPointerException - if Thread.currentThread() instanceof RealtimeThread and Thread.currentThread().getThreadGroup()==null. This can happen for threads of class RealtimeThread since these threads may be allocated in non-heap memory, such that no (direct or indirect) reference from the system thread group to the RealtimeThread can be created.

Since:

1.0

ThreadGroup

public ThreadGroup(ThreadGroup parent,
                   String name)
            throws SecurityException

Creates a new ThreadGroup with the given parent and the given name.

ensure

   (   (getName  () == name)
    && (getParent() == parent));
 

Parameters:

parent - of the new ThreadGroup

name - of the new ThreadGroup

Throws:

NullPointerException - if parent is null

SecurityException - if the parent's checkAccess() function causes this exception.

IllegalAssignmentError - if this is created in ScopedMemory.

Since:

1.0

Method Detail

getName

public final String getName()

getName returns the name of this thread group.

Returns:

the name, null if the name passed to the constructor is null.

getParent

public final ThreadGroup getParent()
                            throws SecurityException

getParent returns the parent of this thread group.

Returns:

the parent of this thread group, null for the system thread group.

Throws:

SecurityException - if the parent is not null and the parent's checkAccess() function causes this exception.

Since:

1.0

getMaxPriority

public final int getMaxPriority()

getMaxPriority returns the maximum priority allowed for threads of this thread group.

Returns:

the maximum priority of this thread group

Since:

1.0

isDaemon

public final boolean isDaemon()

isDaemon returns true if this is a daemon thread group, i.e., this thread group is removed automatically when the last thread running in this thread group terminates or the last child is removed.

Returns:

true iff this is a daemon thread group.

Since:

1.0

isDestroyed

public boolean isDestroyed()

isDestroyed returns true iff this thread group has been destroyed.

Returns:

true iff this has been destroyed.

Since:

1.1

setDaemon

public final void setDaemon(boolean daemon)
                     throws SecurityException

setDaemon sets the daemon state of this thread group.

If this is a daemon thread group this thread group is removed automatically when the last thread running in this thread group terminates or the last child is removed.

ensure

   (isDaemon() == daemon);
 

Parameters:

daemon - the new daemon state for this thread group

Throws:

SecurityException - if this class' checkAccess() function causes this exception.

Since:

1.0

setMaxPriority

public final void setMaxPriority(int pri)
                          throws SecurityException

setMaxPriority sets the maximum priority of this thread group and of all its children.

This function does not change the priority of any threads in this group that may already have a higher priority.

Parameters:

pri - the new maximum priority

Throws:

SecurityException - if this class' checkAccess() function causes this exception.

Since:

1.0

parentOf

public final boolean parentOf(ThreadGroup g)

parentOf tests if this is equal to a given thread group or a (grand-) parent of a given thread group .

Parameters:

g - the other thread group.

Returns:

true iff this is equal to g or g is not null and this is equal to any of g's parents.

Since:

1.0

checkAccess

public final void checkAccess()
                       throws SecurityException

checkAccess checks if access to this ThreadGroup is permitted.

Throws:

SecurityException - if a security manager sm is installed and sm.checkAccess(this) throws this exception.

+ @since 1.

activeCount

public int activeCount()

activeCount returns an estimation of the threads that are currently running in this thread group. Since threads may be started or may terminate any time, the result can change at any point.

Returns:

an estimation for the number of threads in this thread group.

Since:

1.0

enumerate

public int enumerate(Thread[] array)
              throws SecurityException

enumerate enumerates all the threads in this thread group and any sub groups and stores the threads in the given array.

If the array is too small to hold all threads, only those threads that fit will be stored into the array.

Parameters:

array - (out!) the array to hold the result.

Returns:

the number of Threads stored in array.

Throws:

SecurityException - if this class' checkAccess() function causes this exception.

Since:

1.0

enumerate

public int enumerate(Thread[] array,
                     boolean recursive)
              throws SecurityException

enumerate copies into the specified array every active thread in this thread group. If the recursive flag is true, references to every active thread in this thread's subgroups are also included. If the array is too short to hold all the threads, the extra threads are silently ignored.

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

An application should use the activeCount method to get an estimate of how big the array should be.

Parameters:

array - (out!) an array into which to place the list of threads.

recursive - flag indicating whether also to include threads in thread groups that are subgroups of this thread group.

Returns:

the number of threads placed into the array.

Throws:

SecurityException - if this class' checkAccess() function causes this exception, or, if recursive is true and any child's checkAccess() function causes this exception.

Since:

1.0

activeGroupCount

public int activeGroupCount()

activeGroupCount returns an estimation of the number of thread groups that are children of this thread group. Since thread groups may be added or removed any time, the result can change at any point.

Returns:

an estimation for the number of child thread groups in this thread group.

Since:

1.0

enumerate

public int enumerate(ThreadGroup[] list)
              throws SecurityException

enumerate enumerates all the thread groups that are children of this thread group and any sub groups and stores the thread groups in the given array.

If the array is too small to hold all thread groups, only those thread groups that fit will be stored into the array.

Parameters:

list - (out!) the array to hold the result.

Returns:

the number of thread groups stored in array.

Throws:

SecurityException - if this class' checkAccess() function causes this exception.

Since:

1.0

enumerate

public int enumerate(ThreadGroup[] array,
                     boolean recursive)
              throws SecurityException

enumerate enumerates all the thread groups that are children of this thread group and any sub groups and stores the thread groups in the given array.

If recursive==true, then children of this thread group's children are enumerated as well.

If the array is too small to hold all thread groups, only those thread groups that fit will be stored into the array.

Parameters:

array - (out!) the array to hold the result.

recursive - true to also enumerate children's sub groups.

Returns:

the number of thread groups stored in array.

Throws:

SecurityException - if this class' checkAccess() function causes this exception.

Since:

1.0

stop

public final void stop()

Deprecated. this is inherently unsafe. Use AsynchronouslyInterruptedException instead.

stop calls stop on all threads in this thread group and in all of its subgroups.

Throws:

SecurityException - if this class' checkAccess() function causes this exception, or stop() called on any thread that is contained in this causes this exception.

Since:

1.0

interrupt

public final void interrupt()
                     throws SecurityException

interrupt interrupts all threads in this thread group and all of its subgroups.

Throws:

SecurityException - if this class' checkAccess() function causes this exception, or interrupt() called on any thread that is contained in this causes this exception.

Since:

1.2

suspend

public final void suspend()

Deprecated. suspend/resume is deadlock-prone since all locks held by the suspended thread will be held until the thread will be resumed. If the thread that performs the resume() locks on one of these monitors, a deadlock occurs.

suspend calls suspend on all threads in this thread group and in all of its subgroups.

Throws:

SecurityException - if this class' checkAccess() function causes this exception, or suspend() called on any thread that is contained in this causes this exception.

Since:

1.0

resume

public final void resume()

Deprecated. suspend/resume is deadlock-prone since all locks held by the suspended thread will be held until the thread will be resumed. If the thread that performs the resume() locks on one of these monitors, a deadlock occurs.

resume calls resume on all threads in this thread group and in all of its subgroups.

Throws:

SecurityException - if this class' checkAccess() function causes this exception, or resume() called on any thread that is contained in this causes this exception.

Since:

1.0

destroy

public final void destroy()

destroy destroys this thread group and all of its children.

Throws:

IllegalThreadStateException - if this group is not empty or it has already been destroyed.

SecurityException - if this class' checkAccess() function causes this exception.

Since:

1.0

list

public void list()

list prints information about this thread group to System.out. Useful for debugging.

Since:

1.0

uncaughtException

public void uncaughtException(Thread t,
                              Throwable e)

uncaughtException is called by the virtual machine if one thread of this thread group is terminated by an unhandled exception and this thread did not set its own uncaught exception handler.

The default implementation call uncaughtException of the parent thread group. If there is not parent, then the default implementation print the stack trace to stderr unless the exception is ThreadDepth.

In case the exception is OutOfMemoryError, StackOverflowError or Error, the return code of the application will be set to 65, 66 or 2, respectively.

Specified by:

uncaughtException in interface Thread.UncaughtExceptionHandler

Parameters:

t - the thread that terminates with an unhandled exception. For JamaicaVM, this is the current thread that executed this uncaughtException handler.

e - the exception that was not caught.

allowThreadSuspension

public boolean allowThreadSuspension(boolean b)

Deprecated. the behavior of this method was never specified.

allowThreadSuspension is used internally by the VM.

For JamaicaVM, this is unused.

Parameters:

b - unused

Returns:

true

Since:

1.1

toString

public String toString()

toString returns a string representation of this

Overrides:

toString in class Object

Returns:

A string of the form [name=,maxPri=].