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

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

!standard 13.13.1(9) 18-10-14 AI12-0293-1/01
!standard 13.13.1(9.1/1)
!class Amendment 18-10-14
!status work item 18-10-14
!status received 18-10-05
!priority Low
!difficulty Easy
!subject Add predefined FIFO_Streams packages

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.

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).

Rather than having each user address these needs in their own way, a group of predefined child units of Ada.Streams are provided.

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))

-- 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 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;

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.

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.