javax.realtime

Class PeriodicParameters

java.lang.Object

javax.realtime.ReleaseParameters<PeriodicParameters>

javax.realtime.PeriodicParameters

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public class PeriodicParameters
extends ReleaseParameters<PeriodicParameters>

This release parameter indicates that the schedulable is released on a regular basis. For an AsyncEventHandler, this means the handler is either released by a periodic timer or the associated event occurs periodically. For a RealtimeThread, this means the RealtimeThread.waitForNextRelease() method will unblock the associated realtime thread at the start of each period.

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

Only a change to a PeriodicParameters object caused by methods on that object cause the change to be propagate to all instances of Schedulable using that parameter object. For instance, calling setCost on a PeriodicParameters 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 a RelativeTime object that is the cost for this object changes the cost value but 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 PeriodicParameters object is invoked, the parameter object is used in setReleaseParameters(), or it is used in a constructor for an SO.

Periodic parameters use HighResolutionTime values for period and start time. Since these times are expressed as a HighResolutionTime values, these values use accurate timers with nanosecond granularity. The actual resolution available and even the quantity the timers measure depend on the clock associated with each time value.

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 PeriodicParameters instance unless they are passed to the parameter object again, e.g. with a new invocation of setCost.

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

PeriodicParameter Default Values

Attribute	Default Value
start	new RelativeTime(0,0)
period	No default. A value must be supplied
cost	new RelativeTime(0,0)
deadline	new RelativeTime(period)
overrunHandler	None
missHandler	None
EventQueueOverflowPolicy	QueueOverflowPolicy.DISABLE

Periodic release parameters are strictly informational when they are applied to async event handlers. They must be used for any feasibility analysis, but release of the async event handler is not entirely controlled by the scheduler.

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 inherited from class javax.realtime.ReleaseParameters

DISABLE_MONITORING

Constructor Summary

Constructors

Constructor and Description
PeriodicParameters(HighResolutionTime<?> start, RelativeTime period) Equivalent to PeriodicParameters(HighResolutionTime, RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (start, period, null, null, null, null, false);
PeriodicParameters(HighResolutionTime<?> start, RelativeTime period, RelativeTime deadline, AsyncEventHandler missHandler, boolean rousable) Equivalent to PeriodicParameters(HighResolutionTime, RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (start, period, deadline, null, null, missHandler, rousable);
PeriodicParameters(HighResolutionTime<?> start, RelativeTime period, RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler) Equivalent to PeriodicParameters(HighResolutionTime, RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (start, period, cost, deadline, overrunHandler, missHandler, false);
PeriodicParameters(HighResolutionTime<?> start, RelativeTime period, RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler, boolean rousable) Creates a PeriodicParameters object with attributes set to the specified values.
PeriodicParameters(RelativeTime period) Creates a PeriodicParameters object with the specified period and all other attributes set to their default values.

Method Summary

Modifier and Type	Method and Description
RelativeTime	getPeriod() Determines the current value of period.
RelativeTime	getPeriod(RelativeTime value) Determines the current value of period.
HighResolutionTime<?>	getStart() Determines the time used to start an instance of Schedulable, which is not necessarily the time at which it actually started.
boolean	setIfFeasible(RelativeTime period, RelativeTime cost, RelativeTime deadline) Deprecated. as of RTSJ 2.0; the framework for feasibility analysis is inadequate
PeriodicParameters	setPeriod(RelativeTime period) Sets the period.
PeriodicParameters	setStart(HighResolutionTime<?> start) Sets the start time.

Methods inherited from class javax.realtime.ReleaseParameters

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

Methods inherited from class java.lang.Object

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

Constructor Detail

PeriodicParameters

public PeriodicParameters(HighResolutionTime<?> start,
                          RelativeTime period,
                          RelativeTime cost,
                          RelativeTime deadline,
                          AsyncEventHandler overrunHandler,
                          AsyncEventHandler missHandler,
                          boolean rousable)

Creates a PeriodicParameters object with attributes set to the specified values.

Parameters:

start - Time at which the first release begins (i.e. the realtime thread becomes eligible for execution.) When a RelativeTime, this time is relative to the first time the thread becomes activated (that is, when start() is called). When an AbsoluteTime, then the first release is the maximum of the start parameter and the time of the call to the associated RealtimeThread.start() method (modified according to any phasing policy). When null, the default value is a new instance of RelativeTime(0,0).

period - The period is the interval between successive releases. There is no default value. When period is null an 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 new instance of RelativeTime(period).

overrunHandler - This handler is invoked when an invocation of the schedulable exceeds cost in the given release. Implementations may ignore this parameter. When null, the default value is no overrun handler.

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

rousable - When true, an interrupt will cause an early release, otherwise not.

Throws:

StaticIllegalArgumentException - when the period is null or its time value is not greater than zero, or when the time value of cost is less than zero, or when the time value of deadline is not greater than zero, or when the clock associated with the cost is not the realtime clock, or when the clocks associated with the deadline and period parameters are not the same.

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

Since:

RTSJ 2.0

PeriodicParameters

public PeriodicParameters(HighResolutionTime<?> start,
                          RelativeTime period,
                          RelativeTime cost,
                          RelativeTime deadline,
                          AsyncEventHandler overrunHandler,
                          AsyncEventHandler missHandler)

Equivalent to PeriodicParameters(HighResolutionTime, RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (start, period, cost, deadline, overrunHandler, missHandler, false);

PeriodicParameters

public PeriodicParameters(HighResolutionTime<?> start,
                          RelativeTime period,
                          RelativeTime deadline,
                          AsyncEventHandler missHandler,
                          boolean rousable)

Equivalent to PeriodicParameters(HighResolutionTime, RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (start, period, deadline, null, null, missHandler, rousable);

Since:

RTSJ 2.0

PeriodicParameters

public PeriodicParameters(HighResolutionTime<?> start,
                          RelativeTime period)

Equivalent to PeriodicParameters(HighResolutionTime, RelativeTime, RelativeTime, RelativeTime, AsyncEventHandler, AsyncEventHandler, boolean) with the argument list (start, period, null, null, null, null, false);

Since:

RTSJ 1.0.1

PeriodicParameters

public PeriodicParameters(RelativeTime period)

Creates a PeriodicParameters object with the specified period and all other attributes set to their default values. This constructor has the same effect as invoking PeriodicParameters(null, period, null, null, null, null, false)

Since:

RTSJ 1.0.1

Method Detail

getPeriod

public RelativeTime getPeriod()

Determines the current value of period.

Returns:

the object last used to set the period containing the current value of period.

getPeriod

public RelativeTime getPeriod(RelativeTime value)

Determines the current value of period.

Returns:

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

Since:

RTSJ 2.0

getStart

public HighResolutionTime<?> getStart()

Determines the time used to start an instance of Schedulable, which is not necessarily the time at which it actually started.

Returns:

the object last used to set the start containing the current value of start.

setPeriod

public PeriodicParameters setPeriod(RelativeTime period)

Sets the period.

Parameters:

period - The value to which period is set.

Returns:

this

Throws:

StaticIllegalArgumentException - when the given period is null or its time value is not greater than zero. Also when period is incompatible with the scheduler for any associated schedulable or when an associated AsyncBaseEventHandler is associated with a Timer whose period does not match period.

IllegalAssignmentError - when period cannot be stored in this.

Since:

RTSJ 2.0 returns itself

setStart

public PeriodicParameters setStart(HighResolutionTime<?> start)

Sets the start time.

Changes to the start time in a realtime thread’s PeriodicParameters object only have an effect on its initial release time.

Note that an instance of PeriodicParameters may be shared by several schedulables. A change to the start time may take effect on a subset of these schedulables. That leaves the start time returned by getStart unreliable as a way to determine the start time of a schedulable.

Parameters:

start - The new start time. When null, the default value is a new instance of RelativeTime(0,0).

Returns:

this

Throws:

StaticIllegalArgumentException - when the given start time is incompatible with the scheduler for any of the schedulable objects which are presently using this parameter object.

IllegalAssignmentError - when start cannot be stored in this.

Since:

RTSJ 2.0 returns itself

setIfFeasible

@Deprecated
public boolean setIfFeasible(RelativeTime period,
                                         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 period, cost and deadline attributes as replacements for the matching attributes of this. When the resulting system is feasible the method replaces the current attributes of this. When this parameter object is associated with any schedulable, either by being passed through the schedulable's constructor or set with a method such as RealtimeThread.setReleaseParameters(ReleaseParameters), the parameters of those schedulables are altered as specified by each schedulable's respective scheduler.

Parameters:

period - The proposed period. There is no default value. When period is null an 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 new instance of RelativeTime(period).

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 period is null or its time value is not greater than zero, or when the time value of cost is less than zero, or when the time value of deadline is not greater than zero. Also when the values are incompatible with the scheduler for any of the schedulables which are presently using this parameter object.

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