javax.realtime

Class PeriodicParameters

java.lang.Object

javax.realtime.ReleaseParameters<PeriodicParameters>

javax.realtime.PeriodicParameters

All Implemented Interfaces:

Serializable, Cloneable

public class PeriodicParameters
extends ReleaseParameters<PeriodicParameters>
implements Cloneable

Jamaica Real-Time Specification for Java class PeriodicParameters.

This class characterizes the release of schedulable objects that are released regularly at constant intervals. Used as release parameters for a RealtimeThread, this enables the thread to wait for the next release by a call to RealtimeThread.waitForNextRelease(). Used as release parameters for an AsyncBaseEventHandler, this indicates that this handler is released by events that occur periodically such as a PeriodicTimer. Note that for an AsyncBaseEventHandler, the periodic release is not enforced automatically by the scheduler, the release parameters are only used for feasibility analysis in this case.

Note that any changes to RelativeTime or HighResolutionTime arguments of this object do not propagate to the schedulable object until the corresponding setter method of AperiodicParameters is called to notify this object about the change.

NOTE: the methods in this class are not synchronized. They cannot be used by several threads simultaneously without proper explicit synchronization.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
PeriodicParameters(HighResolutionTime<?> start, RelativeTime period) Create a PeriodicParameters object.
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) Constructor to create an instance of PeriodicParameters with the given initial settings.
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) Create a PeriodicParameters object.

Method Summary

Modifier and Type	Method and Description
Object	clone() clone creates a clone of this object with the same parameters but without association to any schedulable object.
RelativeTime	getPeriod() getPeriod returns the current period.
HighResolutionTime<?>	getStart() getStart returns the start time.
boolean	setIfFeasible(RelativeTime period, RelativeTime cost, RelativeTime deadline) setIfFeasible performs a feasibility analysis using the new period, cost, and deadline parameters.
PeriodicParameters	setPeriod(RelativeTime period) setPeriod sets the period.
PeriodicParameters	setStart(HighResolutionTime<?> start) setStart set the start time.

Methods inherited from class javax.realtime.ReleaseParameters

getCost, getCostOverrunHandler, getDeadline, getDeadlineMissHandler, getEventQueueOverflowPolicy, isRousable, setCost, setCostOverrunHandler, setDeadline, setDeadlineMissHandler, setIfFeasible, 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)

Create a PeriodicParameters object. This constructor has the same effect as invoking PeriodicParameters(start, period, null, null, null, null).

Throws:

StaticIllegalArgumentException - if start is a negative RelativeTime, if the period is null or negative or zero, if cost is negative or deadline is negative or zero.

Parameters:

start - The time of the first release. If start is an instance of RelativeTime, its value will be used as the release time of the associated thread relative to the time the start() method of the thread was called. If an instance of class AbsoluteTime is passed, the associated thread will be released either at the time start() is called or at the time corresponding to the start parameter, whichever comes later. If null, the default value will be new RelativeTime(0, 0).

period - The time between two periodic releases, in other words, the time interval between the return of two successive calls to interval between the return of two successive calls to waitForNextRelease() or waitForNextReleaseInterruptible(). This argument must not be null or a time <= 0.

PeriodicParameters

public PeriodicParameters(RelativeTime period)

Create a PeriodicParameters object. This constructor has the same effect as invoking PeriodicParameters(null, period, null, null, null, null).

Throws:

StaticIllegalArgumentException - if start is a negative RelativeTime, if the period is null or negative or zero, if cost is negative or deadline is negative or zero.

Parameters:

period - The time between two periodic releases, in other words, the time interval between the return of two successive calls to waitForNextRelease() or waitForNextReleaseInterruptible(). This argument must not be null or a time <= 0.

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,
                          RelativeTime cost,
                          RelativeTime deadline,
                          AsyncEventHandler overrunHandler,
                          AsyncEventHandler missHandler)

Constructor to create an instance of PeriodicParameters with the given initial settings.

Throws:

StaticIllegalArgumentException - if start is a negative RelativeTime, if the period is null or negative or zero, if cost is negative or deadline is negative or zero.

Parameters:

start - The time of the first release. If start is an instance of RelativeTime, its value will be used as the release time of the associated thread relative to the time the start() method of the thread was called. If an instance of class AbsoluteTime is passed, the associated thread will be released either at the time start() is called or at the time corresponding to the start parameter, whichever comes later. If null, the default value will be new RelativeTime(0, 0).

period - The time between two periodic releases, in other words, the time interval between the return of two successive calls to waitForNextRelease or waitForNextReleaseInterruptible. This argument must not be null or a time <= 0.

cost - The CPU time required for each release. If cost monitoring is performed, this gives the maximum amount of CPU time that will be allowed for each release. In any case, this may be used by the feasibility analysis. If null, the default value will be new RelativeTime(0, 0). Note that on a system with cost monitoring, this default value will allow no execution time for the associated schedulable object.

deadline - The deadline for the completion of one release, relative to the release time of that release. If null, the default value is a new instance of RelativeTime(period).

overrunHandler - This handler will be invoked if the cost of one invocation exceeds the cost parameter. If null, there will be no overrunHandler.

For JamaicaVM, cost overrun checking is enabled if CpuTime.CPU_TIME_SUPPORTED is true. The accuracy of the cost enforcement can be specified in nanoseconds via the property jamaica.cost_monitoring_accuracy. The default value is 5000000, i.e., 5milliseconds.

missHandler - This handler will be invoked if the deadline of one release is missed. If null, there will be no deadline miss handler.

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.

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.

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.

Since:

RTSJ 2.0

Method Detail

setIfFeasible

public boolean setIfFeasible(RelativeTime period,
                             RelativeTime cost,
                             RelativeTime deadline)

setIfFeasible performs a feasibility analysis using the new period, cost, and deadline parameters. If the resulting system remains feasible, the period, cost, and deadline will be set to the new values. This will change the corresponding attributes of all schedulable objects this is associated with.

Throws:

StaticIllegalArgumentException - if the period is null or negative or zero, if cost is negative or deadline is negative or zero.

Parameters:

period - The time between two periodic releases, in other words, the time interval between the return of two successive calls to waitForNextRelease or waitForNextReleaseInterruptible. This argument must not be null or a time <= 0.

cost - The CPU time required for each release. If cost monitoring is performed, this gives the maximum amount of CPU time that will be allowed for each release. In any case, this may be used by the feasibility analysis. If null, the default value will be new RelativeTime(0, 0). Note that on a system with cost monitoring, this default value will allow no execution time for the associated schedulable object.

deadline - The deadline for the completion of one release, relative to the release time of that release. If null, the default value is a new instance of RealtiveTime(Long.MAX_VALUE, 999999).

Returns:

true if the change was performed and the resulting system is feasible. false if the change would result in an infeasible system and hence was not performed.

getStart

public HighResolutionTime<?> getStart()

getStart returns the start time.

Returns:

the start time. Note that this is not necessarily the same HighResolutionTime object that was provided to the constructor or to setStart(), but it will represent the same value.

setStart

public PeriodicParameters setStart(HighResolutionTime<?> start)

setStart set the start time.

Throws:

StaticIllegalArgumentException - if start is a negative RelativeTime.

Parameters:

start - The time of the first release. If start is an instance of RelativeTime, its value will be used as the release time of the associated thread relative to the time the start() method of the thread will be called If an instance of class AbsoluteTime is passed, the associated thread will be released either at the time start() is called or at the time corresponding to the start parameter, whichever comes later. If null, the default value will be new RelativeTime(0, 0).

Since:

RTSJ 2.0 returns itself

getPeriod

public RelativeTime getPeriod()

getPeriod returns the current period.

Returns:

the period. Note that this is not necessarily the same RelativeTime object that was provided to the constructor or to setPeriod(), but it will represent the same value.

setPeriod

public PeriodicParameters setPeriod(RelativeTime period)

setPeriod sets the period.

Throws:

StaticIllegalArgumentException - if the period is null or negative or zero.

Parameters:

period - The time between two periodic releases, in other words, the time interval between the return of two successive calls to waitForNextRelease or waitForNextReleaseInterruptible. This argument must not be null or a time <= 0.

Since:

RTSJ 2.0 returns itself

clone

public Object clone()

clone creates a clone of this object with the same parameters but without association to any schedulable object. According to RTSJ 1.0.2, the cost, deadline, start, and period attributes are deep-copied, whereas the missHandler and overrunHandler attributes are only shallow-copied.

Overrides:

clone in class ReleaseParameters<PeriodicParameters>

Returns:

a new instance of PeriodicParameters with equal cost, deadline, start, and period attributes and copied references of the overrunHandler and missHandler attributes.

Since:

RTSJ V1.0.1

See Also:

Cloneable