java.lang.Object javax.realtime.ProcessingGroupParameters
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 |
public ProcessingGroupParameters(HighResolutionTime start, RelativeTime period, RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler)
ProcessingGroupParameters
object.
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.
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 |
public java.lang.Object clone()
this
. This method should behave effectively as if
it constructed a new object with clones of the high-resolution time values of this
.
clone
does not copy any associations from this
and it does not
implicitly bind the new object to a SO.
public RelativeTime getCost()
cost
.
cost
.public AsyncEventHandler getCostOverrunHandler()
AsyncEventHandler
that is cost overrun handler of this
.public RelativeTime getDeadline()
deadline
.
RelativeTime
that is the deadline of this
.public AsyncEventHandler getDeadlineMissHandler()
AsyncEventHandler
that is deadline miss handler of this
.public RelativeTime getPeriod()
period
.
RelativeTime
that represents the value of period
.public HighResolutionTime getStart()
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.
HighResolutionTime
that represents the value of start
.public void setCost(RelativeTime cost)
cost
.
cost
- The new value for cost
.
If null,
an exception is thrown.
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
.public void setCostOverrunHandler(AsyncEventHandler handler)
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.
IllegalAssignmentError
- Thrown if
handler
cannot be stored in this
.public void setDeadline(RelativeTime deadline)
deadline
.
deadline
- The new value for deadline
.
If null,
the default value is new instance of RelativeTime(period).
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
.public void setDeadlineMissHandler(AsyncEventHandler handler)
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.
IllegalAssignmentError
- Thrown if
handler
cannot be stored in this
.public boolean setIfFeasible(RelativeTime period, RelativeTime cost, RelativeTime deadline)
this
. If the
resulting system is feasible the method replaces
the current attributes of this with the new attributes.
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).
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
.public void setPeriod(RelativeTime period)
period
.
period
- The new value for period
.
There is no default value. If period
is null
an exception is thrown.
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
.public void setStart(HighResolutionTime start)
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.
start
- The new value for start
.
If null,
the default value is a new instance of RelativeTime(0,0)
.
IllegalAssignmentError
- Thrown if
start
cannot be stored in this
.
java.lang.IllegalArgumentException
- Thrown if start
is a relative time value and
less than zero.