java.lang
Class Thread

java.lang.Object
  java.lang.Thread

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

RealtimeThread

public class Thread
extends Object
implements Runnable

Class that represents Java threads.

Since:

1.0

Nested Class Summary

static class	Thread.State JDK 1.5 thread State
static interface	Thread.UncaughtExceptionHandler Interface for handler of uncaught exception.

Field Summary

static int	MAX_PRIORITY maximum value a standard thread priority can have.
static int	MIN_PRIORITY minimum value a standard thread priority can have.
static int	NORM_PRIORITY Default priority for threads.

Constructor Summary

Thread()
Constructor to create a new thread.

Thread(Runnable target)
Constructor to create a new thread.

Thread(Runnable target, String name)
Constructor to create a new thread.

Thread(String name)
Constructor to create a new thread.

Thread(ThreadGroup group, Runnable target)
Constructor to create a new thread.

Thread(ThreadGroup group, Runnable target, String name)
Constructor to create a new thread with given thread group, Runnable and name.

Thread(ThreadGroup group, Runnable target, String name, long stackSize)
Constructor to create a new thread with given thread group, Runnable, name and stack size.

Thread(ThreadGroup group, String name)
Constructor to create a new thread.

Method Summary

static int	activeCount() Return the number of active thread in the current thread's thread group.
void	checkAccess() checkAccess checks if the current thread is permitted to access this thread.
int	countStackFrames() Deprecated. Since this must be suspended for this operation, and suspend is deprecated, this is also deprecated.
static Thread	currentThread() currentThread returns a reference to the current thread.
void	destroy() Deprecated. this is inherently unsafe.
static void	dumpStack() dumpStack print a stack trace for the current thread to System.err.
static int	enumerate(Thread[] tarray) enumerate enumberates all active threads in the current thread's thread group.
static Map<Thread,StackTraceElement[]>	getAllStackTraces() Gets the stack traces of all currently alive threads.
ClassLoader	getContextClassLoader() getContextClassLoader determines the context class loader for this thread.
static Thread.UncaughtExceptionHandler	getDefaultUncaughtExceptionHandler() Return the current default uncaught exception handler.
long	getId() getId returns a unique identifier for this thread.
String	getName() getName returns the name of this thread.
int	getPriority() Return the base priority of this thread.
StackTraceElement[]	getStackTrace() Gets the stack trace of this thread.
Thread.State	getState() Returns the current state of this thread.
ThreadGroup	getThreadGroup() Return the ThreadGroup to which this thread belongs.
Thread.UncaughtExceptionHandler	getUncaughtExceptionHandler() return this thread's uncaught exception handler.
static boolean	holdsLock(Object obj) Checks if the current thread is the owner of the given objects monitor.
void	interrupt() interrupt interrupts this thread by throwing an InterruptedException if this thread is in wait(), sleep() or join().
static boolean	interrupted() interrupted determines the interrupted status of the current thread and clears the interrupted status.
boolean	isAlive() isAlive check if this thread has been started and has not died yet.
boolean	isDaemon() isDaemon return the daemon state of this thread.
boolean	isInterrupted() isInterrupted determines the interrupted status of this thread.
void	join() join waits for this thread to die using no timeout.
void	join(long millis) join waits for this thread to die.
void	join(long millis, int nanos) join waits for this thread to die using given timeout.
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	run() run contains only a call to logic.run if logic is not null and not this.
void	setContextClassLoader(ClassLoader cl) setContextClassLoader sets the context class loader for this thread.
void	setDaemon(boolean on) setDaemon sets the daemon state of this thread.
static void	setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler eh) Set the default handler for handling an exception that caused termination of a thread that was not equipped with an uncaught exception handler.
void	setName(String name) setName sets the name of this thread to the given argument.
void	setPriority(int newPriority) Set the priority of this thread.
void	setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler eh) Sets this thread's uncaught exception handler.
static void	sleep(long millis) sleep stops the execution of this thread for the specified number of milliseconds.
static void	sleep(long millis, int nanos) sleep stops the execution of this thread for the specified number of milliseconds and nanoseconds.
void	start() start starts execution of the new thread.
void	stop() Deprecated. this is inherently unsafe. Use AsynchronouslyInterruptedException instead.
void	stop(Throwable obj) Deprecated. this is inherently unsafe use interrupt() 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 thread consisting of thread name, priority and thread group.
static void	yield() yield does a reschedule of threads

Methods inherited from class java.lang.Object

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

Field Detail

MAX_PRIORITY

public static final int MAX_PRIORITY

maximum value a standard thread priority can have.

Note that RTSJ threads may have a priority that is not within MIN_PRIORITY..MAX_PRIORITY, but that is in the range javax.realtime.PriorityScheduler.getMinPriority() through getMaxPriority().

For JamaicaVM, the extended priority range of RTSJ threads may be used for normal Java threads as well.

See Also:

Constant Field Values

MIN_PRIORITY

public static final int MIN_PRIORITY

minimum value a standard thread priority can have.

Note that RTSJ threads may have a priority that is not within MIN_PRIORITY..MAX_PRIORITY, but that is in the range javax.realtime.PriorityScheduler.getMinPriority() through getMaxPriority().

For JamaicaVM, the extended priority range of RTSJ threads may be used for normal Java threads as well.

See Also:

Constant Field Values

NORM_PRIORITY

public static final int NORM_PRIORITY

Default priority for threads.

See Also:

Constant Field Values

Constructor Detail

Thread

public Thread()

Constructor to create a new thread. Short hand for Thread(null,null,name) for name equal to "Thread-"+n for some thread id n.

Thread

public Thread(Runnable target)

Constructor to create a new thread. Short hand for Thread(null,target,name) for name equal to "Thread-"+n for some thread id n.

Parameters:

target - instance of Runnable whose run method contains the code to be executed by the new thread. null to use this as Runnable.

Thread

public Thread(ThreadGroup group,
              Runnable target)

Constructor to create a new thread. Short hand for Thread(group,target,name) for name equal to "Thread-"+n for some thread id n.

Parameters:

group - the thread group or null.

target - instance of Runnable whose run method contains the code to be executed by the new thread. null to use this as Runnable.

Throws:

SecurityException - if the current thread cannot create a new thread using the provided thread group.

Thread

public Thread(String name)

Constructor to create a new thread. Short hand for Thread(null,null,name).

Parameters:

name - the name of the new thread, must not be null.

Thread

public Thread(ThreadGroup group,
              String name)

Constructor to create a new thread. Short hand for Thread(group,null,name).

Parameters:

group - the thread group or null.

name - the name of the new thread, must not be null.

Throws:

SecurityException - if the current thread cannot create a new thread using the provided thread group.

Thread

public Thread(Runnable target,
              String name)

Constructor to create a new thread. Short hand for Thread(null,target,name).

Parameters:

target - instance of Runnable whose run method contains the code to be executed by the new thread. null to use this as Runnable.

name - the name of the new thread, must not be null.

Thread

public Thread(ThreadGroup group,
              Runnable target,
              String name)

Constructor to create a new thread with given thread group, Runnable and name.

Parameters:

group - the thread group or null.

target - instance of Runnable whose run method contains the code to be executed by the new thread. null to use this as Runnable.

name - the name of the new thread, must not be null.

Thread

public Thread(ThreadGroup group,
              Runnable target,
              String name,
              long stackSize)

Constructor to create a new thread with given thread group, Runnable, name and stack size. The stack size argument is ignored for JamaicaVM. In JamaicaVM, the stack size has to be set via the builder option -javaStackSize, -javaStackSizeFromEnv or the environment variable JAMAICAVM_JAVA_STACKSIZE for the Java (interpreter) stack and the options -nativeStackSize, -nativeStackSizeFromEnv or the environment variable JAMAICAVM_NATIVE_STACKSIZE for the native (C) stack.

Parameters:

group - the thread group or null.

target - instance of Runnable whose run method contains the code to be executed by the new thread. null to use this as Runnable.

name - the name of the new thread, must not be null.

stackSize - the stack size in bytes. The interpretation is highly platform-dependent.

Since:

1.4

Method Detail

currentThread

public static Thread currentThread()

currentThread returns a reference to the current thread.

Returns:

the current thread. Result is never null.

yield

public static void yield()

yield does a reschedule of threads

sleep

public static void sleep(long millis)
                  throws InterruptedException

sleep stops the execution of this thread for the specified number of milliseconds. All monitors owned by this thread will remain owned by this thread.

Parameters:

millis - the time this thread should delay.

Throws:

InterruptedException - if interrupt() is called by another thread on this thread while this thread is sleeping.

IllegalArgumentException - if millis is negative.

sleep

public static void sleep(long millis,
                         int nanos)
                  throws InterruptedException

sleep stops the execution of this thread for the specified number of milliseconds and nanoseconds. All monitors owned by this thread will remain owned by this thread.

Parameters:

millis - the time in milliseconds this thread should delay.

nanos - the time in nanoseconds this thread should delay.

Throws:

InterruptedException - if interrupt() is called by another thread on this thread while this thread is sleeping.

IllegalArgumentException - if millis or nanos is negative or nanos is larger than 999999.

start

public void start()
           throws IllegalThreadStateException

start starts execution of the new thread. Any thread instance may at most be started once.

Throws:

IllegalThreadStateException - if this thread has already been started.

OutOfMemoryError - if starting failed due to lack of memory

InternalError - if this thread instance is allocated in ScopedMemory and it is not a RealtimeThread that can run in scoped memory.

run

public void run()

run contains only a call to logic.run if logic is not null and not this. If this thread is to be started without providing a runnable instance, this method should be redefined to implement the thread body. If a runnable is provided, run calls the runnable's run method. Note that any redefinition of run() must call super.run() in case it is desired that the logic provided to the constructor is to be executed as well.

Specified by:

run in interface Runnable

See Also:

run()

stop

public final void stop()

Deprecated. this is inherently unsafe. Use AsynchronouslyInterruptedException instead.

This is an inherently unsafe way to stop a thread.

For JamaicaVM, this method throws a ThreadDeath exception. Throwing of this exception is, however, delayed until the next time this thread is blocked.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

See Also:

threadPrimitiveDeprecation

stop

public void stop(Throwable obj)

Deprecated. this is inherently unsafe use interrupt() instead

This is an inherently unsafe way to stop a thread.

Parameters:

obj - the Throwable object to be thrown in the new thread. Parameter ignored by JamaicaVM.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

See Also:

threadPrimitiveDeprecation

interrupt

public void interrupt()
               throws SecurityException

interrupt interrupts this thread by throwing an InterruptedException if this thread is in wait(), sleep() or join().

Otherwise, this thread's state will be set to interrupted.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

See Also:

InterruptibleChannel

interrupted

public static boolean interrupted()

interrupted determines the interrupted status of the current thread and clears the interrupted status.

Returns:

the interrupt status before the call.

isInterrupted

public boolean isInterrupted()

isInterrupted determines the interrupted status of this thread. It leaves the status unchanged.

Returns:

the interrupted status of this.

destroy

public void destroy()

Deprecated. this is inherently unsafe.

destroy throws NoSuchMethodError.

Throws:

NoSuchMethodError.

isAlive

public final boolean isAlive()

isAlive check if this thread has been started and has not died yet.

Returns:

true if this thread is still alive.

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.

Suspends the current thread.

For JamaicaVM, this is implemented using the OS's low level suspend/resume mechanism.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

See Also:

stop()

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.

Resumes the current thread.

For JamaicaVM, this is implemented using the OS's low level suspend/resume mechanism.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

See Also:

stop()

setPriority

public final void setPriority(int newPriority)
                       throws SecurityException,
                              IllegalArgumentException

Set the priority of this thread. Note that for RealtimeThread, the preferred way to change the priority is via the associated PriorityParameters.setPriority() method.

Parameters:

newPriority - the new priority, in the range of 1 .. javax.realtime.PriorityScheduler.instance().getMaxPriority().

Throws:

ClassCastException - if this is an instance of RealtimeThread and this.getSchedulingParameters() is not an instance of PriorityParameters.

IllegalArgumentException - if the new priority is less than MIN_PRIORITY or larger than PriorityScheduler.instance().getMaxPriority().

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

getPriority

public final int getPriority()

Return the base priority of this thread.

Returns:

the thread priority, in the range of MIN_PRIORITY .. javax.realtime.PriorityScheduler.instance().getMaxPriority().

Throws:

ClassCastException - if this is an instance of RealtimeThread and this.getSchedulingParameters() is not an instance of PriorityParameters.

setName

public final void setName(String name)
                   throws SecurityException

setName sets the name of this thread to the given argument.

Parameters:

name - the new name. Must not be null.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

NullPointerException - if name is null.

getName

public final String getName()

getName returns the name of this thread.

Returns:

the name, never null.

getThreadGroup

public final ThreadGroup getThreadGroup()

Return the ThreadGroup to which this thread belongs.

Returns:

the threads ThreadGroup, null if this thread has died.

activeCount

public static int activeCount()

Return the number of active thread in the current thread's thread group. If the current thread's thread group is null, return 1.

Returns:

the number of active threads in the current thread's thread group or 1 if the thread group is null.

enumerate

public static int enumerate(Thread[] tarray)
                     throws SecurityException

enumerate enumberates all active threads in the current thread's thread group.

Parameters:

tarray - the target array the thread should be stored in. must not be null.

Returns:

the number of threads stored in tarray.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

countStackFrames

public int countStackFrames()
                     throws IllegalThreadStateException

Deprecated. Since this must be suspended for this operation, and suspend is deprecated, this is also deprecated.

countStackFrames counts the number of stack frames in this thread.

Returns:

the number of stack frames.

Throws:

IllegalThreadStateException

join

public final void join(long millis)
                throws InterruptedException

join waits for this thread to die.

Parameters:

millis - the timeout in milliseconds. 0 for no timeout.

Throws:

InterruptedException - if this thread is interrupted while waiting.

IllegalArgumentException - if millis is negative.

join

public final void join(long millis,
                       int nanos)
                throws InterruptedException,
                       IllegalArgumentException

join waits for this thread to die using given timeout. Use no timeout if millis and nanos are 0.

Parameters:

millis - the timeout in milliseconds.

nanos - the timeout in nanoseconds.

Throws:

InterruptedException - if this thread is interrupted while waiting.

IllegalArgumentException - if millis is negative or nanos is larger than 999999.

join

public final void join()
                throws InterruptedException

join waits for this thread to die using no timeout.

Throws:

InterruptedException - if this thread is interrupted while waiting.

dumpStack

public static void dumpStack()

dumpStack print a stack trace for the current thread to System.err. This function is intended for debugging purposes only.

setDaemon

public final void setDaemon(boolean on)
                     throws SecurityException,
                            IllegalThreadStateException

setDaemon sets the daemon state of this thread. This can only be called before this thread is started.

Parameters:

on - true to set the daemon state, false to clear it.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

IllegalThreadStateException

isDaemon

public final boolean isDaemon()

isDaemon return the daemon state of this thread.

Returns:

this thread's daemon state.

checkAccess

public final void checkAccess()
                       throws SecurityException

checkAccess checks if the current thread is permitted to access this thread.

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

toString

public String toString()

toString returns a string representation of this thread consisting of thread name, priority and thread group.

Overrides:

toString in class Object

Returns:

the string representation of this thread.

getContextClassLoader

public ClassLoader getContextClassLoader()
                                  throws SecurityException

getContextClassLoader determines the context class loader for this thread. If the context class loader was not set explicitly, this will the the class loader that was used to load the application.

Returns:

the context class loader of this thread. The result is never null unless it was set to null explicitly by a call of setContextClassLoader(null). If the context class loader was not set, the class loader used to load the application will be used.

Throws:

SecurityException - if a security manager is installed and a call to checkPermission with a new RuntimePermission("getClassLoader") as argument results in a SecurityException.

Since:

1.2

setContextClassLoader

public void setContextClassLoader(ClassLoader cl)

setContextClassLoader sets the context class loader for this thread.

Parameters:

cl - the new context class loader. may be null to refer to the application class loader.

Throws:

SecurityException - if a security manager is installed and a call to checkPermission with a new RuntimePermission("setContextClassLoader") as argument results in a SecurityException.

Since:

1.2

holdsLock

public static boolean holdsLock(Object obj)

Checks if the current thread is the owner of the given objects monitor.

Parameters:

obj - the object we want to check whether we hold a lock on.

Returns:

true if the current thread owns the monitor of obj, false otherwise.

Throws:

NullPointerExceptions - if obj is null.

Since:

1.4

getStackTrace

public StackTraceElement[] getStackTrace()

Gets the stack trace of this thread. The stack trace may be incomplete if some methods on the stack are compiled. It is possible that an empty stack is returned if all methods are native or compiled. If the thread was not yet started or if it has already terminated an empty stack will be generated.
NOTE: If this method is called on any other thread than the current thread that thread will be blocked unbounded. This may lead to priority inversions and deadlocks. If you expect realtime behavior do not use this method.

Returns:

Stack trace for this thread.

Since:

1.5

getAllStackTraces

public static Map<Thread,StackTraceElement[]> getAllStackTraces()

Gets the stack traces of all currently alive threads. NOTE: To read a threads stack trace that thread is blocked unbounded. This may lead to priority inversions and deadlocks. If you expect realtime behavior do not use this method.

Returns:

A map that maps Thread object to stack traces.

Since:

1.5

getId

public long getId()

getId returns a unique identifier for this thread. The thread id remains unchanged during until this thread has terminated. After the thread object has been reclaimed, the thread id may be reused for new threads.

Returns:

the thread id.

Since:

1.5

getState

public Thread.State getState()

Returns the current state of this thread. This should only be used for monitoring purposes, not for synchronization or similar tasks.

Returns:

the current state of this thread

Since:

1.5

setDefaultUncaughtExceptionHandler

public static void setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler eh)

Set the default handler for handling an exception that caused termination of a thread that was not equipped with an uncaught exception handler.

Parameters:

eh - the new uncaught exception handler, null to reset to default handler.

Since:

1.5

getDefaultUncaughtExceptionHandler

public static Thread.UncaughtExceptionHandler getDefaultUncaughtExceptionHandler()

Return the current default uncaught exception handler. Null if none was set.

Returns:

the default uncaught exception handler, null if none.

Since:

1.5

getUncaughtExceptionHandler

public Thread.UncaughtExceptionHandler getUncaughtExceptionHandler()

return this thread's uncaught exception handler. If none was set and the thread has not died, then return the thread's thread group.

Returns:

the handler that handles uncaught exceptions for this thread. null if this thread has not thread group and no handler was set.

Since:

1.5

setUncaughtExceptionHandler

public void setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler eh)

Sets this thread's uncaught exception handler.

Parameters:

eh - the new uncaught exception handler, null to reset the uncaught exception handler to the default handler (the thread group).

Throws:

SecurityException - if a security manager is installed and a call to checkAccess(this) causes a SecurityException.

Since:

1.5