MPI implementations often use internal variables to control their behavior and performance and rely on internal events for their implementation. Understanding and manipulating these variables and tracking these events 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, as well as expose events that can be tracked by tools. The interface is split into three 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. The third part enables tools to query available events within an MPI implementation and register callbacks for them.
To avoid restrictions on the MPI implementation, the MPI tool information interface allows the implementation to specify which control variables, performance variables, and events exist. Additionally, the user of the MPI tool information interface can obtain metadata about each available variable or event, such as its datatype, and a textual description. The MPI tool information interface provides the necessary routines to find all variables and events that exist in a particular MPI implementation; to query their properties; to retrieve descriptions about their meaning; to access and, if appropriate, to alter their values; and (in case of events) set callbacks triggered by them.
Variables, events, and categories across connected MPI 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 MPI processes are required to have the same meaning, but are allowed to comprise different enumeration items. Enumeration items that have equivalent names across connected MPI 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 MPI 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 is initialized and
after MPI is finalized. 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, performance variables, and events 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 MPI 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 or of a
particular event.
( End of advice to users.)