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

A 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 compuations to be terminated without the overhead or latency of polling with java.lang.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(), interrupt(), or this.fire is called, the AsynchronouslyInterruptedException is compared against any currently pending AsynchronouslyInterruptedException on the thread. If there none, or 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

Field Summary

private boolean

enabled

Fields inherited from class java.lang.Exception

Fields inherited from class java.lang.Throwable

Constructor Summary

AsynchronouslyInterruptedException()
Create an instance of AsynchronouslyInterruptedException.

Method Summary

boolean	disable() Defer the throwing of this exception.
boolean	doInterruptible(javax.realtime.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 javax.realtime.AsynchronouslyInterruptedException	getGeneric() Gets 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, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Field Detail

enabled

private boolean enabled

Constructor Detail

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()

Create an instance of AsynchronouslyInterruptedException.

Method Detail

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 and invoked within a call to doInterruptable(). False if this is enabled and invoked within a call to doInterruptable() or invoked outside of a call to doInterruptable().

doInterruptible

public boolean doInterruptible(javax.realtime.Interruptible logic)

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

Parameters:

logic - An instance of an Interruptable whose run() method will be called.

Returns:

True if the method call completed normally. False if another call to doInterruptible() has not completed.

enable

public boolean enable()

Enable the throwing of this exception. This method is valid only within a call to doInterruptible(). If invoked outside of a call to doInterruptible() this method returns false and does nothing.

Returns:

True if this is enabled and invoked within a call to doInterruptible(). False if this is disabled and invoked within a call to doInterruptible() or invoked outside of a call to doInterruptible().

fire

public boolean fire()

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

Returns:

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

getGeneric

public static javax.realtime.AsynchronouslyInterruptedException getGeneric()

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

Returns:

The generic AsynchronouslyInterruptedException.

happened

public boolean happened(boolean propagate)

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

Parameters:

propagate - If true and this exception is not the current one propagate the exception. 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. False if this is not the current exception.

isEnabled

public boolean isEnabled()

Query the enabled status of this exception.

Returns:

True if this is enabled. False otherwise.

propagate

public static void propagate()

Cause the pending exception to continue up the stack.