!standard A.8.1(10)                          14-10-09   AI12-0130/01
!standard A.8.2(28/3)
!standard A.8.4(10)
!class Amendment 14-10-09
!status work item 14-10-09
!status received 14-10-01
!priority Low
!difficulty Easy
!subject All I/O packages should have Flush

!summary

Flush is added to Sequential_IO and Direct_IO.

!question 

Text_IO and Stream_IO have procedure Flush to ensure that internal
buffers are "flushed". However, Sequential_IO and Direct_IO do
not. This makes it impossible to ensure that a write using one
of these packages has completed.

!proposal

(See summary.)

!wording

Add after A.8.1(10) and A.8.4(10):

   procedure Flush (File : in File_Type);

Add after A.8.2(28/3):

   procedure Flush (File : in File_Type);

      The effect of Flush is the same as the corresponding subprogram
      in Streams.Stream_IO (see A.12.1).   

[Editor's note: This is how Text_IO.Flush is defined. We could consider
removing A.10.3(20-21) since it would be mostly subsumed by A.8.2 (and
rest could be moved to A.10.2), but that seems like work. :-) Note that
Flush doesn't make much sense being defined in A.10.3 (which is about
Standard_Output and the like).]

!discussion

Consistency suggests that Flush should be in all of the I/O packages,
not just two.

It's thought that it wasn't included in Sequential_IO and Direct_IO
because these packages don't use any buffering. But of course the target
system might use buffering whether or not it makes sense to the Ada
program. Most implementations of Flush also call a target OS function to
ensure that any pending writes are completed. It's odd that this
functionality isn't available in Sequential_IO and Direct_IO.

[Editor's note: I used "It's thought" because I don't know for sure, this
is my best guess. Maybe Tucker or Bob could explain this oddity. If not,
delete this note!]

It's possible to use Stream_IO (which has Flush) to emulate Sequential_IO
and Direct_IO. But such code is necessarily more complicated and
error-prone than using the original packages (especially for Direct_IO,
which requires calculating a positioning location, an operation that is
easy to get wrong).

!ASIS

No impact.

!ACATS test

!appendix

From: Dmitry A. Kazakov
Sent: Wednesday, October  1, 2014  3:00 PM

[Editor's note: just the part that's relevant to this AI. The entire thread
can be found in AC-00264.]

...
If something gets changed then I have two further issues:

1. Missing procedure Flush.

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

From: Randy Brukardt
Sent: Thursday, October  2, 2014  2:12 PM

...
> 1. Missing procedure Flush.

Text_IO and Stream_IO have Flush. Sequential_IO and Direct_IO do not. I believe
the presumption is that neither of these other packages will use any buffering,
at least WRT to the underlying target OS. So Flush would have no effect (the
definition in Ada is about flushing *internal* buffers, it doesn't say anything
about the effect on the target OS). [Aside: I believe most implementations of
Flush try to call something in the target OS, if there is such an operation, but
that is clearly not required by the Standard.]

There might be a consistency argument for the other packages, but that clearly
was considered and rejected when Flush was added in Ada 95. Perhaps someone
knows why that was?

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