javax.realtime

Class SporadicParameters

java.lang.Object

javax.realtime.ReleaseParameters<AperiodicParameters>

javax.realtime.AperiodicParameters

javax.realtime.SporadicParameters

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class SporadicParameters
extends AperiodicParameters

A notice to the scheduler that the associated schedulable will be released aperiodically but with a minimum time between releases.

When a reference to a SporadicParameters 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 SporadicParameters object becomes the release parameters object bound to that schedulable. Changes to the values in the SporadicParameters object affect that schedulable object. When bound to more than one schedulable then changes to the values in the SporadicParameters object affect all of the associated objects. Note that this is a one-to-many relationship and not a many-to-many.

The implementation must use modified copy semantics for each HighResolutionTime parameter value. The value of each time object should be treated as when it were copied at the time it is passed to the parameter object, but the object reference must also be retained. Only changes to a SporadicParameters object caused by methods on that object cause the change to propagate to all schedulables using the parameter object. For instance, calling setCost on a SporadicParameters object will make the change, then notify 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 SporadicParameters object is invoked, the parameter object is used in setReleaseParameters(), or the object is used in a constructor for an SO.

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

SporadicParameters Default Values

Attribute	Value
minInterarrival time	No default. A value must be supplied
cost	new RelativeTime(0,0)
deadline	new RelativeTime(mit)
overrunHandler	None
missHandler	None
rousable	false
MIT violation policy	SAVE
Arrival queue overflow policy	SAVE
Initial arrival queue length	0

This class enables the application to specify one of four arrival behaviors defined by MinimumInterarrivalPolicy. Each behavior indicates what to do when an arrival occurs that is closer in time to the previous arrival than the value given in this class as minimum interarrival time. They also specify what to do when, for any reason, the queue overflows, and what the initial size of the queue should be.

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	mitViolationExcept Deprecated. since RTSJ 2.0
static java.lang.String	mitViolationIgnore Deprecated. since RTSJ 2.0
static java.lang.String	mitViolationReplace Deprecated. since RTSJ 2.0
static java.lang.String	mitViolationSave Deprecated. since RTSJ 2.0

Fields inherited from class javax.realtime.AperiodicParameters

arrivalTimeQueueOverflowExcept, arrivalTimeQueueOverflowIgnore, arrivalTimeQueueOverflowReplace, arrivalTimeQueueOverflowSave

Fields inherited from class javax.realtime.ReleaseParameters

DISABLE_MONITORING

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
RelativeTime	getMinimumInterarrival() Determines the current value of minimal interarrival.
RelativeTime	getMinimumInterarrival(RelativeTime value) Determines the current value of minimum interarrival.
MinimumInterarrivalPolicy	getMinimumInterarrivalPolicy() Gets the arrival time queue policy for handling minimal interarrival time underflow.
java.lang.String	getMitViolationBehavior() Deprecated. since RTSJ 2.0 and replaced by getMinimumInterarrivalPolicy().
boolean	setIfFeasible(RelativeTime cost, RelativeTime deadline) Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
boolean	setIfFeasible(RelativeTime interarrival, RelativeTime cost, RelativeTime deadline) Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate
SporadicParameters	setMinimumInterarrival(RelativeTime minimum) Sets the minimum interarrival time.
SporadicParameters	setMinimumInterarrivalPolicy(MinimumInterarrivalPolicy policy) Sets the policy for handling the arrival time queue when the new arrival time is closer to the previous arrival time than the minimum interarrival time given in this.
void	setMitViolationBehavior(java.lang.String behavior) Deprecated. since RTSJ 2.0 and replaced by setMinimumInterarrivalPolicy(javax.realtime.MinimumInterarrivalPolicy).

Methods inherited from class javax.realtime.AperiodicParameters

getArrivalTimeQueueOverflowBehavior, getInitialArrivalTimeQueueLength, setArrivalTimeQueueOverflowBehavior, setInitialArrivalTimeQueueLength

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

mitViolationExcept

@Deprecated
public static final java.lang.String mitViolationExcept

Deprecated. since RTSJ 2.0

Represents the "EXCEPT" policy for dealing with minimum interarrival time violations. Under this policy, when an arrival time for any instance of Schedulable which has this as its instance of ReleaseParameters occurs at a time less then the minimum interarrival time defined here then the fire() method shall throw MITViolationException. Any other associated semantics are governed by the schedulers for the schedulables using these sporadic parameters. When the arrival time is a result of a happening to which the instance of AsyncEventHandler is bound then the arrival time is ignored.

mitViolationIgnore

@Deprecated
public static final java.lang.String mitViolationIgnore

Deprecated. since RTSJ 2.0

Represents the "IGNORE" policy for dealing with minimum interarrival time violations. Under this policy, when an arrival time for any instance of Schedulable which has this as its instance of ReleaseParameters occurs at a time less then the minimum interarrival time defined here then the new arrival time is ignored. Any other associated semantics are governed by the schedulers for the schedulables using these sporadic parameters.

mitViolationSave

@Deprecated
public static final java.lang.String mitViolationSave

Deprecated. since RTSJ 2.0

Represents the "SAVE" policy for dealing with minimum interarrival time violations. Under this policy the arrival time for any instance of Schedulable which has this as its instance of ReleaseParameters is not compared to the specified minimum interarrival time. Any other associated semantics are governed by the schedulers for the schedulable objects using these sporadic parameters.

mitViolationReplace

@Deprecated
public static final java.lang.String mitViolationReplace

Deprecated. since RTSJ 2.0

Represents the "REPLACE" policy for dealing with minimum interarrival time violations. Under this policy when an arrival time for any instance of Schedulable which has this as its instance of ReleaseParameters occurs at a time less then the minimum interarrival time defined here then the information for this arrival replaces a previous arrival. Any other associated semantics are governed by the schedulers for the schedulables using these sporadic parameters.

Constructor Detail

SporadicParameters

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

Creates a SporadicParameters object.

Parameters:

minInterarrival - The release times of the schedulable will occur no closer than this interval. This time object is treated as if it were copied. Changes to minInterarrival will not affect the SporadicParameters object. There is no default value. When minInterarrival is null an illegal argument exception is thrown.

cost - Processing time per release. On implementations which can measure the amount of time a schedulable is executed, this value is the maximum amount of time a schedulable receives per release. 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 minInterarrival: new RelativeTime(minInterarrival).

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

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

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

Throws:

StaticIllegalArgumentException - when minInterarrival is null or its time value is not greater than zero, or the time value of cost is less than zero, or the time value of deadline is not greater than zero, or when the chronograph associated with deadline and minInterarrival parameters are not identical or not an instance of Clock.

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

Since:

RTSJ 2.0

SporadicParameters

public SporadicParameters(RelativeTime minInterarrival,
                          RelativeTime cost,
                          RelativeTime deadline,
                          AsyncEventHandler overrunHandler,
                          AsyncEventHandler missHandler)

Equivalent to SporadicParameters(RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with an argument list of (minInterarrival, cost, deadline, overrunHandler, missHandler, false).

SporadicParameters

public SporadicParameters(RelativeTime minInterarrival,
                          RelativeTime deadline,
                          AsyncEventHandler missHandler,
                          boolean rousable)

Equivalent to SporadicParameters(RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with an argument list of (minInterarrival, null, deadline, null, missHandler, rousable).

Since:

RTSJ 2.0

SporadicParameters

public SporadicParameters(RelativeTime minInterarrival)

Equivalent to SporadicParameters(RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with an argument list of (minInterarrival, null, null, null, null, false).

Since:

RTSJ 1.0.1

Method Detail

getMinimumInterarrival

public RelativeTime getMinimumInterarrival()

Determines the current value of minimal interarrival.

Returns:

the object last used to set the minimal interarrival containing the current value of minimal interarrival.

getMinimumInterarrival

public RelativeTime getMinimumInterarrival(RelativeTime value)

Determines the current value of minimum interarrival.

Parameters:

value - A relative time object to fill and return.

Returns:

value or, when null, the last object used to set the minimal interarrival, set to the current value of minimal interarrival.

Since:

RTSJ 2.0

setMinimumInterarrival

public SporadicParameters setMinimumInterarrival(RelativeTime minimum)

Sets the minimum interarrival time.

Parameters:

minimum - The release times of the schedulable will occur no closer than this interval.

Returns:

this

Throws:

StaticIllegalArgumentException - when minimum is null or its time value is not greater than zero.

IllegalAssignmentError - when minimum cannot be stored in this.

Since:

RTSJ 2.0 returns itself

setMinimumInterarrivalPolicy

public SporadicParameters setMinimumInterarrivalPolicy(MinimumInterarrivalPolicy policy)

Sets the policy for handling the arrival time queue when the new arrival time is closer to the previous arrival time than the minimum interarrival time given in this.

Parameters:

policy - The current policy for MIT violations.

Since:

RTSJ 2.0

getMinimumInterarrivalPolicy

public MinimumInterarrivalPolicy getMinimumInterarrivalPolicy()

Gets the arrival time queue policy for handling minimal interarrival time underflow.

Returns:

the minimum interarrival time violation behavior as a string.

Since:

RTSJ 2.0

setMitViolationBehavior

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

Deprecated. since RTSJ 2.0 and replaced by setMinimumInterarrivalPolicy(javax.realtime.MinimumInterarrivalPolicy).

Sets the behavior of the arrival time queue for the case where the new arrival time is closer to the previous arrival time than the minimum interarrival time given in this.

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 MIT violation behavior values defined in this class.

getMitViolationBehavior

@Deprecated
public java.lang.String getMitViolationBehavior()

Deprecated. since RTSJ 2.0 and replaced by getMinimumInterarrivalPolicy().

Gets the arrival time queue behavior in the event of a minimum interarrival time violation.

Returns:

the minimum interarrival time violation behavior as a string.

setIfFeasible

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

Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate

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 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(mit).

Returns:

true, when the resulting system is feasible and the changes are made; false, when the resulting system is not feasible and no changes are made.

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.

setIfFeasible

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

Deprecated. as of RTSJ 2.0 The framework for feasibility analysis is inadequate

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

Changes to a SporadicParameters instance effect subsequent arrivals.

Parameters:

interarrival - The proposed interarrival time. There is no default value. When minInterarrival is null an illegal argument exception is thrown.

cost - The proposed 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(mit).

Returns:

true, when the resulting system is feasible and the changes are made; false, when the resulting system is not feasible and no changes are made.

Throws:

StaticIllegalArgumentException - when minInterarrival is null or its time value is not greater than zero, or the time value of cost is less than zero, or the time value of deadline is not greater than zero.

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