All variables managed through the MPI tool information interface represent their values through typed buffers of a given length and type using an MPI datatype (similar to regular send/receive buffers). Since the initialization of the MPI tool information interface is separate from the initialization of MPI, MPI tool information interface routines can be called before MPI initialization. Consequently, these routines can also use MPI datatypes before MPI initialization. Therefore, within the context of the MPI tool information interface, it is permissible to use a subset of MPI datatypes as specified below before MPI initialization.
Table 19: MPI datatypes that can be used by the MPI tool information interface
| MPI_INT |
| MPI_INT32_T |
| MPI_INT64_T |
| MPI_UNSIGNED |
| MPI_UNSIGNED_LONG |
| MPI_UNSIGNED_LONG_LONG |
| MPI_UINT32_T |
| MPI_UINT64_T |
| MPI_COUNT |
| MPI_CHAR |
| MPI_DOUBLE |
The MPI tool information interface relies mainly on unsigned datatypes for integer values since most variables are expected to represent counters or resource sizes. MPI_INT is provided for additional flexibility and is expected to be used mainly for control variables and enumeration types (see below).
Providing all basic datatypes, in particular providing all signed and
unsigned variants of integer types, would lead to a larger number of types,
which tools need to interpret. This would cause unnecessary complexity in
the implementation of tools based on the MPI tool information interface.
( End of rationale.)
The MPI tool information interface only relies on a subset of the basic
MPI datatypes and does not use any derived MPI datatypes.
Table 19 lists all MPI datatypes that can
be returned by the MPI tool information interface to represent its
variables.
The use of the datatype MPI_CHAR in the MPI tool information interface implies a null-terminated character array, i.e., a string in the C language. If a variable has type MPI_CHAR, the value of the count parameter returned by MPI_T_CVAR_HANDLE_ALLOC and MPI_T_PVAR_HANDLE_ALLOC must be large enough to include any valid value, including its terminating null character. The contents of returned MPI_CHAR arrays are only defined from index 0 through the location of the first null character.
Rationale.
The MPI tool information interface requires a significantly simpler type
system than MPI itself. Therefore, only its required subset must be
present before MPI initialization and MPI implementations do not need
to initialize the complete MPI datatype system.
( End of rationale.)
For variables of type MPI_INT, an MPI implementation can provide
additional information by associating names with a fixed number of values.
We refer to this information in the following as an enumeration. In this
case, the respective calls that provide additional metadata for each
control or performance variable, i.e., MPI_T_CVAR_GET_INFO
(Section Control Variables), MPI_T_PVAR_GET_INFO
(Section Performance Variables), and MPI_T_EVENT_GET_INFO
(Section Events), return a handle of type
MPI_T_enum that can be passed to the
following functions to extract additional information. Thus, the MPI
implementation can describe variables with a fixed set of values that each
represents a particular state. Each enumeration type can have N
different values, with a fixed N that can be queried using
MPI_T_ENUM_GET_INFO.
| MPI_T_ENUM_GET_INFO(enumtype, num, name, name_len) | |
| IN enumtype | enumeration to be queried (handle) |
| OUT num | number of discrete values represented by this enumeration (integer) |
| OUT name | buffer to return the string containing the name of the enumeration item (string) |
| INOUT name_len | length of the string and/or buffer for name (integer) |
If enumtype is a valid enumeration, this routine returns the number of items represented by this enumeration type as well as its name. N must be greater than 0, i.e., the enumeration must represent at least one value.
The arguments name and name_len are used to return the name of the enumeration as described in Section Convention for Returning Strings.
The routine is required to return a name of at least length one. This name must be unique with respect to all other names for enumerations that the MPI implementation uses.
Names associated with individual values in each enumeration enumtype can be queried using MPI_T_ENUM_GET_ITEM.
| MPI_T_ENUM_GET_ITEM(enumtype, index, value, name, name_len) | |
| IN enumtype | enumeration to be queried (handle) |
| IN index | number of the value to be queried in this enumeration (integer) |
| OUT value | variable value (integer) |
| OUT name | buffer to return the string containing the name of the enumeration item (string) |
| INOUT name_len | length of the string and/or buffer for name (integer) |
The arguments name and name_len are used to return the name of the enumeration item as described in Section Convention for Returning Strings.
If completed successfully, the routine returns the name/value pair that describes the enumeration at the specified index. The call is further required to return a name of at least length one. This name must be unique with respect to all other names of items for the same enumeration.