javax.realtime
Class AsyncEventHandler

java.lang.Object
  javax.realtime.AsyncEventHandler

All Implemented Interfaces:

Runnable, Schedulable

Direct Known Subclasses:

BoundAsyncEventHandler, PooledAsyncEventHandler, ThreadedAsyncEventHandler

public abstract class AsyncEventHandler

extends Object

implements Schedulable

An asynchronous event handler encapsulates code that gets run at some time after an AsyncEvent occurs. It is essentially a java.lang.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 SporadicParameters61 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 i th execution of handleAsyncEvent() will be released for scheduling at the time of the i th entry in thelist. 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 AsyncEvent181 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.

Author:

Angelo Corsaro

Field Summary

protected int	executionEligibility
protected gnu.gcj.RawData	natFireCount_

Constructor Summary

protected

AsyncEventHandler()

Method Summary

protected void	finalize()
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.
protected int	getPendingFireCount() Return the number of pending executions of this handler.
abstract void	handleAsyncEvent() If this handler was constructed using a separate Runnable logic object, then that Runnable objects run method is called; This method will be invoked repeatedly while fireCount is greater than zero.
void	run() Used by the asynchronous event mechanism, see AsyncEvent.

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.Schedulable

addIfFeasible, addToFeasibility, executionEligibility, getMemoryParameters, getProcessingGroupParameters, getReleaseParameters, getScheduler, getSchedulingParameters, removeFromFeasibility, setMemoryParameters, setMemoryParametersIfFeasible, setProcessingGroupParameters, setProcessingGroupParametersIfFeasible, setReleaseParameters, setReleaseParametersIfFeasible, setScheduler, setScheduler, setSchedulingParameters, setSchedulingParametersIfFeasible

Field Detail

natFireCount_

protected gnu.gcj.RawData natFireCount_

executionEligibility

protected int executionEligibility

Constructor Detail

AsyncEventHandler

protected AsyncEventHandler()

Method Detail

getAndClearPendingFireCount

protected 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(); }

Returns:

an int value representing 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() { do { } 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:

an int value representing 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:

an int value representing the pending fire count.

getPendingFireCount

protected int getPendingFireCount()

Return the number of pending executions of this handler.

Returns:

an int value representing the pending fire count.

handleAsyncEvent

public abstract void handleAsyncEvent()

If this handler was constructed using a separate Runnable logic object, then that Runnable objects run method is called; This method will be invoked repeatedly while fireCount is greater than zero.

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 Runnable

finalize

protected void finalize()