public class: Thread [javadoc | source]
java.lang.Objectjava.lang.Thread
All Implemented Interfaces:
Runnable
Every thread has a priority. Threads with higher priority are
executed in preference to threads with lower priority. Each thread
may or may not also be marked as a daemon. When code running in
some thread creates a new Thread object, the new
thread has its priority initially set equal to the priority of the
creating thread, and is a daemon thread if and only if the
creating thread is a daemon.
When a Java Virtual Machine starts up, there is usually a single
non-daemon thread (which typically calls the method named
main of some designated class). The Java Virtual
Machine continues to execute threads until either of the following
occurs:
- The
exitmethod of classRuntimehas been called and the security manager has permitted the exit operation to take place. - All threads that are not daemon threads have died, either by
returning from the call to the
runmethod or by throwing an exception that propagates beyond therunmethod.
There are two ways to create a new thread of execution. One is to
declare a class to be a subclass of Thread. This
subclass should override the run method of class
Thread. An instance of the subclass can then be
allocated and started. For example, a thread that computes primes
larger than a stated value could be written as follows:
class PrimeThread extends Thread {
long minPrime;
PrimeThread(long minPrime) {
this.minPrime = minPrime;
}
public void run() {
// compute primes larger than minPrime
. . .
}
}
The following code would then create a thread and start it running:
PrimeThread p = new PrimeThread(143);
p.start();
The other way to create a thread is to declare a class that
implements the Runnable interface. That class then
implements the run method. An instance of the class can
then be allocated, passed as an argument when creating
Thread, and started. The same example in this other
style looks like the following:
class PrimeRun implements Runnable {
long minPrime;
PrimeRun(long minPrime) {
this.minPrime = minPrime;
}
public void run() {
// compute primes larger than minPrime
. . .
}
}
The following code would then create a thread and start it running:
PrimeRun p = new PrimeRun(143);
new Thread(p).start();
Every thread has a name for identification purposes. More than one thread may have the same name. If a name is not specified when a thread is created, a new name is generated for it.
Unless otherwise noted, passing a {@code null} argument to a constructor or method in this class will cause a NullPointerException to be thrown.
| Nested Class Summary: | ||
|---|---|---|
| public enum class | Thread.State | A thread state. A thread can be in one of the following states:
A thread can be in only one state at a given point in time. These states are virtual machine states which do not reflect any operating system thread states. |
| public interface | Thread.UncaughtExceptionHandler | Interface for handlers invoked when a Thread abruptly
terminates due to an uncaught exception.
When a thread is about to terminate due to an uncaught exception the Java Virtual Machine will query the thread for its UncaughtExceptionHandler using {@link #getUncaughtExceptionHandler} and will invoke the handler's uncaughtException method, passing the thread and the exception as arguments. If a thread has not had its UncaughtExceptionHandler explicitly set, then its ThreadGroup object acts as its UncaughtExceptionHandler. If the ThreadGroup object has no special requirements for dealing with the exception, it can forward the invocation to the {@linkplain #getDefaultUncaughtExceptionHandler default uncaught exception handler}. |
| static class | Thread.WeakClassKey | Weak key for Class objects. * |
| Field Summary | ||
|---|---|---|
| ThreadLocalMap | threadLocals | |
| ThreadLocalMap | inheritableThreadLocals | |
| volatile Object | parkBlocker | The argument supplied to the current call to java.util.concurrent.locks.LockSupport.park. Set by (private) java.util.concurrent.locks.LockSupport.setBlocker Accessed using java.util.concurrent.locks.LockSupport.getBlocker |
| public static final int | MIN_PRIORITY | The minimum priority that a thread can have. |
| public static final int | NORM_PRIORITY | The default priority that is assigned to a thread. |
| public static final int | MAX_PRIORITY | The maximum priority that a thread can have. |
| Constructor: |
|---|
|
|
|
|
|
|
If there is a security manager, its checkAccess method is invoked with the ThreadGroup as its argument. In addition, its {@code checkPermission} method is invoked with the {@code RuntimePermission("enableContextClassLoaderOverride")} permission when invoked directly or indirectly by the constructor of a subclass which overrides the {@code getContextClassLoader} or {@code setContextClassLoader} methods. The priority of the newly created thread is set equal to the priority of the thread creating it, that is, the currently running thread. The method {@linkplain #setPriority setPriority} may be used to change the priority to a new value. The newly created thread is initially marked as being a daemon thread if and only if the thread creating it is currently marked as a daemon thread. The method {@linkplain #setDaemon setDaemon} may be used to change whether or not a thread is a daemon.
|
This constructor is identical to #Thread(ThreadGroup,Runnable,String) with the exception of the fact that it allows the thread stack size to be specified. The stack size is the approximate number of bytes of address space that the virtual machine is to allocate for this thread's stack. The effect of the {@code stackSize} parameter, if any, is highly platform dependent. On some platforms, specifying a higher value for the {@code stackSize} parameter may allow a thread to achieve greater recursion depth before throwing a StackOverflowError . Similarly, specifying a lower value may allow a greater number of threads to exist concurrently without throwing an OutOfMemoryError (or other internal error). The details of the relationship between the value of the stackSize parameter and the maximum recursion depth and concurrency level are platform-dependent. On some platforms, the value of the {@code stackSize} parameter may have no effect whatsoever. The virtual machine is free to treat the {@code stackSize} parameter as a suggestion. If the specified value is unreasonably low for the platform, the virtual machine may instead use some platform-specific minimum value; if the specified value is unreasonably high, the virtual machine may instead use some platform-specific maximum. Likewise, the virtual machine is free to round the specified value up or down as it sees fit (or to ignore it completely). Specifying a value of zero for the {@code stackSize} parameter will cause this constructor to behave exactly like the {@code Thread(ThreadGroup, Runnable, String)} constructor. Due to the platform-dependent nature of the behavior of this constructor, extreme care should be exercised in its use. The thread stack size necessary to perform a given computation will likely vary from one JRE implementation to another. In light of this variation, careful tuning of the stack size parameter may be required, and the tuning may need to be repeated for each JRE implementation on which an application is to run. Implementation note: Java platform implementers are encouraged to document their implementation's behavior with respect to the {@code stackSize} parameter.
|
| Method from java.lang.Thread Summary: |
|---|
| activeCount, blockedOn, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, processQueue, resume, run, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield |
| Methods from java.lang.Object: |
|---|
| clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method from java.lang.Thread Detail: |
|---|
The value returned is only an estimate because the number of threads may change dynamically while this method traverses internal data structures, and might be affected by the presence of certain system threads. This method is intended primarily for debugging and monitoring purposes. |
|
If there is a security manager, its |
|
|
|
Deprecated! This - method was originally designed to destroy this
thread without any cleanup. Any monitors it held would have
remained locked. However, the method was never implemented.
If if were to be implemented, it would be deadlock-prone in
much the manner of #suspend . If the target thread held
a lock protecting a critical system resource when it was
destroyed, no thread could ever access this resource again.
If another thread ever attempted to lock this resource, deadlock
would result. Such deadlocks typically manifest themselves as
"frozen" processes. For more information, see
Why are Thread.stop, Thread.suspend and Thread.resume Deprecated?.
|
|
An application might use the {@linkplain #activeCount activeCount} method to get an estimate of how big the array should be, however if the array is too short to hold all the threads, the extra threads are silently ignored. If it is critical to obtain every active thread in the current thread's thread group and its subgroups, the invoker should verify that the returned int value is strictly less than the length of {@code tarray}. Due to the inherent race condition in this method, it is recommended that the method only be used for debugging and monitoring purposes. |
The threads may be executing while this method is called. The stack trace of each thread only represents a snapshot and each stack trace may be obtained at different time. A zero-length array will be returned in the map value if the virtual machine has no stack trace information about a thread. If there is a security manager, then the security manager's checkPermission method is called with a RuntimePermission("getStackTrace") permission as well as RuntimePermission("modifyThreadGroup") permission to see if it is ok to get the stack trace of all threads. |
If a security manager is present, and the invoker's class loader is not {@code null} and is not the same as or an ancestor of the context class loader, then this method invokes the security manager's checkPermission method with a RuntimePermission {@code ("getClassLoader")} permission to verify that retrieval of the context class loader is permitted. |
|
|
|
|
If there is a security manager, and this thread is not the current thread, then the security manager's checkPermission method is called with a RuntimePermission("getStackTrace") permission to see if it's ok to get the stack trace. Some virtual machines may, under some circumstances, omit one or more stack frames from the stack trace. In the extreme case, a virtual machine that has no stack trace information concerning this thread is permitted to return a zero-length array from this method. |
|
|
|
This method is designed to allow a program to assert that the current thread already holds a specified lock:
assert Thread.holdsLock(obj);
|
Unless the current thread is interrupting itself, which is always permitted, the checkAccess method of this thread is invoked, which may cause a SecurityException to be thrown. If this thread is blocked in an invocation of the wait() , wait(long) , or wait(long, int) methods of the Object class, or of the #join() , #join(long) , #join(long, int) , #sleep(long) , or #sleep(long, int) , methods of this class, then its interrupt status will be cleared and it will receive an InterruptedException . If this thread is blocked in an I/O operation upon an interruptible
channel If this thread is blocked in a java.nio.channels.Selector then the thread's interrupt status will be set and it will return immediately from the selection operation, possibly with a non-zero value, just as if the selector's wakeup method were invoked. If none of the previous conditions hold then this thread's interrupt status will be set. Interrupting a thread that is not alive need not have any effect. |
A thread interruption ignored because a thread was not alive at the time of the interrupt will be reflected by this method returning false. |
|
|
A thread interruption ignored because a thread was not alive at the time of the interrupt will be reflected by this method returning false. |
An invocation of this method behaves in exactly the same way as the invocation {@linkplain #join(long) join}{@code (0)} |
This implementation uses a loop of {@code this.wait} calls conditioned on {@code this.isAlive}. As a thread terminates the {@code this.notifyAll} method is invoked. It is recommended that applications not use {@code wait}, {@code notify}, or {@code notifyAll} on {@code Thread} instances. |
This implementation uses a loop of {@code this.wait} calls conditioned on {@code this.isAlive}. As a thread terminates the {@code this.notifyAll} method is invoked. It is recommended that applications not use {@code wait}, {@code notify}, or {@code notifyAll} on {@code Thread} instances. |
|
Deprecated! This - method exists solely for use with #suspend ,
which has been deprecated because it is deadlock-prone.
For more information, see
Why
are Thread.stop, Thread.suspend and Thread.resume Deprecated?.
First, the If the thread is alive but suspended, it is resumed and is permitted to make progress in its execution. |
Runnable run object, then that
Runnable object's run method is called;
otherwise, this method does nothing and returns.
Subclasses of |
If a security manager is present, its checkPermission method is invoked with a RuntimePermission {@code ("setContextClassLoader")} permission to see if setting the context ClassLoader is permitted. |
This method must be invoked before the thread is started. |
Uncaught exception handling is controlled first by the thread, then by the thread's ThreadGroup object and finally by the default uncaught exception handler. If the thread does not have an explicit uncaught exception handler set, and the thread's thread group (including parent thread groups) does not specialize its uncaughtException method, then the default handler's uncaughtException method will be invoked. By setting the default uncaught exception handler, an application can change the way in which uncaught exceptions are handled (such as logging to a specific device, or file) for those threads that would already accept whatever "default" behavior the system provided. Note that the default uncaught exception handler should not usually defer to the thread's ThreadGroup object, as that could cause infinite recursion. |
name.
First the |
First the
Otherwise, the priority of this thread is set to the smaller of
the specified |
A thread can take full control of how it responds to uncaught exceptions by having its uncaught exception handler explicitly set. If no such handler is set then the thread's ThreadGroup object acts as its handler. |
|
|
run method of this thread.
The result is that two threads are running concurrently: the
current thread (which returns from the call to the
It is never legal to start a thread more than once. In particular, a thread may not be restarted once it has completed execution. |
Deprecated! This - method is inherently unsafe. Stopping a thread with
Thread.stop causes it to unlock all of the monitors that it
has locked (as a natural consequence of the unchecked
ThreadDeath exception propagating up the stack). If
any of the objects previously protected by these monitors were in
an inconsistent state, the damaged objects become visible to
other threads, potentially resulting in arbitrary behavior. Many
uses of stop should be replaced by code that simply
modifies some variable to indicate that the target thread should
stop running. The target thread should check this variable
regularly, and return from its run method in an orderly fashion
if the variable indicates that it is to stop running. If the
target thread waits for long periods (on a condition variable,
for example), the interrupt method should be used to
interrupt the wait.
For more information, see
Why
are Thread.stop, Thread.suspend and Thread.resume Deprecated?.
If there is a security manager installed, its
If this thread is different from the current thread (that is, the current
thread is trying to stop a thread other than itself), the
security manager's
The thread represented by this thread is forced to stop whatever
it is doing abnormally and to throw a newly created
It is permitted to stop a thread that has not yet been started. If the thread is eventually started, it immediately terminates.
An application should not normally try to catch
The top-level error handler that reacts to otherwise uncaught
exceptions does not print out a message or otherwise notify the
application if the uncaught exception is an instance of
|
Deprecated! This - method is inherently unsafe. See #stop()
for details. An additional danger of this
method is that it may be used to generate exceptions that the
target thread is unprepared to handle (including checked
exceptions that the thread could not possibly throw, were it
not for this method).
For more information, see
Why
are Thread.stop, Thread.suspend and Thread.resume Deprecated?.
If there is a security manager installed, the
If this thread is different from the current thread (that is, the current
thread is trying to stop a thread other than itself) or
If the argument
The thread represented by this thread is forced to stop
whatever it is doing abnormally and to throw the
It is permitted to stop a thread that has not yet been started. If the thread is eventually started, it immediately terminates. |
Deprecated! This - method has been deprecated, as it is
inherently deadlock-prone. If the target thread holds a lock on the
monitor protecting a critical system resource when it is suspended, no
thread can access this resource until the target thread is resumed. If
the thread that would resume the target thread attempts to lock this
monitor prior to calling resume, deadlock results. Such
deadlocks typically manifest themselves as "frozen" processes.
For more information, see
Why
are Thread.stop, Thread.suspend and Thread.resume Deprecated?.
First, the If the thread is alive, it is suspended and makes no further progress unless and until it is resumed. |
|
Yield is a heuristic attempt to improve relative progression between threads that would otherwise over-utilise a CPU. Its use should be combined with detailed profiling and benchmarking to ensure that it actually has the desired effect. It is rarely appropriate to use this method. It may be useful for debugging or testing purposes, where it may help to reproduce bugs due to race conditions. It may also be useful when designing concurrency control constructs such as the ones in the java.util.concurrent.locks package. |
public native int