|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object java.lang.Throwable java.lang.Exception java.lang.InterruptedException javax.realtime.AsynchronouslyInterruptedException
public class AsynchronouslyInterruptedException
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.
Constructor Summary | |
---|---|
AsynchronouslyInterruptedException()
Create an instance of AsynchronouslyInterruptedException . |
Method Summary | |
---|---|
boolean |
clear()
Atomically see if this is pending on the currently
executing schedulable object, and if so, make it non-pending. |
boolean |
disable()
Disable the throwing of this exception. |
boolean |
doInterruptible(Interruptible logic)
Executes the run() method of the given Interruptible . |
boolean |
enable()
Enable the throwing of this exception. |
boolean |
fire()
Generate this exception if its doInterruptible() has been invoked
and not completed. |
static AsynchronouslyInterruptedException |
getGeneric()
Gets the singleton system generic AsynchronouslyInterruptedException
that is generated when RealtimeThread.interrupt() is invoked. |
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. |
boolean |
isEnabled()
Query the enabled status of this exception. |
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 . |
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 |
---|
public AsynchronouslyInterruptedException()
AsynchronouslyInterruptedException
.
Method Detail |
---|
public static AsynchronouslyInterruptedException getGeneric()
AsynchronouslyInterruptedException
that is generated when RealtimeThread.interrupt()
is invoked.
AsynchronouslyInterruptedException
.
java.lang.IllegalThreadStateException
- if the current thread is a Java thread.public boolean enable()
doInterruptible()
in progress. If invoked when no
call to doInterruptible()
is in progress, enable
returns false and does nothing.
this
was disabled before the method was called and
the call was invoked whilst the associated doInterruptible()
is in progress.
False: otherwise.public boolean disable()
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).
this
was enabled before the method was called and
the call was invoked with the associated doInterruptible()
in progress.
False: otherwise.public boolean isEnabled()
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.
doInterruptible()
.
False otherwise.public boolean fire()
doInterruptible()
has been invoked
and not completed.
If this
is the only outstanding AIE on the current schedulable
object, it becomes the 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.
this
is not disabled and it has an invocation
of a doInterruptible()
in progress and there is no
outstanding fire request.
False otherwise.public boolean doInterruptible(Interruptible logic)
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.
logic
- An instance of an Interruptible
whose run()
method will be called.
doInterruptible
has not completed.
java.lang.IllegalThreadStateException
- Thrown if called from a Java thread.
java.lang.IllegalArgumentException
- Thrown if a null parameter was passed.public boolean happened(boolean propagate)
happened
method can be replaced with the clear
method and application logic.
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.
propagate
- Control the behavior when this
is not the
current exception:
java.lang.IllegalThreadStateException
- Thrown if called from a Java thread.public static void propagate()
throw
of an instance of AsynchronouslyInterruptedException
.
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).
java.lang.IllegalThreadStateException
- Thrown if called from a Java thread.public boolean clear()
this
is pending on the currently
executing schedulable object, and if so, make it non-pending.
java.lang.IllegalThreadStateException
- Thrown if called from a Java thread.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |