public class ProcessingConstraint extends ResourceConstraint<ProcessingConstraint>
RealtimeThreadGroup
instance. As with
ThreadGroup
and
RealtimeThreadGroup
, instances of ProcessingConstraint
can be nested. The cost of the group, including all tasks in its subgroups
not subject to another ProcessingConstraint
instance, can be both
tracked and limited over a given period, by bounding the execution demands
of those tasks.
A processing constraint has an associated affinity. The precision of cost
monitoring is dependent on the number of processors in the affinity.
In the worst case, it is the base precision times the number of processors
in the processing group. The default affinity is that which was inherited
from the parent ProcessingConstraint
.
For all tasks with a reference to an instance of
ProcessingConstraint
p
, no more than p.cost
will
be allocated to the execution of these tasks on the processors
associated with its processing group in each interval of time given
by p.period
after the time indicated by p.start
. No
execution of the tasks will be allowed on any processor other than
these processors.
For each running task subject to a processing group, there must always be at least one processor in the intersection between a task object's affinity and its processing group's affinity regardless of the group's monitoring state.
Logically, a ProcessingConstraint
represents a virtual
server. This server has a start time, a period, a cost (budget), and
a deadline equal to period
. The server can only logically
execute when
When the cost has been consumed, any overrunHandler
is
released, and the server is not eligible for logical execution until
the period is finished. At this point, its allocated cost (budget) is
replenished. When the server is logically executable when its deadline
expires, any associated missHandler
is released.
When the server is logically executable when its next release time occurs,
any associated underrunHandler
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
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.
The implementation must use copy semantics for each
HighResolutionTime
parameter value. The value
of each time object should be copied at the time it is passed to the
parameter object, and the object reference must not be retained.
Only changes to a ProcessingConstraint
object
caused by methods on that object are immediately visible to the
scheduler. For instance, invoking setPeriod()
on a
ProcessingConstraint
object will make the change,
then notify 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 affects 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 ProcessingConstraint
object is
invoked or the object is used in a constructor for an SO.
The following table gives the default parameter values for the constructors.
Attribute |
Default Value |
---|---|
period | No default. A value must be supplied |
cost | No default. A value must be supplied |
minimum | null , no minimum |
overrunHandler | None |
missHandler | None |
underrunHandler | 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.
Constructor and Description |
---|
ProcessingConstraint(RealtimeThreadGroup group,
float cost)
Equivalent to
ProcessingConstraint(RealtimeThreadGroup,
float, AsyncEventHandler) with the argument list
(group, cost, null) . |
ProcessingConstraint(RealtimeThreadGroup group,
float cost,
AsyncEventHandler overrun)
Creates a
ProcessingConstraint to govern a group of threads. |
Modifier and Type | Method and Description |
---|---|
RelativeTime |
available()
Gets the time still available to this constraint.
|
RelativeTime |
available(RelativeTime dest)
Gets the time still available to this constraint.
|
static ProcessingConstraint |
currentConstraint()
Determine the processing constraint for the current execution context.
|
static ProcessingConstraint |
currentConstraint(java.lang.Thread thread)
Determine the processing constraint for the give execution context.
|
RelativeTime |
getBudget()
Gets the value of
cost . |
RelativeTime |
getBudget(RelativeTime dest)
Gets the value of
cost in the provided
RelativeTime object. |
AsyncEventHandler |
getCostOverrunHandler()
Gets the cost overrun handler.
|
AbsoluteTime |
getEffectiveStart()
Obtains the actual time of the group's start as recorded by the system.
|
AbsoluteTime |
getEffectiveStart(AbsoluteTime dest)
Obtains the actual time of the group's start as recorded by the system.
|
static RelativeTime |
getGranularity()
Determines the measurement granularity of cost monitoring and cost
enforcement.
|
static RelativeTime |
getGranularity(RelativeTime dest)
Determines the measurement granularity of cost monitoring and cost
enforcement.
|
static RelativeTime |
getPeriod()
Gets the value of
period . |
static RelativeTime |
getPeriod(RelativeTime dest)
Gets the value of
period in the provided
RelativeTime object. |
static ProcessingConstraint |
getRootConstraint()
Get the root instance for this constraint type.
|
boolean |
isEnforcing()
Determine whether or not enforcing is in effect.
|
RelativeTime |
lastUsed()
Gets the total cost used in the last period.
|
RelativeTime |
lastUsed(RelativeTime dest)
Gets the total cost used in the last period.
|
ProcessingConstraint |
setCostOverrunHandler(AsyncEventHandler handler)
Sets the cost overrun handler.
|
static void |
setGranularity(RelativeTime time)
Sets the measurement granularity of cost monitoring and cost
enforcement.
|
static void |
setPeriod(RelativeTime period)
Sets the value of
period . |
void |
start()
Start applying this constraint to is tasks.
|
void |
stop()
Stop applying this constraint to is tasks.
|
RelativeTime |
used()
Gets the cost used in the current period so far.
|
RelativeTime |
used(RelativeTime dest)
Gets the cost used in the current period so far.
|
getNotificationHandler, getRealtimeThreadGroup, governs, governs, governs, setNotificationHandler, visitBorrowers, visitGoverned
public ProcessingConstraint(RealtimeThreadGroup group, float cost, AsyncEventHandler overrun)
ProcessingConstraint
to govern a group of threads.group
- The RealtimeThreadGroup
to govern.cost
- The maximum total execution time of all tasks in the
group as a ratio, where one is a complete CPU core.overrun
- It is called when the the total execution of all tasks in
the group exceeds cost
for a given period
.public ProcessingConstraint(RealtimeThreadGroup group, float cost)
ProcessingConstraint(RealtimeThreadGroup,
float, AsyncEventHandler)
with the argument list
(group, cost, null)
.public static ProcessingConstraint getRootConstraint()
public static ProcessingConstraint currentConstraint()
public static ProcessingConstraint currentConstraint(java.lang.Thread thread)
thread
- The given execution context.public static RelativeTime getPeriod(RelativeTime dest)
period
in the provided
RelativeTime
object.dest
- An instance of RelativeTime
which will be set
to the currently configured period
. If dest
is
null, a new RelativeTime
will be created in the current
allocation context.dest
, or a newly created object if
dest
is null.public static RelativeTime getPeriod()
period
.
Equivalent to getPeriod(null)
.
RelativeTime
that represents the
value of period
.public static void setPeriod(RelativeTime period) throws StaticIllegalArgumentException, IllegalAssignmentError
period
.period
- The new value for period
. There is no
default value. When period
is null
an exception is thrown.StaticIllegalArgumentException
- when period
is
null
, or its time value is not greater than zero.IllegalAssignmentError
public static RelativeTime getGranularity()
setGranularity(javax.realtime.RelativeTime)
public static RelativeTime getGranularity(RelativeTime dest)
dest
- An instance of RelativeTime
which will be set
to the currently configured granularity. If dest
is
null, a new RelativeTime
will be created in the current
allocation context.setGranularity(javax.realtime.RelativeTime)
public static void setGranularity(RelativeTime time) throws StaticIllegalArgumentException
nanos
is below this lower bound, granularity silently is
set to the lower bound. In general, the lower bound is the
precision of the realtime clock.
Note that the ganularity applies to a single processor. When a processing group spans more than one processor, the precision of cost monitoring or enforcement is this ganularity times the number of active processors. This is because more than one task could be running at the same time and cost can be measured at most once per the elapse of this ganularity.
time
- the new granularityStaticIllegalArgumentException
- when nanos
is less
than one.public boolean isEnforcing()
isEnforcing
in class ResourceConstraint<ProcessingConstraint>
true
when yes and false
when not.public void start()
start
in class ResourceConstraint<ProcessingConstraint>
public void stop()
stop
in class ResourceConstraint<ProcessingConstraint>
public AbsoluteTime getEffectiveStart(AbsoluteTime dest)
dest
- A time value to fill.AbsoluteTime
, when
dest
is null
, or dest
otherwise.
In either case, its value is the time at which this group
actually started.public AbsoluteTime getEffectiveStart()
Equivalent to getEffectiveStart(AbsoluteTime)
where dest
is set to null
.
AbsoluteTime
that represents the time at which this group started.public RelativeTime getBudget()
cost
.
Equivalent to getMaximumCost(null)
.
cost
.public RelativeTime getBudget(RelativeTime dest)
cost
in the provided
RelativeTime
object.dest
- An instance of RelativeTime
which will be set
to the currently configured cost
. If dest
is
null, a new RelativeTime
will be created in the current
allocation context.dest
, or a newly created object if
dest
is null.public RelativeTime used()
public RelativeTime used(RelativeTime dest)
dest
- The instance to use for returning the time. If
dest
is null, the result will be returned in a newly
allocated object.dest
containing the cost of the current periodpublic RelativeTime available()
public RelativeTime available(RelativeTime dest)
dest
- It is the instance to use for returning the time. If
dest
is null, the result will be returned in a newly
allocated object.dest
containing the available cost.public RelativeTime lastUsed()
public RelativeTime lastUsed(RelativeTime dest)
dest
- It is the instance to use for returning the time. If
dest
is null, the result will be returned in a newly
allocated object.dest
containing the cost of the last periodpublic AsyncEventHandler getCostOverrunHandler()
AsyncEventHandler
that
is cost overrun handler of this
.public ProcessingConstraint setCostOverrunHandler(AsyncEventHandler handler) throws IllegalAssignmentError
handler
- This handler is invoked when the run()
method of the schedulables attempts to
execute for more than cost
time units in any
period. When null
, no handler is attached, and
any previous handler is removed.this
IllegalAssignmentError
- when handler
cannot be stored in this
.