javax.realtime

Class AperiodicParameters

java.lang.Object

javax.realtime.ReleaseParameters<AperiodicParameters>

javax.realtime.AperiodicParameters

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

SporadicParameters

public class AperiodicParameters
extends ReleaseParameters<AperiodicParameters>

When a reference to an AperiodicParameters object is given as a parameter to a schedulable's constructor or passed as an argument to one of the schedulable's setter methods, the AperiodicParameters object becomes the release parameters object bound to that schedulable. Changes to the values in the AperiodicParameters object affect that schedulable. When bound to more than one schedulable, 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 schedulables using the object. For instance, calling setCost on an AperiodicParameters object will make the change, then notify the scheduler that the parameter object has changed. At that point the object is reconsidered for every schedulable 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 schedulables that use the parameter object until a setter method on the AperiodicParameters object is invoked, the parameter object is used in setReleaseParameters(), or it is used in a constructor for a schedulable.

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 aperiodic task. For an instance of RealtimeThread the arrival time is the time at which the start() is invoked. For other instances of Schedulable, the required behavior may force the implementation to act effectively as if it maintained a queue of arrival times.

When the release parameters for a RealtimeThread are set to an instance of this class or one of its subclasses, the thread does not start executing code until the RealtimeThread.release() method is called.

The following table gives the default values for the constructors parameters.

AperiodicParameters Default Values

Attribute	Value
cost	new RelativeTime(0,0)
deadline	new RelativeTime(Long.MAX_VALUE, 999999)
overrunHandler	None
missHandler	None
rousable	false
Arrival time queue size	0
Queue overflow policy	SAVE

See Also:

Serialized Form

Caution: This class is explicitly unsafe for multithreading when being changed. Code that mutates instances of this class should synchronize at a higher level.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	arrivalTimeQueueOverflowExcept Deprecated. since RTSJ 2.0
static java.lang.String	arrivalTimeQueueOverflowIgnore Deprecated. since RTSJ 2.0
static java.lang.String	arrivalTimeQueueOverflowReplace Deprecated. since RTSJ 2.0
static java.lang.String	arrivalTimeQueueOverflowSave Deprecated. since RTSJ 2.0

Fields inherited from class javax.realtime.ReleaseParameters

DISABLE_MONITORING

Constructor Summary

Constructors

Constructor and Description
AperiodicParameters() Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (null, null, null, null, false).
AperiodicParameters(RelativeTime deadline) Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (null, deadline, null, null, false).
AperiodicParameters(RelativeTime deadline, AsyncEventHandler missHandler, boolean rousable) Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (null, deadline, null, missHandler, rousable).
AperiodicParameters(RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler) Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (cost, deadline, overrunHandler, missHandler, false).
AperiodicParameters(RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler, boolean rousable) Creates an AperiodicParameters object.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getArrivalTimeQueueOverflowBehavior() Deprecated. since RTSJ 2.0 and replaced by ReleaseParameters.getEventQueueOverflowPolicy()
int	getInitialArrivalTimeQueueLength() Deprecated. since RTSJ 2.0 replaced by ReleaseParameters.getInitialQueueLength().
void	setArrivalTimeQueueOverflowBehavior(java.lang.String behavior) Deprecated. Since RTSJ 2.0
boolean	setIfFeasible(RelativeTime cost, RelativeTime deadline) Deprecated. as of RTSJ 2.0
void	setInitialArrivalTimeQueueLength(int initial) Deprecated. since RTSJ 2.0 replaced by ReleaseParameters.setInitialQueueLength(int initial).

Methods inherited from class javax.realtime.ReleaseParameters

clone, getCost, getCost, getCostOverrunHandler, getDeadline, getDeadline, getDeadlineMissHandler, getEventQueueOverflowPolicy, getInitialQueueLength, isRousable, setCost, setCostOverrunHandler, setDeadline, setDeadlineMissHandler, setEventQueueOverflowPolicy, setInitialQueueLength, setRousable

Methods inherited from class java.lang.Object

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

Field Detail

arrivalTimeQueueOverflowExcept

@Deprecated
public static final java.lang.String arrivalTimeQueueOverflowExcept

Deprecated. since RTSJ 2.0

Represents the ``EXCEPT'' policy for dealing with arrival time queue overflow. Under this policy, when 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 schedulables using these aperiodic parameters. When the arrival is a result of a happening to which the instance of AsyncEventHandler is bound then the arrival time is ignored.

Since:

RTSJ 1.0.1 Moved here from SporadicParameters.

arrivalTimeQueueOverflowIgnore

@Deprecated
public static final java.lang.String arrivalTimeQueueOverflowIgnore

Deprecated. since RTSJ 2.0

Represents the ``IGNORE'' policy for dealing with arrival time queue overflow. Under this policy, when 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 schedulables using these aperiodic parameters.

Since:

RTSJ 1.0.1 Moved here from SporadicParameters.

arrivalTimeQueueOverflowReplace

@Deprecated
public static final java.lang.String arrivalTimeQueueOverflowReplace

Deprecated. since RTSJ 2.0

Represents the ``REPLACE'' policy for dealing with arrival time queue overflow. Under this policy, when 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 schedulables using these aperiodic parameters.

Since:

RTSJ 1.0.1 Moved here from SporadicParameters.

arrivalTimeQueueOverflowSave

@Deprecated
public static final java.lang.String arrivalTimeQueueOverflowSave

Deprecated. since RTSJ 2.0

Represents the ``SAVE'' policy for dealing with arrival time queue overflow. Under this policy, when 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 schedulables using these aperiodic parameters.

This policy does not update the ``initial queue length;'' 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:

RTSJ 1.0.1 Moved here from SporadicParameters.

Constructor Detail

AperiodicParameters

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

Creates 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 receives. On implementations which cannot measure execution time, it is not possible to determine when any particular object exceeds cost. When 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. When null, the default value is a new instance of RelativeTime(Long.MAX_VALUE, 999999).

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

missHandler - This handler is invoked when the run() method of the schedulable object is still executing after the deadline has passed. When null, the default value is no miss handler.

rousable - determines whether or not an instance of Schedulable can be prematurely released by a thread interrupt.

Throws:

StaticIllegalArgumentException - when the time value of cost is less than zero, or the time value of deadline is less than or equal to zero.

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

Since:

RTSJ 2.0

AperiodicParameters

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

Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (cost, deadline, overrunHandler, missHandler, false).

Parameters:

cost - Processing time per invocation. On implementations that support cost enforcement, this value is the maximum amount of time a schedulable receives. On implementations which do not support cost enforcement, it is not possible to determine when any particular object exceeds cost. When 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. When null, the default value is a new instance of RelativeTime(Long.MAX_VALUE, 999999).

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

missHandler - This handler is invoked when the run() method of the schedulable object is still executing after the deadline has passed. When null, the default value is no miss handler.

Throws:

StaticIllegalArgumentException - when the time value of cost is less than zero, or the time value of deadline is less than or equal to zero.

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

AperiodicParameters

public AperiodicParameters(RelativeTime deadline,
                           AsyncEventHandler missHandler,
                           boolean rousable)

Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (null, deadline, null, missHandler, rousable).

Since:

RTSJ 2.0

AperiodicParameters

public AperiodicParameters(RelativeTime deadline)

Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (null, deadline, null, null, false).

Since:

RTSJ 2.0

AperiodicParameters

public AperiodicParameters()

Equivalent to AperiodicParameters(RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (null, null, null, null, false).

Since:

RTSJ 1.0.1

Method Detail

getInitialArrivalTimeQueueLength

@Deprecated
public int getInitialArrivalTimeQueueLength()

Deprecated. since RTSJ 2.0 replaced by ReleaseParameters.getInitialQueueLength().

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

Returns:

The initial length of the queue.

Since:

RTSJ 1.0.1 Moved here from SporadicParameters.

setInitialArrivalTimeQueueLength

@Deprecated
public void setInitialArrivalTimeQueueLength(int initial)

Deprecated. since RTSJ 2.0 replaced by ReleaseParameters.setInitialQueueLength(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 schedulable 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:

StaticIllegalArgumentException - when initial is less than zero.

Since:

RTSJ 1.0.1 Moved here from SporadicParameters.

getArrivalTimeQueueOverflowBehavior

@Deprecated
public java.lang.String getArrivalTimeQueueOverflowBehavior()

Deprecated. since RTSJ 2.0 and replaced by ReleaseParameters.getEventQueueOverflowPolicy()

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:

RTSJ 1.0.1 Moved from SporadicParameters

setArrivalTimeQueueOverflowBehavior

@Deprecated
public void setArrivalTimeQueueOverflowBehavior(java.lang.String behavior)

Deprecated. Since RTSJ 2.0

Sets the behavior of the arrival time queue for the case where the insertion of a new element makes the queue size greater than the initial size given when this object was constructed.

Values of behavior are compared using reference equality (==) not value equality (equals()).

Parameters:

behavior - A string representing the behavior.

Throws:

StaticIllegalArgumentException - when behavior is not one of the final queue overflow behavior values defined in this class.

Since:

RTSJ 1.0.1 Moved here from SporadicParameters.

setIfFeasible

@Deprecated
public boolean setIfFeasible(RelativeTime cost,
                                         RelativeTime deadline)

Deprecated. as of RTSJ 2.0

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

Overrides:

setIfFeasible in class ReleaseParameters<AperiodicParameters>

Parameters:

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

deadline - The proposed deadline. When 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:

StaticIllegalArgumentException - when 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 schedulables which are presently using this parameter object.

IllegalAssignmentError - when cost or deadline cannot be stored in this.