javax.realtime
Class PriorityScheduler

java.lang.Object
  extended byjavax.realtime.Scheduler
      extended byjavax.realtime.PriorityScheduler

public class PriorityScheduler
extends Scheduler

Class which represents the required (by the RTSJ) priority-based scheduler. The default instance is the base scheduler which does fixed priority, preemptive scheduling.

This scheduler, like all schedulers, governs the default values for scheduling-related parameters in its client schedulable objects. The defaults are as follows:

Attribute
Default Value
Priority parameters
Priority norm priority

Note that the system contains one instance of the PriorityScheduler which is the system's base scheduler and is returned by PriorityScheduler.instance(). It may, however, contain instances of subclasses of PriorityScheduler and even additional instances of PriorityScheduler itself created through this class' protected constructor. The instance returned by the instance() method is the base scheduler and is returned by Scheduler.getDefaultScheduler() unless the default scheduler is reset with Scheduler.setDefaultScheduler(Scheduler).


Field Summary
static int MAX_PRIORITY
          Deprecated. 1.0.1 Use the getMaxPriority() method instead.
static int MIN_PRIORITY
          Deprecated. 1.0.1 Use the getMinPriority() method instead.
 
Constructor Summary
protected PriorityScheduler()
          Construct an instance of PriorityScheduler.
 
Method Summary
protected  boolean addToFeasibility(Schedulable schedulable)
          Inform this scheduler and cooperating facilities that the resource demands of the given instance of Schedulable will be considered in the feasibility analysis of the associated Scheduler until further notice. Whether the resulting system is feasible or not, the addition is completed.

If the object is already included in the feasibility set, do nothing.

 void fireSchedulable(Schedulable schedulable)
          Trigger the execution of a schedulable object (like an AsyncEventHandler).
 int getMaxPriority()
          Gets the maximum priority available for a schedulable object managed by this scheduler.
static int getMaxPriority(java.lang.Thread thread)
          Gets the maximum priority for the given thread.
 int getMinPriority()
          Gets the minimum priority available for a schedulable object managed by this scheduler.
static int getMinPriority(java.lang.Thread thread)
          Gets the minimum priority for the given thread.
 int getNormPriority()
          Gets the normal priority available for a schedulable object managed by this scheduler.
static int getNormPriority(java.lang.Thread thread)
          Gets the "norm" priority for the given thread.
 java.lang.String getPolicyName()
          Gets the policy name of this.
static PriorityScheduler instance()
          Return a reference to the distinguished instance of PriorityScheduler which is the system's base scheduler.
 boolean isFeasible()
          Queries this scheduler about the feasibility of the set of schedulable objects currently in the feasibility set.
protected  boolean removeFromFeasibility(Schedulable schedulable)
          Inform this scheduler and cooperating facilities that the resource demands of the given instance of Schedulable should no longer be considered in the feasibility analysis of the associated Scheduler. Whether the resulting system is feasible or not, the removal is completed.
 boolean setIfFeasible(Schedulable schedulable, ReleaseParameters release, MemoryParameters memory)
          This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of schedulable. If the resulting system is feasible, this method replaces the current parameters of schedulable with the proposed ones.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

 boolean setIfFeasible(Schedulable schedulable, ReleaseParameters release, MemoryParameters memory, ProcessingGroupParameters group)
          This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of schedulable. If the resulting system is feasible, this method replaces the current parameters of schedulable with the proposed ones.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

 boolean setIfFeasible(Schedulable schedulable, SchedulingParameters scheduling, ReleaseParameters release, MemoryParameters memory, ProcessingGroupParameters group)
          This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of schedulable. If the resulting system is feasible, this method replaces the current parameters of schedulable with the proposed ones.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

 
Methods inherited from class javax.realtime.Scheduler
getDefaultScheduler, setDefaultScheduler
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAX_PRIORITY

public static final int MAX_PRIORITY
Deprecated. 1.0.1 Use the getMaxPriority() method instead.

The maximum priority value used by the implementation.

See Also:
Constant Field Values

MIN_PRIORITY

public static final int MIN_PRIORITY
Deprecated. 1.0.1 Use the getMinPriority() method instead.

The minimum priority value used by the implementation.

See Also:
Constant Field Values
Constructor Detail

PriorityScheduler

protected PriorityScheduler()
Construct an instance of PriorityScheduler. Applications will likely not need any instance other than the default instance.

Method Detail

instance

public static PriorityScheduler instance()
Return a reference to the distinguished instance of PriorityScheduler which is the system's base scheduler.

Returns:
A reference to the distinguished instance PriorityScheduler.

getMaxPriority

public int getMaxPriority()
Gets the maximum priority available for a schedulable object managed by this scheduler.

Returns:
The value of the maximum priority.

getMaxPriority

public static int getMaxPriority(java.lang.Thread thread)
Gets the maximum priority for the given thread. If the given thread is a real-time thread that is scheduled by an instance of PriorityScheduler, then the maximum priority for that scheduler is returned. If the given thread is a Java thread then Thread.MAX_PRIORITY is returned. Otherwise an exception is thrown.

Parameters:
thread - An instance of Thread. If null, the maximum priority of this scheduler is returned.
Returns:
The maximum priority for thread
Throws:
java.lang.IllegalArgumentException - Thrown if thread is a real-time thread that is not scheduled by an instance of PriorityScheduler.

getMinPriority

public int getMinPriority()
Gets the minimum priority available for a schedulable object managed by this scheduler.

Returns:
The minimum priority used by this scheduler.

getMinPriority

public static int getMinPriority(java.lang.Thread thread)
Gets the minimum priority for the given thread. If the given thread is a real-time thread that is scheduled by an instance of PriorityScheduler, then the minimum priority for that scheduler is returned. If the given thread is a Java thread then Thread.MIN_PRIORITY is returned. Otherwise an exception is thrown.

Parameters:
thread - An instance of Thread. If null, the minimum priority of this scheduler is returned.
Returns:
The minimum priority for thread
Throws:
java.lang.IllegalArgumentException - Thrown if thread is a real-time thread that is not scheduled by an instance of PriorityScheduler.

getNormPriority

public int getNormPriority()
Gets the normal priority available for a schedulable object managed by this scheduler.

Returns:
The value of the normal priority.

getNormPriority

public static int getNormPriority(java.lang.Thread thread)
Gets the "norm" priority for the given thread. If the given thread is a real-time thread that is scheduled by an instance of PriorityScheduler, then the norm priority for that scheduler is returned. If the given thread is a Java thread then Thread.NORM_PRIORITY is returned. Otherwise an exception is thrown.

Parameters:
thread - An instance of Thread. If null, the norm priority for this scheduler is returned.
Returns:
The norm priority for thread
Throws:
java.lang.IllegalArgumentException - Thrown if thread is a real-time thread that is not scheduled by an instance3 of PriorityScheduler.

isFeasible

public boolean isFeasible()
Queries this scheduler about the feasibility of the set of schedulable objects currently in the feasibility set.

Implementation Notes:

The default feasibility test for the PriorityScheduler considers a set of schedulable objects with bounded resource requirements, to always be feasible. This covers all schedulable objects with release parameters of types PeriodicParameters and SporadicParameters.

If any schedulable object within the feasibility set has release parameters of the exact type AperiodicParameters (not a subclass thereof), then the feasibility set is not feasible, as aperiodic release characteristics require unbounded resources. In that case, this method will return false and all methods in the setIfFeasible family of methods will also return false. Consequently, any call to a setIfFeasible method that passes a schedulable object which has release parameters of type AperiodicParameters, or passes proposed release parameters of type AperiodicParameters, will return false. The only time a setIfFeasible method can return true, when there exists in the feasibility set a schedulable object with release parameters of type AperiodicParameters, is when the method will change those release parameters to not be AperiodicParameters.

Implementations may provide a feasibility test other than the default test just described. In which case the details of that test should be documented here in place of this description of the default implementation.

Specified by:
isFeasible in class Scheduler
Returns:
True, if the system is feasible. False, if not.

setIfFeasible

public boolean setIfFeasible(Schedulable schedulable,
                             ReleaseParameters release,
                             MemoryParameters memory)
This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of schedulable. If the resulting system is feasible, this method replaces the current parameters of schedulable with the proposed ones.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:
setIfFeasible in class Scheduler
Parameters:
schedulable - The schedulable object for which the changes are proposed.
release - The proposed release parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
memory - The proposed memory parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
Returns:
True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.
Throws:
java.lang.IllegalArgumentException - Thrown if schedulable is null, or schedulable is not associated with this scheduler, or the proposed parameters are not compatible with this scheduler.
IllegalAssignmentError - Thrown if schedulable cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to schedulable.
java.lang.IllegalThreadStateException - Thrown if the new release parameters change schedulable from periodic scheduling to some other protocol and schedulable is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setIfFeasible

public boolean setIfFeasible(Schedulable schedulable,
                             ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)
This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of schedulable. If the resulting system is feasible, this method replaces the current parameters of schedulable with the proposed ones.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:
setIfFeasible in class Scheduler
Parameters:
schedulable - The schedulable object for which the changes are proposed.
release - The proposed release parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
memory - The proposed memory parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
group - The proposed processing group parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
Returns:
True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.
Throws:
java.lang.IllegalArgumentException - Thrown if schedulable is null, or schedulable is not associated with this scheduler, or the proposed parameters are not compatible with this scheduler.
IllegalAssignmentError - Thrown if schedulable cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to schedulable.
java.lang.IllegalThreadStateException - Thrown if the new release parameters change schedulable from periodic scheduling to some other protocol and schedulable is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

setIfFeasible

public boolean setIfFeasible(Schedulable schedulable,
                             SchedulingParameters scheduling,
                             ReleaseParameters release,
                             MemoryParameters memory,
                             ProcessingGroupParameters group)
This method first performs a feasibility analysis using the proposed parameter objects as replacements for the current parameters of schedulable. If the resulting system is feasible, this method replaces the current parameters of schedulable with the proposed ones.

This method does not require that the schedulable object be in the feasibility set before it is called. If it is not initially a member of the feasibility set it will be added if the resulting system is feasible.

Specified by:
setIfFeasible in class Scheduler
Parameters:
schedulable - The schedulable object for which the changes are proposed.
scheduling - The proposed scheduling parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
release - The proposed release parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
memory - The proposed memory parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
group - The proposed processing group parameters. If null, the default value of this scheduler is used (a new object is created if the default value is not null). (See PriorityScheduler.)
Returns:
True, if the resulting system is feasible and the changes are made. False, if the resulting system is not feasible and no changes are made.
Throws:
java.lang.IllegalArgumentException - Thrown if schedulable is null, or schedulable is not associated with this scheduler, or the proposed parameters are not compatible with this scheduler.
IllegalAssignmentError - Thrown if schedulable cannot hold references to the proposed parameter objects, or the parameter objects cannot hold a reference to schedulable.
java.lang.IllegalThreadStateException - Thrown if the new release parameters change schedulable from periodic scheduling to some other protocol and schedulable is currently waiting for the next release in RealtimeThread.waitForNextPeriod() or RealtimeThread.waitForNextPeriodInterruptible().

addToFeasibility

protected boolean addToFeasibility(Schedulable schedulable)
Inform this scheduler and cooperating facilities that the resource demands of the given instance of Schedulable will be considered in the feasibility analysis of the associated Scheduler until further notice. Whether the resulting system is feasible or not, the addition is completed.

If the object is already included in the feasibility set, do nothing.

Specified by:
addToFeasibility in class Scheduler
Parameters:
schedulable - A reference to the given instance of Schedulable
Returns:
True, if the system is feasible after the addition. False, if not.
Throws:
java.lang.IllegalArgumentException - Thrown if schedulable is null, or if schedulable is not associated with this; that is schedulable.getScheduler() != this.

removeFromFeasibility

protected boolean removeFromFeasibility(Schedulable schedulable)
Inform this scheduler and cooperating facilities that the resource demands of the given instance of Schedulable should no longer be considered in the feasibility analysis of the associated Scheduler. Whether the resulting system is feasible or not, the removal is completed.

Specified by:
removeFromFeasibility in class Scheduler
Parameters:
schedulable - A reference to the given instance of Schedulable
Returns:
True, if the removal was successful. False, if the schedulable object cannot be removed from the scheduler's feasibility set; e.g., the schedulable object is not part of the scheduler's feasibility set.
Throws:
java.lang.IllegalArgumentException - Thrown if schedulable is null.

fireSchedulable

public void fireSchedulable(Schedulable schedulable)
Trigger the execution of a schedulable object (like an AsyncEventHandler).

Specified by:
fireSchedulable in class Scheduler
Parameters:
schedulable - The schedulable object to make active. If null, nothing happens.
Throws:
java.lang.UnsupportedOperationException - Thrown in all cases by the PriorityScheduler

getPolicyName

public java.lang.String getPolicyName()
Gets the policy name of this.

Specified by:
getPolicyName in class Scheduler
Returns:
The policy name (Fixed Priority) as a string.