javax.realtime.ReleaseParameters
java.lang.Object
public abstract class ReleaseParameters
The top-level class for release characteristics of schedulable
objects.
When a reference to a ReleaseParameters object is given
as a parameter to a constructor, the ReleaseParameters object becomes bound
to the object being created. Changes to the values in the ReleaseParameters
object affect the constructed object. If given to more than one constructor,
then changes to the values in the ReleaseParameters object affect all
of the associated objects. Note that this is a one-to-many relationship and
not a many-to-many.
Only changes to an ReleaseParameters object caused by methods
on that object cause the change to propagate to all schedulable objects using the
object. For instance, invoking setDeadline
on a ReleaseParameters instance
will make the change, and then notify that the scheduler that the object has been
changed. At that point the object is reconsidered for every SO that uses it.
Invoking a method on the RelativeTime object that is the deadline for this
object may change the time value but it does not pass the new time value to the
scheduler at that
time. Even though the changed time value is referenced by
ReleaseParameters objects, it will not change the behavior of
the SOs that use the parameter
object until a setter method on the ReleaseParameters object is invoked,
or the parameter object is used in setReleaseParameters()
or a constructor for an SO.
Release parameters use HighResolutionTime values for
cost, and deadline. Since the
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 ReleaseParameters instance unless they are
passed to the parameter object again, e.g. with a new invocation of setCost.
Attribute |
Default Value |
|---|---|
| cost | new RelativeTime(0,0) |
| deadline | no default |
| overrunHandler | None |
| missHandler | None |
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.
Note: Cost measurement and enforcement is an optional facility for implementations of the RTSJ.
| Constructor Summary | |
|---|---|
protected |
ReleaseParameters()
Create a new instance of ReleaseParameters. |
protected |
ReleaseParameters(RelativeTime cost,
RelativeTime deadline,
AsyncEventHandler overrunHandler,
AsyncEventHandler missHandler)
Create a new instance of ReleaseParameters with the given parameter values. |
| Method Summary | |
|---|---|
java.lang.Object |
clone()
Return a clone of this. |
RelativeTime |
getCost()
Gets a reference to the cost. |
AsyncEventHandler |
getCostOverrunHandler()
Gets a reference to the cost overrun handler. |
RelativeTime |
getDeadline()
Gets a reference to the deadline. |
AsyncEventHandler |
getDeadlineMissHandler()
Gets a reference to the deadline miss handler. |
void |
setCost(RelativeTime cost)
Sets the cost value. |
void |
setCostOverrunHandler(AsyncEventHandler handler)
Sets the cost overrun handler. |
void |
setDeadline(RelativeTime deadline)
Sets the deadline value. |
void |
setDeadlineMissHandler(AsyncEventHandler handler)
Sets the deadline miss handler. |
boolean |
setIfFeasible(RelativeTime cost,
RelativeTime deadline)
This method first performs a feasibility analysis using the new cost, and deadline as replacements for the matching attributes of all schedulable objects associated with this release parameters object. |
| Methods inherited from class java.lang.Object |
|---|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
protected ReleaseParameters()
ReleaseParameters. This constructor creates a default
ReleaseParameters object, i.e., it is
equivalent to ReleaseParameters(null, null, null, null).
protected ReleaseParameters(RelativeTime cost,
RelativeTime deadline,
AsyncEventHandler overrunHandler,
AsyncEventHandler missHandler)
ReleaseParameters with the given parameter values.
cost - Processing time units per release.
On implementations which can measure the amount of time
a schedulable object is executed, this value is the maximum amount of time
a schedulable object receives per release.
On implementations which cannot measure execution time, this value is used
as a hint to the feasibility algorithm. On such systems it is not possible
to determine when any particular object exceeds cost.
If 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 object.
There is no default for deadline in this class.
The default must be determined
by the subclasses.overrunHandler - This handler is invoked if an invocation of the schedulable
object exceeds cost. In the minimum implementation overrunHandler
is ignored.
If null, no application event handler is executed on cost overrun.missHandler - This handler is invoked if the run() method of the schedulable
object is still executing after the deadline has passed.
Although minimum implementations do not consider deadlines in
feasibility calculations, they must recognize variable deadlines
and invoke the miss handler as appropriate.
If null, no application event handler is executed
on the miss deadline condition.
java.lang.IllegalArgumentException - Thrown if the time value of
cost is less than zero, or
the time value of deadline is less than or
equal to zero.
IllegalAssignmentError - Thrown if cost,
deadline, overrunHandler, or
missHandler cannot be stored in this.RealtimeThread.waitForNextPeriod()| 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.
clone in class java.lang.Objectpublic RelativeTime getCost()
cost.
cost.public AsyncEventHandler getCostOverrunHandler()
public RelativeTime getDeadline()
deadline.
deadline.public AsyncEventHandler getDeadlineMissHandler()
public void setCost(RelativeTime cost)
If this parameter object is associated with
any schedulable object (by being passed through the
schedulable object's constructor or set
with a method such as
RealtimeThread.setReleaseParameters(ReleaseParameters))
the cost of those schedulable objects is altered as specified by
each schedulable object's respective scheduler.
cost - Processing time units per release.
On implementations which can measure the amount of time
a schedulable object is executed, this value is the maximum amount of time
a schedulable object receives per release.
On implementations which cannot measure execution time, this value is used
as a hint to the feasibility algorithm. On such systems it is not possible
to determine when any particular object exceeds cost.
If null,
the default value is a new instance of RelativeTime(0,0).
java.lang.IllegalArgumentException - Thrown if the time
value of cost is less than zero.
IllegalAssignmentError - Thrown if cost cannot be stored in this.public void setCostOverrunHandler(AsyncEventHandler handler)
If this parameter object is associated with
any schedulable object (by being passed through the
schedulable object's constructor or set
with a method such as
RealtimeThread.setReleaseParameters(ReleaseParameters))
the cost overrun handler of those schedulable objects is altered as specified by
each schedulable object's respective scheduler.
handler - This handler is invoked if an invocation of the schedulable
object attempts to exceed cost time units in a release.
A null value of handler signifies that no cost overrun
handler should be used.
IllegalAssignmentError - Thrown if handler cannot be stored in this.public void setDeadline(RelativeTime deadline)
If this parameter object is associated with
any schedulable object (by being passed through the
schedulable object's constructor or set
with a method such as
RealtimeThread.setReleaseParameters(ReleaseParameters))
the deadline of those schedulable objects is altered as specified by
each schedulable object's respective scheduler.
deadline - The latest permissible completion time measured from the
release time of the associated invocation of the schedulable object.
The default value of the deadline must be controlled by
the classes that extend ReleaseParameters.
java.lang.IllegalArgumentException - Thrown if deadline is null,
the time value of deadline is less than or equal
to zero, or if the new value of this deadline is incompatible
with the scheduler for any associated schedulable object.
IllegalAssignmentError - Thrown if deadline cannot be stored in this.public void setDeadlineMissHandler(AsyncEventHandler handler)
If this parameter object is associated with
any schedulable object (by being passed through the
schedulable object's constructor or set
with a method such as
RealtimeThread.setReleaseParameters(ReleaseParameters))
the deadline miss handler of those schedulable objects is altered as specified by
each schedulable object's respective scheduler.
handler - This handler is invoked if any release of the
schedulable object fails to complete before the deadline passes.
Although minimum implementations do not consider deadlines in
feasibility calculations, they must recognize variable deadlines
and invoke the miss handler as appropriate.
A null value of handler signifies that no deadline miss
handler should be used.
IllegalAssignmentError - Thrown if handler cannot be stored in this.
public boolean setIfFeasible(RelativeTime cost,
RelativeTime deadline)
this
release parameters object with the new
scheduling characteristics. The change in the release characteristics,
including the timing of the change,
of any associated schedulable objects will take place under the control
of their schedulers.
cost - The proposed cost. Equivalent to
RelativeTime(0,0) if null. (A new instance of
RelativeTime is created in the memory area containing
this ReleaseParameters instance).
If null,
the default value is a new instance of RelativeTime(0,0).deadline - The proposed deadline.
If null,
the default value is new instance of RelativeTime(period).
java.lang.IllegalArgumentException - Thrown if the time value of
cost is less than zero, or
the time value of deadline is less than or
equal to zero.
IllegalAssignmentError - Thrown if cost
or deadline cannot be stored in this.