Version 1.2 of ai12s/ai12-0293-1.txt

Unformatted version of ai12s/ai12-0293-1.txt version 1.2
Other versions for file ai12s/ai12-0293-1.txt

!standard 13.13.1(9)          18-11-28 AI12-0293-1/02
!standard 13.13.1(9.1/1)
!class Amendment 18-10-14
!status Amendment 1-2012 18-11-27
!status ARG Approved 8-0-0 18-10-22
!status work item 18-10-14
!status received 18-10-05
!priority Low
!difficulty Easy
!subject Add predefined FIFO_Streams packages
!summary
A group of 3 predefined child units of Ada.Streams are provided in order to provide capabilities which are useful on their own and, more specifically, in relation to AI12-0020-1.
!problem
With user-defined Image attributes as defined in AI12-0020-1, many users may have a common need for similar streaming-related functionality: a stream type which simply acts as a FIFO buffer and has operations for keeping track of the number of unread elements in the buffer and for efficiently emptying the buffer.
A similar need appears in many other cases. One common example is storing and retrieving Ada objects in an existing API (for example, the Windows Clipboard and the Windows Registry).
!proposal
Rather than having each user address these needs in their own way, a group of predefined child units of Ada.Streams are provided.
!wording
Add after 13.13.1(9) (the end of the static semantics section):
The following related units are also declared; they provide stream implementations which do not make use of any file operations.
package Ada.Streams.FIFO_Streams with Pure, Nonblocking is type FIFO_Stream is abstract new Root_Stream_Type with private;
function Element_Count (Stream : FIFO_Stream) return Stream_Element_Count is abstract;
procedure Clear (Stream : in out FIFO_Stream) is abstract; private ... -- not specified by the language end Ada.Streams.FIFO_Streams;
package Ada.Streams.FIFO_Streams.Unbounded with Prelaborated, Nonblocking is type Stream_Type is new FIFO_Stream with private with Default_Initial_Condition => Element_Count (Stream_Type) = 0;
overriding procedure Read ( Stream : in out Stream_Type; Item : out Stream_Element_Array; Last : out Stream_Element_Offset) with Post => -- Element_Count decreases by the number of elements read. (Item (Item'First .. Last)'Length = Element_Count (Stream)'Old - Element_Count (Stream))
and
-- Number of elements read is minimum of Item'Length and -- number of available items. If that number is 0, then -- Last = Item'First - 1. (if Element_Count (Stream)'Old < Item'Length then Element_Count (Stream) = 0 elsif Item'Length = 0 then Last = Item'First - 1 else Last = Item'Last);
overriding procedure Write ( Stream : in out Stream_Type; Item : in Stream_Element_Array) with Post => Element_Count (Stream) = Element_Count (Stream)'Old + Item'Length;
overriding function Element_Count (Stream : Stream_Type) return Stream_Element_Count;
overriding procedure Clear (Stream : in out Stream_Type) with Post => Element_Count (Stream) = 0; private ... -- not specified by the language end Ada.Streams.FIFO_Streams.Unbounded;
package Ada.Streams.FIFO_Streams.Bounded with Pure, Nonblocking is -- The spec for package Bounded is the same as for package -- Unbounded except that it is Pure instead of Preelaborated, -- the Max_Elements discriminant is present, and there is a -- precondition for Write which references that discriminant. -- It is intended that the implementation of Unbounded might -- make use of controlled types and dynamic storage allocation, -- whereas the implementation of Bounded will not.
type Stream_Type (Max_Elements : Stream_Element_Count) is new FIFO_Stream with private with Default_Initial_Condition => Element_Count (Stream_Type) = 0;
overriding procedure Read ( Stream : in out Stream_Type; Item : out Stream_Element_Array; Last : out Stream_Element_Offset) with Post => -- Element_Count decreases by the number of elements read. (Item (Item'First .. Last)'Length = Element_Count (Stream)'Old - Element_Count (Stream))
and
-- Number of elements read is minimum of Item'Length and -- number of available items. If that number is 0, then -- Last = Item'First - 1. (if Element_Count (Stream)'Old < Item'Length then Element_Count (Stream) = 0 elsif Item'Length = 0 then Last = Item'First - 1 else Last = Item'Last);
overriding procedure Write ( Stream : in out Stream_Type; Item : in Stream_Element_Array) with Pre => Element_Count (Stream) + Item'Length <= Stream.Max_Elements or else (raise Constraint_Error), Post => Element_Count (Stream) = Element_Count (Stream)'Old + Item'Length;
overriding function Element_Count (Stream : Stream_Type) return Stream_Element_Count with Post => Element_Count'Result <= Stream.Max_Elements;
overriding procedure Clear (Stream : in out Stream_Type) with Post => Element_Count (Stream) = 0; private ... -- not specified by the language end Ada.Streams.FIFO_Streams.Bounded;
The Element_Count functions return the number of stream elements that are available for reading from the given stream.
The Read and Write procedures behave as described in section 13.13.1. Stream elements are read in FIFO (first-in, first-out) order; stream elements are available for reading immediately after they are written.
The Clear procedures remove any available stream elements from the given stream.
====
Add after 13.13.1(9.1/1):
Implementation Advice
Bounded.Stream_Type objects should be implemented without implicit pointers or dynamic allocation.
AARM Reason: The FIFO_Streams.Bounded package is provided in order to make available an alternative to the FIFO_Streams.Unbounded package which gives more predictable memory usage.
!discussion
None yet.
!ASIS
No changed needed.
!ACATS test
ACATS C-Tests are needed to check that the new packages are supported.
!appendix

From: Steve Baird
Sent: Friday, October 5, 2018  5:02 PM

The attached is a new version of this AI, incorporating the feedback from the
Lisbon meeting.

It is actually 2 AIs (one of them hasn't been assigned a number yet) because
part of that Lisbon feedback was the suggestion that the AI should be split into
two parts. The other AI just defines some new predefined units,
Ada.Streams.FIFO_Streams and a couple of child units thereof.
[This is version /01 of that split AI - Editor.]

As usual, thanks to Randy for some helpful preliminary review. Also as usual,
don't blame him for any flaws.

****************************************************************


Questions? Ask the ACAA Technical Agent