javax.realtime.enforce

Class ProcessingConstraint

java.lang.Object

javax.realtime.enforce.ResourceConstraint<ProcessingConstraint>

javax.realtime.enforce.ProcessingConstraint

public class ProcessingConstraint
extends ResourceConstraint<ProcessingConstraint>

A class for handling contraining CPU used by tasks as a group via their 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

• (a) it has not consumed more execution time in its current release than the cost (budget) parameter,
• (b) one of its associated tasks is executable and is the most eligible of the executable tasks.

When the server is logically executable, the associated tasks are executed.

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.

ProcessingConstraint Default Values

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.

Since:

RTSJ 2.0

Constructor Summary

Constructors

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 for a given group of threads.

Method Summary

Modifier and Type	Method and Description
RelativeTime	available() Gets the time remaining in the current period.
RelativeTime	available(RelativeTime dest) Gets the time remaining in the current period so far.
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.
static ProcessingConstraint	currentConstraint(java.lang.ThreadGroup group) Determine the processing constraint for the give execution context.
protected void	finalize()
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	getCurrentReleaseTime(AbsoluteTime dest)
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.
AbsoluteTime	getLastRelease()
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.
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 time used in the current period so far.

Methods inherited from class javax.realtime.enforce.ResourceConstraint

getNotificationHandler, getParent, getRealtimeThreadGroup, governs, governs, governs, isEnforcing, setNotificationHandler, visitBorrowers, visitGoverned

Methods inherited from class java.lang.Object

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

Constructor Detail

ProcessingConstraint

public ProcessingConstraint(RealtimeThreadGroup group,
                            float cost,
                            AsyncEventHandler overrun)

Creates a ProcessingConstraint for a given group of threads.

Parameters:

group - The RealtimeThreadGroup to govern.

cost - The maximum total execution time of all tasks in the group during a given period.

overrun - It is called when the the total execution of all tasks in the group exceeds cost for a given period.

ProcessingConstraint

public ProcessingConstraint(RealtimeThreadGroup group,
                            float cost)

Equivalent to ProcessingConstraint(RealtimeThreadGroup, float, AsyncEventHandler) with the argument list (group, cost, null).

Method Detail

getRootConstraint

public static ProcessingConstraint getRootConstraint()

Get the root instance for this constraint type.

Returns:

the root constraint.

currentConstraint

public static ProcessingConstraint currentConstraint()

Determine the processing constraint for the current execution context.

Returns:

the constraint for this context.

currentConstraint

public static ProcessingConstraint currentConstraint(java.lang.Thread thread)

Determine the processing constraint for the give execution context.

Parameters:

thread - The given execution context.

Returns:

the constraint for this context.

currentConstraint

public static ProcessingConstraint currentConstraint(java.lang.ThreadGroup group)

Determine the processing constraint for the give execution context.

Parameters:

group - The given execution context.

Returns:

the constraint for this context.

getPeriod

public static RelativeTime getPeriod()

Gets the value of period.

Equivalent to getPeriod(null).

Returns:

a reference to a newly allocated instance of RelativeTime that represents the value of period.

getPeriod

public static RelativeTime getPeriod(RelativeTime dest)

Gets the value of period in the provided RelativeTime object.

Parameters:

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.

Returns:

a reference to dest, or a newly created object if dest is null.

setPeriod

public static void setPeriod(RelativeTime period)
                      throws StaticIllegalArgumentException,
                             IllegalAssignmentError

Sets the value of period.

Parameters:

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

Throws:

StaticIllegalArgumentException - when period is null, or its time value is not greater than zero.

IllegalAssignmentError

getGranularity

public static RelativeTime getGranularity()

Determines the measurement granularity of cost monitoring and cost enforcement.

Returns:

the current granularity in a new object.

See Also:

setGranularity(javax.realtime.RelativeTime)

getGranularity

public static RelativeTime getGranularity(RelativeTime dest)

Determines the measurement granularity of cost monitoring and cost enforcement.

Parameters:

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.

Returns:

the current granularity

See Also:

setGranularity(javax.realtime.RelativeTime)

setGranularity

public static void setGranularity(RelativeTime time)
                           throws StaticIllegalArgumentException

Sets the measurement granularity of cost monitoring and cost enforcement. The system provides a lower bound for this. When 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.

Parameters:

time - the new granularity.

Throws:

StaticIllegalArgumentException - when nanos is less than one.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class ResourceConstraint<ProcessingConstraint>

Throws:

java.lang.Throwable

start

public void start()

Start applying this constraint to is tasks.

Specified by:

start in class ResourceConstraint<ProcessingConstraint>

stop

public void stop()

Stop applying this constraint to is tasks.

Specified by:

stop in class ResourceConstraint<ProcessingConstraint>

getEffectiveStart

public AbsoluteTime getEffectiveStart(AbsoluteTime dest)

Obtains the actual time of the group's start as recorded by the system. When the start time is absolute, that is the effective start time; otherwise, the effective start is computed relative to the time that the processing group is constructed.

Parameters:

dest - A time value to fill.

Returns:

either, a new instance of AbsoluteTime, when dest is null, or dest otherwise. In either case, its value is the time at which this group actually started.

getEffectiveStart

public AbsoluteTime getEffectiveStart()

Obtains the actual time of the group's start as recorded by the system.

Equivalent to getEffectiveStart(AbsoluteTime) where dest is set to null.

Returns:

a reference to a new instance of AbsoluteTime that represents the time at which this group started.

getCurrentReleaseTime

public AbsoluteTime getCurrentReleaseTime(AbsoluteTime dest)

getLastRelease

public AbsoluteTime getLastRelease()

getBudget

public RelativeTime getBudget()

Gets the value of cost.

Equivalent to getMaximumCost(null).

Returns:

a reference to a newly allocated object containing the value of cost.

getBudget

public RelativeTime getBudget(RelativeTime dest)

Gets the value of cost in the provided RelativeTime object.

Parameters:

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.

Returns:

a reference to dest, or a newly created object if dest is null.

used

public RelativeTime used()

Gets the cost used in the current period so far.

Returns:

an new object containing the cost used in the current period.

used

public RelativeTime used(RelativeTime dest)

Gets the time used in the current period so far.

Parameters:

dest - The instance to use for returning the time. If dest is null, the result will be returned in a newly allocated object.

Returns:

dest containing the cost of the current period

available

public RelativeTime available()

Gets the time remaining in the current period.

Returns:

an new object containing the cost used in the current period.

available

public RelativeTime available(RelativeTime dest)

Gets the time remaining in the current period so far.

Parameters:

dest - The instance to use for returning the time. If dest is null, the result will be returned in a newly allocated object.

Returns:

dest containing the cost of the current period

lastUsed

public RelativeTime lastUsed()

Gets the total cost used in the last period.

Returns:

A new object containing the cost of the last period

lastUsed

public RelativeTime lastUsed(RelativeTime dest)

Gets the total cost used in the last period.

Parameters:

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.

Returns:

dest containing the cost of the last period

getCostOverrunHandler

public AsyncEventHandler getCostOverrunHandler()

Gets the cost overrun handler.

Returns:

a reference to an instance of AsyncEventHandler that is cost overrun handler of this.

setCostOverrunHandler

public ProcessingConstraint setCostOverrunHandler(AsyncEventHandler handler)
                                           throws IllegalAssignmentError

Sets the cost overrun handler.

Parameters:

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.

Returns:

this

Throws:

IllegalAssignmentError - when handler cannot be stored in this.