2.5.DATA TYPES 15 The constants that are required to be compile-time constants (and can thus be used for array length declarations and labels in C/C++switch and Fortran case/select state- ments)are: 3 MPI_MAX_PROCESSOR_NAME 4 MPI_MAX_ERROR_STRING MPI_MAX_DATAREP_STRING 6 MPI_MAX_INFO_KEY MPI_MAX_INFO_VAL MPI_MAX_OBJECT_NAME 9 MPI_MAX_PORT_NAME 10 MPI_STATUS_SIZE (Fortran only) 11 MPI_ADDRESS_KIND (Fortran only) 12 MPI_INTEGER_KIND (Fortran only) 13 MPI_OFFSET_KIND (Fortran only) 14 and their C++counterparts where appropriate 公 The constants that cannot be used in initialization expressions or assignments in For- 16 tran are: 17 MPI_BOTTOM 尔 MPI_STATUS_IGNORE 多 MPI_STATUSES_IGNORE 3 MPI_ERRCODES IGNORE MPI_IN_PLACE 品 MPI ARGV NULL 23 MPI ARGVS NULL 24 MPI_UNWEIGHTED 品 26 Advice to implementors.In Fortran the implementation of these special constants may require the use of language constructs that are outside the Fortran standard. 导 Using special values for the constants (e.g.,by defining them through PARAMETER statements)is not possible because an implementation cannot distinguish these val- 吃 ues from legal data.Typically,these constants are implemented as predefined static variables (e.g.,a variable in an MPl-declared COMMON block),relying on the fact that 32 the target compiler passes data by address.Inside the subroutine,this address can 33 be extracted by some mechanism outside the Fortran standard (e.g.,by Fortran ex- 34 tensions or by implementing the function in C).(End of advice to implementors.) 35 喝 2.5.5 Choice 37 保 MPI functions sometimes use arguments with a choice(or union)data type.Distinct calls to the same routine may pass by reference actual arguments of different types.The mecha- % nism for providing such arguments will differ from language to language.For Fortran,the 41 document uses <type>to represent a choice variable;for C and C++,we use void * 42 43 2.5.6 Addresses 名 Some MPI procedures use address arguments that represent an absolute address in the 45 calling program.The datatype of such an argument is MPI_Aint in C,MPl:Aint in C+ 46 47 and INTEGER (KIND=MPI_ADDRESS_KIND)in Fortran.These types must have the same
2.5. DATA TYPES 15 The constants that are required to be compile-time constants (and can thus be used for array length declarations and labels in C/C++ switch and Fortran case/select statements) are: MPI_MAX_PROCESSOR_NAME MPI_MAX_ERROR_STRING MPI_MAX_DATAREP_STRING MPI_MAX_INFO_KEY MPI_MAX_INFO_VAL MPI_MAX_OBJECT_NAME MPI_MAX_PORT_NAME MPI_STATUS_SIZE (Fortran only) MPI_ADDRESS_KIND (Fortran only) MPI_INTEGER_KIND (Fortran only) MPI_OFFSET_KIND (Fortran only) and their C++ counterparts where appropriate. The constants that cannot be used in initialization expressions or assignments in Fortran are: MPI_BOTTOM MPI_STATUS_IGNORE MPI_STATUSES_IGNORE MPI_ERRCODES_IGNORE MPI_IN_PLACE MPI_ARGV_NULL MPI_ARGVS_NULL MPI_UNWEIGHTED Advice to implementors. In Fortran the implementation of these special constants may require the use of language constructs that are outside the Fortran standard. Using special values for the constants (e.g., by defining them through PARAMETER statements) is not possible because an implementation cannot distinguish these values from legal data. Typically, these constants are implemented as predefined static variables (e.g., a variable in an MPI-declared COMMON block), relying on the fact that the target compiler passes data by address. Inside the subroutine, this address can be extracted by some mechanism outside the Fortran standard (e.g., by Fortran extensions or by implementing the function in C). (End of advice to implementors.) 2.5.5 Choice MPI functions sometimes use arguments with a choice (or union) data type. Distinct calls to the same routine may pass by reference actual arguments of different types. The mechanism for providing such arguments will differ from language to language. For Fortran, the document uses <type> to represent a choice variable; for C and C++, we use void *. 2.5.6 Addresses Some MPI procedures use address arguments that represent an absolute address in the calling program. The datatype of such an argument is MPI_Aint in C, MPI::Aint in C++ and INTEGER (KIND=MPI_ADDRESS_KIND) in Fortran. These types must have the same 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
16 CHAPTER 2.MPI TERMS AND CONVENTIONS width and encode address values in the same manner such that address values in one language may be passed directly to another language without conversion.There is the MPl 3 constant MPI_BOTTOM to indicate the start of the address range. 5 2.5.7 File Offsets 7 For I/O there is a need to give the size,displacement,and offset into a file.These quantities can easily be larger than 32 bits which can be the default size of a Fortran integer.To overcome this,these quantities are declared to be INTEGER (KIND=MPI_OFFSET_KIND)in Fortran.In C one uses MPI_Offset whereas in C++one uses MPl::Offset.These types 11 must have the same width and encode address values in the same manner such that offset 12 values in one language may be passed directly to another language without conversion. 13 14 2.6 Language Binding 15 16 This section defines the rules for MPI language binding in general and for Fortran,ISO 17 C,and C++,in particular.(Note that ANSI C has been replaced by ISO C.)The C++ 18 language bindings have been deprecated.Defined here are various object representations, 19 as well as the naming conventions used for expressing this standard.The actual calling 20 sequences are defined elsewhere. 21 MPI bindings are for Fortran 90,though they are designed to be usable in Fortran 77 22 environments. 23 Since the word PARAMETER is a keyword in the Fortran language,we use the word 24 "argument"to denote the arguments to a subroutine.These are normally referred to 25 as parameters in C and C++,however,we expect that C and C++programmers will 26 understand the word "argument"(which has no specific meaning in C/C++),thus allowing 27 us to avoid unnecessary confusion for Fortran programmers. 28 Since Fortran is case insensitive,linkers may use either lower case or upper case when 29 resolving Fortran names.Users of case sensitive languages should avoid the "mpi_"and 30 “pmpi_"prefixes. 31 32 2.6.1 Deprecated Names and Functions 33 34 A number of chapters refer to deprecated or replaced MPl-1 constructs.These are constructs 35 that continue to be part of the MPI standard,as documented in Chapter 15,but that users 36 are recommended not to continue using,since better solutions were provided with MPl-2. 37 For example,the Fortran binding for MPl-1 functions that have address arguments uses 38 INTEGER.This is not consistent with the C binding,and causes problems on machines with 39 32 bit INTEGERs and 64 bit addresses.In MPl-2,these functions were given new names with new bindings for the address arguments.The use of the old functions is deprecated.For 41 consistency,here and in a few other cases,new C functions are also provided,even though 42 the new functions are equivalent to the old functions.The old names are deprecated. 43 Another example is provided by the MPl-1 predefined datatypes MPI_UB and MPI_LB.They are deprecated,since their use is awkward and error-prone.The MPl-2 function 45 MPI_TYPE_CREATE_RESIZED provides a more convenient mechanism to achieve the same 46 effect. 47 Table 2.1 shows a list of all of the deprecated constructs.Note that the constants 48 MPI_LB and MPI_UB are replaced by the function MPI_TYPE_CREATE_RESIZED;this is
16 CHAPTER 2. MPI TERMS AND CONVENTIONS width and encode address values in the same manner such that address values in one language may be passed directly to another language without conversion. There is the MPI constant MPI_BOTTOM to indicate the start of the address range. 2.5.7 File Offsets For I/O there is a need to give the size, displacement, and offset into a file. These quantities can easily be larger than 32 bits which can be the default size of a Fortran integer. To overcome this, these quantities are declared to be INTEGER (KIND=MPI_OFFSET_KIND) in Fortran. In C one uses MPI_Offset whereas in C++ one uses MPI::Offset. These types must have the same width and encode address values in the same manner such that offset values in one language may be passed directly to another language without conversion. 2.6 Language Binding This section defines the rules for MPI language binding in general and for Fortran, ISO C, and C++, in particular. (Note that ANSI C has been replaced by ISO C.) The C++ language bindings have been deprecated. Defined here are various object representations, as well as the naming conventions used for expressing this standard. The actual calling sequences are defined elsewhere. MPI bindings are for Fortran 90, though they are designed to be usable in Fortran 77 environments. Since the word PARAMETER is a keyword in the Fortran language, we use the word “argument” to denote the arguments to a subroutine. These are normally referred to as parameters in C and C++, however, we expect that C and C++ programmers will understand the word “argument” (which has no specific meaning in C/C++), thus allowing us to avoid unnecessary confusion for Fortran programmers. Since Fortran is case insensitive, linkers may use either lower case or upper case when resolving Fortran names. Users of case sensitive languages should avoid the “mpi_” and “pmpi_” prefixes. 2.6.1 Deprecated Names and Functions A number of chapters refer to deprecated or replaced MPI-1 constructs. These are constructs that continue to be part of the MPI standard, as documented in Chapter 15, but that users are recommended not to continue using, since better solutions were provided with MPI-2. For example, the Fortran binding for MPI-1 functions that have address arguments uses INTEGER. This is not consistent with the C binding, and causes problems on machines with 32 bit INTEGERs and 64 bit addresses. In MPI-2, these functions were given new names with new bindings for the address arguments. The use of the old functions is deprecated. For consistency, here and in a few other cases, new C functions are also provided, even though the new functions are equivalent to the old functions. The old names are deprecated. Another example is provided by the MPI-1 predefined datatypes MPI_UB and MPI_LB. They are deprecated, since their use is awkward and error-prone. The MPI-2 function MPI_TYPE_CREATE_RESIZED provides a more convenient mechanism to achieve the same effect. Table 2.1 shows a list of all of the deprecated constructs. Note that the constants MPI_LB and MPI_UB are replaced by the function MPI_TYPE_CREATE_RESIZED; this is 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
2.6.LANGUAGE BINDING 17 because their principal use was as input datatypes to MPl_TYPE_STRUCT to create resized datatypes.Also note that some C typedefs and Fortran subroutine names are included in this list;they are the types of callback functions. 4 Deprecated MPI-2 Replacement 5 MPI_ADDRESS MPI_GET_ADDRESS 6 MPI_TYPE_HINDEXED MPI_TYPE_CREATE_HINDEXED MPI_TYPE_HVECTOR MPI_TYPE_CREATE_HVECTOR MPI_TYPE_STRUCT MPI_TYPE_CREATE_STRUCT MPI_TYPE_EXTENT MPI_TYPE_GET_EXTENT 10 MPI_TYPE_UB MPI_TYPE_GET_EXTENT MPI_TYPE_LB MPI_TYPE_GET_EXTENT MPI_LB MPI_TYPE_CREATE_RESIZED 的 MPI_UB MPI_TYPE_CREATE_RESIZED 14 MPI_ERRHANDLER_CREATE MPI_COMM_CREATE_ERRHANDLER MPI_ERRHANDLER_GET MPI_COMM_GET_ERRHANDLER MPI_ERRHANDLER_SET MPI_COMM_SET_ERRHANDLER 么 MPI Handler_function MPI_Comm_errhandler_function MPI_KEYVAL_CREATE MPI_COMM_CREATE_KEYVAL 19 MPI_KEYVAL_FREE MPI_COMM_FREE_KEYVAL 20 MPI_DUP_FN MPI_COMM_DUP_FN 总 MPI_NULL_COPY_FN MPI_COMM_NULL_COPY_FN 22 MPI_NULL_DELETE_FN MPI_COMM_NULL_DELETE_FN 23 MPI_Copy_function MPI_Comm_copy_attr_function 24 COPY_FUNCTION COMM_COPY_ATTR_FN 25 MPI_Delete_function MPI_Comm_delete_attr_function 26 DELETE_FUNCTION COMM_DELETE_ATTR_FN 27 MPI_ATTR_DELETE MPI_COMM_DELETE_ATTR 28 MPI_ATTR_GET MPI_COMM_GET_ATTR 多 MPI_ATTR_PUT MPI_COMM_SET_ATTR 吃 绵 32 Table 2.1:Deprecated constructs 33 34 2.6.2 Fortran Binding Issues 客 36 Originally,MPl-1.1 provided bindings for Fortran 77.These bindings are retained,but they 37 are now interpreted in the context of the Fortran 90 standard.MPI can still be used with g most Fortran 77 compilers,as noted below.When the term Fortran is used it means Fortran 吃 90. % All MPI names have an MPI_prefix,and all characters are capitals.Programs must 41 not declare variables,parameters,or functions with names beginning with the prefix MPI. 42 To avoid conflicting with the profiling interface,programs should also avoid functions with 43 the prefix PMPI_.This is mandated to avoid possible name collisions. All MPI Fortran subroutines have a return code in the last argument.A few MPI operations which are functions do not have the return code argument.The return code value 6 for successful completion is MPI_SUCCESS.Other error codes are implementation dependent; 47 see the error codes in Chapter 8 and Annex A. 48
2.6. LANGUAGE BINDING 17 because their principal use was as input datatypes to MPI_TYPE_STRUCT to create resized datatypes. Also note that some C typedefs and Fortran subroutine names are included in this list; they are the types of callback functions. Deprecated MPI-2 Replacement MPI_ADDRESS MPI_GET_ADDRESS MPI_TYPE_HINDEXED MPI_TYPE_CREATE_HINDEXED MPI_TYPE_HVECTOR MPI_TYPE_CREATE_HVECTOR MPI_TYPE_STRUCT MPI_TYPE_CREATE_STRUCT MPI_TYPE_EXTENT MPI_TYPE_GET_EXTENT MPI_TYPE_UB MPI_TYPE_GET_EXTENT MPI_TYPE_LB MPI_TYPE_GET_EXTENT MPI_LB MPI_TYPE_CREATE_RESIZED MPI_UB MPI_TYPE_CREATE_RESIZED MPI_ERRHANDLER_CREATE MPI_COMM_CREATE_ERRHANDLER MPI_ERRHANDLER_GET MPI_COMM_GET_ERRHANDLER MPI_ERRHANDLER_SET MPI_COMM_SET_ERRHANDLER MPI_Handler_function MPI_Comm_errhandler_function MPI_KEYVAL_CREATE MPI_COMM_CREATE_KEYVAL MPI_KEYVAL_FREE MPI_COMM_FREE_KEYVAL MPI_DUP_FN MPI_COMM_DUP_FN MPI_NULL_COPY_FN MPI_COMM_NULL_COPY_FN MPI_NULL_DELETE_FN MPI_COMM_NULL_DELETE_FN MPI_Copy_function MPI_Comm_copy_attr_function COPY_FUNCTION COMM_COPY_ATTR_FN MPI_Delete_function MPI_Comm_delete_attr_function DELETE_FUNCTION COMM_DELETE_ATTR_FN MPI_ATTR_DELETE MPI_COMM_DELETE_ATTR MPI_ATTR_GET MPI_COMM_GET_ATTR MPI_ATTR_PUT MPI_COMM_SET_ATTR Table 2.1: Deprecated constructs 2.6.2 Fortran Binding Issues Originally, MPI-1.1 provided bindings for Fortran 77. These bindings are retained, but they are now interpreted in the context of the Fortran 90 standard. MPI can still be used with most Fortran 77 compilers, as noted below. When the term Fortran is used it means Fortran 90. All MPI names have an MPI_ prefix, and all characters are capitals. Programs must not declare variables, parameters, or functions with names beginning with the prefix MPI_. To avoid conflicting with the profiling interface, programs should also avoid functions with the prefix PMPI_. This is mandated to avoid possible name collisions. All MPI Fortran subroutines have a return code in the last argument. A few MPI operations which are functions do not have the return code argument. The return code value for successful completion is MPI_SUCCESS. Other error codes are implementation dependent; see the error codes in Chapter 8 and Annex A. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
18 CHAPTER 2.MPI TERMS AND CONVENTIONS Constants representing the maximum length of a string are one smaller in Fortran than in C and C++as discussed in Section 16.3.9. 3 Handles are represented in Fortran as INTEGERs.Binary-valued variables are of type LOGICAL. 5 Array arguments are indexed from one. 6 The MPI Fortran binding is inconsistent with the Fortran 90 standard in several re- 7 spects.These inconsistencies,such as register optimization problems,have implications for 8 user codes that are discussed in detail in Section 16.2.2.They are also inconsistent with 9 Fortran 77. 11 2.6.3 C Binding Issues 12 13 We use the ISO C declaration format.All MPI names have an MPI_prefix,defined constants 14 are in all capital letters,and defined types and functions have one capital letter after the 15 prefix.Programs must not declare variables or functions with names beginning with the 16 prefix MPI_.To support the profiling interface,programs should not declare functions with 17 names beginning with the prefix PMPI_. The definition of named constants,function prototypes,and type definitions must be 19 supplied in an include file mpi.h. 20 Almost all C functions return an error code.The successful return code will be MPI_SUCCESS,but failure return codes are implementation dependent. 22 Type declarations are provided for handles to each category of opaque objects. 23 Array arguments are indexed from zero. 24 Logical flags are integers with value 0 meaning "false"and a non-zero value meaning 25 “true.” 26 Choice arguments are pointers of type void * Address arguments are of MPI defined type MPl_Aint.File displacements are of type 28 MPL_Offset.MPI_Aint is defined to be an integer of the size needed to hold any valid address 29 on the target architecture.MPl_Offset is defined to be an integer of the size needed to hold 30 any valid file size on the target architecture. 31 32 2.6.4 C++Binding Issues 33 The C++language bindings have been deprecated.There are places in the standard that 34 give rules for C and not for C++.In these cases,the C rule should be applied to the C++ 35 case,as appropriate.In particular,the values of constants given in the text are the ones 36 for C and Fortran.A cross index of these with the C++names is given in Annex A. 37 We use the ISO C++declaration format.All MPI names are declared within the scope 38 of a namespace called MPI and therefore are referenced with an MPI:prefix.Defined 39 constants are in all capital letters,and class names,defined types,and functions have only 40 their first letter capitalized.Programs must not declare variables or functions in the MPI 41 42 namespace.This is mandated to avoid possible name collisions. The definition of named constants,function prototypes,and type definitions must be 43 supplied in an include file mpi.h. 44 45 Advice to implementors.The file mpi.h may contain both the C and C++defini- 6 tions.Usually one can simply use the defined value(generally__cplusplus,but not 47 required)to see if one is using C++to protect the C++definitions.It is possible 48
18 CHAPTER 2. MPI TERMS AND CONVENTIONS Constants representing the maximum length of a string are one smaller in Fortran than in C and C++ as discussed in Section 16.3.9. Handles are represented in Fortran as INTEGERs. Binary-valued variables are of type LOGICAL. Array arguments are indexed from one. The MPI Fortran binding is inconsistent with the Fortran 90 standard in several respects. These inconsistencies, such as register optimization problems, have implications for user codes that are discussed in detail in Section 16.2.2. They are also inconsistent with Fortran 77. 2.6.3 C Binding Issues We use the ISO C declaration format. All MPI names have an MPI_ prefix, defined constants are in all capital letters, and defined types and functions have one capital letter after the prefix. Programs must not declare variables or functions with names beginning with the prefix MPI_. To support the profiling interface, programs should not declare functions with names beginning with the prefix PMPI_. The definition of named constants, function prototypes, and type definitions must be supplied in an include file mpi.h. Almost all C functions return an error code. The successful return code will be MPI_SUCCESS, but failure return codes are implementation dependent. Type declarations are provided for handles to each category of opaque objects. Array arguments are indexed from zero. Logical flags are integers with value 0 meaning “false” and a non-zero value meaning “true.” Choice arguments are pointers of type void *. Address arguments are of MPI defined type MPI_Aint. File displacements are of type MPI_Offset. MPI_Aint is defined to be an integer of the size needed to hold any valid address on the target architecture. MPI_Offset is defined to be an integer of the size needed to hold any valid file size on the target architecture. 2.6.4 C++ Binding Issues 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 A. 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. Advice to implementors. 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 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
2.6.LANGUAGE BINDING 19 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 3 mpi.h file.(End of advice to implementors.) 5 C++functions that create objects or return information usually place the object or 6 information in the return value.Since the language neutral prototypes of MPl functions include the C++return value as an OUT parameter,semantic descriptions of MPl functions refer to the C++return value by that parameter name.The remaining C++functions 9 return void. 10 In some circumstances,MPI permits users to indicate that they do not want a return 11 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 13 two bindings where one has the optional argument and one does not. 14 C++functions do not return error codes.If the default error handler has been set 15 to MPl::ERRORS_THROW_EXCEPTIONS,the C++exception mechanism is used to signal an error by throwing an MPl:Exception object. 17 It should be noted that the default error handler (i.e.,MPI::ERRORS_ARE_FATAL)on a 18 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; 2 the returned error will be handled by the MPl implementation by invoking the appropriate 23 error handler. 24 25 Advice to users.C++programmers that want to handle MPl errors on their own 26 should use the MPl::ERRORS_THROW_EXCEPTIONS error handler,rather than 27 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.) 品 吃 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. 32 Array arguments are indexed from zero. 33 Logical flags are of type bool. 34 Choice arguments are pointers of type void * 35 Address arguments are of MPl-defined integer type MPl:Aint,defined to be an integer 6 of the size needed to hold any valid address on the target architecture.Analogously, 吃 MPl::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 0 within the MPI namespace.For example,MPI_DATATYPE becomes MPI:Datatype. 41 The names of MPI functions generally follow the naming rules given.In some circum- 42 stances,the MPl function is related to a function defined already for MPl-1 with a name 43 that does not follow the naming conventions.In this circumstance,the language neutral 44 name is in analogy to the MPl name even though this gives an MPl-2 name that violates the naming conventions.The C and Fortran names are the same as the language neutral name 46 in this case.However,the C++names do reflect the naming rules and can differ from the C 47 and Fortran names.Thus,the analogous name in C++to the MPl name may be different 48
2.6. LANGUAGE BINDING 19 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.) 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. 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. Advice to users. 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.) 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 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 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48