The MPI Tool Information Interface (MPI-T), new in MPI-3, provides a way for MPI implementations to expose parameter or measurement variables that may be useful for performance tuning or debugging. An even more advanced use is for applications that control the MPI application's environment, such as a GUI application launcher that allows the user to tune MPI-implementation and application settings in one consolidated interface. In fact, this is the primary purpose of the tool interface. Due to this, the MPI standard only requires the MPI-T to be exposed in C; support for Fortran is optional. Parameter and measurement variables are referred to in the standard as control and performance variables, respectively.

Separate initialization and finalization calls are required on each process that wishes to use MPI-T:

int MPI_T_init_thread(int required, int *provided)

int MPI_T_finalize(void)

Note that the arguments for MPI_T_init_thread are identical to those for MPI_init_thread, discussed in the roadmap on Hybrid Programming with OpenMP and MPI.

As the presence and name of variables exposed by MPI-T is left up to the MPI implementation, including them in one's code will likely break portability. A more portable way to do this in C is to use C preprocessor conditionals. For instance:

#ifdef MVAPICH2_VERSION
// Insert MVAPICH2-specific code here.
#endif

How did we know to look for MVAPICH2_VERSION? In this case, we found the corresponding "mpi.h" file from the MVAPICH2 installation and found a #define'd constant that only MVAPICH2 implementations should have. A possible complication is that many commercial vendors have built their implementation based on some of the open and free implementations, so other more subtle resolutions may be required in some cases.

Note that all identifiers associated with MPI-T begin with "MPI_T_". Typically, most control variables will not be writeable after MPI_Init(...) is called, but this may change or vary among MPI implementations. Control variables are required to always have the same value until they are no longer used, in which case, querying the variable will return an error code. A simple example is to query the number of control variables and then retrieve information about each of them; this can be accomplished by using the following two MPI-3 standard functions:

int MPI_T_cvar_get_num(int *num_cvar)

int MPI_T_cvar_get_info(int cvar_index, char *name, \
     int *name_len, int *verbosity, MPI_Datatype *datatype, \
     MPI_T_enum *enumtype, char *desc, int *desc_len,  \
     int *bind, int *scope)

An interesting note is that the MPI Forum thought of annotating the MPI-T variables based on their verbosity and audience. The verbosity level (the verbose argument above) is one of the output values, and corresponds to the following integer enumeration:

MPI_T_VERBOSITY_USER_BASIC

Basic information of interest to users

MPI_T_VERBOSITY_USER_DETAIL

Detailed information of interest to users

MPI_T_VERBOSITY_USER_ALL

All remaining information of interest to users

MPI_T_VERBOSITY_TUNER_BASIC

Basic information required for tuning

MPI_T_VERBOSITY_TUNER_DETAIL

Detailed information required for tuning

MPI_T_VERBOSITY_TUNER_ALL

All remaining information required for tuning

MPI_T_VERBOSITY_MPIDEV_BASIC

Basic information for MPI implementors

MPI_T_VERBOSITY_MPIDEV_DETAIL

Detailed information for MPI implementors

MPI_T_VERBOSITY_MPIDEV_ALL

All remaining information for MPI implementors

Ultimately it is up to the MPI implementation to decide how to classify variables, and as this is a relatively new feature, it can be expected that some implementations will be lagging behind on classifying verbosity or otherwise describing the MPI-T variables.