javax.realtime
Class ProcessingGroupParameters

java.lang.Object
  javax.realtime.ProcessingGroupParameters

All Implemented Interfaces:

java.lang.Cloneable

public class ProcessingGroupParameters
extends java.lang.Object
implements java.lang.Cloneable

This is associated with one or more schedulable objects for which the system guarantees that the associated objects will not be given more time per period than indicated by cost. On implementations which do not support processing group parameters, this class may be used as a hint to the feasibility algorithm. The motivation for this class is to allow the execution demands of one or more aperiodic schedulable objects to be bound so that they can be included in feasibility analysis. However, periodic or sporadic schedulable objects can also be associated with a processing group.

For all schedulable objects with a reference to an instance of ProcessingGroupParameters p no more than p.cost will be allocated to the execution of these schedulable objects in each interval of time given by p.period after the time indicated by p.start. Logically a virtual server is associated with each instance of ProcessingGroupParameters. This server has a start time, a period, a cost (budget) and a deadline. The server can only logically execute when (a) it has not consumed more execution time in its current release than the cost (budget) parameter, (b) one of its associated schedulable objects is executable and is the most eligible of the executable schedulable objects. If the server is logically executable, the associated schedulable object is executed. When the cost has been consumed, any overrunHandler is released, and the server is not eligible for logical execution until its next period is due. At this point, its allocated cost (budget) is replenished. If the server is logically executing when its deadline expires, any associated missHandler is released. The deadline and cost parameters of all the associated schedulable objects have the same impact as they would if the objects were not bound to a processing group.

Processing group parameters use HighResolutionTime values for cost, deadline, period and start time. Since those times are expressed as a HighResolutionTime, the values use accurate timers with nanosecond granularity. The actual resolution available and even the quantity it measures depends on the clock associated with each time value.

When a reference to a ProcessingGroupParameters 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 ProcessingGroupParameters object becomes the processing group parameters object bound to that schedulable object. Changes to the values in the ProcessingGroupParameters object affect that schedulable object. If bound to more than one schedulable object then changes to the values in the ProcessingGroupParameters 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 if 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 ProcessingGroupParameters object caused by methods on that object are immediately visible to the scheduler. For instance, invoking setPeriod() on a ProcessingGroupParameters object will make the change, then notify that the scheduler that the parameter object has changed. At that point the scheduler's view of the processing group parameters object is updated. Invoking a method on the RelativeTime object that is the period for this object may change the period but it does not pass the change to the scheduler at that time. That new value for period must not change the behavior of the SOs that use the parameter object until a setter method on the ProcessingGroupParameters object is invoked, or the parameter object is used in setProcessingGroupParameters() or a constructor for an SO.

The implementation may use copy semantics for each HighResolutionTime parameter value. For instance the value returned by getCost() must be equal to the value passed in by setCost, but it need not be the same object.

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.

Caution: The cost parameter time should be considered to be measured against the target platform.

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

Constructor Summary

ProcessingGroupParameters(HighResolutionTime start, RelativeTime period, RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler)
Create a ProcessingGroupParameters object.

Method Summary

java.lang.Object	clone() Return a clone of this.
RelativeTime	getCost() Gets the value of cost.
AsyncEventHandler	getCostOverrunHandler() Gets the cost overrun handler.
RelativeTime	getDeadline() Gets the value of deadline.
AsyncEventHandler	getDeadlineMissHandler() Gets the deadline miss handler.
RelativeTime	getPeriod() Gets the value of period.
HighResolutionTime	getStart() Gets the value of start.
void	setCost(RelativeTime cost) Sets the value of cost.
void	setCostOverrunHandler(AsyncEventHandler handler) Sets the cost overrun handler.
void	setDeadline(RelativeTime deadline) Sets the value of deadline.
void	setDeadlineMissHandler(AsyncEventHandler handler) Sets the deadline miss handler.
boolean	setIfFeasible(RelativeTime period, RelativeTime cost, RelativeTime deadline) This method first performs a feasibility analysis using the period, cost and deadline attributes as replacements for the matching attributes this.
void	setPeriod(RelativeTime period) Sets the value of period.
void	setStart(HighResolutionTime start) Sets the value of start.

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessingGroupParameters

public ProcessingGroupParameters(HighResolutionTime start,
                                 RelativeTime period,
                                 RelativeTime cost,
                                 RelativeTime deadline,
                                 AsyncEventHandler overrunHandler,
                                 AsyncEventHandler missHandler)

Create a ProcessingGroupParameters object.

Parameters:

start - Time at which the first period begins. If a RelativeTime, this time is relative to the creation of this. If an AbsoluteTime, then the first release of the logical server is at the start time (or immediately if the absolute time is in the past). If null, the default value is a new instance of RelativeTime(0,0).

period - The period is the interval between successive replenishment of the logical server's associated cost budget. There is no default value. If period is null an exception is thrown.

cost - Processing time per period. The budget CPU time that the logical server can consume each period. If null, an exception is thrown.

deadline - The latest permissible completion time measured from the start of the current period. Changing the deadline might not take effect after the expiration of the current deadline. Specifying a deadline less than the period constrains execution of all the members of the group to the beginning of each period. If null, the default value is new instance of RelativeTime(period).

overrunHandler - This handler is invoked if any schedulable object member of this processing group attempts to use processor time beyond the group's budget. If null, no application async event handler is fired on the overrun condition.

missHandler - This handler is invoked if the logical server is still executing after the deadline has passed. If null, no application async event handler is fired on the deadline miss condition.

Throws:

java.lang.IllegalArgumentException - Thrown if the period is null or its time value is not greater than zero, if cost is null, or if the time value of cost is less than zero, if start is an instance of RelativeTime and its value is negative, or if the time value of deadline is not greater than zero and less than or equal to the period. If the implementation does not support processing group deadline less than period, deadline less than period will cause IllegalArgumentException to be thrown.

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

Method Detail

clone

public java.lang.Object clone()

Return a clone of this. This method should behave effectively as if it constructed a new object with clones of the high-resolution time values of this.

• The new object is in the current allocation context.
• clone does not copy any associations from this and it does not implicitly bind the new object to a SO.
• The new object has clones of all high-resolution time values (deep copy).
• References to event handlers are copied (shallow copy.)

Overrides:

clone in class java.lang.Object

Since:

1.0.1

getCost

public RelativeTime getCost()

Gets the value of cost.

Returns:

a reference to the value of cost.

getCostOverrunHandler

public AsyncEventHandler getCostOverrunHandler()

Gets the cost overrun handler.

Returns:

A reference to an instance of AsyncEventHandlerthat is cost overrun handler of this.

getDeadline

public RelativeTime getDeadline()

Gets the value of deadline.

Returns:

A reference to an instance of RelativeTime that is the deadline of this.

getDeadlineMissHandler

public AsyncEventHandler getDeadlineMissHandler()

Gets the deadline miss handler.

Returns:

A reference to an instance of AsyncEventHandlerthat is deadline miss handler of this.

getPeriod

public RelativeTime getPeriod()

Gets the value of period.

Returns:

A reference to an instance of RelativeTime that represents the value of period.

getStart

public HighResolutionTime getStart()

Gets the value of start. This is the value that was specified in the constructor or by setStart(), not the actual absolute time the corresponding to the start of the processing group.

Returns:

A reference to an instance of HighResolutionTime that represents the value of start.

setCost

public void setCost(RelativeTime cost)

Sets the value of cost.

Parameters:

cost - The new value for cost. If null, an exception is thrown.

Throws:

java.lang.IllegalArgumentException - Thrown if cost is null or its time value is less than zero.

IllegalAssignmentError - Thrown if cost cannot be stored in this.

setCostOverrunHandler

public void setCostOverrunHandler(AsyncEventHandler handler)

Sets the cost overrun handler.

Parameters:

handler - This handler is invoked if the run() method of and of the the schedulable objects attempt to execute for more than cost time units in any period. If null, no handler is attached, and any previous handler is removed.

Throws:

IllegalAssignmentError - Thrown if handler cannot be stored in this.

setDeadline

public void setDeadline(RelativeTime deadline)

Sets the value of deadline.

Parameters:

deadline - The new value for deadline. If null, the default value is new instance of RelativeTime(period).

Throws:

java.lang.IllegalArgumentException - Thrown if deadline has a value less than zero or greater than the period. Unless the implementation supports deadline less than period in processing groups, IllegalArgumentException is also thrown if deadline is less than the period.

IllegalAssignmentError - Thrown if deadline cannot be stored in this.

setDeadlineMissHandler

public void setDeadlineMissHandler(AsyncEventHandler handler)

Sets the deadline miss handler.

Parameters:

handler - This handler is invoked if the run() method of any of the schedulable objects still expect to execute after the deadline has passed. If null, no handler is attached, and any previous handler is removed.

Throws:

IllegalAssignmentError - Thrown if handler cannot be stored in this.

setIfFeasible

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

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

Parameters:

period - The proposed period. There is no default value. If period is null an exception is thrown.

cost - The proposed cost. If null, an exception is thrown.

deadline - The proposed deadline. If null, the default value is new instance of RelativeTime(period).

Returns:

True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.

Throws:

java.lang.IllegalArgumentException - Thrown if the period is null or its time value is not greater than zero, or if the time value of cost is less than zero, or if the time value of deadline is not greater than zero.

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

setPeriod

public void setPeriod(RelativeTime period)

Sets the value of period.

Parameters:

period - The new value for period. There is no default value. If period is null an exception is thrown.

Throws:

java.lang.IllegalArgumentException - Thrown if period is null, or its time value is not greater than zero. If the implementation does not support processing group deadline less than period, and period is not equal to the current value of the processing group's deadline, the deadline is set to a clone of period created in the same memory area as period.

IllegalAssignmentError - Thrown if period cannot be stored in this.

setStart

public void setStart(HighResolutionTime start)

Sets the value of start. If the processing group is already started this method alters the value of this object's start time property, but has no other effect.

Parameters:

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

Throws:

IllegalAssignmentError - Thrown if start cannot be stored in this.

java.lang.IllegalArgumentException - Thrown if start is a relative time value and less than zero.