This file contains the named document blocks for use in generating the 

documentation.  This is divided into several main blocks:

   Threads and interrups/signals

   Fortran

   Misc MPI (e.g., status null)

   Error classes

-----------------------------------------------------------------------------

Note that only one of ThreadSafe and SignalSafe may be used

/*N ThreadSafe

   Thread and Interrupt Safety:

   This routine is thread-safe.  This means that this routine may be

   safely used by multiple threads without the need for any user-provided 

   thread locks.  However, the routine is not interrupt safe.  Typically, 

   this is due to the use of memory allocation routines such as 'malloc'

   or other non-MPICH runtime routines that are themselves not interrupt-safe.

N*/

/*N SignalSafe

   Thread and Interrupt Safety:

   This routine is both thread- and interrupt-safe. 

   This means that this routine may safely be used by multiple threads and

   from within a signal handler.   

N*/

/*N NotThreadSafe

   Thread and Interrupt Safety:

   The user is responsible for ensuring that multiple threads do not try to

   update the same MPI object from different threads.  This routine should 

   not be used from within a signal handler.

   The MPI standard defined a thread-safe interface but this does not 

   mean that all routines may be called without any thread locks.  For

   example, two threads must not attempt to change the contents of the

   same 'MPI_Info' object concurrently.  The user is responsible in this

   case for using some mechanism, such as thread locks, to ensure that 

   only one thread at a time makes use of this routine.  

N*/

Most of the MPI objects are static enough that it isn't necessary to

lock around the routines (even though some ops require updates).  Info isn't

expected to be as robust (there was discussion on the MPI-Forum list

on this). 

/*N ThreadSafeInfoRead

   Thread and Interrupt Safety:

   This routine is thread and interrupt safe only if no MPI routine that 

   updates or frees the same 'MPI_Info' object may be called concurrently 

   with this routine.

   The MPI standard defined a thread-safe interface but this does not 

   mean that all routines may be called without any thread locks.  For

   example, two threads must not attempt to change the contents of the

   same 'MPI_Info' object concurrently.  The user is responsible in this

   case for using some mechanism, such as thread locks, to ensure that 

   only one thread at a time makes use of this routine.  

N*/

/*N ThreadSafeNoUpdate

    Thread and Interrupt Safety:

   This routine is thread and interrupt safe only if no MPI routine that 

   updates or frees the same MPI object may be called concurrently 

   with this routine.

   The MPI standard defined a thread-safe interface but this does not 

   mean that all routines may be called without any thread locks.  For

   example, two threads must not attempt to change the contents of the

   same 'MPI_Info' object concurrently.  The user is responsible in this

   case for using some mechanism, such as thread locks, to ensure that 

   only one thread at a time makes use of this routine.  

N*/

-----------------------------------------------------------------------------

/*N Fortran

Notes for Fortran:

All MPI routines in Fortran (except for 'MPI_WTIME' and 'MPI_WTICK') have 

an additional argument 'ierr' at the end of the argument list.  'ierr'

is an integer and has the same meaning as the return value of the routine 

in C.  In Fortran, MPI routines are subroutines, and are invoked with the 

'call' statement.  

All MPI objects (e.g., 'MPI_Datatype', 'MPI_Comm') are of type 'INTEGER'

in Fortran.  

N*/

Try this as an alias

/*N fortran

.N Fortran

N*/

/*N FortranStatus

 The 'status' argument must be declared as an array of size 'MPI_STATUS_SIZE',

 as in 'integer status(MPI_STATUS_SIZE)'.

N*/

/*N FortStatusArray

 The 'status' argument must be declared as an array of sise 'MPI_STATUS_SIZE',

 as in 'integer status(MPI_STATUS_SIZE,10)' (assuming no more than 10 

 requests are provided as input).

N*/

/*N FortranString

 The sizes of MPI strings in Fortran are one less than the sizes of that 

 string in C/C++ because the C/C++ versions provide room for the trailing

 null character required by C/C++.  For example, 'MPI_MAX_ERROR_STRING' is 

 'mpif.h' is one smaller than the same value in 'mpi.h'.  See the MPI

 standard, sections 2.6.2 and 4.12.9.

N*/

-----------------------------------------------------------------------------

/*N collops

Notes on collective operations:

The reduction functions ('MPI_Op') do not return an error value.  As a result,

if the functions detect an error, all they can do is either call 'MPI_Abort'

or silently skip the problem.  Thus, if you change the error handler from

'MPI_ERRORS_ARE_FATAL' to something else, for example, 'MPI_ERRORS_RETURN', 

then no error may be indicated.

The reason for this is the performance problems in ensuring that 

all collective routines return the same error value.

N*/

/*N waitstatus

 Notes on the MPI_Status argument:

 The 'MPI_ERROR' field of the status return is only set if 

 the return from the MPI routine is 'MPI_ERR_IN_STATUS'.  That error class

 is only returned by the routines that take an array of status arguments

 ('MPI_Testall', 'MPI_Testsome', 'MPI_Waitall', and 'MPI_Waitsome').  In

 all other cases, the value of the 'MPI_ERROR' field in the status is

 unchanged.  See section 3.2.5 in the MPI-1.1 specification for the 

 exact text.

 For send operations, the only use of status is for 'MPI_Test_cancelled' or

 in the case that there is an error in one of the four routines that 

 may return the error class 'MPI_ERR_IN_STATUS', in which case the 

 'MPI_ERROR' field of status will be set.  In that case, the value 

 will be set to 'MPI_SUCCESS' for any send or receive operation that completed

 successfully, or 'MPI_ERR_PENDING' for any operation which has neither

 failed nor completed.

N*/

-----------------------------------------------------------------------------

MPI-2 deprecated some routines (see 2.6.1)

/*N Deprecated

 Deprecated Function:

 The MPI-2 standard deprecated a number of routines because MPI-2 provides

 better versions.  This routine is one of those that was deprecated.  The

 routine may continue to be used, but new code should use the replacement

 routine.

N*/

-----------------------------------------------------------------------------

/*N Errhandler

    Error handlers:

    The MPI error handler for this routine is taken from 'MPI_COMM_WORLD'.

    For MPI routines that do not have an obvious communicator, file, or

    window object, the MPI standard specifies that the error handler 

    attached to 'MPI_COMM_WORLD' be used.

N*/

-----------------------------------------------------------------------------

This part of the file contains definitions of the MPI error CLASSES for

inclusion in the man pages.  Use .N err name

/*N Errors

Errors:

 All MPI routines (except 'MPI_Wtime' and 'MPI_Wtick') return an error value; 

 C routines as the value of the function and Fortran routines in the last 

 argument.  Before the value is returned, the current MPI error handler is

 called.  By default, this error handler aborts the MPI job.  The error handler

 may be changed with 'MPI_Comm_set_errhandler' (for communicators), 

 'MPI_File_set_errhandler' (for files), and 'MPI_Win_set_errhandler' (for

 RMA windows).  The MPI-1 routine 'MPI_Errhandler_set' may be used but

 its use is deprecated.  The predefined error handler 

 'MPI_ERRORS_RETURN' may be used to cause error values to be returned.

 Note that MPI does `not` guarentee that an MPI program can continue past

 an error; however, MPI implementations will attempt to continue whenever

 possible.

N*/

/*N MPI_SUCCESS

. MPI_SUCCESS - No error; MPI routine completed successfully.

N*/

/*N MPI_ERR_BUFFER

. MPI_ERR_BUFFER - Invalid buffer pointer.  Usually a null buffer where

  one is not valid.

N*/

/*N MPI_ERR_COUNT

. MPI_ERR_COUNT - Invalid count argument.  Count arguments must be 

  non-negative; a count of zero is often valid.

N*/

/*N MPI_ERR_TYPE

. MPI_ERR_TYPE - Invalid datatype argument.  Additionally, this error can

  occur if an uncommitted MPI_Datatype (see 'MPI_Type_commit') is used

  in a communication call.

N*/

/*N MPI_ERR_TAG

.  MPI_ERR_TAG - Invalid tag argument.  Tags must be non-negative; tags

   in a receive ('MPI_Recv', 'MPI_Irecv', 'MPI_Sendrecv', etc.) may

   also be 'MPI_ANY_TAG'.  The largest tag value is available through the 

   the attribute 'MPI_TAG_UB'.

N*/

/*N MPI_ERR_COMM

. MPI_ERR_COMM - Invalid communicator.  A common error is to use a null

  communicator in a call (not even allowed in 'MPI_Comm_rank').

N*/

/*N MPI_ERR_RANK

. MPI_ERR_RANK - Invalid source or destination rank.  Ranks must be between

  zero and the size of the communicator minus one; ranks in a receive

  ('MPI_Recv', 'MPI_Irecv', 'MPI_Sendrecv', etc.) may also be 'MPI_ANY_SOURCE'.

N*/

/*N MPI_ERR_ROOT

. MPI_ERR_ROOT - Invalid root.  The root must be specified as a rank in the

  communicator.  Ranks must be between zero and the size of the communicator 

  minus one.

N*/

/*N MPI_ERR_GROUP

. MPI_ERR_GROUP - Null or invalid group passed to function.  

N*/

/*N MPI_ERR_OP

. MPI_ERR_OP - Invalid operation.  MPI operations (objects of type 'MPI_Op')

  must either be one of the predefined operations (e.g., 'MPI_SUM') or

  created with 'MPI_Op_create'.

N*/

/*N MPI_ERR_TOPOLOGY

. MPI_ERR_TOPOLOGY - Invalid topology.  Either there is no topology 

  associated with this communicator, or it is not the correct type (e.g.,

  'MPI_CART' when expecting 'MPI_GRAPH').

N*/

/*N MPI_ERR_DIMS

. MPI_ERR_DIMS - Invalid dimension argument.  A dimension argument

  is null or its length is less than or equal to zero.

N*/

/*N MPI_ERR_ARG

. MPI_ERR_ARG - Invalid argument.  Some argument is invalid and is not

  identified by a specific error class (e.g., 'MPI_ERR_RANK').

N*/

/*N MPI_ERR_PERM_OP

. MPI_ERR_ARG - Invalid argument; the error code associated with this

  error indicates an attempt to free an MPI permanent operation (e.g., 

  'MPI_SUM').

N*/

/*N MPI_ERR_PERM_KEY

. MPI_ERR_ARG - Invalid argument; the error code associated with this

  error indicates an attempt to free or chnage an MPI permanent keyval (e.g., 

  'MPI_TAG_UB').

N*/

/*N MPI_ERR_UNKNOWN

. MPI_ERR_UNKNOWN - Unknown error.  You should never see this.  If you

  do, report it to 'mpi-bugs@mcs.anl.gov'.

N*/

/*N MPI_ERR_TRUNCATE

. MPI_ERR_TRUNCATE - Message truncated on receive.  The buffer size specified

  was too small for the received message.  This is a recoverable error in

  the MPICH implementation.

N*/

/*N MPI_ERR_OTHER

. MPI_ERR_OTHER - Other error; use 'MPI_Error_string' to get more information

  about this error code. 

N*/

/*N MPI_ERR_KEYVAL

. MPI_ERR_KEYVAL - Invalid keyval

N*/

/*N MPI_ERR_INTERN

.  MPI_ERR_INTERN - An internal error has been detected.  This is fatal.

   Please send a bug report to 'mpi-bugs@mcs.anl.gov'.

N*/

/*N MPI_ERR_EXHAUSTED

.   MPI_ERR_INTERN - This error is returned when some part of the MPICH 

    implementation is unable to acquire memory.  

N*/

/*N MPI_ERR_IN_STATUS

. MPI_ERR_IN_STATUS - The actual error value is in the 'MPI_Status' argument.

  This error class is returned only from the multiple-completion routines

  ('MPI_Testall', 'MPI_Testany', 'MPI_Testsome', 'MPI_Waitall', 'MPI_Waitany',

  and 'MPI_Waitsome').  The field 'MPI_ERROR' in the status argument

  contains the error value or 'MPI_SUCCESS' (no error and complete) or

  'MPI_ERR_PENDING' to indicate that the request has not completed.

  The MPI Standard does not specify what the result of the multiple 

  completion routines is when an error occurs.  For example, in an 

  'MPI_WAITALL', does the routine wait for all requests to either fail or

  complete, or does it return immediately (with the MPI definition of 

  immediately, which means independent of actions of other MPI processes)?

  MPICH has chosen to make the return immediate (alternately, local in MPI 

  terms), and to use the error class 'MPI_ERR_PENDING' (introduced in MPI 1.1)

  to indicate which requests have not completed.  In most cases, only

  one request with an error will be detected in each call to an MPI routine

  that tests multiple requests.  The requests that have not been processed

  (because an error occured in one of the requests) will have their

  'MPI_ERROR' field marked with 'MPI_ERR_PENDING'.

N*/

/*N MPI_ERR_PENDING

. MPI_ERR_PENDING - Pending request (not an error).  See 'MPI_ERR_IN_STATUS'. 

  This value indicates that the request is not complete nor has a encountered

  a detected error.  

N*/

/*N MPI_ERR_REQUEST

. MPI_ERR_REQUEST - Invalid 'MPI_Request'.  Either null or, in the case of a

  'MPI_Start' or 'MPI_Startall', not a persistent request.

N*/

/*N MPI_ERR_BUFFER_ALIAS

.   MPI_ERR_BUFFER - This error class is associcated with an error code that

    indicates that two buffer arguments are `aliased`; that is, the 

    describe overlapping storage (often the exact same storage).  This

    is prohibited in MPI (because it is prohibited by the Fortran 

    standard, and rather than have a separate case for C and Fortran, the

    MPI Forum adopted the more restrictive requirements of Fortran).

N*/

/*N MPI_ERR_PERM_KEY

. MPI_ERR_ARG - This error class is associated with an error code that 

  indicates that an attempt was made to free one of the permanent keys.

N*/

/*N MPI_ERR_PERM_GROUP

. MPI_ERR_ARG - This error class is associated with an error code that 

  indicates that an attempt was made to free one of the permanent groups.

N*/

/*N MPI_ERR_INIT

. MPI_ERR_OTHER - This error class is associated with an error code that 

  indicates that an attempt was made to call 'MPI_INIT' a second time.

  'MPI_INIT' may only be called once in a program.

N*/

/*N MPI_ERR_INFO

. MPI_ERR_INFO - Invalid Info 

N*/

/*N MPI_ERR_INFO_KEY  

. MPI_ERR_INFO_KEY - Invalid or null key string for info.

N*/

/*N MPI_ERR_INFO_VALUE

. MPI_ERR_INFO_VALUE - Invalid or null value string for info

N*/

/*N MPI_ERR_INFO_NOKEY 

. MPI_ERR_INFO_NOKEY - 

N*/

/*N MPI_ERR_NAME

. MPI_ERR_NAME - 

N*/

/*N MPI_ERR_NO_MEM

. MPI_ERR_NO_MEM - Insufficient memory available for allocation by 

  'MPI_Alloc_mem'

N*/

/*N MPI_ERR_NOT_SAME

. MPI_ERR_NOT_SAME - 

N*/

/*N MPI_ERR_PORT

. MPI_ERR_PORT -

N*/

/*N MPI_ERR_QUOTA

. MPI_ERR_QUOTA - 

N*/

/*N MPI_ERR_SERVICE

. MPI_ERR_SERVICE - 

N*/

/*N MPI_ERR_SPAWN

. MPI_ERR_SPAWN -

N*/

/*N MPI_ERR_UNSUPPORTED_OPERATION

. MPI_ERR_UNSUPPORTED_OPERATION - 

N*/

/*N MPI_ERR_WIN

. MPI_ERR_WIN - Invalid MPI window object

N*/

/*N MPI_ERR_BASE

. MPI_ERR_BASE - 

N*/

/*N MPI_ERR_LOCKTYPE

. MPI_ERR_LOCKTYPE - 

N*/

/*N MPI_ERR_RMA_CONFLICT

. MPI_ERR_RMA_CONFLICT - 

N*/

/*N MPI_ERR_RMA_SYNC

. MPI_ERR_RMA_SYNC -

N*/

/*N MPI_ERR_SIZE

. MPI_ERR_SIZE - 

N*/

/*N MPI_ERR_DISP

. MPI_ERR_DISP - 

N*/

/*N MPI_ERR_ASSERT

. MPI_ERR_ASSERT - 

N*/

/* MPI I/O Information */

/*N MPI_ERR_FILE

. MPI_ERR_FILE - Invalid MPI File handle

N*/

/*N MPI_ERR_ACCESS

. MPI_ERR_ACCESS -

N*/

/*N MPI_ERR_AMODE

. MPI_ERR_AMODE - 

N*/

/*N MPI_ERR_BAD_FILE

. MPI_ERR_BAD_FILE - 

N*/

/*N MPI_ERR_FILE_EXISTS

. MPI_ERR_FILE_EXISTS - 

N*/

/*N MPI_ERR_FILE_IN_USE

. MPI_ERR_FILE_IN_USE - 

N*/

/*N MPI_ERR_NO_SPACE

. MPI_ERR_NO_SPACE - 

N*/

/*N MPI_ERR_NO_SUCH_FILE

. MPI_ERR_NO_SUCH_FILE - 

N*/

/*N MPI_ERR_IO

. MPI_ERR_IO - 

N*/

/*N MPI_ERR_READ_ONLY

. MPI_ERR_READ_ONLY - 

N*/

/*N MPI_ERR_CONVERSION

. MPI_ERR_CONVERSION - 

N*/

/*N MPI_ERR_DUP_DATAREP

. MPI_ERR_DUP_DATAREP - 

N*/

/*N MPI_ERR_UNSUPPORTED_DATAREP

. MPI_ERR_UNSUPPORTED_DATAREP - 

N*/

/*N MPI_T_ERR_NOT_INITIALIZED

. MPI_T_ERR_NOT_INITIALIZED - The MPI tool information interface is not initialized.

N*/

/*N MPI_T_ERR_MEMORY

. MPI_T_ERR_MEMORY - The MPI tool information interface is out of memory.

N*/

/*N MPI_T_ERR_CANNOT_INIT

. MPI_T_ERR_CANNOT_INIT - The MPI tool information interface is not in the state to be initialized.

N*/

/*N MPI_T_ERR_INVALID_INDEX

. MPI_T_ERR_INVALID_INDEX - Index is invalid or has been deleted.

N*/

/*N MPI_T_ERR_INVALID_ITEM

. MPI_T_ERR_INVALID_ITEM - Item index queried is out of range.

N*/

/*N MPI_T_ERR_INVALID_NAME

. MPI_T_ERR_INVALID_NAME - The variable or category name is invalid

N*/

/*N MPI_T_ERR_INVALID_HANDLE

. MPI_T_ERR_INVALID_HANDLE - The handle is invalid.

N*/

/*N MPI_T_ERR_OUT_OF_HANDLES

. MPI_T_ERR_OUT_OF_HANDLES - No more handles available.

N*/

/*N MPI_T_ERR_OUT_OF_SESSIONS

. MPI_T_ERR_OUT_OF_SESSIONS - No more sessions available.

N*/

/*N MPI_T_ERR_INVALID_SESSION

. MPI_T_ERR_INVALID_SESSION - Session argument is not valid.

N*/

/*N MPI_T_ERR_CVAR_SET_NOT_NOW

. MPI_T_ERR_CVAR_SET_NOT_NOW - The control variable can not be set at this moment.

N*/

/*N MPI_T_ERR_CVAR_SET_NEVER

. MPI_T_ERR_CVAR_SET_NEVER -  The control variable can not be set until end of execution.

N*/

/*N MPI_T_ERR_PVAR_NO_STARTSTOP

. MPI_T_ERR_PVAR_NO_STARTSTOP - The performance variable can not be started or stopped.

N*/

/*N MPI_T_ERR_PVAR_NO_WRITE

. MPI_T_ERR_PVAR_NO_WRITE - The performance variable can not be written or reset.

N*/

/*N MPI_T_ERR_PVAR_NO_ATOMIC

. MPI_T_ERR_PVAR_NO_ATOMIC - The performance variable can not be read/write atomically.

N*/

/*N NULL

Null Handles:

The MPI 1.1 specification, in the section on opaque objects, explicitly

disallows freeing a null communicator.  The text from the standard is\:

.vb

 A null handle argument is an erroneous IN argument in MPI calls, unless an

 exception is explicitly stated in the text that defines the function. Such

 exception is allowed for handles to request objects in Wait and Test calls

 (sections Communication Completion and Multiple Completions ). Otherwise, a

 null handle can only be passed to a function that allocates a new object and

 returns a reference to it in the handle.

.ve

N*/

/*N COMMNULL

 Because MPI specifies that null objects (e.g., 'MPI_COMM_NULL') are invalid

 as input to MPI routines unless otherwise specified, using 'MPI_COMM_NULL'

 as input to this routine is an error.

N*/

/*N AttrErrReturn

 Return value from attribute callbacks:

 The MPI-2 versions of the attribute callbacks should return either 

 'MPI_SUCCESS' on success or a valid MPI error code or class on failure.

 The MPI standard is ambiguous on this point, but as MPI-2 provides

 the routines 'MPI_Add_error_class' and 'MPI_Add_error_code' that allow the

 user to define and use MPI error codes and classes.

N*/