There are places in the standard that give rules for C and not for C++. In these cases, the C rule should be applied to the C++ case, as appropriate. In particular, the values of constants given in the text are the ones for C and Fortran. A cross index of these with the C++ names is given in Annex A.
We use the ANSI C++ declaration format. All MPI-/ names are declared within the scope of a namespace called MPI and therefore are referenced with an MPI:: prefix. Defined constants are in all capital letters, and class names, defined types, and functions have only their first letter capitalized. Programs must not declare variables or functions in the MPI namespace. This is mandated to avoid possible name collisions.
The definition of named constants, function prototypes, and type definitions must be supplied in an include file mpi.h.
C++ functions that create objects or return information usually place
the object or information in the return value. Since the language
neutral prototypes of MPI-/ functions include the C++ return value as
an OUT parameter, semantic descriptions of MPI-/ functions refer to
the C++ return value by that parameter name (see
Section B.13.5 on page ).
The remaining C++ functions return void.
In some circumstances, MPI-/ permits users to indicate that they do not want a return value. For example, the user may indicate that the status is not filled in. Unlike C and Fortran where this is achieved through a special input value, in C++ this is done by having two bindings where one has the optional argument and one does not.
C++ functions do not return error codes. If the default error handler has been set to MPI::ERRORS_THROW_EXCEPTIONS, the C++ exception mechanism is used to signal an error by throwing an MPI::Exception object.
It should be noted that the default error handler (i.e., MPI::ERRORS_ARE_FATAL) on a given type has not changed. User error handlers are also permitted. MPI::ERRORS_RETURN simply returns control to the calling function; there is no provision for the user to retrieve the error code.
User callback functions that return integer error codes should not throw exceptions; the returned error will be handled by the MPI-/ implementation by invoking the appropriate error handler.
Opaque object handles must be objects in themselves, and have the assignment and equality operators overridden to perform semantically like their C and Fortran counterparts.
Array arguments are indexed from zero.
Logical flags are of type bool.
Choice arguments are pointers of type void *.
Address arguments are of MPI-/-defined integer type MPI::Aint, defined to be an integer of the size needed to hold any valid address on the target architecture. Analogously, MPI::Offset is an integer to hold file offsets.
Most MPI-/ functions are methods of MPI-/ C++ classes. MPI-/ class names are generated from the language neutral MPI-/ types by dropping the MPI_ prefix and scoping the type within the MPI namespace. For example, MPI_DATATYPE becomes MPI::Datatype.
The names of MPI-// functions generally follow the naming rules given. In some circumstances, the new MPI-// function is related to an MPI-/ function with a name that does not follow the naming conventions. In this circumstance, the language neutral name is in analogy to the MPI-/ name even though this gives an MPI-// name that violates the naming conventions. The C and Fortran names are the same as the language neutral name in this case. However, the C++ names for MPI-/ do reflect the naming rules and can differ from the C and Fortran names. Thus, the analogous name in C++ to the MPI-/ name is different than the language neutral name. This results in the C++ name differing from the language neutral name. An example of this is the language neutral name of MPI_FINALIZED and a C++ name of MPI::Is_finalized.
In C++, function typedefs are made publicly within appropriate classes. However, these declarations then become somewhat cumbersome, as with the following:
typedef MPI::Grequest::Query_function();
would look like the following:
namespace MPI { class Request { // ... }; class Grequest : public MPI::Request { // ... typedef Query_function(void* extra_state, MPI::Status& status); }; };Rather than including this scaffolding when declaring C++ typedefs, we use an abbreviated form. In particular, we explicitly indicate the class and namespace scope for the typedef of the function. Thus, the example above is shown in the text as follows:
typedef int MPI::Grequest::Query_function(void* extra_state, MPI::Status& status)
The C++ bindings presented in Annex B and throughout this document were generated by applying a simple set of name generation rules to the MPI-/ function specifications. While these guidelines may be sufficient in most cases, they may not be suitable for all situations. In cases of ambiguity or where a specific semantic statement is desired, these guidelines may be superseded as the situation dictates.
MPI-Standard for MARMOT