CVS difference for ai05s/ai05-0159-1.txt

--- ai05s/ai05-0159-1.txt	2010/05/20 03:54:01	1.9
+++ ai05s/ai05-0159-1.txt	2010/05/20 04:05:16	1.10
@@ -1,4 +1,4 @@
-!standard  A.18.24                                 10-05-10    AI05-0159-1/06
+!standard  A.18.24                                 10-05-19    AI05-0159-1/07
 !class Amendment 05-10-24
 !status work item 10-04-29
 !status ARG Approved  11-0-0  10-02-27
@@ -44,7 +44,7 @@
    type Element_Type is private;
 
 package Ada.Containers.Synchronized_Queue_Interfaces is
-   pragma Pure;
+   pragma Pure(Synchronized_Queue_Interfaces);
 
    type Queue is synchronized interface;
 
@@ -105,7 +105,7 @@
    with package Queue_Interfaces is new Ada.Containers.Synchronized_Queue_Interfaces (<>);
    Default_Ceiling: System.Any_Priority := System.Priority'Last;
 package Ada.Containers.Unbounded_Synchronized_Queues is
-   pragma Preelaborate;
+   pragma Preelaborate(Unbounded_Synchronized_Queues);
 
    protected type Queue (Ceiling: System.Any_Priority := Default_Ceiling) is
          new Queue_Interfaces.Queue with
@@ -143,10 +143,10 @@
 with Ada.Containers.Synchronized_Queue_Interfaces;
 generic
    with package Queue_Interfaces is new Ada.Containers.Synchronized_Queue_Interfaces (<>);
-   Default_Capacity : Count_Type := 1;
-   Default_Ceiling: System.Any_Priority := System.Priority'Last; package Ada.Containers.Bounded_Synchronized_Queues is
+   Default_Capacity : Count_Type;
+   Default_Ceiling: System.Any_Priority := System.Priority'Last;
 package Ada.Containers.Bounded_Synchronized_Queues is
-   pragma Preelaborate;
+   pragma Preelaborate(Bounded_Synchronized_Queues);
 
    protected type Queue
         (Capacity : Count_Type := Default_Capacity;
@@ -199,10 +199,10 @@
    with function Get_Priority
      (Element: Queues.Element_Type) return Queue_Priority is <>;
    with function "<"
-     (Left, Right : Queues.Element_Type) return Boolean is <>;
+     (Left, Right : Queue_Priority) return Boolean is <>;
    Default_Ceiling: System.Any_Priority := System.Priority'Last;
 package Ada.Containers.Unbounded_Priority_Queues is
-   pragma Preelaborate;
+   pragma Preelaborate(Unbounded_Priority_Queues);
 
    protected type Queue
         (Ceiling: System.Any_Priority := Default_Ceiling) is
@@ -233,9 +233,10 @@
 Two elements E1 and E2 are equivalent if Get_Priority(E1) < Get_Priority(E2) and
 Get_Priority(E2) < Get_Priority(E1) both return False.
 
-Enqueue inserts an item according to the order specified by the "<" function. If
-the queue already contains elements equivalent to New_Item, then it is inserted
-after the existing equivalent elements.
+Enqueue inserts an item according to the order specified by the "<" function on
+the result of Get_Priority on the elements. If the queue already contains
+elements equivalent to New_Item, then it is inserted after the existing
+equivalent elements.
 
 AARM Ramification: Enqueue never blocks; if more storage is
 needed for a new element, it is allocated dynamically.
@@ -267,11 +268,11 @@
    with function Get_Priority
      (Element: Queues.Element_Type) return Queue_Priority is <>;
    with function "<"
-     (Left, Right : Queues.Element_Type) return Boolean is <>;
-   Default_Capacity : Count_Type := 1;
+     (Left, Right : Queue_Priority) return Boolean is <>;
+   Default_Capacity : Count_Type;
    Default_Ceiling: System.Any_Priority := System.Priority'Last;
 package Ada.Containers.Bounded_Priority_Queues is
-   pragma Preelaborate;
+   pragma Preelaborate(Bounded_Priority_Queues);
 
    protected type Queue
         (Capacity : Count_Type := Default_Capacity;
@@ -1255,6 +1256,108 @@
 are only a small distance away.
 
 [This is version /06 - Editor.]
+
+****************************************************************
+
+From: Tucker Taft
+Date: Monday, May 10, 2010  11:06 AM
+
+I don't see why you need a default for the generic formal object
+Default_Capacity. It seems reasonable to require that the user specify a
+Default_Capacity when instantiating, rather than allowing it to unintentionally
+become one, which turns the "queue" into a mailbox. That seems error-prone.
+
+Otherwise, looks good...
+
+****************************************************************
+
+From: Bob Duff
+Date: Monday, May 10, 2010  11:38 AM
+
+> I don't see why you need a default for the generic formal object
+> Default_Capacity.
+> It seems reasonable to require that the user specify a
+> Default_Capacity when instantiating, rather than allowing it to
+> unintentionally become one, which turns the "queue" into a mailbox.
+> That seems error-prone.
+
+OK, I'm convinced.
+
+> Otherwise, looks good...
+
+Thanks for reviewing.
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Monday, May 10, 2010  10:40 PM
+
+...
+> I also tried to remove some duplicated verbiage.  For example, the
+> "interfaces" part says that Enqueue blocks if and only of the thing is
+> bounded and is full.  We don't need to mention that again in AARM
+> notes for the concrete types, which are only a small distance away.
+
+Yes, we do. The intent is that this is reference information, so that someone
+can look up just the definition of the single package that they care about
+(prehaps by clicking on the page) and get the important information. The
+blocking/non-blocking seems important enough to put in each place (in the AARM
+only, of course). Indeed, I would argue that a user note in each place might be
+appropriate. Remember that in the HTML version, that "short distance" is on a
+different HTML page that the user probably will not see (printed is different,
+but there is less use of that version every year).
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Monday, May 10, 2010  10:53 PM
+
+...
+> The generic library package
+> Containers.Synchronized_Queue_Interfaces has the following
+> declaration:
+>
+> generic
+>    type Element_Type is private;
+>
+> package Ada.Containers.Synchronized_Queue_Interfaces is
+>    pragma Pure;
+
+This wasn't your mistake, but the name of the package is always included in the
+pragma Pure or Preelaborate.
+
+...
+> with System;
+> with Ada.Containers.Synchronized_Queue_Interfaces;
+> generic
+>    with package Queue_Interfaces is new
+> Ada.Containers.Synchronized_Queue_Interfaces (<>);
+>    type Queue_Priority is private;
+>    with function Get_Priority
+>      (Element: Queues.Element_Type) return Queue_Priority is <>;
+>    with function "<"
+>      (Left, Right : Queues.Element_Type) return Boolean is <>;
+
+It took me forever to understand this; I finally realized that the English
+wording makes no sense because you actually meant:
+
+   with function "<"
+     (Left, Right : Queue_Priority) return Boolean is <>;
+
+...
+> Enqueue inserts an item according to the order specified by the "<"
+> function.
+> If the queue already contains elements equivalent to New_Item, then it
+> is inserted after the existing equivalent elements.
+
+I don't think this quite works. I think you need to mention Get_Priority
+somewhere. Maybe:
+
+Enqueue inserts an item according to the order specified by the "<" function on
+the result of Get_Priority on the elements.
+
+I've made these changes (and Tucker's suggestion) in a separate version (so we
+can recover yours if necessary). [This is version /07 - Editor.]
 
 ****************************************************************