public abstract class ReleaseParameters<T extends ReleaseParameters<T>>
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
Schedulable.
When a reference to a ReleaseParameters object is given as a
parameter to a constructor of a schedulable, the ReleaseParameters
object becomes bound to the object being created. Changes to the values in
the ReleaseParameters object affect the constructed object. When
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 schedulables using the
object. For instance, invoking setDeadline on a
ReleaseParameters instance will make the change, and then notify
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, the parameter object is
used in setReleaseParameters(), or the object is used in a
constructor for a schedulable.
Release parameters use HighResolutionTime values for cost, and
deadline. Since the times are expressed as HighResolutionTime
values, these values use accurate timers with nanosecond granularity. The
actual precision 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 when 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.
The following table gives the default parameter values for the constructors.
Attribute |
Default Value |
|---|---|
| cost | new RelativeTime(0,0) |
| deadline | no default |
| overrunHandler | None |
| missHandler | None |
| rousable | false |
| initial event queue length | 0 |
Caution: This class is explicitly unsafe for multithreading when being changed. Code that mutates instances of this class should synchronize at a higher level.
| Modifier and Type | Field and Description |
|---|---|
static RelativeTime |
DISABLE_MONITORING
A special value for cost for turning off cost monitoring.
|
| Modifier | Constructor and Description |
|---|---|
protected |
ReleaseParameters()
Equivalent to
ReleaseParameters(RelativeTime, RelativeTime,
AsyncEventHandler, AsyncEventHandler) with the argument list
(null, null, null, null). |
protected |
ReleaseParameters(RelativeTime cost,
RelativeTime deadline,
AsyncEventHandler overrunHandler,
AsyncEventHandler missHandler)
Creates a new instance of
ReleaseParameters with the
given parameter values. |
protected |
ReleaseParameters(RelativeTime cost,
RelativeTime deadline,
AsyncEventHandler overrunHandler,
AsyncEventHandler missHandler,
boolean rousable)
Creates a new instance of
ReleaseParameters with the
given parameter values. |
| Modifier and Type | Method and Description |
|---|---|
java.lang.Object |
clone()
Obtains a clone of
this. |
RelativeTime |
getCost()
Determines the current value of cost.
|
RelativeTime |
getCost(RelativeTime value)
Determines the current value of cost, where
Relative(0,0) means
no cost enforcement in being done and DISABLE_MONITORING means
cost monitoring is disabled as well. |
AsyncEventHandler |
getCostOverrunHandler()
Gets a reference to the cost overrun handler.
|
RelativeTime |
getDeadline()
Determines the current value of deadline.
|
RelativeTime |
getDeadline(RelativeTime value)
Determines the current value of deadline.
|
AsyncEventHandler |
getDeadlineMissHandler()
Gets a reference to the deadline miss handler.
|
QueueOverflowPolicy |
getEventQueueOverflowPolicy()
Gets the behavior of the arrival time queue in the event of
an overflow.
|
int |
getInitialQueueLength()
Gets the initial number of elements the event queue can hold.
|
boolean |
isRousable()
Determines whether or not a thread interrupt will cause instances of
Schedulable associated with an instance of this class
to be prematurely released, i.e., released before the very first release
event happens. |
T |
setCost(RelativeTime cost)
Sets the cost value.
|
T |
setCostOverrunHandler(AsyncEventHandler handler)
Sets the cost overrun handler.
|
T |
setDeadline(RelativeTime deadline)
Sets the deadline value.
|
T |
setDeadlineMissHandler(AsyncEventHandler handler)
Sets the deadline miss handler.
|
T |
setEventQueueOverflowPolicy(QueueOverflowPolicy policy)
Sets the policy for the arrival time queue for when the
insertion of a new element would make the queue size greater than
the initial size given in
this. |
boolean |
setIfFeasible(RelativeTime cost,
RelativeTime deadline)
Deprecated.
as of RTSJ 2.0
|
T |
setInitialQueueLength(int initial)
Sets the initial number of elements the arrival time queue can hold
without lengthening the queue.
|
T |
setRousable(boolean value)
Dictates whether or not a thread interrupt will cause instances of
Schedulable associated with an instance of this class
to be prematurely released, i.e., released before the very first release
event happens. |
public static final RelativeTime DISABLE_MONITORING
Schedulable. What the VM does
with it is system dependent; though, when a cost is so set, the application
cannot rely on any cost tracking that involves said instance.protected ReleaseParameters(RelativeTime cost, RelativeTime deadline, AsyncEventHandler overrunHandler, AsyncEventHandler missHandler, boolean rousable)
ReleaseParameters with the
given parameter values.cost - Processing time units per release. On implementations
which can measure the amount of time an instance of
schedulable is executed, when null, the default
value is a new instance of RelativeTime(0, 0)
meaning that no cost enforcement will take place. Setting
it to DISABLE_MONITORING disables cost monitoring as well.deadline - The latest permissible completion time measured
from the release time of the associated invocation of the
schedulable. There is no default for deadline in this
class. The default must be determined by the subclasses.overrunHandler - This handler is invoked when an invocation of
the schedulable exceeds cost. In the minimum implementation
overrunHandler is ignored. When null, no application event
handler is executed on cost overrun.missHandler - This handler is invoked when the run() method of
the schedulable is still executing after the deadline has
passed. When null, no application
event handler is executed on the miss deadline condition.rousable - When true, an interrupt will cause this
schedulable fire immediately.StaticIllegalArgumentException - when the time value of cost is less
than zero, or the time value of deadline is less than
or equal to zero, or the chronograph associated with the
cost or deadline parameters is not an instance
of Clock.IllegalAssignmentError - when cost, deadline,
overrunHandler, or missHandler cannot be stored in this.
Since RTSJ 2.0protected 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 an instance of
schedulable is executed, when null, the default
value is a new instance of RelativeTime(0, 0)
meaning that no cost enforcement will take place. Setting
it to DISABLE_MONITORING disables cost monitoring as well.deadline - The latest permissible completion time measured
from the release time of the associated invocation of the
schedulable. There is no default for deadline in this
class. The default must be determined by the subclasses.overrunHandler - This handler is invoked when an invocation of
the schedulable exceeds cost. In the minimum implementation
overrunHandler is ignored. When null, no application event
handler is executed on cost overrun.missHandler - This handler is invoked when the run() method of
the schedulable is still executing after the deadline has
passed. When null, no application
event handler is executed on the miss deadline condition.StaticIllegalArgumentException - when the time value of cost is less
than zero, or the time value of deadline is less than
or equal to zero, or the chronograph associated with the
cost or deadline parameters is not an instance
of Clock.IllegalAssignmentError - when cost, deadline,
overrunHandler, or missHandler cannot be stored in this.protected ReleaseParameters()
ReleaseParameters(RelativeTime, RelativeTime,
AsyncEventHandler, AsyncEventHandler) with the argument list
(null, null, null, null).public java.lang.Object clone()
this. This method should behave
effectively as when 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()
RelativeTime(0,0
meaning that no cost enforcement will take place; whereas a value of
DISABLE_MONITORING means cost monitoring is disabled.public RelativeTime getCost(RelativeTime value)
Relative(0,0) means
no cost enforcement in being done and DISABLE_MONITORING means
cost monitoring is disabled as well.value - The parameter in which to return the cost.value or, when null, the last object used
to set the cost, set to the current value of cost.public AsyncEventHandler getCostOverrunHandler()
public RelativeTime getDeadline()
public RelativeTime getDeadline(RelativeTime value)
value - The parameter in which to return the deadline.value or, when null, the last object used
to set the deadline, set to the current value of deadline.public AsyncEventHandler getDeadlineMissHandler()
public T setCost(RelativeTime cost)
When this parameter object is associated with any schedulable
object (by being passed through the schedulable's
constructor or set with a method such as
RealtimeThread.setReleaseParameters(ReleaseParameters)) the
cost of those schedulables takes effect immmediately.
cost - Processing time units 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. On
implementations which cannot measure execution time,
it is not possible to determine when any
particular object exceeds cost. When null, the
default value is a new instance of
RelativeTime(0,0).thisStaticIllegalArgumentException - when the time
value of cost is less than zero, or the clock
associated with the cost parameters is not the
realtime clock.IllegalAssignmentError - when cost cannot be
stored in this.public T setCostOverrunHandler(AsyncEventHandler handler) throws IllegalAssignmentError
When this parameter object is associated with any schedulable
object (by being passed through the schedulable's
constructor or set with a method such as RealtimeThread.setReleaseParameters(ReleaseParameters)) the cost
overrun handler of those schedulables is effective immediately.
handler - This handler is invoked when an invocation of the
schedulable attempts to exceed cost time
units in a release. A null value of
handler signifies that no cost overrun handler
should be used.thisIllegalAssignmentError - when handler cannot be
stored in this.public T setDeadline(RelativeTime deadline)
When this parameter object is associated with any schedulable
object (by being passed through the schedulable's
constructor or set with a method such as
RealtimeThread.setReleaseParameters(ReleaseParameters)) the
deadline of those schedulables take effect at completion.
deadline - The latest permissible completion time measured
from the release time of the associated invocation of the
schedulable. The default value of the deadline must
be controlled by the classes that extend
ReleaseParameters.thisStaticIllegalArgumentException - when deadline is
null, the time value of deadline
is less than or equal to zero, or when the new value of this
deadline is incompatible with the scheduler for any
associated schedulable.IllegalAssignmentError - when deadline cannot be
stored in this.public T setDeadlineMissHandler(AsyncEventHandler handler)
When this parameter object is associated with any schedulable
object (by being passed through the schedulable's
constructor or set with a method such as RealtimeThread.setReleaseParameters(ReleaseParameters)) the
deadline miss handler of those schedulables take effect at completion.
handler - This handler is invoked when any release of the
schedulable fails to complete before the deadline
passes. A null value of
handler signifies that no deadline miss
handler should be used.thisIllegalAssignmentError - when handler cannot be
stored in this.public boolean isRousable()
Schedulable associated with an instance of this class
to be prematurely released, i.e., released before the very first release
event happens. It has no effect for periodic realtime threads, since
the first event of a timing is when start is called. The default value,
i.e., before any call to setRousable(boolean), is false.
Note that the rousable state has no effect on instances of
RealtimeThread which have an instance of
BackgroundParameters for ReleaseParameters or
on ordinary event handlers, i.e., those which do not extend
ActiveEvent. In the former case, there are no releases to
interrupt and, in the case, the handler does not have a
ActiveEventDispatcher to release it.
true when rousable and false when not.public T setRousable(boolean value)
Schedulable associated with an instance of this class
to be prematurely released, i.e., released before the very first release
event happens.value - When rousable, true and false when not.thispublic QueueOverflowPolicy getEventQueueOverflowPolicy()
public T setEventQueueOverflowPolicy(QueueOverflowPolicy policy)
this.policy - A queue overflow policy to use for handlers associated
with this.thispublic int getInitialQueueLength()
SAVE the initial queue length may not be related to the
current queue lengths of schedulables associated
with this parameter object.AperiodicParameters.getInitialArrivalTimeQueueLength().public T setInitialQueueLength(int initial)
initial - The initial length of the queue.thisStaticIllegalArgumentException - when initial is
less than zero.AperiodicParameters.setInitialArrivalTimeQueueLength(int).@Deprecated 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 schedulables will take place under
the control of their schedulers.cost - The proposed cost. Equivalent to
RelativeTime(0,0) when null. (A new
instance of RelativeTime is created in the memory area
containing this ReleaseParameters instance). When
null, the default value is a new instance of
RelativeTime(0,0).deadline - The proposed deadline. There is no default for
deadline in this class. The default must be
determined by the subclasses.true, when the resulting system is feasible and
the changes are made, and
false, when the resulting system is
not feasible and no changes are made.StaticIllegalArgumentException - when the time value of
cost is less than zero, or
the time value of deadline is less than or
equal to zero.IllegalAssignmentError - when cost
or deadline cannot be stored in this.