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:
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.)
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,
All MPI functions are first specified in the language-independent
notation. Immediately below this, the
ISO C
version of the function
is shown followed by a version of the same function in Fortran and
then the C++ binding.
Fortran in this document refers to Fortran 90; see
Section Language Binding
.
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.
Thus, in C++, IN arguments are
usually
either references or pointers to
const objects.
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.
void copyIntBuffer( int *pin, int *pout, int len )
{ int i;
for (i=0; i<len; ++i) *pout++ = *pin++;
}
then a call to it in the following code fragment has aliased arguments.
int a[10];
copyIntBuffer( a, a+3, 7);
Although the C language allows this, such usage of MPI procedures is
forbidden unless otherwise specified. Note that Fortran prohibits
aliasing of arguments.
Up: Contents
Next: Semantic Terms
Previous: Naming Conventions
Return to MPI-2.1 Standard Index
Return to MPI Forum Home Page
MPI-2.0 of July 1, 2008
HTML Generated on July 6, 2008