ftn_mpio(5)

NAME
     FTN_MPIO - Fortran 77 multi-threaded I/O

DESCRIPTION
     Multi-threaded I/O functionality for Fortran is available with MIPSpro
     Fortran 77 programs compiled with the -mips3 or -mips4 option.

     The 64-bit Fortran compiler and runtime libraries provide multi-
     threaded I/O functionality for Fortran.  This capability is available
     only to programs compiled with the -mips3 or -mips4 option.  To
     perform Fortran I/O in parallel, the threaded subroutine must be
     compiled with the -mpio option.

     The following notes provide details about MPIO:

     * All subroutines in source files compiled with the -mpio option use a
       different I/O interface which allows MP-safe Fortran I/O.  However,
       these MP interfaces do take extra runtime checks to ensure the
       integrity of the I/O operations and so can affect runtime
       performance (usually less than 5%).

       For applications to make the most of runtime performance, only those
       subroutines which are executed in parallel or which contain
       parallelized loops with I/O statements in them should be compiled
       with the -mpio option.  The rest should be compiled without the
       -mpio option.

     * The I/O runtime library ensures that only one thread gets a lock on
       a particular logical unit.  The lock is only released after this
       thread completes the I/O operation.

       This implies the following:

       1.  Multiple threads can write to multiple files connected to
           different Fortran logical units at the same time.

       2.  You cannot have multiple threads writing to the same logical
           unit and expect it to be faster. It will probably be
           significantly slower due to all the lockings, queryings, and
           unlockings on that same logical unit.

       3.  When you open the same file as different logical units and then
           have multiple threads writing to those logical units to the same
           file, the integrity of the file will be compromised.

     * The I/O runtime routines do not have control over which threads get
       executed. They execute whichever thread first obtains the lock on a
       particular logical unit.  Therefore, this ability to have multi-
       threaded I/O is most useful in direct access or keyed access I/O
       where each thread performs I/O on a pre-determined record (or where
       each thread performs I/O on a different file) and, therefore, the
       result is independent of the execution order of the threads.

       Because the order of the records written out or read in for
       sequential files depends on which thread gets executed first, the
       result could be incorrect unless the records are not sequentially
       related and can be written or read in any order. In the following
       example, if this loop is threaded, the numbers printed out are no
       longer in the sequential order from 1 to 100 and applications
       depending on the numbers being in that strict order receive the
       wrong result:

                DO 10, I=1,100
                  PRINT *, I
          10    CONTINUE



     * Because of the problem with sequential files above, the compiler
       does not parallelize loops containing I/O statements automatically
       because it would compromise the correctness of the application.
       Loops containing I/O statements must be parallelized manually by
       adding the appropriate directives.

       To use APO to analyze the loop for multi-threading, you can comment
       out the I/O statements to get the .m file with all the
       parallelization directives added to the appropriate loops, and then
       uncomment the I/O statements and compile the .m file with the -mpio
       option.  Do this only if you are sure that the I/O statements won't
       be affected by the order in which they are executed.

       Because of the performance loss associated with multi-threaded
       Fortran I/O, the -mpio option is never the default, regardless of
       other compilation options.  You must explicitly specify this option
       to have I/O statements inside multi-threaded loops or subroutines.

     * The Fortran standard forbids the use of a function call in a list of
       items to be written out in a WRITE or PRINT statement if that
       function itself performs I/O.  This nested I/O usage gives random
       results or coredumps before the multi-threaded I/O implementation
       and still gives random results if the application is not compiled
       with -mpio option.

       The -mpio option gives the correct result if the I/O operation
       inside the function is not performed on the same logical unit as the
       one in the I/O statement where the function call is used.  It does
       result in a deadlock and the process hangs if the nested I/O
       operations are done on the same logical unit.

     * Internal file I/O is treated as if it were an independent logical
       unit.  Therefore, only one thread can do internal file I/O at a
       time.

     * Because the MP I/O runtime library sets its own internal lock on the
       logical unit, it does not affect the normal I/O operation to the
       files and does not impose additional constraint on the operability
       of the I/O statements.  I/O operations to NFS-mounted files, tapes,
       sockets, etc. do not have any more limitations than those they
       already have, if any.

     * The -mpio option affects the runtime library calls generated from
       the I/O statements directly: a different set of MP-safe I/O
       interfaces are used instead of the default interfaces.  Therefore,
       this option, unlike those compilation options which change the
       behavior of the runtime I/O library (such as -vms_cc) by setting a
       flag inside the Fortran main program, is not affected whether you
       have the main program written in C or written in Fortran.

     * The default maximum number of Fortran logical units that can be
       opened at the same time is 100, including 4 system files.  In
       single-threaded mode this limit is automatically increased if the
       number opened exceeds it.  However, while I/O operations are being
       executed in multi-threaded mode, if additional files are opened and
       cause the number of opened files to exceed this limit, the runtime
       library returns an error message asking the user to set the
       environment variable FORTRAN_OPENED_UNITS to a bigger number and
       then the program aborts.  In order to run the program to completion,
       the user must set FORTRAN_OPENED_UNITS to a number big enough to
       accommodate all the files being opened at the same time.

       To avoid setting FORTRAN_OPENED_UNITS, all OPEN statements can be
       done in single-threaded mode before doing other I/O operations in
       parallel.

SEE ALSO
     cc(1), f77(1)