Version 1.1 of ai05s/ai05-0283-1.txt

Unformatted version of ai05s/ai05-0283-1.txt version 1.1
Other versions for file ai05s/ai05-0283-1.txt

!standard A.12.1(3) 11-11-08 AI05-0283-1/01
!class Amendment 11-11-08
!status work item 11-11-08
!status received 11-09-28
!priority Low
!difficulty Easy
!subject Stream_IO should be preelaborated

!summary

Ada.Stream_IO is be preelaborated.

!proposal

Ada.Stream_IO should be preelaborated, so that logging, persistence, and the like can be programmed for packages that support Annex E.

!wording

Add pragma Preelaborate (Stream_IO) to A.12.1(3).

!discussion

** TBD.

Aside: The e-mail thread also touches on the need to be able to serialize containers into memory-based structures. The best way to do this is with a memory stream. Claw defines one to use for writing to the registry and clipboard (and also makes it available to users). Ada probably ought to have one. Claw's version looks like:

with Ada.Streams; package Claw.Marshalling is

-- Writes to a buffer will allocate additional memory from the -- heap as needed. If you know reasonably accurately how much -- you'll need, it will be more efficient to make the -- Initial_Length big enough and thus avoid heap allocation. -- -- Any heap allocation will be freed automatically when a Buffer -- ceases to exist.

type Buffer_Type(Initial_Length : Ada.Streams.Stream_Element_Count) is new Ada.Streams.Root_Stream_Type with private;

procedure Read( Stream : in out Buffer_Type; Item : out Ada.Streams.Stream_Element_Array; Last : out Ada.Streams.Stream_Element_Offset);

procedure Write( Stream : in out Buffer_Type; Item : in Ada.Streams.Stream_Element_Array);

function Length(Stream : in Buffer_Type) return Ada.Streams.Stream_Element_Count; -- Return the total length of data written into the buffer.

procedure Clear(Stream : in out Buffer_Type); -- Empty the buffer.

private ... end Claw.Marshalling;

Should we consider something on this line for Ada??

!ACATS test

** TBD.

!ASIS

No ASIS impact.

!appendix


!topic IO packages should have preelaborate aspect
!reference Ada 2005 RM A.10.1 (2)
!from /Brad Moore 11-09-27/
!keywords Preelaborate Remote_Types Text_IO
!discussion

It would be nice if the IO packages (Ada.Text_IO, etc)
had the Preelaborate aspect. This would
facilitate use for Remote_Types. This would make it easier to
create RACW types that have persistence, provide remote file
access, and database access for direct IO, for example.
One cannot currently with IO packages from a Remote_Types package,
because the IO packages are not preelaborable.

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

From: Randy Brukardt
Sent: Wednesday, September 28, 2011  7:33 PM

This problem was extensively discussed during the Ada 2005 work -- see
AI95-0362-1. Note that the problem statement in that AI specifically
mentions IO.

The discussion section of that AI gives a very detailed look at the results
of that discussion. It should be noted that the original version of the AI
proposed making Direct_IO, Sequential_IO and Stream_IO preelaborable
(Text_IO is not reasonable for reasons discussed in the AI). We circulated
that to implementers to get feedback, and various objections were recorded.
In the end, those proposals were dropped in order to get consensus on the
remainder of the AI.

Calendar and Text_IO are the biggest impediment to making most packages
Preelaborable, but it does not appear reasonable for either to be
Preelaborable. (And probably Calendar shouldn't be a Remote_Types package
even if it was Preelaborable.) There was a brief amount of discussion of
having a Preelaborable "Simple_Text_IO", but that appeared like a long
argument over exactly what to include (the original proposal not having any
file I/O, just StdOut, making it useless for logging, my #1 need).

A case can be made for the other I/O packages, but that case would have to
be stronger than the one I made in 2003. (Wow, was it really that long ago?)
I'm pretty sure "It would be nice" is not a strong case. :-) So if you have
more examples of places where I/O was needed in preelaborated units, it
would help consideration of your proposal.

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

From: Brad Moore
Sent: Thursday, September 29, 2011  12:58 AM

> The discussion section of that AI gives a very detailed look at the results
> of that discussion. It should be noted that the original version of the AI
> proposed making Direct_IO, Sequential_IO and Stream_IO preelaborable
> (Text_IO is not reasonable for reasons discussed in the AI). We circulated
> that to implementers to get feedback, and various objections were recorded.
> In the end, those proposals were dropped in order to get consensus on the
> remainder of the AI.

In my particular case, I was looking for Direct_IO to have the 
preelaborate pragma. I was implementing
a suite of buffer generics (essentially a deque container), including 
persistent buffers where the storage for the buffer is
entirely in a file. The buffers were designed to support remote access 
via Remote Access to Class Wide
types (RACW types). I ended up having to create my own IO package, 
called Preelaborated_IO.
Note using GNAT_IO was not a possibility because;
    1) I needed the package to be generic, where the element type is a 
generic formal parameter. GNAT_IO is non-generic and only
        deals with integers, and strings.
    2) I wanted the buffers to be portable to other compiler vendors.

> Calendar and Text_IO are the biggest impediment to making most packages
> Preelaborable, but it does not appear reasonable for either to be
> Preelaborable. (And probably Calendar shouldn't be a Remote_Types package
> even if it was Preelaborable.) There was a brief amount of discussion of
> having a Preelaborable "Simple_Text_IO", but that appeared like a long
> argument over exactly what to include (the original proposal not having any
> file I/O, just StdOut, making it useless for logging, my #1 need).

I think I'm OK with Text_IO not being preelaborable. I'm more interested 
in Sequential_IO and Direct_IO.

> A case can be made for the other I/O packages, but that case would have to
> be stronger than the one I made in 2003. (Wow, was it really that long ago?)
> I'm pretty sure "It would be nice" is not a strong case. :-) So if you have
> more examples of places where I/O was needed in preelaborated units, it
> would help consideration of your proposal.

If I was asked before I had implemented my own package, my response 
would have been  a lot stronger,
possibly, "It would be bleeping awesome!"

Also, all the buffer containers (including non-persistent ones) have a 
Save and a Restore primitive that
can load or save the container to a file, which is another case where I 
needed to use Preelaborated_IO.

Maybe such primitives might be worth considering some day for the 
Standard Ada containers?
While a container can be streamed to a file, it is not as convenient, 
nor likely as efficient, as having a Save and Restore primitive.

It seems a shame that every time someone wants to do something similar 
with Remote_Types packages, they would have to end up
writing their own Preelaborated_IO package. (Or possibly use mine)

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

From: Randy Brukardt
Sent: Thursday, September 29, 2011  1:18 AM

...
> If I was asked before I had implemented my own package, my 
> response would have been  a lot stronger, possibly, "It would 
> be bleeping awesome!"

<Grin>
 
> Also, all the buffer containers (including non-persistent 
> ones) have a Save and a Restore primitive that can load or 
> save the container to a file, which is another case where I 
> needed to use Preelaborated_IO.

That sounds like a job for a (Preelaborated version of) Stream_IO.
 
> Maybe such primitives might be worth considering some day for 
> the Standard Ada containers?
> While a container can be streamed to a file, it is not as 
> convenient, nor likely as efficient, as having a Save and 
> Restore primitive.

No, you just need a memory stream. Claw has such a stream (I think we called
it a marshalling stream); we use it for writing to/from the clipboard and
registry (but we also made it generally available). It's better to do that
than reinvent the wheel (for streaming).

I think the Standard should have something similar. Ada has Storage_IO for
this purpose, but that isn't likely to work with user-defined types
(certainly not if there is any indirection in the types).

> It seems a shame that every time someone wants to do 
> something similar with Remote_Types packages, they would have 
> to end up writing their own Preelaborated_IO package. (Or 
> possibly use mine)

Probably we should bite the bullet and make Stream_IO preelaborated (you can
write all of the others using it, and most of the time you would be better
off using it anyway -- almost all non-text files are heterogeneous in
practice). Otherwise, we should create a preelaborated version of it, but
there doesn't seem to be much point in having two packages with the same
contents.

If we left the others alone, the pain would be fairly localized. And a
motivated user could write their own Sequential_IO and Direct_IO analogs.

Anyway, something to consider.

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

From: Brad Moore
Sent: Saturday, October  1, 2011  10:39 AM

I agree with your suggestion. That sounds like the best way forward.

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

Questions? Ask the ACAA Technical Agent