javax.realtime

Class AsyncBaseEventHandler

java.lang.Object

javax.realtime.AsyncBaseEventHandler

All Implemented Interfaces:

Runnable, Schedulable, Subsumable<Schedulable>

Direct Known Subclasses:

AsyncEventHandler, AsyncLongEventHandler, AsyncObjectEventHandler

public abstract class AsyncBaseEventHandler
extends Object
implements Schedulable

This is the base class for all event handlers.

An instance of this class contains code that will be released for execution when an asynchronous event occurs.

If an event occurs multiple times, the releases of one event handler will be serialized, i.e., one event handler will never be released more than once simultaneously. However, one event that is attached to several handlers can cause the simultaneous release of several event handlers.

If the release parameters associated with this handler are SporadicParameters, then the minimum interarrival time specified in these parameters will be enforced. The deadline specified is always relative to the fire time, even if the actual release time may be later to enforce the minimum interarrival time.

Handlers run in the context of a RealtimeThread, they may run for short or long times and they may block. Note that a handler that is blocked may block all other handlers with the same scheduling parameters since these handlers may share one instance of RealtimeThread. A handler may not call RealtimeThread.waitForNextPeriod().

Several handlers share a common set of RealtimeThreads for their execution. This causes some additional overhead when releasing a handler and it may cause a delayed execution if a handler with equal scheduling parameters is blocked during execution. To avoid these delays, handlers of type BoundSchedulable may be used, these handlers are bound to their own RealtimeThread for execution, but they require more system resources (threads and memory).

A AsyncBaseEventHandler may make use of memory areas just as a RealtimeThread does.

Since:

RTSJ V1.1

Method Summary

Modifier and Type	Method and Description
boolean	addToFeasibility() addToFeasibility notifies the scheduler associated with this that this schedulable object's scheduling, release, memory, and processing group parameters take part in the feasibility analysis.
protected int	getAndClearPendingFireCount() Set the pending fire count to zero and returns the original value.
protected int	getAndDecrementPendingFireCount() Decrements the pending fire count and returns the original value.
ConfigurationParameters	getConfigurationParameters() Obtain the configuration parameters.
AbsoluteTime	getCurrentReleaseTime() Gets the last release time of this handler.
AbsoluteTime	getCurrentReleaseTime(AbsoluteTime dest)
MemoryArea	getMemoryArea() getMemoryArea returns the initial memory area provided to the constructor of this handler.
MemoryParameters	getMemoryParameters() getMemoryParameters returns a reference to the MemoryParameters of this AsyncBaseEventHandler.
protected int	getPendingFireCount() getPendingFireCount returns the current number of pending invocations to handleAsyncEvent().
ProcessingGroupParameters	getProcessingGroupParameters() getProcessingGroupParameters returns the current ProcessingGroupParameters of this AsyncBaseEventHandler.
int	getQueueLength() Finds the current length of the event queue.
ReleaseParameters<?>	getReleaseParameters() getReleaseParameters returns the current ReleaseParameters of this AsyncBaseEventHandler.
ReleaseRunner	getReleaseRunner() Obtain the configuration parameters.
Scheduler	getScheduler() getScheduler returns the current scheduler of this handler.
SchedulingParameters	getSchedulingParameters() getSchedulingParameters returns the SchedulingParameters of this handler.
boolean	isArmed() Determine whether or not this handler is attached to an event.
boolean	isDaemon() Check if this is a daemon handler, i.e., one that does not keep the VM from exiting.
boolean	mayUseHeap() Determines whether or not this schedulable may use the heap.
boolean	removeFromFeasibility() removeFromFeasibility informs the scheduler associated with this AsyncBaseEventHandler that this AsyncBaseEventHandler should no longer be taken into account in the feasibility analysis.
void	run() Calls handleAsyncEvent repeatedly until the fire count reaches zero.
void	setDaemon(boolean on) Mark this handler as daemon or non-daemon.
Schedulable	setMemoryParameters(MemoryParameters memory) setMemoryParameters replaces the memory parameters for this handler with the parameters provided.
void	setProcessingGroupParameters(ProcessingGroupParameters pgp) setProcessingGroupParameters sets the processing group parameters of this handler.
Schedulable	setReleaseParameters(ReleaseParameters<?> release) setReleaseParameters replaces the release parameters for this handler with the parameters provided.
Schedulable	setScheduler(Scheduler scheduler) setScheduler sets the scheduler for this handler.
Schedulable	setScheduler(Scheduler scheduler, SchedulingParameters scheduling, ReleaseParameters<?> release, MemoryParameters memory) setScheduler set the scheduler and scheduling, release, memory and processing group parameters for this Schedulable.
Schedulable	setSchedulingParameters(SchedulingParameters scheduling) setSchedulingParameters sets the scheduling parameters for this Schedulable.
boolean	setSchedulingParametersIfFeasible(SchedulingParameters scheduling) setSchedulingParametersIfFeasible performs a feasibility analysis using the provided scheduling parameters.
boolean	subsumes(Schedulable other) Determine whether or not this instance of Schedulable is more eligible than other.

Methods inherited from class java.lang.Object

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

Method Detail

getPendingFireCount

protected int getPendingFireCount()

getPendingFireCount returns the current number of pending invocations to handleAsyncEvent(). During the execution of handleAsyncEvent(), the fire count is at least 1 unless it has been reset manually (by a call to getAndClearPendingFireCount() or getAndDecrementPendingFireCount()).

Returns:

The current number of pending executions of handleAsyncEvent().

getAndClearPendingFireCount

protected int getAndClearPendingFireCount()

Set the pending fire count to zero and returns the original value. It is not thread safe and should only be used in the context of handleAsyncEvent.

Returns:

the original fire count.

getAndDecrementPendingFireCount

protected int getAndDecrementPendingFireCount()

Decrements the pending fire count and returns the original value. It is not thread safe and should only be used in the context of handleAsyncEvent.

Returns:

the original fire count.

isDaemon

public final boolean isDaemon()

Check if this is a daemon handler, i.e., one that does not keep the VM from exiting. By default, all newly created handlers are daemon handlers unless they are turned into non-daemon handlers explicitly by a call to setDaemon(false).

Specified by:

isDaemon in interface Schedulable

Returns:

true iff this is a daemon handler.

Since:

RTSJ V1.0.1

mayUseHeap

public boolean mayUseHeap()

Determines whether or not this schedulable may use the heap.

Specified by:

mayUseHeap in interface Schedulable

Returns:

true only when this Schedulable may allocate on the heap and may enter the Heap.

Since:

RTSJ 2.0

getConfigurationParameters

public ConfigurationParameters getConfigurationParameters()

Obtain the configuration parameters.

Specified by:

getConfigurationParameters in interface Schedulable

Returns:

the current configuration parameters.

Since:

RTSJ 2.0

getReleaseRunner

public ReleaseRunner getReleaseRunner()

Obtain the configuration parameters.

Returns:

the current configuration parameters.

Since:

RTSJ 2.0

setDaemon

public final void setDaemon(boolean on)

Mark this handler as daemon or non-daemon. Non-Daemon event handlers prevent the VM from exiting as long as they run. This must be called before this handler is attached to an event, the state cannot be changed later.

By default, all newly created handlers are daemon handler unless they are turned into non-daemon handlers explicitly by a call to setDaemon(false).

Specified by:

setDaemon in interface Schedulable

Throws:

IllegalTaskStateException - if this handler is attached to an async event.

SecurityException - if this change is not allowed for the current schedulable object.

Parameters:

on - true to select daemon state, false for non-daemon state.

Since:

RTSJ V1.0.1

isArmed

public boolean isArmed()

Determine whether or not this handler is attached to an event.

Returns:

true when it is attached to at least one event; false otherwise.

getMemoryArea

public MemoryArea getMemoryArea()

getMemoryArea returns the initial memory area provided to the constructor of this handler. If none was provided, the default is the current allocation context when this was constructed.

Returns:

the initial memory area of this handler.

getMemoryParameters

public MemoryParameters getMemoryParameters()

getMemoryParameters returns a reference to the MemoryParameters of this AsyncBaseEventHandler.

Specified by:

getMemoryParameters in interface Schedulable

Returns:

the MemoryParameters of this AsyncBaseEventHandler.

getReleaseParameters

public ReleaseParameters<?> getReleaseParameters()

getReleaseParameters returns the current ReleaseParameters of this AsyncBaseEventHandler.

Specified by:

getReleaseParameters in interface Schedulable

Returns:

the ReleaseParameters.

getScheduler

public Scheduler getScheduler()

getScheduler returns the current scheduler of this handler.

Specified by:

getScheduler in interface Schedulable

Returns:

the scheduler.

getSchedulingParameters

public SchedulingParameters getSchedulingParameters()

getSchedulingParameters returns the SchedulingParameters of this handler.

Specified by:

getSchedulingParameters in interface Schedulable

Returns:

the SchedulingParameters.

getProcessingGroupParameters

public ProcessingGroupParameters getProcessingGroupParameters()

getProcessingGroupParameters returns the current ProcessingGroupParameters of this AsyncBaseEventHandler.

Specified by:

getProcessingGroupParameters in interface Schedulable

Returns:

the ProcessingGroupParameters

setMemoryParameters

public Schedulable setMemoryParameters(MemoryParameters memory)
                                throws IllegalThreadStateException

setMemoryParameters replaces the memory parameters for this handler with the parameters provided.

This change may change the feasibility of the current feasible set of this handler's scheduler.

In JamaicaVM, this change becomes effective at the next release of the handler.

Specified by:

setMemoryParameters in interface Schedulable

Throws:

StaticIllegalArgumentException - if the memory parameter value is not compatible with the scheduler associated to this AsyncBaseEventHandler.

IllegalAssignmentError - if memory and this reside in memory areas whose objects cannot refer to one another (in both directions).

IllegalThreadStateException

Parameters:

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

Since:

RTSJ 2.0 returns itself

setReleaseParameters

public Schedulable setReleaseParameters(ReleaseParameters<?> release)
                                 throws IllegalThreadStateException

setReleaseParameters replaces the release parameters for this handler with the parameters provided.

This change may change the feasibility of the current feasible set of this handler's scheduler.

Specified by:

setReleaseParameters in interface Schedulable

Throws:

StaticIllegalArgumentException - if the release parameter value is not compatible with the scheduler associated to this AsyncBaseEventHandler.

IllegalAssignmentError - if release and this reside in memory areas whose objects cannot refer to one another (in both directions).

IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

Parameters:

release - the new release parameters. If null, the default value for the associated scheduler will be used.

Since:

RTSJ 2.0 returns itself

setScheduler

public Schedulable setScheduler(Scheduler scheduler,
                                SchedulingParameters scheduling,
                                ReleaseParameters<?> release,
                                MemoryParameters memory)

setScheduler set the scheduler and scheduling, release, memory and processing group parameters for this Schedulable.

The change of the scheduler and scheduling and memory parameters will be immediate for the default scheduler. release and processing group parameters will take effect on the next release.

This change may change the feasibility of the current feasible set of this Schedulable's scheduler.

Specified by:

setScheduler in interface Schedulable

Throws:

IllegalArgumentException - when scheduler is null or the scheduling, release, memory or processing group parameters are not compatible with the scheduler.

IllegalAssignmentError - if scheduler, scheduling, release, memory, or group reside in memory areas whose objects cannot be referred to by this or this object resides in a memory area that cannot be referenced by scheduling, release or memory.

IllegalThreadStateException - If the old release parameters are periodic, the new release parameters are not periodic, and the schedulable object is currently blocked in waitForNextPeriod or waitForNextPeriodInterruptible.

SecurityException - if setting of the scheduler is not allowed by the current RealtimeSystem setting.

Parameters:

scheduler - The scheduler to be used for this Schedulable. Must not be null.

scheduling - SchedulingParameters to be associated with the RealtimeThread. If null, the default value of the scheduler will be used.

release - the new release parameters. If null, the default value for the associated scheduler will be used.

memory - the new memory parameters. If null, the default value for the associated scheduler will be used.

Since:

RTSJ 2.0

setScheduler

public Schedulable setScheduler(Scheduler scheduler)
                         throws StaticIllegalArgumentException,
                                IllegalAssignmentError,
                                SecurityException

setScheduler sets the scheduler for this handler. If this has been admitted to the feasible set, it remains in the feasible set.

This change may change the feasibility of the current feasible set of this handler's scheduler.

Specified by:

setScheduler in interface Schedulable

Throws:

StaticIllegalArgumentException - iff the scheduler is null or the current parameters of this are not compatible with the new scheduler.

IllegalAssignmentError - if scheduler and this reside in memory areas whose objects cannot refer to one another (in both directions).

SecurityException - if setting of the scheduler is not allowed by the current RealtimeSystem setting.

Parameters:

scheduler - the new scheduler to be used. Must not be null.

Since:

RTSJ 2.0 returns itself

setSchedulingParameters

public Schedulable setSchedulingParameters(SchedulingParameters scheduling)
                                    throws IllegalThreadStateException

Description copied from interface: Schedulable

setSchedulingParameters sets the scheduling parameters for this Schedulable.

In JamaicaVM, this change of scheduling parameters becomes effective immediately for the default PriorityScheduler.

Specified by:

setSchedulingParameters in interface Schedulable

Throws:

IllegalThreadStateException

Parameters:

scheduling - the new scheduling parameters.

setProcessingGroupParameters

public void setProcessingGroupParameters(ProcessingGroupParameters pgp)

setProcessingGroupParameters sets the processing group parameters of this handler.

In JamaicaVM, this change becomes effective immediately.

This change may change the feasibility of the current feasible set of this AsyncBaseEventHandler's scheduler.

Specified by:

setProcessingGroupParameters in interface Schedulable

Throws:

StaticIllegalArgumentException - if the pgp argument is not compatible with the scheduler of this RealtimeThread.

Parameters:

pgp - the new processing group parameters to be applied for the next release of this. If null, use the default value for the scheduler.

getCurrentReleaseTime

public AbsoluteTime getCurrentReleaseTime()

Gets the last release time of this handler.

Throws:

StaticIllegalStateException - when this handler has not been released since it was last started.

Returns:

a reference to a newly-created AbsoluteTime object representing this handler's last release time. When the handler has not been released since it was last started, throws an exception.

Since:

RTSJ 2.0

getCurrentReleaseTime

public AbsoluteTime getCurrentReleaseTime(AbsoluteTime dest)

getQueueLength

public int getQueueLength()

Finds the current length of the event queue. The event queue holds the time and payload of all released events that are still outstanding. The queue may have a length of zero.

Returns:

the queue length.

Since:

RTSJ 2.0 Inherited by AyncEventHandler

setSchedulingParametersIfFeasible

public boolean setSchedulingParametersIfFeasible(SchedulingParameters scheduling)

setSchedulingParametersIfFeasible performs a feasibility analysis using the provided scheduling parameters. If the system remains feasible with these new parameters, the scheduling parameters are replaced.

In JamaicaVM, this change of the scheduling parameters becomes effective immediately for the default PriorityScheduler.

If this object is not a member of the feasible set of the scheduler and the resulting system is feasible, this will be added to the set.

Throws:

StaticIllegalArgumentException - if the parameter values are not compatible with the scheduler associated to this AsyncBaseEventHandler.

IllegalAssignmentError - if sched, release, memory or pgp and this reside in memory areas whose objects cannot refer to one another (in both directions).

Parameters:

scheduling - the new scheduling parameters. If null, the default value of the associated scheduler will be used. This default value may be null.

Returns:

true iff the resulting system is feasible and the new scheduling parameters have been activated. false if the resulting system is not feasible, no changes are made in this case.

subsumes

public boolean subsumes(Schedulable other)

Description copied from interface: Schedulable

Determine whether or not this instance of Schedulable is more eligible than other. On multicore systems, this only gives a partial ordering over all schedulables. Schedulables with disjoint processor affinity do not subsume one another.

Specified by:

subsumes in interface Schedulable

Specified by:

subsumes in interface Subsumable<Schedulable>

Parameters:

other - The object to be compared with.

Returns:

true when and only when this instance of Schedulable is more eligible than other.

run

public final void run()

Calls handleAsyncEvent repeatedly until the fire count reaches zero. The method is only to be used by the infrastructure, and should not be called by the application. The handleAsyncEvent method should be overridden instead.

The handleAsyncEvent() family of methods provides the equivalent functionality to Runnable.run() for asynchronous event handlers, including execution of the logic argument passed to this object's constructor. Applications should override the handleAsyncEvent() method instead of overwriting this method.

Specified by:

run in interface Runnable

See Also:

Thread.run()

addToFeasibility

public boolean addToFeasibility()

addToFeasibility notifies the scheduler associated with this that this schedulable object's scheduling, release, memory, and processing group parameters take part in the feasibility analysis.

In case this schedulable object is already part of the feasibility analysis, do nothing.

Specified by:

addToFeasibility in interface Schedulable

Returns:

true iff the resulting system is feasible.

removeFromFeasibility

public boolean removeFromFeasibility()

removeFromFeasibility informs the scheduler associated with this AsyncBaseEventHandler that this AsyncBaseEventHandler should no longer be taken into account in the feasibility analysis.

Specified by:

removeFromFeasibility in interface Schedulable

Returns:

true iff this could be removed successfully, false iff this was not part of the feasible set of the assigned scheduler.