javax.realtime
Class AsynchronouslyInterruptedException

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--java.lang.InterruptedException
                    |
                    +--javax.realtime.AsynchronouslyInterruptedException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

Timed

public class AsynchronouslyInterruptedException

extends java.lang.InterruptedException

An special exception that is thrown in response to an attempt to asynchronously transfer the locus of control of a RealtimeThread.

When a method is declared with AsynchronouslyInterruptedException in its throws clause the platform is expected to asynchronously throw this exception if RealtimeThread.interrupt() is called while the method is executing, or if such an interrupt is pending any time control returns to the method. The interrupt is not thrown while any methods it invokes are executing, unless they are, in turn, declared to throw the exception. This is intended to allow long-running computations to be terminated without the overhead or latency of polling with Thread.interrupted().

The throws AsynchronouslyInterruptedException clause is a marker on a stack frame which allows a method to be statically marked as asynchronously interruptible. Only methods that are marked this way can be interrupted.

When Thread.interrupt(), RealtimeThread.interrupt(), or this.fire() is called, the AsynchronouslyInterruptedException is compared against any currently pending AsynchronouslyInterruptedException on the thread. If there is none, or if the depth of the AsynchronouslyInterruptedException is less than the currently pending AsynchronouslyInterruptedException -- i.e., it is targeted at a less deeply nested method call -- it becomes the currently pending interrupt. Otherwise, it is discarded.

If the current method is interruptible, the exception is thrown on the thread. Otherwise, it just remains pending until control returns to an interruptible method, at which point the AsynchronouslyInterruptedException is thrown. When an interrupt is caught, the caller should invoke the happened() method on the AsynchronouslyInterruptedException in which it is interested to see if it matches the pending AsynchronouslyInterruptedException. If so, the pending AsynchronouslyInterruptedException is cleared from the thread. Otherwise, it will continue to propagate outward.

Thread.interrupt() and RealtimeThread.interrupt() generate a system available generic AsynchronouslyInterruptedException which will always propagate outward through interruptible methods until the generic AsynchronouslyInterruptedException is identified and stopped. Other sources (e.g., this.fire() and Timed) will generate a specific instance of AsynchronouslyInterruptedException which applications can identify and thus limit propagation.

See Also:

Serialized Form

Constructor Summary

AsynchronouslyInterruptedException()
Create an instance of AsynchronouslyInterruptedException.

Method Summary

boolean	disable() Defer the throwing of this exception.
boolean	doInterruptible(Interruptible logic) Execute the run() method of the given Interruptible.
boolean	enable() Enable the throwing of this exception.
boolean	fire() Make this exception the current exception if doInterruptible() has been invoked and not completed.
static AsynchronouslyInterruptedException	getGeneric() Return the system generic AsynchronouslyInterruptedException, which is generated when RealtimeThread.interrupt() is invoked.
boolean	happened(boolean propagate) Used with an instance of this exception to see if the current exception is this exception.
boolean	isEnabled() Query the enabled status of this exception.
static void	propagate() Cause the pending exception to continue up the stack.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()

Create an instance of AsynchronouslyInterruptedException.

Method Detail

getGeneric

public static AsynchronouslyInterruptedException getGeneric()

Return the system generic AsynchronouslyInterruptedException, which is generated when RealtimeThread.interrupt() is invoked.

enable

public boolean enable()

Enable the throwing of this exception. This is valid only within a call to doInterruptible(). Otherwise it returns false and does nothing.

Returns:

True if this is enabled otherwise returns false.

disable

public boolean disable()

Defer the throwing of this exception. If interrupt() is called when this exception is disabled, the exception is put in pending state. The exception will be thrown if this exception is subsequently enabled. This is valid only within a call to doInterruptible(). Otherwise it returns false and does nothing.

Returns:

True if this is disabled otherwise returns false.

isEnabled

public boolean isEnabled()

Query the enabled status of this exception.

Returns:

True if this is enabled otherwise returns false.

fire

public boolean fire()

Make this exception the current exception if doInterruptible() has been invoked and not completed.

Returns:

True if this was fired. If there is no current invocation of doInterruptible(), then false is returned with no other effect. False is also returned if there is already a current doInterruptible() or if disable() has been called.

doInterruptible

public boolean doInterruptible(Interruptible logic)

Execute the run() method of the given Interruptible. This method may be on the stack in exactly one RealtimeThread. An attempt to invoke this method in a thread while it is on the stack of another or the same thread will cause an immediate return with a value of false.

Parameters:

code - An instance of an Interruptible whose run() method will be called.

Returns:

True if the method call completed normally. Returns false if another call to doInterruptible has not completed.

happened

public boolean happened(boolean propagate)

Used with an instance of this exception to see if the current exception is this exception.

Parameters:

propagate - Propagate the exception if true and this exception is not the current one. If false, then the state of this is set to nonpending (i.e., it will stop propagating).

Returns:

True if this is the current exception. Returns false if this is not the current exception.

propagate

public static void propagate()

Cause the pending exception to continue up the stack.