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.

If a thread or schedulable object 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 object. The practical effect of this rule is that the thread or schedulable object'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 object's base priority was changed in the interim).

The implementation must perform the following checks when a thread or schedulable object 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 (if t is holding any other PriorityCeilingEmulation locks) does not exceed ceil.

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

More formally:

• If a thread or schedulable object 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. A CeilingViolationException is likewise thrown in t if t is holding a PriorityCeilingEmulation lock and has a ceiling priority exceeding p2.

A consequence of the above rule is that a thread or schedulable object 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. If a thread or schedulable object 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 object 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 IllegalThreadStateException 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.

instance

public static PriorityCeilingEmulation instance(int ceiling)

Return 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:

java.lang.IllegalArgumentException - Thrown if ceiling is outside 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:

1.0.1

getDefaultCeiling

public int getDefaultCeiling()

Deprecated. Since 1.0.1. The method name is misleading. Replaced with getCeiling()

Gets the priority ceiling for this PriorityCeilingEmulation object.

Returns:

The priority ceiling.

getCeiling

public int getCeiling()

Gets the priority ceiling for this PriorityCeilingEmulation object.

Returns:

The priority ceiling.

Since:

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:

1.0.1