The C++ language bindings have been deprecated.
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 Language Bindings Summary
.
We use the
ISO 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.
The file mpi.h may contain both the C and C++ definitions.
Usually one can simply use the defined value (generally __cplusplus,
but not required) to see if one is using
C++ to protect the C++ definitions. It is possible that a C compiler
will require that the source protected this way be legal C code. In
this case, all the C++ definitions can be placed in a different
include file and the ``#include'' directive can be used to include the
necessary C++ definitions in the mpi.h file.
( End of advice to implementors.)
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.
C++ programmers that want to handle MPI errors on their own should
use the MPI::ERRORS_THROW_EXCEPTIONS error handler, rather
than MPI::ERRORS_RETURN, that is used for that purpose in
C. Care should be taken using exceptions in mixed language
situations.
( End of advice to users.)
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
MPI function is related to a function defined already for MPI-1
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-2 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
do reflect the naming rules and can differ from the C and
Fortran names. Thus, the analogous name in C++ to the
MPI name may be
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(); (binding deprecated, see Section Deprecated since MPI-2.2
)}
would look like the following:
The C++ bindings presented in Annex C++ Bindings (deprecated)
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.
Advice
to implementors.
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.
The remaining C++ functions return void.
Advice to users.
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.
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)
1. All functions, types, and constants are declared within the
scope of a namespace called MPI.
2. Arrays of MPI handles are always left in the argument list
(whether they are IN or OUT arguments).
3. If the argument list of an MPI function contains a scalar IN
handle, and it makes sense to define the function as a method of the
object corresponding to that handle, the function is made a member
function of the corresponding MPI class.
The member functions are named according to the corresponding MPI
function name, but without the `` MPI_'' prefix and without
the object name prefix (if applicable). In addition:
1. The scalar IN handle is dropped from the argument list, and
this corresponds to the dropped argument.
2. The function is declared const.
4. MPI functions are made into class functions (static) when they
belong on a class but do not have a unique scalar IN or INOUT
parameter of that class.
5. If the argument list contains a single OUT argument that is
not of type MPI_STATUS (or an array), that argument is
dropped from the list and the function returns that value.
Example
The C++ binding for MPI_COMM_SIZE is
int MPI::Comm::Get_size(void) const.
6. If there are multiple OUT arguments in the argument list, one
is chosen as the return value and is removed from the list.
7. If the argument list does not contain any OUT arguments,
the function returns void.
Example
The C++ binding for MPI_REQUEST_FREE is
void MPI::Request::Free(void)
8. MPI functions to which the above rules do not apply are not
members of any class, but are defined in the MPI namespace.
Example
The C++ binding for MPI_BUFFER_ATTACH is
void MPI::Attach_buffer(void* buffer, int size).
9. All class names, defined types, and function names have only
their first letter capitalized. Defined constants are in all
capital letters.
10. Any IN pointer, reference, or array argument must be declared
const.
11. Handles are passed by reference.
12. Array arguments are denoted with square brackets ( []), not
pointers, as this is more semantically precise.
Up: Language Binding
Next: Functions and Macros
Previous: C Binding Issues
Return to MPI-2.2 Standard Index
Return to MPI Forum Home Page
(Unofficial) MPI-2.2 of September 4, 2009
HTML Generated on September 10, 2009