javax.realtime
Class AsynchronouslyInterruptedException

java.lang.Object
  extended byjava.lang.Throwable
      extended byjava.lang.Exception
          extended byjava.lang.InterruptedException
              extended byjavax.realtime.AsynchronouslyInterruptedException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Timed

public class AsynchronouslyInterruptedException
extends 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 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.

Author:
Morgan Deters
See Also:
Serialized Form

Constructor Summary
AsynchronouslyInterruptedException()
          Constructs an AsynchronouslyInterruptedException.
 
Method Summary
 boolean clear()
          Query whether this is in a pending state for the currently-executing Schedulable object, and, if so, make it non-pending.
 boolean disable()
          Disable the throwing of this exception.
 boolean doInterruptible(Interruptible logic)
          Execute the argument's run() method.
 boolean enable()
          Enable the throwing of this exception.
 boolean fire()
          If doInterruptible() has been invoked but not completed, this method makes this exception the current exception.
 boolean happened(boolean propagate)
          Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ. Quoting from the spec: "This method seriously violates standard Java exception semantics, and while it is a convenience it is not required. The happened(boolean) method can be replaced with the clear() method and application logic."
 boolean isEnabled()
          Returns true if this exception is enabled; otherwise false.
static void propagate()
          Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ. Quoting from the spec: "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."
 
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
 

Constructor Detail

AsynchronouslyInterruptedException

public AsynchronouslyInterruptedException()
Constructs an AsynchronouslyInterruptedException.

Method Detail

enable

public boolean enable()
Enable the throwing of this exception. This is valid only within a call to doInterruptible(). Otherwise it is a no-op (and returns false).

Returns:
true if this is enabled; otherwise returns false

disable

public boolean disable()
Disable the throwing of this exception. If RealtimeThread.interrupt() is called while the exception is disabled, the exception is put in a pending state, and it will be thrown if subsequently enabled. This is valid only within a call to doInterruptible(). Otherwise it is a no-op (and returns false).

Returns:
true if this is disabled; otherwise returns false

isEnabled

public boolean isEnabled()
Returns true if this exception is enabled; otherwise false.

Returns:
true if this exception is enabled; otherwise false

fire

public boolean fire()
If doInterruptible() has been invoked but not completed, this method makes this exception the current exception. If this exception is disabled or if there is no current invocation of doInterruptible(), this method is a no-op (and returns false).

Returns:
true if this was fired; false otherwise.

doInterruptible

public boolean doInterruptible(Interruptible logic)
Execute the argument's run() method. Only one RealtimeThread at a time may call a given AsynchronouslyInterruptedException's doInterruptible() method, and recursive calls within the same thread are not permitted (and attempts to do so will result in this method immediately returning false and taking no other action).

Parameters:
logic - the interruptible logic to be executed
Returns:
true if the method call completed normally; false if another invocation of doInterruptible() is ongoing.

happened

public boolean happened(boolean propagate)
Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ. Quoting from the spec: "This method seriously violates standard Java exception semantics, and while it is a convenience it is not required. The happened(boolean) method can be replaced with the clear() method and application logic."

Query whether this exception is the current exception.

Parameters:
propagate - if true and this exception is not the current one, propagate the exception; if false, then set the state of this exception to nonpending (terminate propagation)
Returns:
true if this is the current exception; false otherwise

propagate

public static void propagate()
Deprecated. This method is deprecated in version 1.0.1(b) of the RTSJ. Quoting from the spec: "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.


clear

public boolean clear()
Query whether this is in a pending state for the currently-executing Schedulable object, and, if so, make it non-pending. This operation is done atomically.

Returns:
true if this was pending; false otherwise
Throws:
IllegalThreadStateException - if called from a regular Java Thread


jRate is developed and maintained by the jRate project development team.
Copyright (c) 2001-2006 Angelo Corsaro and Morgan Deters.