AsyncBaseEventHandler

java.lang.Object
- javax.realtime.AsyncBaseEventHandler

All Implemented Interfaces:

java.lang.Runnable, Schedulable, Subsumable<Schedulable>

Direct Known Subclasses:

AsyncEventHandler, AsyncLongEventHandler, AsyncObjectEventHandler
```
public abstract class AsyncBaseEventHandler
extends java.lang.Object
implements Schedulable
```
This is the base class for all asynchronous event handlers, where asynchronous is in regards to running code, not external time. This class unifies the original AsyncEventHandler with AsyncLongEventHandler and AsyncObjectEventHandler. Each of these subclasses has its own handleAsyncEvent method, whose only difference is whether and what argument it has.

Since:

RTSJ 2.0

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`addToFeasibility()` Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
`protected int`	`getAndClearPendingFireCount()` This is an accessor method for `fireCount`.
`protected int`	`getAndDecrementPendingFireCount()` This is an accessor method for `fireCount`.
`ConfigurationParameters`	`getConfigurationParameters()` Gets a reference to the `ConfigurationParameters` object for this schedulable.
`AbsoluteTime`	`getCurrentReleaseTime()` Gets the last release time of this handler.
`AbsoluteTime`	`getCurrentReleaseTime(AbsoluteTime dest)`
`MemoryArea`	`getMemoryArea()` This is an accessor method for the initial instance of `MemoryArea` associated with `this`.
`MemoryParameters`	`getMemoryParameters()` Gets a reference to the `MemoryParameters` object for this schedulable.
`protected int`	`getPendingFireCount()` This is an accessor method for `fireCount`.
`ProcessingGroupParameters`	`getProcessingGroupParameters()` Deprecated. since RTSJ 2.0
`int`	`getQueueLength()` Finds the current length of the event queue.
`ReleaseParameters<?>`	`getReleaseParameters()` Gets a reference to the `ReleaseParameters` object for this schedulable.
`ReleaseRunner`	`getReleaseRunner()` Obtain the configuration parameters.
`Scheduler`	`getScheduler()` Gets a reference to the `Scheduler` object for this schedulable.
`SchedulingParameters`	`getSchedulingParameters()` Gets a reference to the `SchedulingParameters` object for this schedulable.
`boolean`	`isArmed()` Determine whether or not this handler is attached to an event.
`boolean`	`isDaemon()` Tests if this event handler is a daemon handler.
`boolean`	`mayUseHeap()` Determines whether or not this `schedulable` may use the heap.
`boolean`	`removeFromFeasibility()` Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
`void`	`run()` Calls `handleAsyncEvent` repeatedly until the fire count reaches zero.
`void`	`setDaemon(boolean on)` Marks this schedulable as either a daemon or a user task.
`Schedulable`	`setMemoryParameters(MemoryParameters memory)` Sets the memory parameters associated with this instance of `Schedulable`.
`void`	`setProcessingGroupParameters(ProcessingGroupParameters pgp)` Deprecated. since RTSJ 2.0
`Schedulable`	`setReleaseParameters(ReleaseParameters<?> release)` Sets the release parameters associated with this instance of `Schedulable`.
`Schedulable`	`setScheduler(Scheduler scheduler)` Sets the reference to the Scheduler object.
`Schedulable`	`setScheduler(Scheduler scheduler, SchedulingParameters scheduling, ReleaseParameters<?> release, MemoryParameters memoryParameters)` Sets the scheduler and associated parameter objects.
`Schedulable`	`setSchedulingParameters(SchedulingParameters scheduling)` Sets the scheduling parameters associated with this instance of `Schedulable`.
`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
  - getCurrentReleaseTime
```
public AbsoluteTime getCurrentReleaseTime()
```
    Gets the last release time of this handler.
    
    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.
    
    Throws:
    
    StaticIllegalStateException - when this handler has not been released since it was last started.
    
    Since:
    
    RTSJ 2.1
  - getCurrentReleaseTime
```
public AbsoluteTime getCurrentReleaseTime(AbsoluteTime dest)
```
  - getPendingFireCount
```
protected int getPendingFireCount()
```
    This is an accessor method for fireCount. The fireCount field nominally holds the number of times associated instances of AsyncEvent have occurred that have not had the method handleAsyncEvent() invoked. It is incremented and decremented by the implementation of the RTSJ. The application logic may manipulate the value in this field for application-specific reasons.
    
    Returns:
    
    the value held by fireCount.
  - getAndClearPendingFireCount
```
protected int getAndClearPendingFireCount()
```
    This is an accessor method for fireCount. This method atomically sets the value of fireCount to zero and returns the value from before it was set to zero. This may be used by handlers for which the logic can accommodate multiple releases in a single execution.
    The general form for using this is
```
 public void handleAsyncEvent()
 {
   int numberOfReleases = getAndClearPendingFireCount();
   <handle the events>
 }
 
```
    The effect of a call to getAndClearPendingFireCount on the scheduling of this AEH depends on the semantics of the scheduler controlling this AEH.
    Returns:
    
    the value held by fireCount prior to setting the value to zero.
  - getAndDecrementPendingFireCount
```
protected int getAndDecrementPendingFireCount()
```
    This is an accessor method for fireCount. This method atomically decrements, by one, the value of fireCount (when it is greater than zero) and returns the value from before the decrement. This method can be used in the handleAsyncEvent() method to handle multiple releases:
```
 public void handleAsyncEvent()
 {
   <setup>
   do
     {
       <handle the event>
     }
   while(getAndDecrementPendingFireCount() > 0);
 }
 
```
    This construction is necessary only in cases where a handler wishes to avoid the setup costs, since the framework guarantees that handleAsyncEvent() will be invoked whenever the fireCount is greater than zero. The effect of a call to getAndDecrementPendingFireCount on the scheduling of this AEH depends on the semantics of the scheduler controlling this AEH.
    Returns:
    
    the value held by fireCount prior to decrementing it by one.
  - getMemoryArea
```
public MemoryArea getMemoryArea()
```
    This is an accessor method for the initial instance of MemoryArea associated with this.
    
    Returns:
    
    the instance of MemoryArea which was passed as the area parameter when this was created (or the default value when area was allowed to default.
  - getMemoryParameters
```
public MemoryParameters getMemoryParameters()
```
    Description copied from interface: Schedulable
    
    Gets a reference to the MemoryParameters object for this schedulable.
    
    Specified by:
    
    getMemoryParameters in interface Schedulable
    
    Returns:
    
    a reference to the current MemoryParameters object.
  - getReleaseParameters
```
public ReleaseParameters<?> getReleaseParameters()
```
    Description copied from interface: Schedulable
    
    Gets a reference to the ReleaseParameters object for this schedulable.
    
    Specified by:
    
    getReleaseParameters in interface Schedulable
    
    Returns:
    
    a reference to the current ReleaseParameters object.
  - getScheduler
```
public Scheduler getScheduler()
```
    Description copied from interface: Schedulable
    
    Gets a reference to the Scheduler object for this schedulable.
    
    Specified by:
    
    getScheduler in interface Schedulable
    
    Returns:
    
    a reference to the associated Scheduler object.
  - getSchedulingParameters
```
public SchedulingParameters getSchedulingParameters()
```
    Description copied from interface: Schedulable
    
    Gets a reference to the SchedulingParameters object for this schedulable.
    
    Specified by:
    
    getSchedulingParameters in interface Schedulable
    
    Returns:
    
    A reference to the current SchedulingParameters object.
  - getReleaseRunner
```
public ReleaseRunner getReleaseRunner()
```
    Obtain the configuration parameters.
    
    Returns:
    
    the current configuration parameters.
    
    Since:
    
    RTSJ 2.0
  - getConfigurationParameters
```
public ConfigurationParameters getConfigurationParameters()
```
    Gets a reference to the ConfigurationParameters object for this schedulable.
    
    Specified by:
    
    getConfigurationParameters in interface Schedulable
    
    Returns:
    
    the ConfigurationParameters instance of its ReleaseRunner instance, i.e., getReleaseRunner().getConfigurationParameters()
  - setMemoryParameters
```
public Schedulable setMemoryParameters(MemoryParameters memory)
```
    Description copied from interface: Schedulable
    
    Sets the memory parameters associated with this instance of Schedulable.
    This change becomes effective at the next allocation; on multiprocessor systems, there may be some delay due to synchronization between processors.
    
    Specified by:
    
    setMemoryParameters in interface Schedulable
    
    Parameters:
    
    memory - A MemoryParameters object which will become the memory parameters associated with this after the method call. When null, the default value is governed by the associated scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)
    
    Returns:
    
    this
  - setReleaseParameters
```
public Schedulable setReleaseParameters(ReleaseParameters<?> release)
```
    Description copied from interface: Schedulable
    
    Sets the release parameters associated with this instance of Schedulable.
    This change becomes effective under conditions determined by the scheduler controlling the schedulable. For instance, the change may be immediate or it may be delayed until the next release of the schedulable. The different properties of the release parameters may take effect at different times. See the documentation for the scheduler for details.
    
    Specified by:
    
    setReleaseParameters in interface Schedulable
    
    Parameters:
    
    release - A ReleaseParameters object which will become the release parameters associated with this after the method call, and take effect as determined by the associated scheduler. When null, the default value is governed by the associated scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)
    
    Returns:
    
    this
  - setScheduler
```
public Schedulable setScheduler(Scheduler scheduler)
```
    Sets the reference to the Scheduler object. The timing of the change must be agreed between the scheduler currently associated with this schedulable, and scheduler. If the Schedulable is running, its associated SchedulingParameters (if any) must be compatible with scheduler.
    For an instance of AsyncBaseEventHandler, the Schedulable is running for the purpose of setting the scheduler when it is attached to an AsyncEvent, even when AsyncBaseEvent.isRunning() would return false for that event.
    
    Specified by:
    
    setScheduler in interface Schedulable
    
    Parameters:
    
    scheduler - A reference to the scheduler that will manage execution of this schedulable. Null is not a permissible value.
    
    Returns:
    
    this
    
    Throws:
    
    StaticIllegalArgumentException - when scheduler is null, or the schedulable's existing parameter values are not compatible with scheduler. Also when this schedulable may not use the heap and scheduler is located in heap memory.
    
    IllegalAssignmentError - when the schedulable cannot hold a reference to scheduler or the current Schedulable is running and its associated SchedulingParameters are incompatible with scheduler.
    
    StaticSecurityException - when the caller is not permitted to set the scheduler for this schedulable.
    
    IllegalTaskStateException - when scheduler has scheduling or release parameters that are not compatible with the new scheduler and this schedulable is running.
    
    Since:
    
    RTSJ 2.0 returns itself
  - setScheduler
```
public Schedulable setScheduler(Scheduler scheduler,
                                SchedulingParameters scheduling,
                                ReleaseParameters<?> release,
                                MemoryParameters memoryParameters)
```
    Sets the scheduler and associated parameter objects. The timing of the change must be agreed between the scheduler currently associated with this schedulable, and scheduler.
    
    Specified by:
    
    setScheduler in interface Schedulable
    
    Parameters:
    
    scheduler - A reference to the scheduler that will manage the execution of this schedulable. Null is not a permissible value.
    
    scheduling - A reference to the SchedulingParameters which will be associated with this. When null, the default value is governed by scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)
    
    release - A reference to the ReleaseParameters which will be associated with this. When null, the default value is governed by scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)
    
    memoryParameters - A reference to the MemoryParameters which will be associated with this. When null, the default value is governed by scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)
    
    Returns:
    
    this
    
    Throws:
    
    StaticIllegalArgumentException - when scheduler is null or the parameter values are not compatible with scheduler. Also thrown when this schedulable may not use the heap and scheduler, scheduling release, memoryParameters, or group is located in heap memory.
    
    IllegalAssignmentError - when this object cannot hold references to all the parameter objects or the parameters cannot hold references to this.
    
    StaticSecurityException - when the caller is not permitted to set the scheduler for this schedulable.
    
    Since:
    
    RTSJ 2.0
  - setSchedulingParameters
```
public Schedulable setSchedulingParameters(SchedulingParameters scheduling)
```
    Description copied from interface: Schedulable
    
    Sets the scheduling parameters associated with this instance of Schedulable.
    This change becomes effective under conditions determined by the scheduler controlling the schedulable. For instance, the change may be immediate or it may be delayed until the next release of the schedulable. See the documentation of the scheduler for details.
    
    Specified by:
    
    setSchedulingParameters in interface Schedulable
    
    Parameters:
    
    scheduling - A reference to the SchedulingParameters object. When null, the default value is governed by the associated scheduler; a new object is created when the default value is not null. (See PriorityScheduler.). When the Affinity is not defined in scheduling, then the affinity that will be used is the one of the creating Thread. However, this default affinity will not appear when calling Schedulable.getSchedulingParameters(), unless explicitly set using this method.
    
    Returns:
    
    this
  - setDaemon
```
public final void setDaemon(boolean on)
```
    Description copied from interface: Schedulable
    
    Marks this schedulable as either a daemon or a user task. A realtime virtual machine exits when the only tasks running are all daemons. This method must be called before the task is attached to any event or started. Once attached or started, it cannot be changed.
    
    Specified by:
    
    setDaemon in interface Schedulable
    
    Parameters:
    
    on - When true, marks this event handler as a daemon handler.
  - isDaemon
```
public final boolean isDaemon()
```
    Description copied from interface: Schedulable
    
    Tests if this event handler is a daemon handler.
    
    Specified by:
    
    isDaemon in interface Schedulable
    
    Returns:
    
    true when this event handler is a daemon handler; false otherwise.
  - 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.
  - 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
  - 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.
  - 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 java.lang.Runnable
  - getProcessingGroupParameters
```
@Deprecated
public ProcessingGroupParameters getProcessingGroupParameters()
```
    Deprecated. since RTSJ 2.0
    
    Gets a reference to the ProcessingGroupParameters object for this schedulable.
    
    Specified by:
    
    getProcessingGroupParameters in interface Schedulable
    
    Returns:
    
    A reference to the current ProcessingGroupParameters object.
  - setProcessingGroupParameters
```
@Deprecated
public void setProcessingGroupParameters(ProcessingGroupParameters pgp)
```
    Deprecated. since RTSJ 2.0
    
    Sets the ProcessingGroupParameters of this.
    This change becomes effective under conditions determined by the scheduler controlling the schedulable. For instance, the change may be immediate or it may be delayed until the next release of the schedulable. See the documentation for the scheduler for details.
    
    Specified by:
    
    setProcessingGroupParameters in interface Schedulable
    
    Parameters:
    
    pgp - A ProcessingGroupParameters object which will take effect as determined by the associated scheduler. When null, the default value is governed by the associated scheduler (a new object is created when the default value is not null). (See PriorityScheduler.)
    
    Throws:
    
    StaticIllegalArgumentException - when group is not compatible with the scheduler for this schedulable object. Also when this schedulable may not use the heap and group is located in heap memory.
    
    IllegalAssignmentError - when this object cannot hold a reference to group or group cannot hold a reference to this.
    
    java.lang.IllegalThreadStateException - when the schedulable's scheduler prohibits the changing of the processing group parameter at this time due to the state of the schedulable object.
  - addToFeasibility
```
@Deprecated
public boolean addToFeasibility()
```
    Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
    
    Informs the scheduler and cooperating facilities that this instance of Schedulable should be considered in feasibility analysis until further notified.
    When the object is already included in the feasibility set, does nothing.
    
    Specified by:
    
    addToFeasibility in interface Schedulable
    
    Returns:
    
    true, when the resulting system is feasible. False, when not.
  - removeFromFeasibility
```
@Deprecated
public boolean removeFromFeasibility()
```
    Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
    
    Informs the scheduler and cooperating facilities that this instance of Schedulable should not be considered in feasibility analysis until it is further notified.
    
    Specified by:
    
    removeFromFeasibility in interface Schedulable
    
    Returns:
    
    true when the removal was successful. false when the schedulable cannot be removed from the scheduler's feasibility set; e.g., the schedulable is not part of the scheduler's feasibility set.

Class AsyncBaseEventHandler

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getCurrentReleaseTime

getCurrentReleaseTime

getPendingFireCount

getAndClearPendingFireCount

getAndDecrementPendingFireCount

getMemoryArea

getMemoryParameters

getReleaseParameters

getScheduler

getSchedulingParameters

getReleaseRunner

getConfigurationParameters

setMemoryParameters

setReleaseParameters

setScheduler

setScheduler

setSchedulingParameters

setDaemon

isDaemon

isArmed

getQueueLength

mayUseHeap

subsumes

run

getProcessingGroupParameters

setProcessingGroupParameters

addToFeasibility

removeFromFeasibility