java.lang.ThreadGroup

java.lang.ThreadGroup Class Reference

Inheritance diagram for java.lang.ThreadGroup:

Detailed Description

An implementation of this class is provided, but the documented constructors are used by the vm specific implementation to create the required "system" and "main" ThreadGroups.

The documented methods are used by java.lang.Thread to add and remove Threads from their ThreadGroups.

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:: Thread
SecurityManager


Public Member Functions
	ThreadGroup (String name)
	Constructs a new ThreadGroup with the name provided.
	ThreadGroup (ThreadGroup parent, String name)
	Constructs a new ThreadGroup with the name provided, as child of the ThreadGroup `parent`.
int	activeCount ()
	Returns the number of Threads which are children of the receiver, directly or indirectly.
int	activeGroupCount ()
	Returns the number of ThreadGroups which are children of the receiver, directly or indirectly.
boolean	allowThreadSuspension (boolean b)
	The definition of this method depends on the deprecated method `suspend()`.
final void	checkAccess ()
	If there is a SecurityManager installed, call `checkAccess` in it passing the receiver as parameter, otherwise do nothing.
final void	destroy ()
	Destroys the receiver and recursively all its subgroups.
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	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.
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	getMaxPriority ()
	Answers the maximum allowed priority for a Thread in the receiver.
final String	getName ()
	Answers the name of the receiver.
final ThreadGroup	getParent ()
	Answers the receiver's parent ThreadGroup.
final void	interrupt ()
	Interrupts every Thread in the receiver and recursively in all its subgroups.
final boolean	isDaemon ()
	Answers true if the receiver is a daemon ThreadGroup, false otherwise.
boolean	isDestroyed ()
	Answers true if the receiver has been destroyed already, false otherwise.
void	list ()
	Outputs to `System.out` a text representation of the hierarchy of Threads and ThreadGroups in the receiver (and recursively).
final boolean	parentOf (ThreadGroup g)
	Answers true if the receiver is a direct or indirect parent group of ThreadGroup `g`, false otherwise.
final void	resume ()
	Resumes every Thread in the receiver and recursively in all its subgroups.
final void	setDaemon (boolean isDaemon)
	Configures the receiver to be a daemon ThreadGroup or not.
final void	setMaxPriority (int newMax)
	Configures the maximum allowed priority for a Thread in the receiver and recursively in all its subgroups.
final void	stop ()
	Stops every Thread in the receiver and recursively in all its subgroups.
final void	suspend ()
	Suspends every Thread in the receiver and recursively in all its subgroups.
String	toString ()
	Answers a string containing a concise, human-readable description of the receiver.
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).
Package Functions
	ThreadGroup (ThreadGroup parent)
	Initialize the "main" ThreadGroup.
final void	add (Thread thread) throws IllegalThreadStateException
	Adds a Thread to the receiver.
final void	remove (java.lang.Thread thread)
	Removes a Thread from the receiver.
Package Attributes
ThreadGroup	parent
int	numThreads
int	numGroups
Private Member Functions
	ThreadGroup ()
	Used by the JVM to create the "system" ThreadGroup.
void	add (ThreadGroup g) throws IllegalThreadStateException
	Adds a ThreadGroup to the receiver.
void	destroyIfEmptyDaemon ()
int	enumerateGeneric (Object[] enumeration, boolean recurse, int enumerationIndex, boolean enumeratingThreads)
	Copies into enumeration starting at enumerationIndex all Threads or ThreadGroups in the receiver.
void	list (int levels)
void	remove (ThreadGroup g)
	Removes an immediate subgroup from the receiver.
void	setParent (ThreadGroup parent)
	Sets the parent ThreadGroup of the receiver, and adds the receiver to the parent's collection of immediate children (if `parent` is not `null`).
final boolean	stopHelper ()
final boolean	suspendHelper ()
Private Attributes
String	name
int	maxPriority = Thread.MAX_PRIORITY
Thread[]	childrenThreads = new Thread[5]
ThreadGroup[]	childrenGroups = new ThreadGroup[3]
Object	childrenGroupsLock = new ChildrenGroupsLock()
Object	childrenThreadsLock = new ChildrenThreadsLock()
boolean	isDaemon
boolean	isDestroyed
Classes
class	ChildrenGroupsLock
class	ChildrenThreadsLock

Constructor & Destructor Documentation

java.lang.ThreadGroup.ThreadGroup ( ) [private]

Used by the JVM to create the "system" ThreadGroup.

Construct a ThreadGroup instance, and assign the name "system".

java.lang.ThreadGroup.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

Exceptions:

SecurityException if checkAccess() for the parent group fails with a SecurityException

See also:: java.lang.Thread.currentThread

java.lang.ThreadGroup.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

Exceptions:

	NullPointerException	if `parent` is `null`
	SecurityException	if `checkAccess()` for the parent group fails with a SecurityException
	IllegalThreadStateException	if `parent` has been destroyed already

java.lang.ThreadGroup.ThreadGroup ( ThreadGroup parent ) [package]

Initialize the "main" ThreadGroup.

Member Function Documentation

int java.lang.ThreadGroup.activeCount ( )

Returns the number of Threads which are children of the receiver, directly or indirectly.

Returns:: Number of children Threads

int java.lang.ThreadGroup.activeGroupCount ( )

Returns the number of ThreadGroups which are children of the receiver, directly or indirectly.

Returns:: Number of children ThreadGroups

final void java.lang.ThreadGroup.add ( Thread thread ) throws IllegalThreadStateException [package]

Adds a Thread to the receiver.

This should only be visible to class java.lang.Thread, and should only be called when a new Thread is created and initialized by the constructor.

Parameters:

thread

Thread to add to the receiver

Exceptions:

IllegalThreadStateException

if the receiver has been destroyed already

See also:: remove(java.lang.Thread)

void java.lang.ThreadGroup.add ( ThreadGroup g ) throws IllegalThreadStateException [private]

Adds a ThreadGroup to the receiver.

Parameters:

ThreadGroup to add to the receiver

Exceptions:

IllegalThreadStateException

if the receiver has been destroyed already

boolean java.lang.ThreadGroup.allowThreadSuspension ( boolean b )

The definition of this method depends on the deprecated method suspend().

The behavior of this call was never specified.

Parameters:

Used to control low memory implicit suspension

Deprecated:: Required deprecated method suspend().

final void java.lang.ThreadGroup.checkAccess ( )

If there is a SecurityManager installed, call checkAccess in it passing the receiver as parameter, otherwise do nothing.

final void java.lang.ThreadGroup.destroy ( )

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).

Exceptions:

	IllegalThreadStateException	if the receiver or any of its subgroups has been destroyed already
	SecurityException	if `this.checkAccess()` fails with a SecurityException

int java.lang.ThreadGroup.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

int java.lang.ThreadGroup.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

int java.lang.ThreadGroup.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

int java.lang.ThreadGroup.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

int java.lang.ThreadGroup.enumerateGeneric	(	Object[]	enumeration,
		boolean	recurse,
		int	enumerationIndex,
		boolean	enumeratingThreads
	)			`[private]`

Copies into enumeration

starting at enumerationIndex

all Threads or ThreadGroups in the receiver.

If recurse

is true, recursively enumerate the elements in subgroups.

If the array passed as parameter is too small no exception is thrown - the extra elements are simply not copied.

Parameters:

	enumeration	array into which the elements will be copied
	recurse	Indicates whether subgroups should be enumerated or not
	enumerationIndex	Indicates in which position of the enumeration array we are
	enumeratingThreads	Indicates whether we are enumerating Threads or ThreadGroups

Returns:: How many elements were enumerated/copied over

final int java.lang.ThreadGroup.getMaxPriority ( )

Answers the maximum allowed priority for a Thread in the receiver.

Returns:: the maximum priority (an int)

See also:: setMaxPriority

final String java.lang.ThreadGroup.getName ( )

Answers the name of the receiver.

Returns:: the receiver's name (a java.lang.String)

final ThreadGroup java.lang.ThreadGroup.getParent ( )

Answers the receiver's parent ThreadGroup.

It can be null if the receiver is the the root ThreadGroup.

Returns:: the parent ThreadGroup

final void java.lang.ThreadGroup.interrupt ( )

Interrupts every Thread in the receiver and recursively in all its subgroups.

Exceptions:

SecurityException if this.checkAccess() fails with a SecurityException

See also:: Thread.interrupt

final boolean java.lang.ThreadGroup.isDaemon ( )

Answers true if the receiver is a daemon ThreadGroup, false otherwise.

Returns:: if the receiver is a daemon ThreadGroup

See also:: setDaemon
destroy

boolean java.lang.ThreadGroup.isDestroyed ( )

Answers true if the receiver has been destroyed already, false otherwise.

Returns:: if the receiver has been destroyed already

See also:: destroy

void java.lang.ThreadGroup.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.

final boolean java.lang.ThreadGroup.parentOf ( ThreadGroup g )

Answers true if the receiver is a direct or indirect parent group of ThreadGroup g, false otherwise.

Parameters:

ThreadGroup to test

Returns:: if the receiver is parent of the ThreadGroup passed as parameter

final void java.lang.ThreadGroup.remove ( java.lang.Thread thread ) [package]

Removes a Thread from the receiver.

This should only be visible to class java.lang.Thread, and should only be called when a Thread dies.

Parameters:

thread

Thread to remove from the receiver

See also:: add(Thread)

void java.lang.ThreadGroup.remove ( ThreadGroup g ) [private]

Removes an immediate subgroup from the receiver.

Parameters:

Threadgroup to remove from the receiver

See also:: add(Thread)
add(ThreadGroup)

final void java.lang.ThreadGroup.resume ( )

Resumes every Thread in the receiver and recursively in all its subgroups.

Exceptions:

SecurityException if this.checkAccess() fails with a SecurityException

See also:: Thread.resume
suspend

Deprecated:: Requires deprecated method Thread.resume().

final void java.lang.ThreadGroup.setDaemon ( boolean isDaemon )

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

Exceptions:

SecurityException if checkAccess() for the parent group fails with a SecurityException

See also:: isDaemon
destroy

final void java.lang.ThreadGroup.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

Exceptions:

	SecurityException	if `checkAccess()` fails with a SecurityException
	IllegalArgumentException	if the new priority is greater than Thread.MAX_PRIORITY or less than Thread.MIN_PRIORITY