javax.realtime
Class AsyncEventHandler

java.lang.Object
  |
  +--javax.realtime.AsyncEventHandler
All Implemented Interfaces:
java.lang.Runnable, Schedulable
Direct Known Subclasses:
BoundAsyncEventHandler

public class AsyncEventHandler
extends java.lang.Object
implements Schedulable

An asynchronous event handler encapsulates code that gets run at some time after an AsyncEvent occurs.

It is essentially a Runnable with a set of parameter objects, making it very much like a RealtimeThread. The expectation is that there may be thousands of events, with corresponding handlers, averaging about one handler per event. The number of unblocked (i.e., scheduled) handlers is expected to be relatively small.

It is guaranteed that multiple firings of an event handler will be serialized. It is also guaranteed that (unless the handler explicitly chooses otherwise) for each firing of the handler, there will be one execution of the handleAsyncEvent() method.

For instances of AsyncEventHandler with a release parameter of type SporadicParameters have a list of release times which correspond to execution times of AsyncEvent.fire(). The minimum interarrival time specified in SporadicParameters is enforced as defined there. Unless the handler explicitly chooses otherwise there will be one execution of the code in handleAsyncEvent() for each entry in the list. The ith execution of handleAsyncEvent() will be released for scheduling at the time of the ith entry in the list.

There is no restriction on what handlers may do. They may run for a long or short time, and they may block. (Note: blocked handlers may hold system resources.)

Normally, handlers are bound to an execution context dynamically, when their AsyncEvent occurs. This can introduce a (small) time penalty. For critical handlers that can not afford the expense, and where this penalty is a problem, use a BoundAsyncEventHandler.

The semantics for memory areas that were defined for realtime threads apply in the same way to instances of AsyncEventHandler They may inherit a scope stack when they are created, and the single parent rule applies to the use of memory scopes for instances of AsyncEventHandler just as it does in realtime threads.


Constructor Summary
AsyncEventHandler()
          Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.
AsyncEventHandler(boolean nonheap)
          Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.
AsyncEventHandler(boolean nonheap, java.lang.Runnable logic)
          Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.
AsyncEventHandler(java.lang.Runnable logic)
          Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.
AsyncEventHandler(SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, MemoryArea area, ProcessingGroupParameters group, boolean nonheap)
          Create a handler with the specified parameters.
AsyncEventHandler(SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, MemoryArea area, ProcessingGroupParameters group, boolean nonheap, java.lang.Runnable logic)
          Create a handler with the specified parameters.
AsyncEventHandler(SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, MemoryArea area, ProcessingGroupParameters group, java.lang.Runnable logic)
          Create a handler with the specified parameters.
 
Method Summary
 boolean addIfFeasible()
          Add to the feasibility of the associated scheduler if the resulting feasibility is schedulable.
 boolean addToFeasibility()
          Inform the scheduler and cooperating facilities that the resource demands (as expressed in the associated instances of SchedulingParameters, ReleaseParameters, MemoryParameters, and ProcessingGroupParameters) of this instance of Schedulable will be considered in the feasibility analysis of the associated Scheduler until further notice.
protected  int getAndClearPendingFireCount()
          Atomically set to zero the number of pending executions of this handler and returns the value from before it was cleared.
protected  int getAndDecrementPendingFireCount()
          Atomically decrements the number of pending executions of this handler (if it was non-zero) and returns the value from before the decrement.
protected  int getAndIncrementPendingFireCount()
          Atomically increments the number of pending executions of this handler and returns the value from before the increment.
 MemoryArea getMemoryArea()
          Get the current memory area.
 MemoryParameters getMemoryParameters()
          Get the memory parameters associated with this handler.
protected  int getPendingFireCount()
          Return the number of pending executions of this handler
 ProcessingGroupParameters getProcessingGroupParameters()
          Returns a reference to the ProcessingGroupParameters object.
 ReleaseParameters getReleaseParameters()
          Get the release parameters associated with this handler.
 Scheduler getScheduler()
          Return the Scheduler for this handler.
 SchedulingParameters getSchedulingParameters()
          Returns a reference to the scheduling parameters object.
 void handleAsyncEvent()
          If this handler was constructed using a separate Runnable logic object, then that Runnable object's run method is called; This method will be invoked repeatedly while fireCount is greater than zero.
 boolean removeFromFeasibility()
          Inform the scheduler and cooperating facilities that the resource demands, as expressed in the associated instances of SchedulingParameters, ReleaseParameters, MemoryParameters, and ProcessingGroupParameters, of this instance of Schedulable should no longer be considered in the feasibility analysis of the associated Scheduler.
 void run()
          Used by the asynchronous event mechanism, see AsyncEvent.
 boolean setIfFeasible(ReleaseParameters release, MemoryParameters memory)
          Returns true if, after considering the values of the parameters, the task set would still be feasible.
 boolean setIfFeasible(ReleaseParameters release, MemoryParameters memory, ProcessingGroupParameters group)
          Returns true if, after considering the values of the parameters, the task set would still be feasible.
 boolean setIfFeasible(ReleaseParameters release, ProcessingGroupParameters group)
          Returns true if, after considering the values of the parameters, the task set would still be feasible.
 void setMemoryParameters(MemoryParameters memory)
          Set the memory parameters associated with this handler.
 boolean setMemoryParametersIfFeasible(MemoryParameters memory)
          Set the MemoryParameters of this schedulable object.
 void setProcessingGroupParameters(ProcessingGroupParameters group)
          Sets the reference to the ProcessingGroupParameters object.
 boolean setProcessingGroupParametersIfFeasible(ProcessingGroupParameters group)
          Set the ProcessingGroupParameters of this schedulable object only if the resulting task set is feasible.
 void setReleaseParameters(ReleaseParameters release)
          Set the release parameters associated with this handler.
 boolean setReleaseParametersIfFeasible(ReleaseParameters release)
          Set the ReleaseParameters for this schedulable object only if the resulting task set is feasible.
 void setScheduler(Scheduler scheduler)
          Set the scheduler for this handler.
 void setScheduler(Scheduler scheduler, SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memoryParameters, ProcessingGroupParameters processingGroup)
          Set the scheduler for this handler.
 void setSchedulingParameters(SchedulingParameters scheduling)
          Set the scheduling parameters associated with this handler.
 boolean setSchedulingParametersIfFeasible(SchedulingParameters sched)
          Set the SchedulingParameters of this scheduable object only if the resulting task set is feasible.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AsyncEventHandler

public AsyncEventHandler()
Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.

AsyncEventHandler

public AsyncEventHandler(java.lang.Runnable logic)
Create a handler whose SchedulingParameters are inherited from the current thread and does not have either ReleaseParameters or MemoryParameters.
Parameters:
logic - The Runnable object whose run is executed by handleAsyncEvent.

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         MemoryArea area,
                         ProcessingGroupParameters group,
                         java.lang.Runnable logic)
Create a handler with the specified parameters.
Parameters:
release - A ReleaseParameters object which will be associated with the constructed instance of this. If null this will have no ReleaseParameters.
scheduling - A SchedulingParameters object which will be associated with the constructed instance of this. If null this will be assigned the reference to the SchedulingParameters of the current thread.
memory - A MemoryParameters object which will be associated with the constructed instance of this. If null this will have no MemoryParameters.
area - The MemoryArea for this. If null the memory area will be that of the current thread.
group - A ProcessingGroupParameters object to which this will be associated. If null this will not be associated with any processing group.
logic - The Runnable object whose run is executed by handleAsyncEvent.

AsyncEventHandler

public AsyncEventHandler(boolean nonheap)
Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.
Parameters:
nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread. A false value means this will have characteristics identical to a RealtimeThread. If true and the current thread is not a NoHeapRealtimeThread or a RealtimeThread executing within a ScopedMemory or ImmortalMemory scope then an IllegalArgumentException is thrown.

AsyncEventHandler

public AsyncEventHandler(boolean nonheap,
                         java.lang.Runnable logic)
Create a handler whose parameters are inherited from the current thread, if it is a RealtimeThread, or null otherwise.
Parameters:
nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread. A false value means this will have characteristics identical to a RealtimeThread. If true and the current thread is not a NoHeapRealtimeThread or a RealtimeThread executing within a ScopedMemory or ImmortalMemory scope then an IllegalArgumentException is thrown.
logic - The Runnable object whose run is executed by handleAsyncEvent.

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         MemoryArea area,
                         ProcessingGroupParameters group,
                         boolean nonheap)
Create a handler with the specified parameters.
Parameters:
scheduling - A SchedulingParameters object which will be associated with the constructed instance of this. If null this will be assigned the reference to the SchedulingParameters of the current thread.
release - A ReleaseParameters object which will be associated with the constructed instance of this. If null this will have no ReleaseParameters.
memory - A MemoryParameters object which will be associated with the constructed instance of this. If null this will have no MemoryParameters.
area - The MemoryArea for this AsyncEventHandler. If null, inherit the current memory area at the time of construction. The initial memory area must be a reference to a ScopedMemory or ImmortalMemory object if noheap is true.
group - A ProcessingGroupParameters object to which this will be associated. If null this will not be associated with any processing group.
nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread.
logic - The Runnable object whose run is executed by handleAsyncEvent.
Throws:
{@link - IllegalArgumentException} if the initial memory area is in heap memory, and the noheap parameter is true.

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         MemoryArea area,
                         ProcessingGroupParameters group,
                         boolean nonheap,
                         java.lang.Runnable logic)
Create a handler with the specified parameters.
Parameters:
scheduling - A SchedulingParameters object which will be associated with the constructed instance of this. If null this will be assigned the reference to the SchedulingParameters of the current thread.
release - A ReleaseParameters object which will be associated with the constructed instance of this. If null this will have no ReleaseParameters.
memory - A MemoryParameters object which will be associated with the constructed instance of this. If null this will have no MemoryParameters.
area - The MemoryArea for this AsyncEventHandler. If null, inherit the current memory area at the time of construction. The initial memory area must be a reference to a ScopedMemory or ImmortalMemory object if noheap is true.
group - A ProcessingGroupParameters object to which this will be associated. If null this will not be associated with any processing group.
nonheap - A flag meaning, when true, that this will have characteristics identical to a NoHeapRealtimeThread.
Throws:
{@link - IllegalArgumentException} if the initial memory area is in heap memory, and the noheap parameter is true.
Method Detail

handleAsyncEvent

public void handleAsyncEvent()
If this handler was constructed using a separate Runnable logic object, then that Runnable object's run method is called; This method will be invoked repeatedly while fireCount is greater than zero.

getPendingFireCount

protected final int getPendingFireCount()
Return the number of pending executions of this handler
Returns:
The pending fire count.

getAndClearPendingFireCount

protected final int getAndClearPendingFireCount()
Atomically set to zero the number of pending executions of this handler and returns the value from before it was cleared. This is used in handlers that can handle multiple firings and that want to collapse them together. The general form for using this is:
public void handleAsyncEvent() {
int fireCount = getAndClearPendingFireCount();
<handle the events>
}
Returns:
The pending fire count.

getAndDecrementPendingFireCount

protected int getAndDecrementPendingFireCount()
Atomically decrements the number of pending executions of this handler (if it was non-zero) and returns the value from before the decrement. This can be used in the handleAsyncEvent() method in this form to handle multiple firings:
public void handleAsyncEvent() {
<setup>
do {
<handle the event>
} while(getAndDecrementPendingFireCount()>0);
}
This construction is necessary only in the case where one wishes to avoid the setup costs since the framework guarantees that handleAsyncEvent() will be invoked the appropriate number of times.
Returns:
The pending fire count.

getAndIncrementPendingFireCount

protected int getAndIncrementPendingFireCount()
Atomically increments the number of pending executions of this handler and returns the value from before the increment. The handleAsyncEvent() method does not need to do this, since the surrounding framework guarantees that the handler will be re-executed the appropriate number of times. It is only of value when there is common setup code that is expensive.
Returns:
The pending fire count.

run

public final void run()
Used by the asynchronous event mechanism, see AsyncEvent. This method invokes handleAsyncEvent() repeatedly while the fire count is greater than zero. Applications cannot override this method and should thus override handleAsyncEvent() in subclasses with the logic of the handler.
Specified by:
run in interface java.lang.Runnable

getMemoryArea

public MemoryArea getMemoryArea()
Get the current memory area.
Returns:
The current memory area in which allocations occur.

addToFeasibility

public boolean addToFeasibility()
Inform the scheduler and cooperating facilities that the resource demands (as expressed in the associated instances of SchedulingParameters, ReleaseParameters, MemoryParameters, and ProcessingGroupParameters) of this instance of Schedulable will be considered in the feasibility analysis of the associated Scheduler until further notice. Whether the resulting system is feasible or not, the addition is completed.
Specified by:
addToFeasibility in interface Schedulable
Returns:
true If the resulting system is feasible.

addIfFeasible

public boolean addIfFeasible()
Add to the feasibility of the associated scheduler if the resulting feasibility is schedulable. If successful return true, if not return false. If there is not assigned scheduler false is returned.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memory)
Returns true if, after considering the values of the parameters, the task set would still be feasible. In this case the values of the parameters are changed. Returns false if, after considering the values of the parameters, the task set would not be feasible. In this case the values of the parameters are not changed.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)
Returns true if, after considering the values of the parameters, the task set would still be feasible. In this case the values of the parameters are changed. Returns false if, after considering the values of the parameters, the task set would not be feasible. In this case the values of the parameters are not changed.

setReleaseParametersIfFeasible

public boolean setReleaseParametersIfFeasible(ReleaseParameters release)
Description copied from interface: Schedulable
Set the ReleaseParameters for this schedulable object only if the resulting task set is feasible.
Specified by:
setReleaseParametersIfFeasible in interface Schedulable
Following copied from interface: javax.realtime.Schedulable
Parameters:
release - The ReleaseParameters object. If null nothing happens.

setProcessingGroupParametersIfFeasible

public boolean setProcessingGroupParametersIfFeasible(ProcessingGroupParameters group)
Description copied from interface: Schedulable
Set the ProcessingGroupParameters of this schedulable object only if the resulting task set is feasible.
Specified by:
setProcessingGroupParametersIfFeasible in interface Schedulable
Following copied from interface: javax.realtime.Schedulable
Parameters:
groupParameters - The ProcessingGroupParameters object.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             ProcessingGroupParameters group)
Returns true if, after considering the values of the parameters, the task set would still be feasible. In this case the values of the parameters are changed. Returns false if, after considering the values of the parameters, the task set would not be feasible. In this case the values of the parameters are not changed.

setMemoryParametersIfFeasible

public boolean setMemoryParametersIfFeasible(MemoryParameters memory)
Description copied from interface: Schedulable
Set the MemoryParameters of this schedulable object.
Specified by:
setMemoryParametersIfFeasible in interface Schedulable
Following copied from interface: javax.realtime.Schedulable
Parameters:
memory - The MemoryParameters object. If null nothing happens.

getMemoryParameters

public MemoryParameters getMemoryParameters()
Get the memory parameters associated with this handler.
Specified by:
getMemoryParameters in interface Schedulable
Returns:
The MemoryParameters object associated with this.

getReleaseParameters

public ReleaseParameters getReleaseParameters()
Get the release parameters associated with this handler.
Specified by:
getReleaseParameters in interface Schedulable
Returns:
The ReleaseParameters object associated with this.

getScheduler

public Scheduler getScheduler()
Return the Scheduler for this handler.
Specified by:
getScheduler in interface Schedulable
Returns:
The instance of the scheduler managing this.

getSchedulingParameters

public SchedulingParameters getSchedulingParameters()
Returns a reference to the scheduling parameters object.
Specified by:
getSchedulingParameters in interface Schedulable
Returns:
The SchedulingParameters object associated with this.

getProcessingGroupParameters

public ProcessingGroupParameters getProcessingGroupParameters()
Returns a reference to the ProcessingGroupParameters object.
Specified by:
getProcessingGroupParameters in interface Schedulable

removeFromFeasibility

public boolean removeFromFeasibility()
Inform the scheduler and cooperating facilities that the resource demands, as expressed in the associated instances of SchedulingParameters, ReleaseParameters, MemoryParameters, and ProcessingGroupParameters, of this instance of Schedulable should no longer be considered in the feasibility analysis of the associated Scheduler. Whether the resulting system is feasible or not, the subtraction is completed.
Specified by:
removeFromFeasibility in interface Schedulable
Returns:
true If the resulting system is feasible.

setMemoryParameters

public void setMemoryParameters(MemoryParameters memory)
Set the memory parameters associated with this handler. When it is next fired, the executing thread will use these parameters to control memory allocation. Does not affect the current invocation of the run() of this handler.
Specified by:
setMemoryParameters in interface Schedulable
Parameters:
memory - A MemoryParameters object which will become the MemoryParameters associated with this after the method call.

setReleaseParameters

public void setReleaseParameters(ReleaseParameters release)
Set the release parameters associated with this handler. When it is next fired, the executing thread will use these parameters to control scheduling. If the scheduling parameters of a handler is set to null, the handler will be executed immediately when it is fired, in the thread of the firer. Does not affect the current invocation of the run() of this handler.

Since this affects the constraints expressed in the release parameters of the existing schedulable objects, this may change the feasibility of the current schedule.

Specified by:
setReleaseParameters in interface Schedulable
Parameters:
parameters - A ReleaseParameters object which will become the ReleaseParameters associated with this after the method call.

setScheduler

public void setScheduler(Scheduler scheduler)
                  throws java.lang.IllegalThreadStateException
Set the scheduler for this handler. A reference to the scheduler which will manage the execution of this thread.
Specified by:
setScheduler in interface Schedulable
Parameters:
scheduler - An instance of Scheduler (or subclasses) which will manage the execution of this thread. If scheduler is null nothing happens.

setScheduler

public void setScheduler(Scheduler scheduler,
                         SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memoryParameters,
                         ProcessingGroupParameters processingGroup)
                  throws java.lang.IllegalThreadStateException
Set the scheduler for this handler. A reference to the scheduler which will manage the execution of this thread.
Specified by:
setScheduler in interface Schedulable
Parameters:
scheduler - An instance of Scheduler (or subclasses) which will manage the execution of this thread. If scheduler is null nothing happens.
scheduling - A SchedulingParameters object which will be associated with the constructed instance of this. If null this will be assigned the reference to the SchedulingParameters of the current thread.
release - A ReleaseParameters object which will be associated with the constructed instance of this. If null this will have no ReleaseParameters.
memory - A MemoryParameters object which will be associated with the constructed instance of this. If null this will have no MemoryParameters.
group - A ProcessingGroupParameters object to which this will be associated. If null this will not be associated with any processing group.

setSchedulingParameters

public void setSchedulingParameters(SchedulingParameters scheduling)
Set the scheduling parameters associated with this handler. When it is next fired, the executing thread will use these parameters to control scheduling. Does not affect the current invocation of the run() of this handler.
Specified by:
setSchedulingParameters in interface Schedulable
Parameters:
parameters - A SchedulingParameters object which will become the SchedulingParameters object associated with this after the method call.

setProcessingGroupParameters

public void setProcessingGroupParameters(ProcessingGroupParameters group)
Sets the reference to the ProcessingGroupParameters object.
Specified by:
setProcessingGroupParameters in interface Schedulable
Following copied from interface: javax.realtime.Schedulable
Parameters:
groupParameters - The ProcessingGroupParameters object.

setSchedulingParametersIfFeasible

public boolean setSchedulingParametersIfFeasible(SchedulingParameters sched)
Set the SchedulingParameters of this scheduable object only if the resulting task set is feasible.
Specified by:
setSchedulingParametersIfFeasible in interface Schedulable
Parameters:
scheduling - The SchedulingParameters object. If null nothing happens.