javax.realtime.control

Class AsynchronouslyInterruptedException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.InterruptedException

javax.realtime.control.AsynchronouslyInterruptedException

All Implemented Interfaces:

java.io.Serializable, StaticThrowable<AsynchronouslyInterruptedException>

Direct Known Subclasses:

AsynchronouslyInterruptedException, Timed

public class AsynchronouslyInterruptedException
extends java.lang.InterruptedException
implements StaticThrowable<AsynchronouslyInterruptedException>

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

An instance of Schedulable executing a method or constructor, which lists 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 when the called method/constructor is asynchronously interruptible. (See this chapter's introduction section for the detailed semantics).

The asynchronous interrupt is generated for a Schedulable, s, when the s.interrupt() method is called or the fire() method is called of an AIE for which s has a doInterruptible method call in progress.

When an asynchronous interrupt is generated when the target Schedulable is executing within an ATC-deferred section, the asynchronous interrupt becomes pending. A pending asynchronous interrupt is delivered when the target Schedulable 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 java.lang.Thread.interrupted().

When RealtimeThread.interrupt(), or AsynchronouslyInterruptedException.fire() is called, the AsynchronouslyInterruptedException is compared against any currently pending AsynchronouslyInterruptedException on the Schedulable. When there is none, or when 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. When so, the pending AsynchronouslyInterruptedException is cleared for the Schedulable and clear returns true. Otherwise, the current AIE remains pending and clear returns false.

Schedulable.interrupt() generates the 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-instance of Schedulable.

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

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface javax.realtime.StaticThrowable

StaticThrowable.Hidden

Constructor Summary

Constructors

Constructor and Description
AsynchronouslyInterruptedException() Creates an instance of AsynchronouslyInterruptedException.
AsynchronouslyInterruptedException(java.lang.String message) Creates an instance of AsynchronouslyInterruptedException.

Method Summary

Modifier and Type	Method and Description
boolean	clear() Atomically checks whether or not this is pending on the currently executing schedulable, and when so, makes it non-pending.
boolean	disable() Disables the throwing of this exception.
boolean	doInterruptible(Interruptible logic) Executes the run() method of the given Interruptible.
boolean	enable() Enables the throwing of this exception.
java.lang.Throwable	fillInStackTrace() Does nothing, since no stacktrace is kept.
boolean	fire() Generates this exception when its doInterruptible has been invoked and not completed.
static AsynchronouslyInterruptedException	get() Gets the preallocated version of this Throwable.
static AsynchronouslyInterruptedException	getGeneric() Gets the singleton system generic AsynchronouslyInterruptedException that is generated when RealtimeThread.interrupt() is invoked.
AsynchronouslyInterruptedException	getSingleton() For the case of legacy code that creates an RTSJ exception explicity, this provides a means of obtaining its singleton version.
java.lang.StackTraceElement[]	getStackTrace() No stacktrace is kept, so none can be returned.
boolean	isEnabled() Queries the enabled status of this exception.
void	printStackTrace() No stacktrace is kept, so a message to that effect is printed.
void	printStackTrace(java.io.PrintStream stream) No stacktrace is kept, so a message to that effect is printed.
void	printStackTrace(java.io.PrintWriter writer) No stacktrace is kept, so a message to that effect is printed.
void	setStackTrace(java.lang.StackTraceElement[] new_stackTrace) Does nothing, since no stacktrace is kept.
static void	throwPending() Causes a pending AsynchronouslyInterruptedException to be thrown as a synchronous exception in an ATC-deferred region if one exists.

Methods inherited from class java.lang.Throwable

addSuppressed, getCause, getLocalizedMessage, getMessage, getSuppressed, initCause, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.StaticThrowable

getCause, getLocalizedMessage, getMessage, init, init, init, init, initCause, isStatic, writeReplace

Constructor Detail

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()

Creates an instance of AsynchronouslyInterruptedException.

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException(java.lang.String message)

Creates an instance of AsynchronouslyInterruptedException.

Parameters:

message - A message to identify this instance.

Method Detail

get

public static AsynchronouslyInterruptedException get()

Gets the preallocated version of this Throwable. Allocation is done in memory that acts like ImmortalMemory. The message and cause are cleared and the stack trace is filled out.

Returns:

the preallocated exception.

getGeneric

public static AsynchronouslyInterruptedException getGeneric()
                                                     throws IllegalTaskStateException

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

Returns:

the generic AsynchronouslyInterruptedException.

Throws:

IllegalTaskStateException - when the current thread context is not an instance of Schedulable.

getSingleton

public AsynchronouslyInterruptedException getSingleton()

Description copied from interface: StaticThrowable

For the case of legacy code that creates an RTSJ exception explicity, this provides a means of obtaining its singleton version.

Specified by:

getSingleton in interface StaticThrowable<AsynchronouslyInterruptedException>

Returns:

the singleton version of this exception.

enable

public boolean enable()

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

Returns:

true, when this was disabled before the method was called and the call was invoked whilst the associated doInterruptible was in progress, and false otherwise.

disable

public boolean disable()

Disables the throwing of this exception. When 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. When 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.

Returns:

true, when this was enabled before the method was called and the call was invoked with the associated doInterruptible in progress, and false otherwise.

isEnabled

public boolean isEnabled()

Queries 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, when this is enabled and the method call was invoked in the context of the associated doInterruptible, and false otherwise.

fire

public boolean fire()

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

Behaves as if Thread.interrupt() were called on the task currently operating within this exception's doInterruptible.

Returns:

true, when this is not disabled and it has an invocation of a doInterruptible in progress and there is no outstanding fire request, and 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 while it is on the stack of another or the same schedulable will cause an immediate return with a value of false.

The run() method of the 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().

This AIE is cleared on return from doInterruptible.

Parameters:

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

Returns:

true, when the method call completed normally, and false, when another call to doInterruptible has not completed.

Throws:

IllegalTaskStateException - when called on the generic AsynchronouslyInterruptedException.

StaticIllegalArgumentException - when logic is null.

Since:

RTSJ 2.0 no longer throws an exception when called from a Java thread.

clear

public boolean clear()

Atomically checks whether or not this is pending on the currently executing schedulable, and when so, makes it non-pending.

This method may be called at any time, and in particular need not be called in a try or catch block.

Returns:

true, when this was pending, and false, when this was not pending.

Since:

RTSJ 1.0.1, RTSJ 2.0 no longer throws an exception when called from a task that is not an instance of Schedulable.

throwPending

public static void throwPending()
                         throws AsynchronouslyInterruptedException

Causes a pending AsynchronouslyInterruptedException to be thrown as a synchronous exception in an ATC-deferred region if one exists.

Throws:

AsynchronouslyInterruptedException - if an AIE is pending.

Since:

RTSJ 2.0

fillInStackTrace

public java.lang.Throwable fillInStackTrace()

Does nothing, since no stacktrace is kept.

Specified by:

fillInStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

fillInStackTrace in class java.lang.Throwable

Returns:

this instance.

setStackTrace

public void setStackTrace(java.lang.StackTraceElement[] new_stackTrace)
                   throws java.lang.NullPointerException

Does nothing, since no stacktrace is kept.

Specified by:

setStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

setStackTrace in class java.lang.Throwable

Parameters:

new_stackTrace - the stack trace to be used as replace.

Throws:

java.lang.NullPointerException - when new_stackTrace or any element of new_stackTrace is null.

getStackTrace

public java.lang.StackTraceElement[] getStackTrace()

No stacktrace is kept, so none can be returned.

Specified by:

getStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

getStackTrace in class java.lang.Throwable

Returns:

an empty array.

printStackTrace

public void printStackTrace()

No stacktrace is kept, so a message to that effect is printed.

Specified by:

printStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

printStackTrace in class java.lang.Throwable

printStackTrace

public void printStackTrace(java.io.PrintStream stream)

No stacktrace is kept, so a message to that effect is printed.

Specified by:

printStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

stream - A PrintStream for printing

printStackTrace

public void printStackTrace(java.io.PrintWriter writer)

No stacktrace is kept, so a message to that effect is printed.

Specified by:

printStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

writer - A PrintWriter for printing