Version 1.4 of ai12s/ai12-0130-1.txt
!standard A.8.1(10) 14-11-14 AI12-0130-1/02
!standard A.8.2(28/3)
!standard A.8.4(10)
!standard A.10.3(21)
!standard A.12.1(28/2)
!standard A.12.1(28.6/1)
!class binding interpretation 14-10-19
!status Corrigendum 2015 14-11-14
!status ARG Approved 7-0-1 14-10-19
!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. Should these routines be added? (Yes.)
!recommendation
(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 Flush procedure synchronizes the external file with the internal
file (by flushing any internal buffers) without closing the file. For
a direct file, the current index is unchanged; for a stream file
(see A.12.1), the current position is unchanged.
The exception Status_Error is propagated if the file is not open. The
exception Mode_Error is propagated if the mode of the file is In_File.
Modify A.10.3(21):
The effect of Flush is the same as the corresponding subprogram in
{Sequential_IO (see A.8.2)}[Streams.Stream_IO (see A.12.1)]. If File is
not explicitly specified, Current_Output is used.
Modify A.12.1(28/2):
The subprograms given in subclause A.8.2 for the control of external files
(Create, Open, Close, Delete, Reset, Mode, Name, Form, [and] Is_Open{, and
Flush}) are available for stream files.
Delete A.12.1(28.6/1).
!discussion
Consistency suggests that Flush should be in all of the I/O packages,
not just two.
It's thought that Flush wasn't included in Sequential_IO and Direct_IO
because these packages don't use any buffering. But the definition of those
packages only specify the behavior relative to the internal file; what the
target system does with the external file isn't specified. In particular,
it could 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; this
lack makes it harder to write cooperating programs using these I/O packages.
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).
Since this is inconsistent for no obvious reason, and the routine has value
for all of the I/O packages, we add the missing procedures.
!corrigendum A.8.1(10)
Insert after the paragraph:
function Is_Open(File : in File_Type) return Boolean;
the new paragraph:
procedure Flush (File : in File_Type);
!corrigendum A.8.2(28/3)
Insert after the paragraph:
Returns True if the file is open (that is, if it is associated
with an external file); otherwise, returns False.
the new paragraphs:
procedure Flush(File : in File_Type);
The Flush procedure synchronizes the external file with the internal
file (by flushing any internal buffers) without closing the file. For
a direct file, the current index is unchanged; for a stream file
(see A.12.1), the current position is unchanged.
The exception Status_Error is propagated if the file is not open. The
exception Mode_Error is propagated if the mode of the file is In_File.
!corrigendum A.8.4(10)
Insert after the paragraph:
function Is_Open(File : in File_Type) return Boolean;
the new paragraph:
procedure Flush (File : in File_Type);
!corrigendum A.10.3(21)
Replace the paragraph:
The effect of Flush is the same as the corresponding subprogram in
{Sequential_IO (see A.8.2)}[Streams.Stream_IO (see A.12.1)]. If File is
not explicitly specified, Current_Output is used.
by:
The effect of Flush is the same as the corresponding subprogram in
Sequential_IO (see A.8.2). If File is not explicitly specified,
Current_Output is used.
!corrigendum A.12.1(28/2)
Replace the paragraph:
The subprograms given in subclause A.8.2 for the control of external files
(Create, Open, Close, Delete, Reset, Mode, Name, Form, and Is_Open) are
available for stream files.
by:
The subprograms given in subclause A.8.2 for the control of external files
(Create, Open, Close, Delete, Reset, Mode, Name, Form, Is_Open, and Flush)
are available for stream files.
!corrigendum A.12.1(28.6/1)
Delete the paragraph:
The Flush procedure synchronizes the external file with the internal file
(by flushing any internal buffers) without closing the file or changing
the position. Mode_Error is propagated if the mode of the file is In_File.
!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?
***************************************************************
Questions? Ask the ACAA Technical Agent