MPI manages system memory that is used for buffering messages and for storing internal representations of various MPI objects such as groups, communicators, datatypes, etc. This memory is not directly accessible to the user, and objects stored there are opaque: their size and shape is not visible to the user. Opaque objects are accessed via handles, which exist in user space. MPI procedures that operate on opaque objects are passed handle arguments to access these objects. In addition to their use by MPI calls for object access, handles can participate in assignments and comparisons.
In Fortran with USE mpi or (deprecated) INCLUDE 'mpif.h', all handles have type INTEGER. In Fortran with USE mpi_f08, and in C, a different handle type is defined for each category of objects. With Fortran USE mpi_f08, the handles are defined as Fortran BIND(C) derived types that consist of only one element INTEGER :: MPI_VAL. The internal handle value is identical to the Fortran INTEGER value used in the mpi module and (deprecated) mpif.h. The operators .EQ., .NE., == and /= are overloaded to allow the comparison of these handles. The type names are identical to the names in C, except that they are not case sensitive. For example:
The C types must support the use of the assignment and equality operators.
Advice
to implementors.
In Fortran, the handle can be an index into a table of opaque objects
in a system table; in C it can be such an index or a pointer to the
object.
( End of advice to implementors.)
Rationale.
Since the Fortran integer values are equivalent, applications can easily
convert MPI handles between all three supported Fortran methods. For
example, an integer communicator handle COMM can be converted directly
into an exactly equivalent mpi_f08 communicator handle named comm_f08
by comm_f08%MPI_VAL=COMM, and vice versa.
The use of the INTEGER defined handles and the
BIND(C) derived type handles is different:
Fortran 2003 (and later) define that BIND(C) derived types
can be used within user defined common blocks, but it is up to
the rules of the companion C compiler how many numerical storage units
are used for these BIND(C) derived type handles.
Most compilers use one unit for both, the INTEGER handles and the handles defined as
BIND(C) derived types.
( End of rationale.)
Advice to users.
If a user wants to substitute the mpi module or the (deprecated) mpif.h
by the mpi_f08 module and the
application program stores a handle in a Fortran common block
then it is necessary to change the Fortran support method
in all application routines that use this common block,
because the number of numerical storage units of such a handle
can be different in the two modules.
( End of advice to users.)
Opaque objects are allocated and deallocated
by calls that are specific to each object type.
These are listed in the sections where the objects are described.
The calls accept a handle argument of matching type.
In an allocate call this is an OUT argument that
returns a valid reference to the object.
In a call to deallocate this is an INOUT argument that returns
with an ``invalid handle'' value.
MPI provides an ``invalid handle'' constant
for each object type. Comparisons to this constant are used to test for
validity of the handle.
A call to a deallocate routine invalidates the handle and marks the object for deallocation. The object is not accessible to the user after the call. However, MPI need not deallocate the object immediately. Any operation pending (at the time of the deallocate) and decoupled MPI activity (see Section Progress) that involves this object will complete normally; the object will be deallocated afterwards.
An opaque object and its handle are significant only at the process where the object was created and cannot be transferred to another process.
MPI provides certain predefined opaque objects and predefined, static handles to these objects. The user must not free such objects.
Rationale.
This design hides the internal representation used for MPI data structures, thus allowing similar calls in C and Fortran. It also avoids conflicts with the typing rules in these languages, and easily allows future extensions of functionality. The mechanism for opaque objects used here loosely follows the POSIX Fortran binding standard.
The explicit separation of handles in user space and objects in system space allows space-reclaiming and deallocation calls to be made at appropriate points in the user program. If the opaque objects were in user space, one would have to be very careful not to go out of scope before any pending operation requiring that object completed. The specified design allows an object to be marked for deallocation, the user program can then go out of scope, and the object itself still persists until any pending operations are complete.
The requirement that handles support
assignment/comparison is made since
such operations are common.
This restricts the domain of possible implementations.
The alternative in C would have been
to allow handles to have been an arbitrary, opaque type. This would
force the introduction of routines to do assignment and comparison, adding
complexity, and was therefore ruled out.
In Fortran, the handles are defined such that assignment and comparison
are available through the operators of the language or overloaded
versions of these operators.
( End of rationale.)
Advice to users.
A user may accidentally create a dangling reference by assigning to a
handle the value of another handle, and then deallocating the object
associated with these handles. Conversely, if a handle variable is
deallocated before the associated object is freed, then the object
becomes inaccessible (this may occur, for example, if the handle is a
local variable within a subroutine, and the subroutine is exited
before the associated object is deallocated). It is the user's
responsibility to avoid adding or deleting references to opaque
objects, except as a result of MPI calls that allocate or deallocate
such objects.
( End of advice to users.)
Advice
to implementors.
The intended semantics of opaque objects is that opaque objects are separate
from one another; each call to allocate such an object copies all the information
required for the object. Implementations may avoid excessive copying by
substituting referencing for copying. For example, a derived datatype
may contain
references to its components, rather than copies of its components; a call to
MPI_COMM_GROUP may return a reference to the group associated with
the communicator, rather than a copy of this group. In such cases, the
implementation must maintain reference counts, and allocate and deallocate
objects in such a way that the visible effect is as if the objects were copied.
( End of advice to implementors.)