MPI_Type_get_envelopeget type envelope
int MPI_Type_get_envelope( MPI_Datatype datatype, int *num_integers, int *num_addresses, int *num_datatypes, int *combiner );
- [in] datatype
- [out] num integers
- [out] num addresses
- [out] num datatypes
- [out] combiner
For the given datatype, MPI_TYPE_GET_ENVELOPE returns information on the number and type of input arguments used in the call that created the datatype. The number-of-arguments values returned can be used to provide sufficiently large arrays in the decoding routine MPI_TYPE_GET_CONTENTS. This call and the meaning of the returned values is described below. The combiner reflects the MPI datatype constructor call that was used in creating datatype.
By requiring that the combiner reflect the constructor used in the creation of the datatype, the decoded information can be used to effectively recreate the calling sequence used in the original creation. One call is effectively the same as another when the information obtained from MPI_TYPE_GET_CONTENTS may be used with either to produce the same outcome. C calls MPI_Type_hindexed and MPI_Type_create_hindexed are always effectively the same while the Fortran call MPI_TYPE_HINDEXED will be different than either of these in some MPI implementations. This is the most useful information and was felt to be reasonable even though it constrains implementations to remember the original constructor sequence even if the internal representation is different.
The decoded information keeps track of datatype duplications. This is
important as one needs to distinguish between a predefined datatype and
a dup of a predefined datatype. The former is a constant object that
cannot be freed, while the latter is a derived datatype that can be
freed. ( End of rationale.)
The list below has the values that can be returned in combiner on the left and the call associated with them on the right.
MPI_COMBINER_NAMEDa named predefined datatype
MPI_COMBINER_HVECTOR_INTEGER MPI_TYPE_HVECTOR from Fortran
MPI_COMBINER_HVECTOR MPI_TYPE_HVECTOR from C or C++
and in some case Fortran
MPI_COMBINER_HINDEXED_INTEGER MPI_TYPE_HINDEXED from Fortran
MPI_COMBINER_HINDEXED MPI_TYPE_HINDEXED from C or C++
and in some case Fortran
MPI_COMBINER_STRUCT_INTEGER MPI_TYPE_STRUCT from Fortran
MPI_COMBINER_STRUCT MPI_TYPE_STRUCT from C or C++
and in some case Fortran
If combiner is MPI_COMBINER_NAMED then datatype is a named predefined datatype.
For calls with address arguments, we sometimes need to differentiate whether the call used an integer or an address size argument. For example, there are two combiners for hvector: MPI_COMBINER_HVECTOR_INTEGER and MPI_COMBINER_HVECTOR. The former is used if it was the MPI-1 call from Fortran, and the latter is used if it was the MPI-1 call from C or C++. However, on systems where MPI_ADDRESS_KIND = MPI_INTEGER_KIND (i.e., where integer arguments and address size arguments are the same), the combiner MPI_COMBINER_HVECTOR may be returned for a datatype constructed by a call to MPI_TYPE_HVECTOR from Fortran. Similarly, MPI_COMBINER_HINDEXED may be returned for a datatype constructed by a call to MPI_TYPE_HINDEXED from Fortran, and MPI_COMBINER_STRUCT may be returned for a datatype constructed by a call to MPI_TYPE_STRUCT from Fortran. On such systems, one need not differentiate constructors that take address size arguments from constructors that take integer arguments, since these are the same. The new MPI-2 calls all use address sized arguments.
For recreating the original call, it is important to know if address information may have been truncated. The MPI-1 calls from Fortran for a few routines could be subject to truncation in the case where the default INTEGER size is smaller than the size of an address.
Notes for FortranAll MPI routines in Fortran (except for MPI_WTIME and MPI_WTICK) have an additional argument ierr at the end of the argument list. ierr is an integer and has the same meaning as the return value of the routine in C. In Fortran, MPI routines are subroutines, and are invoked with the call statement.
All MPI objects (e.g., MPI_Datatype, MPI_Comm) are of type INTEGER in Fortran.
All MPI routines (except MPI_Wtime and MPI_Wtick) return an error value; C routines as the value of the function and Fortran routines in the last argument. Before the value is returned, the current MPI error handler is called. By default, this error handler aborts the MPI job. The error handler may be changed with MPI_Comm_set_errhandler (for communicators), MPI_File_set_errhandler (for files), and MPI_Win_set_errhandler (for RMA windows). The MPI-1 routine MPI_Errhandler_set may be used but its use is deprecated. The predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned. Note that MPI does not guarentee that an MPI program can continue past an error; however, MPI implementations will attempt to continue whenever possible.
- No error; MPI routine completed successfully.
The following sample code illustrates MPI_Type_get_envelope.
Insert code here.