MPI implementations often use internal variables to control their operation and performance. Understanding and manipulating these variables can provide a more efficient execution environment or improve performance for many applications. This section describes the MPI tool information interface, which provides a mechanism for MPI implementors to expose variables, each of which represents a particular property, setting, or performance measurement from within the MPI implementation. The interface is split into two parts: the first part provides information about and supports the setting of control variables through which the MPI implementation tunes its configuration. The second part provides access to performance variables that can provide insight into internal performance information of the MPI implementation.
To avoid restrictions on the MPI implementation, the MPI tool information interface allows the implementation to specify which control and performance variables exist. Additionally, the user of the MPI tool information interface can obtain metadata about each available variable, such as its datatype, and a textual description. The MPI tool information interface provides the necessary routines to find all variables that exist in a particular MPI implementation, to query their properties, to retrieve descriptions about their meaning, and to access and, if appropriate, to alter their values.
Variables and categories across connected processes with equivalent names are required to have the same meaning (see the definition of ``equivalent'' as related to strings in Section Convention for Returning Strings ). Furthermore, enumerations with equivalent names across connected processes are required to have the same meaning, but are allowed to comprise different enumeration items. Enumeration items that have equivalent names across connected processes in enumerations with the same meaning must also have the same meaning. In order for variables and categories to have the same meaning, routines in the tools information interface that return details for those variables and categories have requirements on what parameters must be identical. These requirements are specified in their respective sections.
Rationale.
The intent of requiring the same meaning for entities with equivalent names is to enforce consistency
across connected processes.
For example, variables describing the number of packets sent
on different types of network devices should have different names to reflect their
potentially different meanings.
( End of rationale.)
The MPI tool information interface can be used independently from
the MPI communication functionality. In particular, the routines of this interface can be called
before MPI_INIT (or equivalent) and after MPI_FINALIZE.
In order to support this behavior cleanly,
the MPI tool information interface uses separate initialization
and finalization routines. All identifiers used in the MPI tool information interface have
the prefix MPI_T_.
On success, all MPI tool information interface routines return MPI_SUCCESS, otherwise they return an appropriate and unique return code indicating the reason why the call was not successfully completed. Details on return codes can be found in Section Return Codes for the MPI Tool Information Interface . However, unsuccessful calls to the MPI tool information interface are not fatal and do not impact the execution of subsequent MPI routines.
Since the MPI tool information interface primarily focuses on tools and support libraries, MPI implementations are only required to provide C bindings for functions and constants introduced in this section. Except where otherwise noted, all conventions and principles governing the C bindings of the MPI API also apply to the MPI tool information interface, which is available by including the mpi.h header file. All routines in this interface have local semantics.
Advice to users.
The number and type of control variables and performance variables can vary between MPI implementations, platforms and different builds of the same implementation on the same platform as well as between runs. Hence, any application relying on a particular variable will not be portable. Further, there is no guarantee that the number of variables and variable indices are the same across connected processes.
This interface is primarily intended for performance monitoring tools,
support tools, and libraries controlling the application's
environment. When maximum portability is desired, application programmers
should either avoid using the
MPI tool information interface or avoid being dependent on the existence of a
particular control or performance variable.
( End of advice to users.)