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 is released after an instance of AsyncEvent to which it is attached occurs.

It is guaranteed that multiple releases of an event handler will be serialized. It is also guaranteed that (unless the handler explicitly chooses otherwise) for each release of the handler, there will be one execution of the handleAsyncEvent() method. Control over the number of calls to handleAsyncEvent() is given by methods which manipulate a fireCount. These may be called by the application via sub-classing and overriding handleAsyncEvent().

Instances of AsyncEventHandler with a release parameter of type SporadicParameters or AperiodicParameters have a list of release times which correspond to the occurrence times of instances of AsyncEvent to which they are attached. The minimum interarrival time specified in SporadicParameters is enforced when a release time is added to the list. Unless the handler explicitly chooses otherwise, there will be one execution of the code in handleAsyncEvent() for each entry in the list.

The deadline and the time each release event causes the AEH to become eligible for execution are properties of the scheduler that controls the AEH. For the base scheduler, the deadline for each release event is relative to its fire time, and the release takes place at fire time but execution eligibility may be deferred if the queue's MIT violation policy is SAVE.

Handlers may do almost anything a real-time thread can do. They may run for a long or short time, and they may block. (Note: blocked handlers may hold system resources.) A handler may not use the RealtimeThread.waitForNextPeriod() method.

Normally, handlers are bound to an execution context dynamically when the instances of AsyncEvents to which they are bound occur. This can introduce a (small) time penalty. For critical handlers that can not afford the expense, and where this penalty is a problem, BoundAsyncEventHandlers can be used.

The scheduler for an asynchronous event handler is inherited from the thread/schedulable object that created it. If it was created from a Java thread, the scheduler is the current default scheduler.

The semantics for memory areas that were defined for real-time 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 real-time threads.

AsyncEventHandler

public AsyncEventHandler()

Create an instance of AsyncEventHandler with default values for all parameters. This constructor is equivalent to AsyncEventHandler(null, null, null, null, null, false, null).

AsyncEventHandler

public AsyncEventHandler(boolean nonheap)

Create an instance of AsyncEventHandler with the specified nonheap flag and default values for all other parameters. This constructor is equivalent to AsyncEventHandler(null, null, null, null, null, nonheap, null).

Throws:

java.lang.IllegalArgumentException - Thrown if this is in heap memory, and nonheap is true.

AsyncEventHandler

public AsyncEventHandler(boolean nonheap,
                         java.lang.Runnable logic)

Create an instance of AsyncEventHandler with the specified nonheap flag and logic value, and default values for all other parameters. This constructor is equivalent to AsyncEventHandler(null, null, null, null, null, nonheap, logic).

Throws:

java.lang.IllegalArgumentException - Thrown if logic or this is in heap memory, and nonheap is true.

IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to logic.

AsyncEventHandler

public AsyncEventHandler(java.lang.Runnable logic)

Create an instance of AsyncEventHandler with the given logic parameter and default values for all other parameters. This constructor is equivalent to AsyncEventHandler(null, null, null, null, null, false, logic).

Throws:

IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to logic.

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         MemoryArea area,
                         ProcessingGroupParameters group,
                         boolean nonheap)

Create an instance of AsyncEventHandler with the specified values for scheduling parameters, release parameters, memory parameters, initial memory area, processing group parameters and non-heap flag. This constructor is equivalent to: AsyncEventHandler (scheduling, release, memory, area, group, nonheap, null)

Throws:

java.lang.IllegalArgumentException - Thrown if nonheap is true and this or any object passed as a parameter is in heap memory. Also thrown if noheap is true and area is heap memory.

IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to non-null values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to area.

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         MemoryArea area,
                         ProcessingGroupParameters group,
                         boolean nonheap,
                         java.lang.Runnable logic)

Create an instance of AsyncEventHandler with the specified parameters.

Parameters:

scheduling - A SchedulingParameters object which will be associated with the constructed instance. If null, and the creator is a Java thread, a SchedulingParameters object is created which has the default scheduling parameters value for the scheduler associated with the current thread. If null, and the creator is a schedulable object, the scheduling parameters are inherited from the current schedulable object (a new SchedulingParameters object is cloned).

release - A ReleaseParameters object which will be associated with the constructed instance. If null, this will have default ReleaseParameters for this AEH's scheduler.

memory - A MemoryParameters object which will be associated with the constructed instance. If null, this will have no MemoryParameters.

area - The MemoryArea for this. If null, the memory area will be that of the current thread/schedulable object.

group - A ProcessingGroupParameters object which will be associated with the constructed instance. 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. A false value means this will have characteristics identical to a RealtimeThread. If true and the current thread/schedulable object is not executing within a ScopedMemory or ImmortalMemory scope then an IllegalArgumentException is thrown.

logic - The Runnable object whose run() method is executed by handleAsyncEvent(). If null, the default handleAsyncEvent() method invokes nothing.

Throws:

java.lang.IllegalArgumentException - Thrown if nonheap is true and any parameter, or this is in heap memory or area is heap memory.

IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to non-null values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to non-null values of area and logic.

AsyncEventHandler

public AsyncEventHandler(SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memory,
                         MemoryArea area,
                         ProcessingGroupParameters group,
                         java.lang.Runnable logic)

Create an instance of AsyncEventHandler with the specified values for scheduling parameters, release parameters, memory parameters, initial memory area, processing group parameters and runnable logic. This constructor is equivalent to: AsyncEventHandler (scheduling, release, memory, area, group, false, logic)

Throws:

java.lang.IllegalArgumentException - Thrown if nonheap is true and logic, any parameter object, or this is in heap memory. Also thrown if noheap is true and area is heap memory.

IllegalAssignmentError - Thrown if the new AsyncEventHandler instance cannot hold a reference to non-null values of scheduling release memory and group, or if those parameters cannot hold a reference to the new AsyncEventHandler. Also thrown if the new AsyncEventHandler instance cannot hold a reference to non-null values of area and logic.

handleAsyncEvent

public void handleAsyncEvent()

This method holds the logic which is to be executed when any AsyncEvent with which this handler is associated is fired. This method will be invoked repeatedly while fireCount is greater than zero.

The default implementation of this method invokes the run method of any non-null logic instance passed to the constructor of this handler.

If the initial memory area of this AsyncEventHandler is a ScopedMemory, the initial memory area's reference count does not drop below one between invocations of handleAsyncEvent() unless this AsyncEventHandler becomes unfireable.

All throwables from (or propagated through) handleAsyncEvent are caught, a stack trace is printed and execution continues as if handleAsyncEvent had returned normally.

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 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 (if it was 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 the case 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.

getAndIncrementPendingFireCount

protected int getAndIncrementPendingFireCount()

This is an accessor method for fireCount. This method atomically increments, by one, the value of fireCount and returns the value from before the increment.

The effect of a call to getAndIncrementPendingFireCount on the arrival-time queue and the scheduling of this AEH depends on the semantics of the scheduler controlling this AEH.

Returns:

The value held by fireCount prior to incrementing it by one.

Throws:

MITViolationException - Thrown when this AEH is controlled by sporadic scheduling parameters under the base scheduler, the parameters specify the mitViolationExcept policy, and this method would introduce a release that would violate the specified minimum interarrival time.

ArrivalTimeQueueOverflowException - Thrown when this AEH is controlled by aperiodic scheduling parameters under the base scheduler, the release parameters specify the arrivalTimeQueueOverflowExcept policy, and this method would cause the arrival time queue to overflow.

run

public final void run()

When used as part of the internal mechanism activated by firing an async event, this method's detailed semantics are defined by the scheduler associated with this handler. The general outline is:

    while (fireCount > 0) {
       [initiate release]
       fireCount--;
       try { 
          handleAsyncEvent();
       } catch (Throwable th){
          th.printStackTrace();
       }
       [effect completion]
    }

All throwables from (or propagated through) handleAsyncEvent() are caught, a stack trace is printed and execution continues as if handleAsyncEvent had returned normally.

When it is directly invoked, this method invokes handleAsyncEvent() repeatedly while the fireCount is greater than zero; e.g.,

    while (getAndDecrementPendingFireCount() > 0)
      handleAsyncEvent();

however direct invocation of run is not recommended as it may interact with the normal release of this handler.

Applications cannot override this method and thus should use the logic parameter at construction, or override handleAsyncEvent() in subclasses with the logic of the handler.

Specified by:

run in interface java.lang.Runnable

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 if area was allowed to default. To determine the current status of the memory area stack associated with this, use the static methods defined in the RealtimeThread class. That is RealtimeThread.getCurrentMemoryArea(), RealtimeThread.getInitialMemoryAreaIndex(), RealtimeThread.getMemoryAreaStackDepth().

addToFeasibility

public boolean addToFeasibility()

Inform the scheduler and cooperating facilities that this instance of Schedulable should be considered in feasibility analysis until further notified.

If the object is already included in the feasibility set, do nothing.

Specified by:

addToFeasibility in interface Schedulable

Returns:

True, if the resulting system is feasible. False, if not.

addIfFeasible

public boolean addIfFeasible()

This method first performs a feasibility analysis with this added to the system. If the resulting system is feasible, inform the scheduler and cooperating facilities that this instance of Schedulable should be considered in feasibility analysis until further notified. If the analysis showed that the system including this would not be feasible, this method does not admit this to the feasibility set.

If the object is already included in the feasibility set, do nothing.

Specified by:

addIfFeasible in interface Schedulable

Returns:

True if inclusion of this in the feasibility set yields a feasible system, and false otherwise. If true is returned then this is known to be in the feasibility set. If false is returned this was not added to the feasibility set, but may already have been present.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memory)

This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of this. If the resulting system is feasible, this method replaces the current parameters of this with the proposed ones.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

release - The proposed release parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

memory - The proposed memory parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter values are not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and any of the proposed parameter objects are located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setIfFeasible

public boolean setIfFeasible(SchedulingParameters scheduling,
                             ReleaseParameters release,
                             MemoryParameters memory)

This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of this. If the resulting system is feasible, this method replaces the current parameters of this with the proposed ones.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

scheduling - The proposed scheduling parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

release - The proposed release parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

memory - The proposed memory parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter values are not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and any of the proposed parameter objects are located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)

This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of this. If the resulting system is feasible, this method replaces the current parameters of this with the proposed ones.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

release - The proposed release parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

memory - The proposed memory parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

group - The proposed processing group parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter values are not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and any of the proposed parameter objects are located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setIfFeasible

public boolean setIfFeasible(SchedulingParameters scheduling,
                             ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)

This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of this. If the resulting system is feasible, this method replaces the current parameters of this with the proposed ones.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

scheduling - The proposed scheduling parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

release - The proposed release parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

memory - The proposed memory parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

group - The proposed processing group parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter values are not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and any of the proposed parameter objects are located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setReleaseParametersIfFeasible

public boolean setReleaseParametersIfFeasible(ReleaseParameters release)

This method first performs a feasibility analysis using the proposed parameter object as replacement for the current parameter of this. If the resulting system is feasible, this method replaces the current parameter of this with the proposed one.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setReleaseParametersIfFeasible in interface Schedulable

Parameters:

release - The proposed release parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter value is not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and the proposed parameter object is located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold a reference to the proposed parameter object, or the parameter object cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setProcessingGroupParametersIfFeasible

public boolean setProcessingGroupParametersIfFeasible(ProcessingGroupParameters group)

This method first performs a feasibility analysis using the proposed parameter object as replacement for the current parameter of this. If the resulting system is feasible, this method replaces the current parameter of this with the proposed one.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setProcessingGroupParametersIfFeasible in interface Schedulable

Parameters:

group - The proposed processing group parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter value is not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and the proposed parameter object is located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold a reference to the proposed parameter object, or the parameter object cannot hold a reference to this.

setIfFeasible

public boolean setIfFeasible(ReleaseParameters release,
                             ProcessingGroupParameters group)

This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of this. If the resulting system is feasible, this method replaces the current parameters of this with the proposed ones.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setIfFeasible in interface Schedulable

Parameters:

release - The proposed release parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

group - The proposed processing group parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter values are not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and any of the proposed parameter objects are located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setMemoryParametersIfFeasible

public boolean setMemoryParametersIfFeasible(MemoryParameters memory)

This method first performs a feasibility analysis using the proposed parameter object as replacement for the current parameter of this. If the resulting system is feasible, this method replaces the current parameter of this with the proposed one.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setMemoryParametersIfFeasible in interface Schedulable

Parameters:

memory - The proposed memory parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter value is not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and the proposed parameter object is located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold a reference to the proposed parameter object, or the parameter object cannot hold a reference to this.

getMemoryParameters

public MemoryParameters getMemoryParameters()

Gets a reference to the MemoryParameters object for this schedulable object.

Specified by:

getMemoryParameters in interface Schedulable

Returns:

A reference to the current MemoryParameters object.

getReleaseParameters

public ReleaseParameters getReleaseParameters()

Gets a reference to the ReleaseParameters object for this schedulable object.

Specified by:

getReleaseParameters in interface Schedulable

Returns:

A reference to the current ReleaseParameters object.

getScheduler

public Scheduler getScheduler()

Gets a reference to the Scheduler object for this schedulable object.

Specified by:

getScheduler in interface Schedulable

Returns:

A reference to the associated Scheduler object.

getSchedulingParameters

public SchedulingParameters getSchedulingParameters()

Gets a reference to the SchedulingParameters object for this schedulable object.

Specified by:

getSchedulingParameters in interface Schedulable

Returns:

A reference to the current SchedulingParameters object.

getProcessingGroupParameters

public ProcessingGroupParameters getProcessingGroupParameters()

Gets a reference to the ProcessingGroupParameters object for this schedulable object.

Specified by:

getProcessingGroupParameters in interface Schedulable

Returns:

A reference to the current ProcessingGroupParameters object.

removeFromFeasibility

public boolean removeFromFeasibility()

Inform 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, if the removal was successful. False, if the schedulable object cannot be removed from the scheduler's feasibility set; e.g., the schedulable object is not part of the scheduler's feasibility set.

setMemoryParameters

public void setMemoryParameters(MemoryParameters memory)

Sets the memory parameters associated with this instance of Schedulable.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

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

Specified by:

setMemoryParameters in interface Schedulable

Parameters:

memory - A MemoryParameters object which will become the memory parameters associated with this after the method call. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Throws:

java.lang.IllegalArgumentException - Thrown if memory is not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and memory is located in heap memory.

IllegalAssignmentError - Thrown if the schedulable object cannot hold a reference to memory, or if memory cannot hold a reference to this schedulable object instance.

setReleaseParameters

public void setReleaseParameters(ReleaseParameters release)

Sets the release parameters associated with this instance of Schedulable.

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

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. 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. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Throws:

java.lang.IllegalArgumentException - Thrown when release is not compatible with the associated scheduler. Also thrown if this schedulable object is no-heap and release is located in heap memory.

IllegalAssignmentError - Thrown if this object cannot hold a reference to release or release cannot hold a reference to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setScheduler

public void 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 object, and scheduler.

Specified by:

setScheduler in interface Schedulable

Parameters:

scheduler - A reference to the scheduler that will manage execution of this schedulable object. Null is not a permissible value.

Throws:

java.lang.IllegalArgumentException - Thrown when scheduler is null, or the schedulable object's existing parameter values are not compatible with scheduler. Also thrown if this schedulable object is no-heap and scheduler is located in heap memory.

IllegalAssignmentError - Thrown if the schedulable object cannot hold a reference to scheduler.

java.lang.SecurityException - Thrown if the caller is not permitted to set the scheduler for this schedulable object.

setScheduler

public void setScheduler(Scheduler scheduler,
                         SchedulingParameters scheduling,
                         ReleaseParameters release,
                         MemoryParameters memoryParameters,
                         ProcessingGroupParameters group)

Sets the scheduler and associated parameter objects. The timing of the change must be agreed between the scheduler currently associated with this schedulable object, and scheduler.

Specified by:

setScheduler in interface Schedulable

Parameters:

scheduler - A reference to the scheduler that will manage the execution of this schedulable object. Null is not a permissible value.

scheduling - A reference to the SchedulingParameters which will be associated with this. If null, the default value is governed by scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

release - A reference to the ReleaseParameters which will be associated with this. If null, the default value is governed by scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

memoryParameters - A reference to the MemoryParameters which will be associated with this. If null, the default value is governed by scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

group - A reference to the ProcessingGroupParameters which will be associated with this. If null, the default value is governed by scheduler (a new object is created). (See PriorityScheduler.)

Throws:

java.lang.IllegalArgumentException - Thrown when scheduler is null or the parameter values are not compatible with scheduler. Also thrown when this schedulable object is no-heap and scheduler, scheduling release, memoryParameters, or group is located in heap memory.

IllegalAssignmentError - Thrown if this object cannot hold references to all the parameter objects or the parameters cannot hold references to this.

java.lang.IllegalThreadStateException - Thrown if the new release parameters change the schedulable object from periodic scheduling to some other protocol and the schedulable object is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

java.lang.SecurityException - Thrown if the caller is not permitted to set the scheduler for this schedulable object.

setSchedulingParameters

public void setSchedulingParameters(SchedulingParameters scheduling)

Sets the scheduling parameters associated with this instance of Schedulable.

Since this affects the scheduling parameters of the existing schedulable objects, this may change the feasibility of the current system.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

Specified by:

setSchedulingParameters in interface Schedulable

Parameters:

scheduling - A reference to the SchedulingParameters object. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Throws:

java.lang.IllegalArgumentException - Thrown when scheduling is not compatible with the associated scheduler. Also thrown if this schedulable object is no-heap and scheduling is located in heap memory.

IllegalAssignmentError - Thrown if this object cannot hold a reference to scheduling or scheduling cannot hold a reference to this.

setSchedulingParametersIfFeasible

public boolean setSchedulingParametersIfFeasible(SchedulingParameters scheduling)

This method first performs a feasibility analysis using the proposed parameter object as replacement for the current parameter of this. If the resulting system is feasible, this method replaces the current parameter of this with the proposed one.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:

setSchedulingParametersIfFeasible in interface Schedulable

Parameters:

scheduling - The proposed scheduling parameters. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown when the parameter value is not compatible with the schedulable object's scheduler. Also thrown if this schedulable object is no-heap and the proposed parameter object is located in heap memory.

IllegalAssignmentError - Thrown if this cannot hold a reference to the proposed parameter object, or the parameter object cannot hold a reference to this.

setProcessingGroupParameters

public void setProcessingGroupParameters(ProcessingGroupParameters group)

Sets the ProcessingGroupParameters of this.

This change becomes effective under conditions determined by the scheduler controlling the schedulable object. For instance, the change may be immediate or it may be delayed until the next release of the schedulable object. See the documentation for the scheduler for details.

Since this affects the constraints expressed in the processing group parameters of the existing schedulable objects, this may change the feasibility of the current system.

Specified by:

setProcessingGroupParameters in interface Schedulable

Parameters:

group - A ProcessingGroupParameters object which will take effect as determined by the associated scheduler. If null, the default value is governed by the associated scheduler (a new object is created if the default value is not null). (See PriorityScheduler.)

Throws:

java.lang.IllegalArgumentException - Thrown when group is not compatible with the scheduler for this schedulable object. Also thrown if this schedulable object is no-heap and group is located in heap memory.

IllegalAssignmentError - Thrown if this object cannot hold a reference to group or group cannot hold a reference to this.

setDaemon

public final void setDaemon(boolean on)

Marks this event handler as either a daemon event handler or a user event handler. The Real-Time Virtual Machine exits when the only schedulable objects and threads running are all daemon. This method must be called before the event handler is attached to any event. Once attached, it cannot be changed.

Parameters:

on - If true, marks this event handler as a daemon handler.

Throws:

java.lang.IllegalThreadStateException - Thrown if this event handler is attached to an AE.

java.lang.SecurityException - Thrown if the current schedulable object cannot modify this event handler.

Since:

1.0.1

isDaemon

public final boolean isDaemon()

Tests if this event handler is a daemon handler.

Returns:

True if this event handler is a daemon handler; false otherwise.

Since:

1.0.1