javax.realtime
Class AperiodicParameters

java.lang.Object
  javax.realtime.ReleaseParameters
      javax.realtime.AperiodicParameters

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

SporadicParameters

public class AperiodicParameters

extends ReleaseParameters

This release parameter object characterizes a schedulable object that may be released at any time.

When a reference to an AperiodicParameters object is given as a parameter to a schedulable object's constructor or passed as an argument to one of the schedulable object's setter methods, the AperiodicParameters object becomes the release parameters object bound to that schedulable object. Changes to the values in the AperiodicParameters object affect that schedulable object. If bound to more than one schedulable object then changes to the values in the AperiodicParameters object affect all of the associated objects. Note that this is a one-to-many relationship and not a many-to-many.

Only changes to an AperiodicParameters object caused by methods on that object cause the change to propagate to all schedulable objects using the object. For instance, calling setCost on an AperiodicParameters object will make the change, then notify that the scheduler that the parameter object has changed. At that point the object is reconsidered for every SO that uses it. Invoking a method on the RelativeTime object that is the cost for this object may change the cost but it does not pass the change to the scheduler at that time. That change must not change the behavior of the SOs that use the parameter object until a setter method on the AperiodicParameters object is invoked, or the parameter object is used in setReleaseParameters() or a constructor for an SO.

The implementation must use modified copy semantics for each HighResolutionTime parameter value. The value of each time object should be treated as if it were copied at the time it is passed to the parameter object, but the object reference must also be retained. For instance, the value returned by getCost() must be the same object passed in by setCost(), but any changes made to the time value of the cost must not take effect in the associated AperiodicParameters instance unless they are passed to the parameter object again, e.g. with a new invocation of setCost.

Correct initiation of the deadline miss and cost overrun handlers requires that the underlying system know the arrival time of each sporadic task. For an instance of RealtimeThread the arrival time is the time at which the start() is invoked. For other instances of Schedulable required behaviors may require the implementation to behave effectively as if it maintained a queue of arrival times.

Caution: This class is explicitly unsafe in multithreaded situations when it is being changed. No synchronization is done. It is assumed that users of this class who are mutating instances will be doing their own synchronization at a higher level.

Correct initiation of the deadline miss and cost overrun handlers requires that the underlying system know the arrival time of each aperiodic task. For an instance of RealtimeThread the arrival time is the time at which the start() is invoked. For other instances of Schedulable required behaviors may require the implementation to behave effectively as if it maintained a queue of arrival times.

arrivalTimeQueueOverflowExcept

public static final java.lang.String arrivalTimeQueueOverflowExcept

Represents the "EXCEPT" policy for dealing with arrival time queue overflow. Under this policy, if an arrival occurs and its time should be queued, but the queue already holds a number of times equal to the initial queue length defined by this then the fire() method shall throw a ArrivalTimeQueueOverflowException. Any other associated semantics are governed by the schedulers for the schedulable objects using these aperiodic parameters. If the arrival is a result of a happening to which the instance of AsyncEventHandler is bound, then the arrival time is ignored.

Since:

1.0.1 Moved here from SporadicParameters.

See Also:

Constant Field Values

arrivalTimeQueueOverflowIgnore

public static final java.lang.String arrivalTimeQueueOverflowIgnore

Represents the "IGNORE" policy for dealing with arrival time queue overflow. Under this policy, if an arrival occurs and its time should be queued, but the queue already holds a number of times equal to the initial queue length defined by this then the arrival is ignored. Any other associated semantics are governed by the schedulers for the schedulable objects using these aperiodic parameters.

Since:

1.0.1 Moved here from SporadicParameters.

See Also:

Constant Field Values

arrivalTimeQueueOverflowReplace

public static final java.lang.String arrivalTimeQueueOverflowReplace

Represents the "REPLACE" policy for dealing with arrival time queue overflow. Under this policy if an arrival occurs and should be queued but the queue already holds a number of times equal to the initial queue length defined by this then the information for this arrival replaces a previous arrival. Any other associated semantics are governed by the schedulers for the schedulable objects using these aperiodic parameters.

Since:

1.0.1 Moved here from SporadicParameters.

See Also:

Constant Field Values

arrivalTimeQueueOverflowSave

public static final java.lang.String arrivalTimeQueueOverflowSave

Represents the "SAVE" policy for dealing with arrival time queue overflow. Under this policy if an arrival occurs and should be queued but the queue is full, then the queue is lengthened and the arrival time is saved. Any other associated semantics are governed by the schedulers for the schedulable objects using these aperiodic parameters.

This policy does not update the "initial queue length" as it alters the actual queue length. Since the SAVE policy grows the arrival time queue as necessary, for the SAVE policy the initial queue length is only an optimization.

Since:

1.0.1 Moved here from SporadicParameters.

See Also:

Constant Field Values

AperiodicParameters

public AperiodicParameters()

Create an AperiodicParameters object. This constructor is equivalent to:
AperiodicParameters(null, null, null, null)

Since:

1.0.1

AperiodicParameters

public AperiodicParameters(RelativeTime cost,
                           RelativeTime deadline,
                           AsyncEventHandler overrunHandler,
                           AsyncEventHandler missHandler)

Create an AperiodicParameters object.

Parameters:

cost - Processing time per invocation. On implementations which can measure the amount of time a schedulable object is executed, this value is the maximum amount of time a schedulable object receives. On implementations which cannot measure execution time, this value is used as a hint to the feasibility algorithm. On such systems it is not possible to determine when any particular object exceeds cost. If null, the default value is a new instance of RelativeTime(0,0).

deadline - The latest permissible completion time measured from the release time of the associated invocation of the schedulable object. If null, the default value is a new instance of RelativeTime(Long.MAX_VALUE, 999999).

overrunHandler - This handler is invoked if an invocation of the schedulable object exceeds cost. Not required for minimum implementation. If null, the default value is no overrun handler.

missHandler - This handler is invoked if the run() method of the schedulable object is still executing after the deadline has passed. Although minimum implementations do not consider deadlines in feasibility calculations, they must recognize variable deadlines and invoke the miss handler as appropriate. If null, the default value is no miss handler.

Throws:

java.lang.IllegalArgumentException - Thrown if the time value of cost is less than zero, or the time value of deadline is less than or equal to zero.

IllegalAssignmentError - Thrown if cost, deadline, overrunHandler or missHandler cannot be stored in this.

getArrivalTimeQueueOverflowBehavior

public java.lang.String getArrivalTimeQueueOverflowBehavior()

Gets the behavior of the arrival time queue in the event of an overflow.

Returns:

The behavior of the arrival time queue as a string.

Since:

1.0.1 Moved from SporadicParameters

getInitialArrivalTimeQueueLength

public int getInitialArrivalTimeQueueLength()

Gets the initial number of elements the arrival time queue can hold. This returns the initial queue length currently associated with this parameter object. If the overflow policy is SAVE the initial queue length may not be related to the current queue lengths of schedulable objects associated with this parameter object.

Returns:

The initial length of the queue.

Since:

1.0.1 Moved here from SporadicParameters.

setDeadline

public void setDeadline(RelativeTime deadline)

Sets the deadline value.

If this parameter object is associated with any schedulable object (by being passed through the schedulable object's constructor or set with a method such as RealtimeThread.setReleaseParameters(ReleaseParameters)) the deadline of those schedulable objects is altered as specified by each schedulable object's respective scheduler.

Overrides:

setDeadline in class ReleaseParameters

Parameters:

deadline - The latest permissible completion time measured from the release time of the associated invocation of the schedulable object. If deadline is null, the deadline is set to a new instance of RelativeTime(Long.MAX_VALUE, 999999).

Throws:

java.lang.IllegalArgumentException - Thrown if the time value of deadline is less than or equal to zero, or if the new value of this deadline is incompatible with the scheduler for any associated schedulable object.

IllegalAssignmentError - Thrown if deadline cannot be stored in this.

setArrivalTimeQueueOverflowBehavior

public void setArrivalTimeQueueOverflowBehavior(java.lang.String behavior)

Sets the behavior of the arrival time queue in the case where the insertion of a new element would make the queue size greater than the initial size given in this.

Parameters:

behavior - A string representing the behavior.

Throws:

java.lang.IllegalArgumentException - Thrown if behavior is not one of the final queue overflow behavior values defined in this class.

Since:

1.0.1 Moved here from SporadicParameters.

setIfFeasible

public boolean setIfFeasible(RelativeTime cost,
                             RelativeTime deadline)

This method first performs a feasibility analysis using the new cost, and deadline as replacements for the matching attributes of this. If the resulting system is feasible, the method replaces the current scheduling characteristics, of this with the new scheduling characteristics.

Overrides:

setIfFeasible in class ReleaseParameters

Parameters:

cost - The proposed cost. to determine when any particular object exceeds cost. If null, the default value is a new instance of RelativeTime(0,0).

deadline - The proposed deadline. If null, the default value is a new instance of RelativeTime(Long.MAX_VALUE, 999999).

Returns:

false. Aperiodic parameters never yield a feasible system. (Subclasses of AperiodicParameters, such as SporadicParameters, need not return false.)

Throws:

java.lang.IllegalArgumentException - Thrown if the time value of cost is less than zero, or the time value of deadline is less than or equal to zero, or the values are incompatible with the scheduler for any of the schedulable objects which are presently using this parameter object.

IllegalAssignmentError - Thrown if cost or deadline cannot be stored in this.

setInitialArrivalTimeQueueLength

public void setInitialArrivalTimeQueueLength(int initial)

Sets the initial number of elements the arrival time queue can hold without lengthening the queue. The initial length of an arrival queue is set when the SO using the queue is constructed, after that time changes in the initial queue length are ignored.

Parameters:

initial - The initial length of the queue.

Throws:

java.lang.IllegalArgumentException - Thrown if initial is less than zero.

Since:

1.0.1 Moved here from SporadicParameters.