Java Thread Interrupt && API Introduction

http://java.sun.com/docs/books/tutorial/essential/concurrency/interrupt.html





Interrupts
An interrupt is an indication to a thread that it should stop what it is doing and do something else. It's up to the programmer to decide exactly how a thread responds to an interrupt, but it is very common for the thread to terminate. This is the usage emphasized in this lesson.
A thread sends an interrupt by invoking

interrupt

on the

Thread

object for the thread to be interrupted. For the interrupt mechanism to work correctly, the interrupted thread must support its own interruption.

Supporting Interruption

How does a thread support its own interruption? This depends on what it's currently doing. If the thread is frequently invoking methods that throw

InterruptedException

, it simply returns from the

run

method after it catches that exception. For example, suppose the central message loop in the

SleepMessages

example were in the

run

method of a thread's

Runnable

object. Then it might be modified as follows to support interrupts:

for (int i = 0; i < importantInfo.length; i++) {
    //Pause for 4 seconds
    try {
        Thread.sleep(4000);
    } catch (InterruptedException e) {
        //We've been interrupted: no more messages.
        return;
    }
    //Print a message
    System.out.println(importantInfo[i]);
}

Many methods that throw

InterruptedException

, such as

sleep

, are designed to cancel their current operation and return immediately when an interrupt is received.
What if a thread goes a long time without invoking a method that throws

InterruptedException

? Then it must periodically invoke

Thread.interrupted

, which returns

true

if an interrupt has been received. For example:

for (int i = 0; i < inputs.length; i++) {
    heavyCrunch(inputs[i]);
    if (Thread.interrupted()) {
        //We've been interrupted: no more crunching.
        return;
    }
}

In this simple example, the code simply tests for the interrupt and exits the thread if one has been received. In more complex applications, it might make more sense to throw an

InterruptedException

:

if (Thread.interrupted()) {
    throw new InterruptedException();
}

This allows interrupt handling code to be centralized in a

catch

clause.

The Interrupt Status Flag

The interrupt mechanism is implemented using an internal flag known as the interrupt status. Invoking

Thread.interrupt

sets this flag. When a thread checks for an interrupt by invoking the static method

Thread.interrupted

, interrupt status is cleared. The non-static

Thread.isInterrupted

, which is used by one thread to query the interrupt status of another, does not change the interrupt status flag.
By convention, any method that exits by throwing an

InterruptedException

clears interrupt status when it does so. However, it's always possible that interrupt status will immediately be set again, by another thread invoking

interrupt

.







API Introduction:

interrupt

public void interrupt()

Interrupts this thread.
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 then the channel will be closed, the thread's interrupt status will be set, and the thread will receive a

ClosedByInterruptException

.



If this thread is blocked in a

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.



Throws:

SecurityException

- if the current thread cannot modify this thread