ftn_mpio(5)

NAME
     FTN_MPIO - Fortran Multi-Threaded I/O

DESCRIPTION
     The 64-bit Fortran compiler and runtime libraries provide multi-threaded
     I/O functionality for Fortran, in other words, this capability is
     available only to programs compiled with -mips3 or -mips4 option and not
     those compiled with -mips1 or -mips2.  To do Fortran I/O in parallel, the
     threaded subroutine must be compiled with the -mpio option.   A few
     things need to be noted:
          1) All subroutines in source files compiled with -mpio option use a
     different I/O interface which allows MP-safe Fortran I/O. However, these
     MP interfaces do take extra runtime check to ensure the integrity of the
     I/O operations and so would effect runtime performance a little (probably
     less than 5%).   For applications which wish to make the most out of
     runtime performance, only those subroutines which get executed in
     parallel or contain parallelized loops with I/O statements in them should
     be compiled with -mpio option.  The rest could and should be compiled
     without -mpio option.
          2) The I/O runtime library will ensure that only one thread gets a
     lock on a particular logical unit to avoid several threads stepping on
     each others.   The lock is only released after this thread completes the
     I/O operation.  This implementation means three things: firstly, multiple
     threads can write to multiple files connected to different Fortran
     logical units at the same time; secondly, you cannot have multiple
     threads writing to the same logical unit and expect it to be faster as,
     most likely, it will be significantly slower due to all the lockings,
     queryings, and unlockings on that same logical unit; and, thirdly, when
     you open the same file as different logical units and then having
     multiple threads writing to those logical units to the same file the
     integrity of the file will be compromised.
          3) The I/O runtime routines do not have control over which threads
     get executed and will execute whichever thread that obtains the lock on a
     particular logical unit first.   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 on the execution order of the threads.  For sequential files,
     since the order of the records written out or read in 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.   For example:

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

     If this loop is threaded, then the numbers printed out will no longer in
     the sequential order from 1 to 100 and applications depending on the
     numbers being in that strict order will get the wrong result.
          4) Because of the problem with sequential files above, the compiler
     (and/or pfa) will not parallelize loops containing I/O statements
     automatically as it would compromise the correctness of the application.
     Loops containing I/O statements must be parallelized manually by adding
     the appropriate directives.  Users who wish to use the ability of pfa,
     for example, to analyze the loop for multi-threading 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.  That is if they are sure that
     the I/O statements won't be effected by the order in which they are
     executed.  Also because of the performance loss associated with multi-
     threaded Fortran I/O the -mpio option is never the default regardless of
     other compilation options.  The user must explicitly specify this option
     in case he wants to have I/O statements inside multi-threaded
     loops/subroutines.
          5) The Fortran standard forbids the use of a function call in a list
     of items to be written out in a WRITE/PRINT statement if that function
     itself performs I/O.  This nested I/O usage used to give random result or
     coredump before the multi-threaded I/O implementation and still does now
     if the application is not compiled with -mpio option.  With the -mpio
     option, this will give 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 but will result in a deadlock
     and the process will hang if the nested I/O operations are done on the
     same logical unit.
          6) Internal file I/O is treated as if it were an independent logical
     unit.  That means only one thread can do internal file I/O at a time.
          7) Since the MP I/O runtime library sets its own internal lock on
     the logical unit, it does not effect the normal I/O operation to the
     files and does not impose additional constraint on the operability of the
     I/O statements.  In other words, I/O operations to NFS-mounted files,
     tapes, sockets, etc. do not have any more limitations than those they
     already have, if any.
          8) The -mpio option effects the runtime library calls generated from
     the I/O statements directly: a different set of MP-safe I/O interfaces
     will be used instead of the default interfaces.  That means this option,
     unlike those compilation options which changes the behavior of the
     runtime I/O library such as -vms_cc by setting a flag inside the Fortran
     main program, is not effected by the fact whether you have the main
     program written in C or Fortran.       9) 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 of opened exceeds it.  However,
     while I/O operations are being executed in multi-threaded mode, if
     additional files are opened causing the number of opened files to exceed
     this limit, the runtime library will return an error message asking the
     user to set the environment variable FORTRAN_OPENED_UNITS to a bigger
     number and then abort.  In order to run the program to completion, the
     user will need to set FORTRAN_OPENED_UNITS to a number big enough to
     accommodate for all the files being opened at the same time.  To avoid
     this from occurring at all without having to set FORTRAN_OPENED_UNITS,
     all OPEN statements can be done in single-threaded mode before doing
     other I/O operations in parallel.

AUTHOR
     Calvin Vu