Re: [fortran,patch] FLUSH vs. fsync() documentation

[Tobias Burnus <burnus at net-b dot de>]

On 06/10/2010 02:46 PM, FX wrote:
> This is tracked as PR 43032. Attached is a proposed doc patch that 1.
> notes what FLUSH (intrinsic and statement) do and don't do, and 2.
> explains with an example how to call POSIX fsync() function from GNU
> Fortran code.


I wonder whether the following is not too explicit:

+On POSIX systems, you can ensure that all data is transferred  to  the
+storage device by calling the @code{fsync()} function

(Nit: two spaces around "to". I would also get rid of the () after
fsync, though I have not checked what is the current GNU/GCC style.)


While POSIX has:

" The fsync() function shall request that all data for the open file
descriptor named by <fildes> is to be transferred to the storage device
associated with the file described by fildes in an
implementation-defined manner. The fsync() function shall not return
until the system has completed that action or until an error is detected."

It qualifies this in the following informal section:

The "wording relies heavily on the conformance document to tell the user
what can be expected from the system. It is explicitly intended that a
null implementation is permitted. This could be valid in the case where
the system cannot  assure nonvolatile storage under any circumstances or
when the system is highly fault-tolerant and the functionality is not
required. In the middle ground between these extremes, fsync() might or
might not actually cause data to be written where it is safe from a
power failure."

Thus, how about changing "ensuring" into "requesting"? That is: "On
POSIX systems, you can request that all data is transferred to the
storage device by calling the @code{fsync} function".

 * * *

+The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
+have identical effect. They flush the runtime library's I/O buffer to the
+kernel, so that the data becomes visible to other processes.


I would use a colon after "identical effect". I am not sure whether I
like "kernel" here. Maybe something simpler like "They flush the the
runtime library's I/O buffer such that the data becomes visible to other
processes." - though I am also not 100% happy with that sentence.

 * * *

Instead of using a PRINT statement at

+  if (ret /= 0) then
+    print *, "Error calling FSYNC"
+    stop

I would either simply use
  (ERROR) STOP "Error calling FSYNC"
or
  |call perror(|"Error calling FSYNC"|)|
  (error) stop
(ERROR STOP is Fortran 2008 thus I am not sure whether one should already advertise it.)


 * * *

The patch looks fine to me; thus: OK after considering the suggestions
and remarks.

Tobias