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*/