Version 1.7 of ai12s/ai12-0130-1.txt

Unformatted version of ai12s/ai12-0130-1.txt version 1.7
Other versions for file ai12s/ai12-0130-1.txt

!standard A.8.1(10)          15-01-19 AI12-0130-1/03
!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 1-2012 14-11-14
!status WG9 Approved 15-06-26
!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. We moved the definition of Flush to the Sequential_IO subclause, as that is where all of the existing file management subprograms are defined, and it would be strange to have all but one defined there. (Flush was defined in Stream_IO in Ada 95-Ada 2012.)
!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