CVS difference for ai05s/ai05-0069-1.txt
--- ai05s/ai05-0069-1.txt 2007/10/25 01:10:00 1.1
+++ ai05s/ai05-0069-1.txt 2007/11/21 05:39:24 1.2
@@ -1,10 +1,11 @@
-!standard A.18(0/2) 07-10-24 AI05-0069-1/01
+!standard A.18.17(0) 07-11-20 AI05-0069-1/02
!class Amendment 07-10-24
+!status ARG Approved 9-0-0 06-11-10
!status work item 07-10-24
!status received 07-10-02
!priority Medium
!difficulty Hard
-!subject Singleton container
+!subject Holder container
!summary
@@ -34,14 +35,26 @@
generic
type Element_Type (<>) is private;
-package Ada.Containers.Holders is
+ with function "=" (Left, Right : Element_Type) return Boolean is <>;
+package Ada.Containers.Indefinite_Holders is
+ pragma Preelaborate (Indefinite_Holders);
-- This package provides a "holder" of a definite type that contains
-- a single value of an indefinite type.
-- This allows one to effectively declare an uninitialized variable
-- or component of an indefinite type.
type Holder is tagged private;
+ pragma Preelaborable_Initialization (Holder);
+ Empty_Holder : constant Holder;
+
+ function "=" (Left, Right : Holder) return Boolean;
+ -- If Left and Right denote the same holder object, then the function returns True.
+ -- Otherwise, it compares the element contained in Left to the element contained in
+ -- Right using the generic formal equality operator, returning the result of that
+ -- operation. Any exception raised during the evaluation of element equality is
+ -- propagated.
+
function To_Holder (New_Item : Element_Type) return Holder;
-- Returns a non-empty holder containing an element initialized to New_Item.
@@ -49,7 +62,7 @@
-- Returns True if the holder is empty, and
-- False if it contains an element.
- procedure Clear (Container : Holder);
+ procedure Clear (Container : in out Holder);
-- Removes the element from Container.
function Element (Container : Holder) return Element_Type;
@@ -84,14 +97,86 @@
private
-- ... Not specified by the language.
-end Ada.Containers.Holders;
+end Ada.Containers.Indefinite_Holders;
!wording
+
+The language-defined generic package Containers.Indefinite_Holders provides private type
+Holder and a set of operations for that type. A holder container holds a single element
+of an indefinite type.
+
+A holder containers allows the declaration of an object that can be used like an
+uninitialized variable or component of an indefinite type.
+
+A holder container may be *empty*. An empty holder does not contain an element.
-** TBD ** (Most of the needed wording is given as comments above; the definition of
-tampering is given below.)
+Static Semantics
-A subprogram is said to tamper with elements of a holder object H if:
+The generic library package Containers.Holders has the following declaration:
+
+generic
+ type Element_Type (<>) is private;
+ with function "=" (Left, Right : Element_Type) return Boolean is <>;
+package Ada.Containers.Indefinite_Holders is
+ pragma Preelaborate (Indefinite_Holders);
+
+ type Holder is tagged private;
+ pragma Preelaborable_Initialization (Holder);
+
+ Empty_Holder : constant Holder;
+
+ function "=" (Left, Right : Holder) return Boolean;
+
+ function To_Holder (New_Item : Element_Type) return Holder;
+
+ function Is_Empty (Container : Holder) return Boolean;
+
+ procedure Clear (Container : in out Holder);
+
+ function Element (Container : Holder) return Element_Type;
+
+ procedure Replace_Element (Container : in out Holder;
+ New_Item : in Element_Type);
+
+ procedure Query_Element (Container : in Holder;
+ Process : not null access procedure (Element : in Element_Type));
+
+ procedure Update_Element (Container : in Holder;
+ Process : not null access procedure (Element : in out Element_Type));
+
+ procedure Move (Target : in out Holder; Source : in out Holder);
+
+private
+ -- ... Not specified by the language.
+end Ada.Containers.Indefinite_Holders;
+
+The actual function for the generic formal function "=" on Element_Type values is
+expected to define a reflexive and symmetric relationship and return the same result
+value each time it is called with a particular pair of values. If it behaves in
+some other manner, the function "=" on holder values returns an unspecified value.
+The exact arguments and number of calls of this generic formal function by the
+function "=" on holder values are unspecified.
+
+ AARM Ramification: If the actual function for "=" is not symmetric and consistent,
+ the result returned by any of the functions defined to use "=" cannot be predicted.
+ The implementation is not required to protect against "=" raising an exception,
+ or returning random results, or any other “bad” behavior. And it can call "="
+ in whatever manner makes sense. But note that only the results of the function "="
+ is unspecified; other subprograms are not allowed to break if "=" is bad.
+
+The type Holder is used to represent holder containers. The type Holder
+needs finalization (see 7.6).
+
+Empty_Holder represents an empty holder object. If an object of type Holder
+is not otherwise initialized, it is initialized to the same value as Empty_Holder.
+
+[Some operations of this generic package have access-to-subprogram parameters.
+To ensure such operations are well-defined, they guard against certain actions
+by the designated subprogram. In particular, some operations check for
+"tampering with elements" of a container because they depend on elements
+of the container not being replaced.]
+
+A subprogram is said to *tamper with elements* of a holder object H if:
* It clears the element contained by H, that is, it calls the Clear procedure with H
as a parameter;
* It replaces the element contained by H, that is, it calls the Replace_Element
@@ -99,6 +184,128 @@
* It calls the Move procedure with H as a parameter;
* It finalizes H.
+ AARM Reason: Complete replacement of an element can cause its memory to be
+ deallocated while another operation is holding onto a reference to it.
+ That can't be allowed. However, a simple modification of (part of) an
+ element is not a problem, so Update_Element does not cause a problem.
+
+function "=" (Left, Right : Holder) return Boolean;
+
+If Left and Right denote the same holder object, then the function returns True.
+Otherwise, it compares the element contained in Left to the element contained in
+Right using the generic formal equality operator, returning the result of that
+operation. Any exception raised during the evaluation of element equality is
+propagated.
+
+ AARM Implementation Note: This wording describes the canonical semantics.
+ However, the order and number of calls on the formal equality function
+ is unspecified, so an implementation can call it as many or as few times
+ as it needs to get the correct answer.
+
+function To_Holder (New_Item : Element_Type) return Holder;
+
+Returns a non-empty holder containing an element initialized to New_Item.
+
+function Is_Empty (Container : Holder) return Boolean;
+
+Returns True if the holder is empty, and False if it contains an element.
+
+procedure Clear (Container : in out Holder);
+
+Removes the element from Container. Container is empty after a successful
+Clear operation.
+
+function Element (Container : Holder) return Element_Type;
+
+If Container is empty, Constraint_Error is propagated.
+Otherwise, returns the element stored in Container.
+
+procedure Replace_Element (Container : in out Holder;
+ New_Item : in Element_Type);
+
+Replace_Element assigns the value New_Item into Container, replacing
+any preexisting content of Container. Container is not empty
+after a successful call to Replace_Element.
+
+procedure Query_Element (Container : in Holder;
+ Process : not null access procedure (Element : in Element_Type));
+
+If Container is empty, Constraint_Error is propagated.
+Otherwise, Query_Element calls Process.all with the contained element as
+the argument. Program_Error is raised if Process.all tampers with the elements
+of Container. Any exception raised by Process.all is propagated.
+
+ AARM Reason: The "tamper with the elements" check is intended to prevent the
+ Element parameter of Process from being modified or deleted outside of Process.
+ The check prevents data loss (if Element_Type is passed by copy) or
+ erroneous execution (if Element_Type is an unconstrained type).
+
+procedure Update_Element (Container : in Holder;
+ Process : not null access procedure (Element : in out Element_Type));
+
+If Container is empty, Constraint_Error is propagated.
+Otherwise, Query_Element calls Process.all with the contained element as
+the argument. Program_Error is raised if Process.all tampers with the elements
+of Container. Any exception raised by Process.all is propagated.
+
+ AARM Implementation Note: The Element parameter of Process.all may be
+ constrained even if Element_Type is unconstrained.
+
+procedure Move (Target : in out Holder; Source : in out Holder);
+
+If Target denotes the same object as Source, then Move has no effect.
+Otherwise, the element contained by Source (if any) is removed from Source
+and inserted into Target, replacing any preexisting content. Source is empty
+after a successful call to Move.
+
+Bounded Errors
+
+It is a bounded error for the actual function associated with a
+generic formal subprogram, when called as part of an operation of
+this package, to tamper with elements of any Holder parameter to the
+operation. Either Program_Error is raised, or the operation works as
+defined on the value of the Holder either prior to, or subsequent to,
+some or all of the modifications to the Holder.
+
+[Editor's note: This is from AI05-0022-1.]
+
+It is a bounded error to call any subprogram declared in the visible part
+of Containers.Indefinite_Holders when the associated container has been
+finalized. If the operation takes Container as an IN OUT parameter,
+then it raises Constraint_Error or Program_Error. Otherwise, the operation
+either proceeds as it would for an empty container, or it raises
+Constraint_Error or Program_Error.
+
+[Editor's note: This is from AI05-0027-1.]
+
+Implementation Requirements
+
+No storage associated with a holder object shall be lost upon assignment or scope exit.
+
+The execution of an assignment_statement for a holder shall have the effect of
+copying the element (if any) from the source holder object to the target holder object.
+
+ AARM Implementation Note: An assignment of a holder is a "deep" copy;
+ that is the elements are copied as well as the data structures. We say
+ "effect of" in order to allow the implementation to avoid copying elements
+ immediately if it wishes. For instance, an implementation that avoided copying
+ until one of the containers is modified would be allowed.
+
+Implementation Advice
+
+Move should not copy elements, and should minimize copying of internal data structures.
+
+ AARM Implementation Note: Usually that can be accomplished simply by moving
+ the pointer(s) to the internal data structures from the Source holder
+ to the Target holder.
+
+If an exception is propagated from a holder operation, no storage should be lost,
+nor should the element be removed from a holder unless specified by the operation.
+
+ AARM Reason: This is important so that programs can recover from errors.
+ But we don't want to require heroic efforts, so we just require documentation
+ of cases where this can't be accomplished.
+
!discussion
Note that it isn't necessary to define a definite version of this container; that would
@@ -106,7 +313,7 @@
!example
-** TBD **
+--!corrigendum A.18.17(0)
!ACATS test
@@ -456,6 +663,237 @@
the only way to do this.
Amazing how many details there are even in such a simple container...
+
+****************************************************************
+
+From: Stephen W. Baird
+Date: Monday, November 19, 2007 5:04 PM
+
+Rich Paige, who has implemented all of the other
+container generics for IBM/Rational, had the following
+questions about differences between the Holder spec
+and the other container specs (in addition to noticing
+the parameter mode problem with Clear which was fixed
+in Fairfax):
+
+ Should the holder generic take a formal "=" operator?
+ Should the holder generic export an explicitly declared "=" operator?
+ Should the spec include a Preelaborate pragma and a
+ Preelaborable_Initialization pragma for the holder type?
+ Should the spec export an Empty_Holder constant?
+
+ ----
+
+ Many happy returns of Eeyore's birthday," said Pooh.
+
+ "Oh, is that what it is?"
+
+ "What are you giving him, Owl?"
+
+ "What are you giving him, Pooh?"
+
+ I'm giving him a Useful Pot to Keep Things In, and I
+ wanted to ask you "
+
+ "Is this it?" said Owl, taking it out of Pooh's paw.
+
+ "Yes, and I wanted to ask you -- "
+
+ "Somebody has been keeping honey in it," said Owl.
+
+ "You can keep anything in it," said Pooh earnestly.
+ "It's Very Useful like that".
+
+ -- A.A. Milne
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Monday, November 19, 2007 5:11 PM
+
+...
+> Should the holder generic take a formal "=" operator?
+
+I don't think so, because there is no Find operation that would use it.
+
+> Should the holder generic export an explicitly declared "=" operator?
+
+I thought it did (doesn't everything?). Of course, then we need the formal
+"=" and all of the wording that goes with that. Ugh.
+
+> Should the spec include a Preelaborate pragma and a
+> Preelaborable_Initialization pragma for the holder type?
+
+Yes, of course.
+
+> Should the spec export an Empty_Holder constant?
+
+I suppose. Not sure how I could have missed that (and "="). Probably just
+didn't start at the very top when looking through Vectors.
+
+Anyone else have thoughts? I suppose these are too much change to do without
+bringing it back for another ARG approval.
+
+****************************************************************
+
+From: Ed Schonberg
+Date: Monday, November 19, 2007 5:37 PM
+
+>> Should the holder generic take a formal "=" operator?
+>
+> I don't think so, because there is no Find operation that would use
+> it.
+
+But the re-exported "=" will most likely use it, as you note.
+
+>
+>> Should the holder generic export an explicitly declared "="
+>> operator?
+>
+> I thought it did (doesn't everything?). Of course, then we need the
+> formal "=" and all of the wording that goes with that. Ugh.
+>
+>> Should the spec include a Preelaborate pragma and a
+>> Preelaborable_Initialization pragma for the holder type?
+>
+> Yes, of course.
+>
+>> Should the spec export an Empty_Holder constant?
+>
+> I suppose. Not sure how I could have missed that (and "="). Probably just
+> didn't start at the very top when looking through Vectors.
+>
+> Anyone else have thoughts? I suppose these are too much change to
+> do without bringing it back for another ARG approval.
+
+This may be settled by e-mail, these are straightforward consistency
+changes (said he in his naive optimism).
+
+****************************************************************
+
+From: Robert A. Duff
+Date: Monday, November 19, 2007 5:58 PM
+
+> This may be settled by e-mail, these are straightforward consistency changes
+> (said he in his naive optimism).
+
+In general, I'm in favor of settling things by e-mail, and I encourage the new
+chair to encourage that. I hate to travel half-way round the world to deal
+with obvious stuff. Anyway, this one seems straightforward.
+
+I'm also in favor of including the Pooh story in the AARM. ;-)
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Monday, November 19, 2007 6:28 PM
+
+Has Tampa been moved to Europe? ;-)
+
+The problem, of course, is that what is obvious to me and Ed may not be
+obvious to everyone. We had a number of incidents in the past where the
+integrity of the leadership of the ARG was questioned, and thus we became
+rather conservative in handling changes - it is hard to argue with a vote of
+the entire ARG.
+
+We could of course vote to approve the "obvious" changes of the editor each
+meeting, but I suspect that such a resolution would end up with a 2-0-8
+vote, as no one would want to vote for a blank check.
+
+Note that we had a case where an "obvious" AI (AI-13) was reversed by the
+full ARG in Fairfax. (We also had more "obvious" AIs in Fairfax than usual
+because we did not manage to finish all of them at the previous meeting,
+leaving twelve of them to carry over.) Moreover, the review of "obvious" AIs
+sometimes finds additional problems beyond just typos. And they provide a
+needed break from the really tough nuts.
+
+All of that said, I don't have a problem in this particular case in making
+the improvements by e-mail. (WG 9 still will have to approve it in any case,
+plus a second review when we make a Corrigendum or other standards document.
+And there is plenty of precident for these particular changes.) I think we
+would need to deal with E-mail approval as we do with initial comments.
+
+Does anyone out there want additional ARG review of these changes to
+AI05-0069-1 (package Ada.Containers.Holder)? So far, no one has indicated
+that.
+
+****************************************************************
+
+From: Tucker Taft
+Date: Monday, November 19, 2007 7:42 PM
+
+Yes, Yes, Yes, Yes. ;-)
+Now it is even more useful!
+
+****************************************************************
+
+From: John Barnes
+Date: Tuesday, November 20, 2007 2:10 AM
+
+> Does anyone out there want additional ARG review of these changes to
+> AI05-0069-1 (package Ada.Containers.Holder)? So far, no one has indicated
+> that.
+
+
+Well you have made rather a lot of changes by now and although they seem
+straightforward, I think it would be good to circulate the result soon while
+it is still in our minds (rather than just saying go read the database). Of
+course, it will be sent for editorial review along with a whole lot of
+others in due course but it won't perhaps receive the scrutiny it deserves
+by then.
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Tuesday, November 20, 2007 9:47 PM
+
+Well, I haven't made any changes at all yet -- I was trying to find out if
+that was a good idea first. I think I have my answer to that, so I'll get to
+work.
+
+There is one remaining question: we didn't change the status of this AI.
+That leaves it in limbo for the time being (we're not intending to forward
+Amendment AIs to WG 9). But we're planning to use this particular package in
+ASIS, and waiting for the next Amendment or container TR probably would
+leave it undefined (formally) when ASIS goes to Standardization (not much is
+happening with the container TR - I haven't had time to push the
+development). Is that OK? Or should we make this a Binding Interpretation?
+(It's surely short enough, and there is no sane incompatibility.)
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Tuesday, November 20, 2007 11:27 PM
+
+Since we're enjoyably thinking about this package (rather than one of
+Steve Baird's problems ;-), here's some additional consistency questions:
+
+ (1) All of the indefinite containers start with "Indefinite_". A holder
+ is defined only for an indefinite element type. Should this package
+ really be called "Indefinite_Holders"?? It would be inconsistent for
+ it not to be named that way. (Side-effect: the name makes it more
+ obvious what these are for. At least if you know what an indefinite
+ type is.)
+
+ (2) Adding the formal "=" means that we'll need AI05-0071-1 to be finished
+ and adopted before this will actually work with the ASIS definition.
+ (That's probably a good thing.)
+
+****************************************************************
+
+From: Randy Brukardt
+Date: Tuesday, November 20, 2007 11:27 PM
+
+> Well you have made rather a lot of changes by now and although they seem
+> straightforward, I think it would be good to circulate the result
+> soon while it is still in our minds (rather than just saying go read the
+> database).
+
+Ask and ye shall receive. Even if you didn't *really* mean it. Below find the entire
+wording section for AI05-0069-1, as revised and all of the missing chunks filled in
+(I hope). The rest of the AI is essentially unchanged.
+
+[Editor's note: This is from version /02 of the AI, not repeated here.]
****************************************************************
Questions? Ask the ACAA Technical Agent