Version 1.1 of 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
!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
... --
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 =>
--
(Item (Item'First .. Last)'Length =
Element_Count (Stream)'Old - Element_Count (Stream))
and
--
--
--
(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
... --
end Ada.Streams.FIFO_Streams.Unbounded;
package Ada.Streams.FIFO_Streams.Bounded
with Pure, Nonblocking
is
--
--
--
--
--
--
--
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 =>
--
(Item (Item'First .. Last)'Length =
Element_Count (Stream)'Old - Element_Count (Stream))
and
--
--
--
(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
... --
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