3.3. Procedure Specification

PreviousUpNext
Up: MPI Terms and Conventions Next: Semantic Terms Previous: Naming Conventions

MPI procedures are specified using a language-independent notation. The arguments of procedure calls are marked as IN, OUT, or INOUT. The meanings of these are:

IN:
the call may use the input value but does not update the argument from the perspective of the caller at any time during the call's execution,
OUT:
the call may update the argument but does not use its input value,
INOUT:
the call may both use and update the argument.

There is one special case---if an argument is a handle to an opaque object (these terms are defined in Section Opaque Objects), and the object is updated by the procedure call, then the argument is marked INOUT or OUT. It is marked this way even though the handle itself is not modified---we use the INOUT or OUT attribute to denote that what the handle references is updated.


Rationale.

The definition of MPI tries to avoid, to the largest possible extent, the use of INOUT arguments, because such use is error-prone, especially for scalar arguments. ( End of rationale.)
MPI's use of IN, OUT, and INOUT is intended to indicate to the user how an argument is to be used, but does not provide a rigorous classification that can be translated directly into all language bindings (e.g., INTENT in Fortran 90 bindings or const in C bindings). For instance, the ``constant'' MPI_BOTTOM can usually be passed to OUT buffer arguments. Similarly, MPI_STATUS_IGNORE can be passed as the OUT status argument.

A common occurrence for MPI functions is an argument that is used as IN by some processes and OUT by other processes. Such an argument is, syntactically, an INOUT argument and is marked as such, although, semantically, it is not used in one call both for input and for output on a single process.

Another frequent situation arises when an argument value is needed only by a subset of the processes. When an argument is not significant at a process then an arbitrary value can be passed as an argument.

Unless specified otherwise, an argument of type OUT or type INOUT cannot be aliased with any other argument passed to an MPI procedure. An example of argument aliasing in C appears below. If we define a C procedure like this,

Image file

then a call to it in the following code fragment has aliased arguments.

Image file

Although the C language allows this, such usage of MPI procedures is forbidden unless otherwise specified. Note that Fortran prohibits aliasing of arguments.

All MPI functions are first specified in the language-independent notation. Immediately below this, language dependent bindings follow:


Some MPI procedures have two interfaces for a given language support; see Sections Absolute Addresses and Relative Address Displacements and Counts.

An exception is Section The MPI Tool Information Interface ``The MPI Tool Information Interface'', which only provides ISO C interfaces.

``Fortran'' in this document refers to Fortran 90 or later; see Section Language Binding.

The words function, routine, procedure, procedure call, and call are often used as synonyms within this standard.


PreviousUpNext
Up: MPI Terms and Conventions Next: Semantic Terms Previous: Naming Conventions


Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023