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_INIT. Consequently, these routines can also use MPI datatypes before MPI_INIT. Therefore, within the context of the MPI tool information interface, it is permissible to use a subset of MPI datatypes as specified below before a call to MPI_INIT (or equivalent).
| MPI_INT |
| MPI_UNSIGNED |
| MPI_UNSIGNED_LONG |
| MPI_UNSIGNED_LONG_LONG |
| MPI_COUNT |
| MPI_CHAR |
| MPI_DOUBLE |
Rationale.
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 14
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_INIT (or equivalent) 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
) and MPI_T_PVAR_GET_INFO
(Section Performance Variables
), 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 (string) |
| INOUT name_len | length of the string and/or buffer for name (integer) |
int MPI_T_enum_get_info(MPI_T_enum enumtype, int *num, char *name, int *name_len)
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) |
int MPI_T_enum_get_item(MPI_T_enum enumtype, int index, int *value, char *name, int *name_len)
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.