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 schedulable object.

A schedulable object that is executing a method or constructor, which is declared with an AsynchronouslyInterruptedException in its throws clause, can be asynchronously interrupted except when it is executing in the lexical scope of a synchronized statement within that method/constructor. As soon as the schedulable object leaves the lexical scope of the method by calling another method/constructor it may be asynchronously interrupted if the called method/constructor is asynchronously interruptible. (See this chapter's introduction section for the detailed semantics).

The asynchronous interrupt is generated for a real-time thread, t, when the t.interrupt() method is called or the fire method is called of an AIE for which t has a doInterruptible method call in progress.

The interrupt is generated for an AEH (or BAEH), h, if the fire method is called of an AIE for which h has a doInterruptible method call in progress.

If an asynchronous interrupt is generated when the target real-time thread/schedulable object is executing within an ATC-deferred section, the asynchronous interrupt becomes pending. A pending asynchronous interrupt is delivered when the target real-time thread/schedulable object next attempts to enter asynchronously interruptible code.

Asynchronous transfers of control (ATCs) are intended to allow long-running computations to be terminated without the overhead or latency of polling with Thread.interrupted().

When RealtimeThread.interrupt(), or AsynchronouslyInterruptedException.fire() is called, the AsynchronouslyInterruptedException is compared against any currently pending AsynchronouslyInterruptedException on the schedulable object. 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), the new AsynchronouslyInterruptedException becomes the currently pending AsynchronouslyInterruptedException and the previously pending AsynchronouslyInterruptedException is discarded. Otherwise, the new AsynchronouslyInterruptedException is discarded.

When an AsynchronouslyInterruptedException is caught, the catch clause may invoke the clear() method on the AsynchronouslyInterruptedException in which it is interested to see if the exception matches the pending AsynchronouslyInterruptedException. If so, the pending AsynchronouslyInterruptedException is cleared for the schedulable object and clear returns true. Otherwise, the current AIE remains pending and clear returns false.

RealtimeThread.interrupt() generates a system-wide generic AsynchronouslyInterruptedException which will always propagate outward through interruptible methods until the generic AsynchronouslyInterruptedException is identified and handled. The pending state of the generic AIE is per-schedulable object.

Other sources (e.g., AsynchronouslyInterruptedException.fire() and Timed) will generate specific instances of AsynchronouslyInterruptedException which applications can identify and thus limit propagation.

AsyncEventHandler objects should interact with the ATC mechanisms via the Interruptible interface.

See Also:

Serialized Form

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()

Create an instance of AsynchronouslyInterruptedException.

getGeneric

public static AsynchronouslyInterruptedException getGeneric()

Gets the singleton system generic AsynchronouslyInterruptedException that is generated when RealtimeThread.interrupt()is invoked.

Returns:

The generic AsynchronouslyInterruptedException.

Throws:

java.lang.IllegalThreadStateException - if the current thread is a Java thread.

enable

public boolean enable()

Enable the throwing of this exception. This method is valid only when the caller has a call to doInterruptible() in progress. If invoked when no call to doInterruptible() is in progress, enable returns false and does nothing.

Returns:

True if this was disabled before the method was called and the call was invoked whilst the associated doInterruptible() is in progress. False: otherwise.

disable

public boolean disable()

Disable the throwing of this exception. If the fire method is called on this AIE whilst it is disabled, the fire is held pending and delivered as soon as the AIE is enabled and the interruptible code is within an AI-method. If an AIE is pending when the associated disable method is called, the AIE remains pending, and is delivered as soon as the AIE is enabled and the interruptible code is within an AI-method.

This method is valid only when the caller has a call to doInterruptible() in progress. If invoked when no call to doInterruptible() is in progress, disable returns false and does nothing.

Note: disabling the genericAIE associated with a real-time thread only affects the firing of that AIE. If the genericAIE is generated by the RealtimeThread.interrupt() mechanism, the AIE is delivered (unless the Interruptible code is in an AI-deferred region, in which case it is marked as pending and handled in the usual way).

Returns:

True if this was enabled before the method was called and the call was invoked with the associated doInterruptible() in progress. False: otherwise.

isEnabled

public boolean isEnabled()

Query the enabled status of this exception.

This method is valid only when the caller has a call to doInterruptible() in progress. If invoked when no call to doInterruptible() is in progress, enable returns false and does nothing.

Returns:

True if this is enabled and the method call was invoked in the context of the associated doInterruptible(). False otherwise.

fire

public boolean fire()

Generate this exception if its doInterruptible() has been invoked and not completed. If this is the only outstanding AIE on the schedulable object that invoked this AIE's doInterruptible(Interruptible) method, this AIE becomes that schedulable object's current AIE. Otherwise, it only becomes the current AIE if it is at a less deeper level of nesting compared with the current outstanding AIE.

Returns:

True if this is not disabled and it has an invocation of a doInterruptible() in progress and there is no outstanding fire request. False otherwise.

doInterruptible

public boolean doInterruptible(Interruptible logic)

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

The run method of given Interruptible is always entered with the exception in the enabled state, but that state can be modified with enable() and disable() and the state can be observed with isEnabled().

The interruptAction method of the given Interruptible is called if any AIE is generated for the schedulable object executing the doInterruptible method. The generated AIE remains pending after the interruptAction method has finished if the pending AIE is not the AIE executing the doInterruptible method. If it is, the pending AIE is cleared.

Parameters:

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

Returns:

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

Throws:

java.lang.IllegalThreadStateException - Thrown if called from a Java thread.

java.lang.IllegalArgumentException - Thrown if a null parameter was passed.

happened

public boolean happened(boolean propagate)

Deprecated. Since 1.0.1. This method seriously violates standard Java exception semantics, and while it is a convenience it is not required. The happened method can be replaced with the clear method and application logic.

Used with an instance of this exception to see if the current exception is this exception. When an AsynchronouslyInterruptedException is caught, the catch clause may 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 for the schedulable object and happened returns true. Otherwise, the behavior of happened depends on its propagation parameter. If propagation parameter is true, the AsynchronouslyInterruptedException will continue to propagate outward; i.e., it will be re-thrown by a mechanism that bypassed the normal requirement that the checked exception be identified in the method's signature. If propagation parameter is false, happened will return false and the AsynchronouslyInterruptedException remains pending.

Parameters:

propagate - Control the behavior when this is not the current exception:

• If true and this exception is the current one, set the state of this to non pending and return true.
• If true and this exception is not the current one, propagate the exception; i.e., rethrow it.
• If false and this exception is the current one, the state of this is set to nonpending (i.e., it will stop propagating) and return true.
• If false and this exception is not the current one, return false.

Returns:

True if this is the current exception. False if this is not the current exception.

Throws:

java.lang.IllegalThreadStateException - Thrown if called from a Java thread.

propagate

public static void propagate()

Deprecated. Since 1.0.1. This method seriously violates standard Java exception semantics, and while it is a convenience it is not required. It should be replaced with throw of an instance of AsynchronouslyInterruptedException.

Cause the pending exception to continue up the stack. The current AIE remains pending and control is transferred immediately to the next suitable catch or finally clause under the normal rules for AIE propagation.

If there is no current AIE, the method does nothing and simply returns.

This method is normally used in a catch clause that is handling an AIE, but that is not required. The method may be invoked at any time (from a schedulable object).

Throws:

java.lang.IllegalThreadStateException - Thrown if called from a Java thread.

clear

public boolean clear()

Atomically see if this is pending on the currently executing schedulable object, and if so, make it non-pending.

Returns:

True if this was pending. False if this was not pending.

Throws:

java.lang.IllegalThreadStateException - Thrown if called from a Java thread.

Since:

1.0.1