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>

Jamaica Real-Time Specification for Java class AsynchronouslyInterruptedException.

This class is used to identify methods that should be asynchronously interruptible. Any methods that lists AsynchronouslyInterruptedException or any subclass of this class in its throws clause will be asynchronously interruptible. Within such a method, only code sequences that are enclosed by a synchronized() block are not asynchronously interruptible. However, calls to asynchronously interruptible methods that are performed within a synchronized block are, again, interruptible.

The asynchronous interrupt is generated by either a call to t.interrupt() for a RealtimeThread t or by a call to fire() for a schedulable object that currently performs code within a call to doInterruptible().

An asynchronous interrupt that is caused while the target schedulable object executes code that is not interruptible (a method that does not throw AsynchronouslyInterruptedException or a synchronized() block), the interrupt remains pending until this code enters an interruptible code section.

An AsynchronouslyInterruptedException may be caught, and it may be cleared by a call to clear(). However, propagation of an outer AsynchronouslyInterruptedException may not be stopped by a call to clear.

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() Constructor to create an instance of AsynchronouslyInterruptedException.
AsynchronouslyInterruptedException(java.lang.String message) Creates an instance of AsynchronouslyInterruptedException.

Method Summary

Modifier and Type	Method and Description
boolean	clear() clear checks if it is called on the AIE that is currently pending.
boolean	disable() disable interruption by this exception.
boolean	doInterruptible(Interruptible logic) doInterruptible executes the run() method of the provided Interruptible.
boolean	enable() enable interruption by this exception.
java.lang.Throwable	fillInStackTrace() Calls into the virtual machine to capture the current stack trace in task's local memory.
boolean	fire() fire this exception during the execution of a doInterruptible() section.
static AsynchronouslyInterruptedException	get() Gets the preallocated version of this Throwable.
java.lang.Throwable	getCause() getCause returns the cause of this exception or null when no cause was set.
static AsynchronouslyInterruptedException	getGeneric() getGeneric returns the generic instance of AsynchronouslyInterruptedException that is thrown on a call to RealtimeThread.interrupt().
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() Get the stack trace created by fillInStackTrace for this Throwable as an array of StackTraceElements.
java.lang.Throwable	initCause(java.lang.Throwable causingThrowable) Initializes the cause to the given Throwable is task's local memory.
boolean	isEnabled() isEnabled returns the current state of this AIE: enabled or disabled.
void	printStackTrace() Print stack trace of this Throwable to System.err.
void	printStackTrace(java.io.PrintStream stream) Print the stack trace of this Throwable to the given stream.
void	printStackTrace(java.io.PrintWriter writer) Print the stack trace of this Throwable to the given PrintWriter.
void	setStackTrace(java.lang.StackTraceElement[] new_stackTrace) This method allows overriding the stack trace that was filled during construction of this object.
static void	throwPending() Causes a pending AsynchronouslyInterruptedException to be thrown as a synchronous exception in an AI-deferred region if one exists.

Methods inherited from class java.lang.Throwable

addSuppressed, getLocalizedMessage, getMessage, getSuppressed, 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

getLocalizedMessage, getMessage, init, init, init, init, isStatic, writeReplace

Constructor Detail

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()

Constructor to create 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()

getGeneric returns the generic instance of AsynchronouslyInterruptedException that is thrown on a call to RealtimeThread.interrupt().

Returns:

the generic instance of AsynchronouslyInterruptedException.

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()

enable interruption by this exception. This can be used during the execution of a doInterruptible() section to control interruption by this exception.

If called from an environment that is not currently executing a doInterruptible() section for this exception, this returns false.

If an interruption with this exception occurred during the time this was disabled, a fire() will occur at the point this is re-enabled.

Returns:

true if this was disabled before the call and is enabled now. False if it was already enabled or it could not be enabled because this method was not called from an environment that is executing a doInterruptible() section for this exception.

disable

public boolean disable()

disable interruption by this exception. This can be used during the execution of a doInterruptible section to control interruption by this exception.

If called from an environment that is not currently executing a doInterruptible() section for this exception, this returns false.

If an interruption with this exception occurred during the time this was disabled, a fire() will occur at the point this is re-enabled.

Returns:

true if this was enabled before the call and is disabled now. False if it was already disabled or it could not be enabled because this method was not called from an environment that is executing a doInterruptible() section for this exception.

isEnabled

public boolean isEnabled()

isEnabled returns the current state of this AIE: enabled or disabled.

Returns:

true iff this AIE is enabled.

fire

public boolean fire()

fire this exception during the execution of a doInterruptible() section. This becomes the current AsynchronouslyInterruptedException if the current schedulable object is not interrupted or it is interrupted by an AsynchronouslyInterruptedException with a deeper nesting level than this.

Returns:

true iff this is enabled, a doInterruptible is in progress and the current schedulable object is not interrupted by an AsynchronouslyInterruptedException with a shallower nesting level.

doInterruptible

public boolean doInterruptible(Interruptible logic)

doInterruptible executes the run() method of the provided Interruptible. The execution of this run() method will be interruptible by this exception.

Parameters:

logic - Contains the run() method that specifies the logic to be executed in an interruptible way.

Returns:

false iff this call failed since this AIE is currently running a call to doInterruptible for the current or a different thread.

Throws:

StaticIllegalArgumentException - iff the provided logic parameter is null.

clear

public boolean clear()
              throws java.lang.IllegalThreadStateException

clear checks if it is called on the AIE that is currently pending. If this is the case, this pending exception is cleared and true is returned.

Returns:

true if this is equal to the currently pending AIE, false if it is not.

Throws:

java.lang.IllegalThreadStateException

throwPending

public static void throwPending()
                         throws AsynchronouslyInterruptedException

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

Throws:

AsynchronouslyInterruptedException - when an AIE is pending.

initCause

public java.lang.Throwable initCause(java.lang.Throwable causingThrowable)

Description copied from interface: StaticThrowable

Initializes the cause to the given Throwable is task's local memory.

Specified by:

initCause in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

initCause in class java.lang.Throwable

Parameters:

causingThrowable - the reason why this Throwable gets Thrown.

Returns:

the reference to this Throwable.

getCause

public java.lang.Throwable getCause()

Description copied from interface: StaticThrowable

getCause returns the cause of this exception or null when no cause was set. The cause is another exception that was caught before this exception was created.

Specified by:

getCause in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

getCause in class java.lang.Throwable

Returns:

The cause or null.

fillInStackTrace

public java.lang.Throwable fillInStackTrace()

Description copied from interface: StaticThrowable

Calls into the virtual machine to capture the current stack trace in task's local memory.

Specified by:

fillInStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

fillInStackTrace in class java.lang.Throwable

Returns:

a reference to this Throwable.

setStackTrace

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

Description copied from interface: StaticThrowable

This method allows overriding the stack trace that was filled during construction of this object. It is intended to be used in a serialization context when the stack trace of a remote exception should be treated like a local.

Specified by:

setStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

setStackTrace in class java.lang.Throwable

Parameters:

new_stackTrace - the stack trace to replace be used.

Throws:

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

getStackTrace

public java.lang.StackTraceElement[] getStackTrace()

Description copied from interface: StaticThrowable

Get the stack trace created by fillInStackTrace for this Throwable as an array of StackTraceElements.

The stack trace does not need to contain entries for all methods that are actually on the call stack, the virtual machine may decide to skip some stack trace entries. Even an empty array is a valid result of this function.

Repeated calls of this function without intervening calls to fillInStackTrace will return the same result.

When memory areas of the RTSJ are used (see MemoryArea), and this Throwable was allocated in a different memory area than the current allocation context, the resulting stack trace will be allocated in either the same memory area this was allocated in or the current memory area, depending on which is the least deeply nested, thereby creating objects that are assignment compatible with both areas.

Specified by:

getStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

getStackTrace in class java.lang.Throwable

Returns:

array representing the stack trace, never null.

printStackTrace

public void printStackTrace()

Description copied from interface: StaticThrowable

Print stack trace of this Throwable to System.err.

The printed stack trace contains the result of toString() as the first line followed by one line for each stack trace element that contains the name of the method or constructor, optionally followed by the source file name and source file line number when available.

Specified by:

printStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

printStackTrace in class java.lang.Throwable

printStackTrace

public void printStackTrace(java.io.PrintStream stream)

Description copied from interface: StaticThrowable

Print the stack trace of this Throwable to the given stream.

The printed stack trace contains the result of toString() as the first line followed by one line for each stack trace element that contains the name of the method or constructor, optionally followed by the source file name and source file line number when available.

Specified by:

printStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

stream - the stream to print to.

printStackTrace

public void printStackTrace(java.io.PrintWriter writer)

Description copied from interface: StaticThrowable

Print the stack trace of this Throwable to the given PrintWriter.

The printed stack trace contains the result of toString() as the first line followed by one line for each stack trace element that contains the name of the method or constructor, optionally followed by the source file name and source file line number when available.

Specified by:

printStackTrace in interface StaticThrowable<AsynchronouslyInterruptedException>

Overrides:

printStackTrace in class java.lang.Throwable

Parameters:

writer - the PrintWriter to write to.