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(Thread thread) Determine the processing constraint for the give execution context.
static ProcessingConstraint	currentConstraint(ThreadGroup group) Determine the processing constraint for the give execution context.
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
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(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(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.

Throws:

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

IllegalAssignmentError

Parameters:

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

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.

Throws:

StaticIllegalArgumentException - when nanos is less than one.

Parameters:

time - the new granularity.

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

JamaicaVM: Realtime code requires special care when using finalize:

NOTE: The use of finalize() is strongly discouraged for realtime or safety-critical code. This method should only be used for debugging purposes. If used as a last resort to reclaim non-memory resources, finalize() should indicate the resource leak with a loud error message.

There is no guarantee that finalize() will be called, the memory management may decide not to reclaim this object's memory or to delay the call to finalize() to an unspecified point in time. It is therefore recommended never to use the finalize method to release any resources (files, network connections, non-Java memory, etc.) since releasing of these resource may be delayed perpetually.

The order of finalization is not specified, i.e., the finalize method of any two objects that become unreachable may be called in an arbitrary order. It therefore has to be assumed that when finalize() is called on an object, that the finalize() method of any object that is only reachable through this object() has been called as well or is called simultaneously by another thread.

The presence of a finalize-method in any sub-class of Object causes the reclamation of the memory of this object to be delayed until the finalize() method has been executed. The finalize() method is typically executed by the finalizer thread (that may run at a low priority) or by a call to Runtime.runFinalization().

Any code sequence that creates instances of a class that defines a finalize() method must therefore ensure that sufficient CPU time is allocated to the finalizer thread or that Runtime.runFinalization() is called regularly such that the finalize() methods can be executed and the object's memory can be reclaimed.

The finalize method itself should never block or run for long times since it would otherwise block the finalizer thread or the thread that called Runtime.runFinalization() and prevent the execution other finalize() method and consequently prevent the reclamation of these object's memory.

For objects that are allocated in a javax.realtime.memory.ScopedMemory, the finalize() methods will be called when this scoped memory is exited by the last thread. Unlike HeapMemory, which is controlled by the garbage collector, ScopedMemory provides a defined execution point for the finalize() mehods and it is therefore safer to use finalize() here.

Overrides:

finalize in class ResourceConstraint<ProcessingConstraint>

Throws:

Throwable - the Exception raised by this method

See Also:

WeakReference, PhantomReference

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.

Throws:

IllegalAssignmentError - when handler cannot be stored in this.

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