javax.realtime

Class PriorityCeilingEmulation

java.lang.Object

javax.realtime.MonitorControl

javax.realtime.PriorityCeilingEmulation

public class PriorityCeilingEmulation
extends MonitorControl

Monitor control class specifying the use of the priority ceiling emulation protocol (also known as the "highest lockers" protocol). Each PriorityCeilingEmulation instance is immutable; it has an associated ceiling, initialized at construction and queryable but not updatable thereafter.

When a thread or schedulable synchronizes on a target object governed by a PriorityCeilingEmulation policy, then the target object becomes a priority source for the thread or schedulable object. When the object is unlocked, it ceases serving as a priority source for the thread or schedulable. The practical effect of this rule is that the thread or schedulable's active priority is boosted to the policy's ceiling when the object is locked, and is reset when the object is unlocked. The value that it is reset to may or may not be the same as the active priority it held when the object was locked; this depends on other factors (e.g. whether the thread or schedulable's base priority was changed in the interim).

The implementation must perform the following checks when a thread or schedulable t attempts to synchronize on a target object governed by a PriorityCeilingEmulation policy with ceiling ceil:

• t's base priority does not exceed ceil
• t's ceiling priority (when t is holding any other PriorityCeilingEmulation locks) does not exceed ceil.

Thus for any object targetObj that will be governed by priority ceiling emulation, the programmer needs to provide (via MonitorControl.setMonitorControl(Object, MonitorControl)) a PriorityCeilingEmulation policy whose ceiling is at least as high as the maximum of the following values:

• the highest base priority of any thread or schedulable that could synchronize on targetObj
• the maximum ceiling priority value that any task may have when it attempts to synchronize on targetObj.

More formally,

• when a thread or schedulable t, whose base priority is p1, attempts to synchronize on an object governed by a PriorityCeilingEmulation policy with ceiling p2, where p1 > p2, then a CeilingViolationException is thrown in t; likewise, a CeilingViolationException is thrown in t when t is holding a PriorityCeilingEmulation lock and has a ceiling priority exceeding p2.

The values of p1 and p2 are passed to the constructor for the exception and may be queried by an exception handler.

A consequence of the above rule is that a thread or schedulable may nest synchronizations on PriorityCeilingEmulation-governed objects as long as the ceiling for the inner lock is not less than the ceiling for the outer lock.

The possibility of nested synchronizations on objects governed by a mix of PriorityInheritance and PriorityCeilingEmulation policies requires one other piece of behavior in order to avoid unbounded priority inversions. When a thread or schedulable holds a PriorityInheritance lock, then any PriorityCeilingEmulation lock that it either holds or attempts to acquire will exhibit priority inheritance characteristics. This rule is captured above in the definition of priority sources (4.d).

When a thread or schedulable t attempts to synchronize on a PriorityCeilingEmulation-governed object with ceiling ceil, then ceil must be within the priority range allowed by t's scheduler; otherwise, an IllegalTaskStateException is thrown. Note that this does not prevent a regular Java thread from synchronizing on an object governed by a PriorityCeilingEmulation policy with a ceiling higher than 10.

The priority ceiling for an object obj can be modified by invoking MonitorControl.setMonitorControl(obj, newPCE) where newPCE's ceiling has the desired value.

See also MonitorControl PriorityInheritance, and CeilingViolationException.

Method Summary

Modifier and Type	Method and Description
int	getCeiling() Gets the priority ceiling for this PriorityCeilingEmulation object.
static PriorityCeilingEmulation	getMaxCeiling() Gets a PriorityCeilingEmulation object whose ceiling is PriorityScheduler.instance().getMaxPriority().
static PriorityCeilingEmulation	instance(int ceiling) Creates a PriorityCeilingEmulation object with the specified ceiling.

Methods inherited from class javax.realtime.MonitorControl

getMonitorControl, getMonitorControl, setMonitorControl, setMonitorControl

Methods inherited from class java.lang.Object

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

Method Detail

instance

public static PriorityCeilingEmulation instance(int ceiling)

Creates a PriorityCeilingEmulation object with the specified ceiling. This object is in ImmortalMemory. All invocations with the same ceiling value return a reference to the same object.

Parameters:

ceiling - Priority ceiling value.

Throws:

StaticIllegalArgumentException - when ceiling is out of the range of permitted priority values (e.g., less than PriorityScheduler.instance().getMinPriority() or greater than PriorityScheduler.instance().getMaxPriority() for the base scheduler).

Since:

RTSJ 1.0.1

getCeiling

public int getCeiling()

Gets the priority ceiling for this PriorityCeilingEmulation object.

Returns:

the priority ceiling.

Since:

RTSJ 1.0.1

getMaxCeiling

public static PriorityCeilingEmulation getMaxCeiling()

Gets a PriorityCeilingEmulation object whose ceiling is PriorityScheduler.instance().getMaxPriority(). This method returns a reference to a PriorityCeilingEmulation object allocated in immortal memory. All invocations of this method return a reference to the same object.

Returns:

a PriorityCeilingEmulation object whose ceiling is PriorityScheduler.instance().getMaxPriority().

Since:

RTSJ 1.0.1