CVS difference for ais/ai-00355.txt

Differences between 1.6 and version 1.7
Log of other versions for file ais/ai-00355.txt

--- ais/ai-00355.txt	2004/09/09 02:24:06	1.6
+++ ais/ai-00355.txt	2004/10/05 22:49:18	1.7
@@ -1,5 +1,10 @@
-!standard D.03 (00)                                  04-09-06  AI95-00355/05
+!standard D.02.05 (00)                                 04-09-27  AI95-00355/06
+!standard D.02.01 (01)
+!standard D.02.02 (00)
+!standard D.02.02 (01)
 !class amendment 03-09-27
+!status Amendment 200Y 04-09-27
+!status ARG Approved 9-0-0  04-09-17
 !status work item 03-09-27
 !status received 03-09-27
 !priority Medium
@@ -32,8 +37,8 @@
 The method proposed is a general one and will allow any priority
 level/band to have a specific scheme defined (eg FIFO, Round_Robin, EDF,
 etc). This not only extends the facilities of Ada but also provides
-a well defined means of combining different dispatching schemes. A need
-that is increasingly identified in OS provisions and application surveys.
+a well defined means of combining different dispatching schemes. This is a
+need that is increasingly identified in OS provisions and application surveys.
 
 !proposal
 
@@ -49,8 +54,8 @@
 in AI-357). In addition a means of specifying mixed scheduling is proposed
 in this AI.
 
-This AI deals with modifying 2.2 and 2.3, and adding a new 2.4 (it
-assumes EDF is also to be supported, in 2.5).
+This AI deals with modifying 2.2 and 2.3, and adding a new 2.5 (it
+assumes EDF is also to be supported, in 2.6).
 
 In addition a new package is added to D.2.1 for parameters
 to dispatching policies.
@@ -65,7 +70,7 @@
 
 package Ada.Dispatching is
   pragma Pure(Dispatching);
-  exception Dispatching_Policy_Error;
+  Dispatching_Policy_Error : exception;
 end Ada.Dispatching;
 
 Dispatching serves as the parent of other language-defined library
@@ -85,38 +90,42 @@
 
 pragma Task_Dispatching_Policy(policy_identifier);
 
-Pragma Task_Dispatching_Policy specifies the task dispatching policy;
-the policy_identifier shall designate a task dispatching policy.
-
 The form of a pragma Priority_Specific_Dispatching is as follows:
 
 pragma Priority_Specific_Dispatching (policy_identifier,
           first_priority_expression, last_priority_expression);
 
-Pragma Priority_Specific_Dispatching specifies the task dispatching policy
-for the designated range of priorities; the policy_identifier shall
-designate a task dispatching policy.
-
 Name Resolution Rules
 
 The expected type for first_priority_expression and
 last_priority_expression is Integer.
 
 Legality Rules
+
+The policy_identifier used in a pragma Task_Dispatching_Policy
+shall be the name of a task dispatching policy.
 
-The policy_identifier for use with pragma Task_Dispatching_Policy
-shall either be one defined in this Annex or an
-implementation-defined identifier.
-
-The policy_identifier for use with pragma Priority_Specific_Dispatching
-shall be FIFO_Within_Priorities, Round_Robin_Within_Priorities,
-EDF_Across_Priorities or an implementation-defined identifier.
+The policy_identifier used in a pragma Priority_Specific_Dispatching shall
+be the name of a task dispatching policy.
 
 Both first_priority_expression and last_priority_expression
 shall be static expressions in the range of System.Any_Priority;
 last_priority_expression shall have a value greater than or equal
 to first_priority_expression.
 
+Static Semantics
+
+Pragma Task_Dispatching_Policy specifies the task dispatching policy.
+
+Pragma Priority_Specific_Dispatching specifies the task dispatching policy for
+the specified range of priorities. Tasks within the range of priorities
+specified in a Priority_Specific_Dispatching pragma are dispatched according to
+the specified dispatching policy.
+
+If a partition contains one or more Priority_Specific_Dispatching pragmas
+the dispatching policy for priorities not covered by any
+Priority_Specific_Dispatching pragmas is FIFO_Within_Priorities.
+
 Post-Compilation Rules
 
 A Task_Dispatching_Policy pragma is a configuration pragma.
@@ -132,16 +141,6 @@
 then the Ceiling_Locking policy (see D.3) shall also be specified for
 the partition.
 
-Static Semantics
-
-Tasks within the range of priorities specified in a
-Priority_Specific_Dispatching pragma are dispatched according to
-the specified dispatching policy.
-
-If a partition contains one or more Priority_Specific_Dispatching pragmas
-the dispatching policy for priorities not covered by any
-Priority_Specific_Dispatching pragmas is FIFO_Within_Priorities.
-
 Dynamic Semantics
 
 A task dispatching policy specifies the details of task dispatching that
@@ -159,7 +158,7 @@
 processor whenever there is a non-empty ready queue for that processor
 with a higher priority than the priority of the running task.
 
-A task that has its base priority changed, via the use of Set_Priority,
+A task that has its base priority changed
 may move from one dispatching policy to another. It is immediately
 dispatched according to the new policy.
 
@@ -168,26 +167,33 @@
 Implementations are allowed to define other task dispatching policies, but
 need not support more than one task dispatching policy per partition.
 
+An implementation need not support pragma Priority_Specific_Dispatching if it
+is infeasible to support it in the target environment.
 
 
 Add to D.2.3 The Standard Task Dispatching Policy
 
 Static Semantics
+
+The policy_identifier FIFO_Within_Priorities is a task dispatching policy.
 
-The policy_identifier FIFO_Within_Priorities designates a
-task dispatching policy.
+Add to D.2.4 Non-Preemptive Dispatching - Legality Rules (see AI-298):
 
+Non_Preemptive_FIFO_Within_Priorities shall not be specified as the
+policy_identifier of pragma Priority_Specific_Dispatching (see D.2.2).
+
+
 Add a new section:
 
-D.2.4 Round Robin Dispatching
+D.2.5 Round Robin Dispatching
 
 This clause defines the task dispatching policy
-Round_Robin_Within_Priorities and package Round_Robin_Dispatching.
+Round_Robin_Within_Priorities and the package Round_Robin_Dispatching.
 
 Static Semantics
 
-The policy_identifier Round_Robin_Within_Priorities designates a
-task dispatching policy.
+The policy_identifier Round_Robin_Within_Priorities is a task dispatching
+policy.
 
 The following language-defined library package exists:
 
@@ -206,13 +212,13 @@
 end Ada.Dispatching.Round_Robin_Dispatching;
 
 When task dispatching policy Round_Robin_Within_Priorities is the single
-policy in effect for a partition, tasks with priority in the range of
+policy in effect for a partition, each task with priority in the range of
 System.Interrupt_Priority are dispatched according to policy
 FIFO_Within_Priorities.
 
 Dynamic Semantics
 
-A call of either Set_Quantum procedure sets the required quantum value
+The procedure Set_Quantum sets the required quantum value
 for the priority level Pri in the first procedure, and priorities in
 the range Low..High in the second procedure. If no quantum is set for
 a Round Robin priority level, Default_Quantum is used.
@@ -224,15 +230,15 @@
 task dispatching policy Round_Robin_Within_Priorities; otherwise it
 returns False.
 
-A call of Actual_Quantum or either Set_Quantum with a priority that is
-not covered by policy Round_Robin_Within_Priorities raises exception
-Ada.Dispatching.Dispatching_Policy_Error.
+A call of Actual_Quantum or Set_Quantum raises exception
+Ada.Dispatching.Dispatching_Policy_Error if if a predefined policy other than
+Round_Robin_Within_Priorities applies to the specified priority.
 
 For Round_Robin_Within_Priorities, the dispatching rules
-for FIFO_Within_Priorities apply with the following additional rules.
+for FIFO_Within_Priorities apply with the following additional rules:
 
-o When a task is added to the tail of the ready queue for its base
-  priority, it has an execution time budget set equal to the quantum for
+o When a task is added or moved to the tail of the ready queue for its base
+  priority, it has an execution time budget equal to the quantum for
   that priority level. This will also occur when a blocked task becomes
   executable again.
 
@@ -240,43 +246,43 @@
   head of the ready queue for its priority level, it retains its remaining
   budget.
 
-o When a task is executing, its budget is decreased by the amount of
-  execution time it uses. The accuracy of this accounting follows
+o While a task is executing, its budget is decreased by the amount of
+  execution time it uses. The accuracy of this accounting is the same as
   that for execution time clocks (see D.14).
+
+o A task that has its base priority set to
+  a Round Robin priority is moved to the tail of the ready queue for its
+  new priority level.
 
-o A task that has its base priority set, via the use of Set_Priority, to
-  a Round Robin priority is moved to the tail of the ready queue and given
-  a budget equal to the quantum for the new priority level.
-
-o When a task has an active priority higher than its base priority it is
-  given an infinite quantum at its active priority level; its base priority
-  budget is still decreased when it executes.
+  AARM Note: It will be given a budget as described in the first bullet.
 
-o When a task has exhausted its budget, and is without an inherited
+o When a task has exhausted its budget and is without an inherited
   priority (and is not executing within a protected operation), it is moved
-  to the tail of the ready queue for its priority level and is given a budget
-  equal to the quantum for its priority level. This is a task dispatching point.
+  to the tail of the ready queue for its priority level. This is a
+  task dispatching point.
+
+  AARM Note: It will be given a budget as described in the first bullet.
 
-Documentation Requirement
+Documentation Requirements
 
-An implementation shall document the range of quantum supported, or the
+An implementation shall document the range of quanta supported, or the
 distinct values supported.
 
 An implementation shall document the accuracy with which it detects the
-exhaustion of a task's budget.
+exhaustion of the budget of a task.
 
 Notes
 
-Due to implementation constraints, the quantum value returned by a call of
-Actual_Quantum may not be identical to that set by a call of Set_Quantum.
+Due to implementation constraints, the quantum value returned by
+Actual_Quantum might not be identical to that set with Set_Quantum.
 
 A task that executes continuously with an inherited priority will not
 be subject to round robin dispatching.
 
 !example
 
-To specify round robin dispatching for the lowest priority in a 32
-priority system:
+To specify round robin dispatching for the lowest priority in a 32-priority
+system:
 
 pragma Priority_Specific_Dispatching (FIFO_Within_Priorities, 2, 32);
 pragma Priority_Specific_Dispatching (Round_Robin_Within_Priorities, 1, 1);
@@ -308,6 +314,260 @@
 Round Robin scheduling. Indeed it has been implemented in this way by
 Michael Gonzalez Harbour. He reports no difficulty with the implementation.
 
+
+!corrigendum D.2.1(01)
+
+@dinsa
+The task dispatching model specifies preemptive scheduling, based on conceptual
+priority-ordered ready queues.
+@dinss
+@i<@s8<Static Semantics>>
+
+The following language-defined library package exists:
+
+@xcode<@b<package> Ada.Dispatching @b<is>
+  @b<pragma> Pure(Dispatching);
+  Dispatching_Policy_Error : @b<exception>;
+@b<end> Ada.Dispatching;>
+
+Dispatching serves as the parent of other language-defined library
+units concerned with dispatching.
+
+!corrigendum D.02.02(00)
+
+@drepl
+The Standard Task Dispatching Policy
+@dby
+Pragmas Task_Dispatching_Policy and Priority_Specific_Dispatching
+
+!corrigendum D.02.02(01)
+
+@dinsb
+@i<@s8<Syntax>>
+
+The form of a pragma Task_Dispatching_Policy is as follows:
+@dinst
+This clause allows a single task dispatching policy to be
+defined for all priorities, or the range of priorities to be
+split into subranges that are assigned distinct dispatching policies.
+
+!corrigendum D.2.2(02)
+
+@dinsa
+@fa<@b<pragma> Task_Dispatching_Policy (@i<policy_>identifier);>
+@dinss
+The form of a pragma Priority_Specific_Dispatching is as follows:
+
+@fa<@b<pragma> Priority_Specific_Dispatching (@i<policy_>identifier,
+@i<first_priority_>expression, @i<last_priority_>expression);>
+
+@i<@s8<Name Resolution Rules>>
+
+The expected type for @i<first_priority_>@fa<expression> and
+@i<last_priority_>@fa<expression> is Integer.
+
+!corrigendum D.2.2(03)
+
+@drepl
+The @i<policy>_@fa<identifier> shall either be FIFO_Within_Priorities or an
+implementation-defined @fa<identifier>.
+@dby
+The @i<policy>_@fa<identifier> used in a pragma Task_Dispatching_Policy
+shall be the name of a task dispatching policy.
+
+The @i<policy>_@fa<identifier> policy_identifier used in a pragma
+Priority_Specific_Dispatching shall be the name of a task dispatching policy.
+
+Both @i<first_priority_>@fa<expression> and @i<last_priority_>@fa<expression>
+shall be static expressions in the range of System.Any_Priority;
+@i<last_priority_>@fa<expression> shall have a value greater than or equal
+to @i<first_priority_>@fa<expression>.
+
+@i<@s8<Static Semantics>>
+
+@fa<Pragma> Task_Dispatching_Policy specifies the task dispatching policy.
+
+@fa<Pragma> Priority_Specific_Dispatching specifies the task dispatching policy
+for the specified range of priorities. Tasks within the range of priorities
+specified in a Priority_Specific_Dispatching pragma are dispatched according to
+the specified dispatching policy.
+
+If a partition contains one or more Priority_Specific_Dispatching pragmas
+the dispatching policy for priorities not covered by any
+Priority_Specific_Dispatching pragmas is FIFO_Within_Priorities.
+
+!corrigendum D.2.2(04)
+
+@drepl
+A Task_Dispatching_Policy pragma is a configuration pragma.
+@dby
+A Task_Dispatching_Policy pragma is a configuration pragma.
+A Priority_Specific_Dispatching pragma is a configuration pragma.
+
+The priority ranges specified in more than one Priority_Specific_Dispatching
+pragma within the same partition shall not be overlapping.
+
+If a partition contains one or more Priority_Specific_Dispatching pragmas
+it shall not contain a Task_Dispatching_Policy pragma.
+
+If a partition contains one or more Priority_Specific_Dispatching pragmas
+then the Ceiling_Locking policy (see D.3) shall also be specified for
+the partition.
+
+!corrigendum D.2.2(06)
+
+@drepl
+A @i<task dispatching policy> specifies the details of task dispatching that
+are not covered by the basic task dispatching model. These rules govern when
+tasks are inserted into and deleted from the ready queues, and whether a task
+is inserted at the head or the tail of the queue for its active priority. The
+task dispatching policy is specified by a Task_Dispatching_Policy configuration
+pragma. If no such pragma appears in any of the program units comprising a
+partition, the task dispatching policy for that partition is unspecified.
+@dby
+A @i<task dispatching policy> specifies the details of task dispatching that
+are not covered by the basic task dispatching model. These rules govern when
+tasks are inserted into and deleted from the ready queues. A single
+task dispatching policy is specified by a Task_Dispatching_Policy pragma.
+Pragma Priority_Specific_Dispatching assigns distinct dispatching policies
+to ranges of System.Any_Priority.
+
+If neither pragma appears in any of the program units comprising a partition,
+the task dispatching policy for that partition is unspecified.
+
+If a partition contains one or more Priority_Specific_Dispatching pragmas
+a task dispatching point occurs for the currently running task of a
+processor whenever there is a non-empty ready queue for that processor
+with a higher priority than the priority of the running task.
+
+A task that has its base priority changed
+may move from one dispatching policy to another. It is immediately
+dispatched according to the new policy.
+
+!corrigendum D.2.2(17)
+
+@drepl
+Implementations are allowed to define other task dispatching policies, but
+need not support more than one such policy per partition.
+@dby
+Implementations are allowed to define other task dispatching policies, but
+need not support more than one task dispatching policy per partition.
+
+An implementation need not support pragma Priority_Specific_Dispatching if it
+is infeasible to support it in the target environment.
+
+
+!corrigendum D.2.3(01)
+!comment This is a fake to trigger conflict processing. The real change is
+!comment in conflict text.
+@dinsc
+
+@i<@s8<Static Semantics>>
+
+The @i<policy_>@fa<identifier> FIFO_Within_Priorities is a task dispatching
+policy.
+
+!corrigendum D.2.4(01)
+!comment This is a fake to trigger conflict processing. The real change is
+!comment in conflict text.
+@dinsc
+
+Non_Preemptive_FIFO_Within_Priorities shall not be specified as the
+@i<policy_>@fa<identifier> of pragma Priority_Specific_Dispatching (see D.2.2).
+
+
+!corrigendum D.2.5(1)
+
+@dinsc
+
+This clause defines the task dispatching policy
+Round_Robin_Within_Priorities and the package Round_Robin_Dispatching.
+
+@i<@s8<Static Semantics>>
+
+The @i<policy>_@fa<identifier> Round_Robin_Within_Priorities is a task
+dispatching policy.
+
+The following language-defined library package exists:
+
+@xcode<@b<with> System;
+@b<with> Ada.Real_Time;
+@b<package> Ada.Dispatching.Round_Robin_Dispatching @b<is>
+  Default_Quantum : @b<constant> Ada.Real_Time.Time_Span :=
+             @ft<@i<implementation-defined>>;
+  @b<procedure> Set_Quantum (Pri     : @b<in> System.Priority;
+                         Quantum : @b<in> Ada.Real_Time.Time_Span);
+  @b<procedure> Set_Quantum (Low, High : @b<in> System.Priority;
+                         Quantum   : @b<in> Ada.Real_Time.Time_Span);
+  @b<function> Actual_Quantum (Pri : System.Priority) @b<return> Ada.Real_Time.Time_Span;
+  @b<function> Is_Round_Robin (Pri : System.Priority) @b<return> Boolean;
+@b<end> Ada.Dispatching.Round_Robin_Dispatching;>
+
+When task dispatching policy Round_Robin_Within_Priorities is the single
+policy in effect for a partition, each task with priority in the range of
+System.Interrupt_Priority are dispatched according to policy
+FIFO_Within_Priorities.
+
+@i<@s8<Dynamic Semantics>>
+
+The procedure Set_Quantum sets the required quantum value
+for the priority level Pri in the first procedure, and priorities in
+the range Low..High in the second procedure. If no quantum is set for
+a Round Robin priority level, Default_Quantum is used.
+
+The function Actual_Quantum returns the actual quantum used
+by the implementation for the priority level Pri.
+
+The function Is_Round_Robin returns True if priority Pri is covered by
+task dispatching policy Round_Robin_Within_Priorities; otherwise it
+returns False.
+
+A call of Actual_Quantum or Set_Quantum raises exception
+Ada.Dispatching.Dispatching_Policy_Error if if a predefined policy other than
+Round_Robin_Within_Priorities applies to the specified priority.
+
+
+For Round_Robin_Within_Priorities, the dispatching rules
+for FIFO_Within_Priorities apply with the following additional rules:
+
+@xbullet<When a task is added or moved to the tail of the ready queue for its
+  base priority, it has an execution time budget equal to the quantum for
+  that priority level. This will also occur when a blocked task becomes
+  executable again.>
+
+@xbullet<When a task is preempted (by a higher priority task) and is added to
+  the head of the ready queue for its priority level, it retains its remaining
+  budget.>
+
+@xbullet<While a task is executing, its budget is decreased by the amount of
+  execution time it uses. The accuracy of this accounting is the same as
+  that for execution time clocks (see D.14).>
+
+@xbullet<A task that has its base priority set to
+  a Round Robin priority is moved to the tail of the ready queue for its
+  new priority level.>
+
+@xbullet<When a task has exhausted its budget and is without an inherited
+  priority (and is not executing within a protected operation), it is moved
+  to the tail of the ready queue for its priority level. This is a
+  task dispatching point.>
+
+@i<@s8<Documentation Requirements>>
+
+An implementation shall document the range of quanta supported, or the
+distinct values supported.
+
+An implementation shall document the accuracy with which it detects the
+exhaustion of the budget of a task.
+
+@xindent<@s9<NOTES@hr
+17 Due to implementation constraints, the quantum value returned by
+Actual_Quantum might not be identical to that set with Set_Quantum.>>
+
+@xindent<@s9<18 A task that executes continuously with an inherited priority
+will not be subject to round robin dispatching.>>
+
+
 !ACATS test
 
 Tests should be created to check on the implementation of this feature.
@@ -395,6 +655,85 @@
 
 I think so. No one else seems to have a strong enough opinion to write, so
 I'd suggest going ahead.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Friday, September 24, 2004  7:28 PM
+
+AI-355 says:
+
+When task dispatching policy Round_Robin_Within_Priorities is the single
+policy in effect for a partition, each task with priority in the range of
+System.Interrupt_Priority are dispatched according to policy
+FIFO_Within_Priorities.
+
+Later, it says:
+
+A call of Actual_Quantum or Set_Quantum with a priority that is
+not covered by policy Round_Robin_Within_Priorities raises exception
+Ada.Dispatching.Dispatching_Policy_Error.
+
+What does "covered by policy" mean? In particular, if
+   pragma Task_Dispatching_Policy (Round_Robin_within_Priorities);
+applies to a partition, what does
+    Set_Quantum (System.Interrupt_Priority'Last, 0.01);
+do? Since the priority passed is dispatching according to FIFO_Within_Priority,
+perhaps Dispatching_Policy_Error is raised. Or maybe since the entire partition
+is a round-robin one, the call is allowed and the quantum as no effect.
+
+What's the intent? At the very least, we should have an AARM ramification
+note to explain this.
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Friday, September 24, 2004  8:59 PM
+
+> What does "covered by policy" mean? In particular, if
+>    pragma Task_Dispatching_Policy (Round_Robin_within_Priorities);
+> applies to a partition, what does
+>     Set_Quantum (System.Interrupt_Priority'Last, 0.01);
+> do?
+
+It seems clear this should raise an exception, since FIFO_Within_Priorities
+applies to this priority.  So we should define "covered by policy"
+carefully to make sure this is true, or use a different term
+(e.g., "A call of Actual_Quantum or Set_Quantum raises exception
+Ada.Dispatching.Dispatching_Policy_Error if policy
+Round_Robin_Within_Priorities does not apply to the specified
+priority.").
+
+****************************************************************
+
+From: Alan Burns
+Sent: Sunday, September 26, 2004  4:22 AM
+
+I fully agree with Tuck, exception should be raised ed and the wording
+proposed above is clear (and better!)
+
+****************************************************************
+
+From: Robert I. Eachus
+Sent: Sunday, September 26, 2004  1:20 PM
+
+I like the new wording but...  It seems to me that if we are too
+specific here it can hurt.  An implementation should be able to provide
+"Sort_of_Round_Robin_within_Priorities."  However the rule as stated
+means that this dispatching policy has to use different operations to
+set the quantum.  Saying: "A call of Actual_Quantum or Set_Quantum
+raises exception Ada.Dispatching.Dispatching_Policy_Error if a
+predefined policy other than Round_Robin_Within_Priorities applies to
+the specified priority," is at least as clear for the predefined
+policies, and I don't think we should be stating what happens with
+implementation defined policies.
+
+****************************************************************
+
+From: Robert A. Duff
+Sent: Sunday, September 26, 2004  6:01 PM
+
+I agree that imp-def policies should not be restricted in any way.
 
 ****************************************************************
 

Questions? Ask the ACAA Technical Agent