MPI implementations can optionally group performance and control variables into categories to express logical relationships between various variables. For example, an MPI implementation could group all control and performance variables that refer to message transfers in the MPI implementation and thereby distinguish them from variables that refer to local resources such as memory allocations or other interactions with the operating system.
Categories can also contain other categories to form a hierarchical grouping. Categories can never include themselves, either directly or transitively within other included categories. Expanding on the example above, this allows MPI to refine the grouping of variables referring to message transfers into variables to control and to monitor message queues, message matching activities and communication protocols. Each of these groups of variables would be represented by a separate category and these categories would then be listed in a single category representing variables for message transfers.
The category information may be queried in a fashion similar to the mechanism for querying variable information. The MPI implementation exports a set of N categories via the MPI tool information interface. If N=0, then the MPI implementation does not export any categories, otherwise the provided categories are indexed from 0 to N-1. This index number is used in subsequent calls to functions of the MPI tool information interface to identify the individual categories.
An MPI implementation is permitted to increase the number of categories during the execution of an MPI program when new categories become available through dynamic loading. However, MPI implementations are not allowed to change the index of a category or delete it once it has been added to the set.
Similarly, MPI implementations are allowed to add variables to categories, but they are not allowed to remove variables from categories or change the order in which they are returned.
The following function can be used to query the number of categories, mpiargnum_cat.
| MPI_T_CATEGORY_GET_NUM(num_cat) | |
| OUT num_cat | current number of categories (integer) |
Individual category information can then be queried by calling the following function:
| MPI_T_CATEGORY_GET_INFO(cat_index, name, name_len, desc, desc_len, num_cvars, num_pvars, num_categories) | |
| IN cat_index | index of the category to be queried (integer) |
| OUT name | buffer to return the string containing the name of the category (string) |
| INOUT name_len | length of the string and/or buffer for name (integer) |
| OUT desc | buffer to return the string containing the description of the category (string) |
| INOUT desc_len | length of the string and/or buffer for desc (integer) |
| OUT num_cvars | number of control variables in the category (integer) |
| OUT num_pvars | number of performance variables in the category (integer) |
| OUT num_categories | number of categories contained in the category (integer) |
The arguments name and name_len are used to return the name of the category 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 categories used by the MPI implementation.
If any OUT parameter to MPI_T_CATEGORY_GET_INFO is the NULL pointer, the implementation will ignore the parameter and not return a value for the parameter.
The arguments desc and desc_len are used to return the description of the category as described in Section Convention for Returning Strings.
Returning a description is optional. If an MPI implementation decides not to return a description, the first character for desc must be set to the null character and desc_len must be set to one at the return of this call.
The function returns the number of control variables, performance variables and other categories contained in the queried category in the arguments num_cvars, num_pvars, and num_categories, respectively.
If the name of a category is equivalent across connected MPI processes, then the returned description must be equivalent.
| MPI_T_CATEGORY_GET_NUM_EVENTS(cat_index, num_events) | |
| IN cat_index | index of the category to be queried (integer) |
| OUT num_events | number of event types in the category (integer) |
MPI_T_CATEGORY_GET_NUM_EVENTS returns the number of event types contained in the queried category.
| MPI_T_CATEGORY_GET_INDEX(name, cat_index) | |
| IN name | the name of the category (string) |
| OUT cat_index | the index of the category (integer) |
MPI_T_CATEGORY_GET_INDEX is a function for retrieving the index of a category given a known category name. The name parameter is provided by the caller, and cat_index is returned by the MPI implementation. The name parameter is a string terminated with a null character.
This routine returns MPI_SUCCESS on success and returns MPI_T_ERR_INVALID_NAME if name does not match the name of any category provided by the implementation at the time of the call.
Rationale.
This routine is provided to enable fast retrieval of a category index by a
tool, assuming it knows the name of the category for which it is looking.
The number of categories exposed by the implementation can change over
time, so it is not possible for the tool to simply iterate over the list of
categories once at initialization. Although using MPI implementation
specific category names is not portable across MPI implementations, tool
developers may choose to take this route for lower overhead at runtime
because the tool will not have to iterate over the entire set of categories
to find a specific one.
( End of rationale.)
| MPI_T_CATEGORY_GET_CVARS(cat_index, len, indices) | |
| IN cat_index | index of the category to be queried, in the range from 0 to mpiargnum_cat-1 (integer) |
| IN len | the length of the indices array (integer) |
| OUT indices | an integer array of size len, indicating control variable indices (array of integers) |
MPI_T_CATEGORY_GET_CVARS can be used to query which control variables are contained in a particular category. A category contains zero or more control variables.
| MPI_T_CATEGORY_GET_PVARS(cat_index, len, indices) | |
| IN cat_index | index of the category to be queried, in the range from 0 to mpiargnum_cat-1 (integer) |
| IN len | the length of the indices array (integer) |
| OUT indices | an integer array of size len, indicating performance variable indices (array of integers) |
MPI_T_CATEGORY_GET_PVARS can be used to query which performance variables are contained in a particular category. A category contains zero or more performance variables.
| MPI_T_CATEGORY_GET_EVENTS(cat_index, len, indices) | |
| IN cat_index | index of the category to be queried, in the range from 0 to mpiargnum_cat-1 (integer) |
| IN len | the length of the indices array (integer) |
| OUT indices | an integer array of size len, indicating event type indices (array of integers) |
MPI_T_CATEGORY_GET_EVENTS can be used to query which event types are contained in a particular category. A category contains zero or more event types.
| MPI_T_CATEGORY_GET_CATEGORIES(cat_index, len, indices) | |
| IN cat_index | index of the category to be queried, in the range from 0 to mpiargnum_cat-1 (integer) |
| IN len | the length of the indices array (integer) |
| OUT indices | an integer array of size len, indicating category indices (array of integers) |
MPI_T_CATEGORY_GET_CATEGORIES can be used to query which other categories are contained in a particular category. A category contains zero or more other categories.
As mentioned above, MPI implementations can grow the number of categories as well as the number of variables or other categories within a category. In order to allow users of the MPI tool information interface to check quickly whether new categories have been added or new variables or categories have been added to a category, MPI maintains an update number that is monotonically increasing during the execution and is returned by the following function:
| MPI_T_CATEGORY_CHANGED(update_number) | |
| OUT update_number | update number (integer) |
If two calls to this routine return the same update number, it is guaranteed that the category information has not changed between the two calls. If the update number retrieved from the second call is higher, then some categories have been added or expanded. If the number of changes to categories exceeds the limit of update_number, an implementation shall set update_number to the maximum possible value for the type of update_number.
The index values returned in indices by MPI_T_CATEGORY_GET_CVARS, MPI_T_CATEGORY_GET_PVARS, MPI_T_CATEGORY_GET_EVENTS, and MPI_T_CATEGORY_GET_CATEGORIES can be used as input to MPI_T_CVAR_GET_INFO, MPI_T_PVAR_GET_INFO, MPI_T_EVENT_GET_INFO, and MPI_T_CATEGORY_GET_INFO, respectively.
The user is responsible for allocating the arrays passed into the functions MPI_T_CATEGORY_GET_CVARS, MPI_T_CATEGORY_GET_PVARS, MPI_T_CATEGORY_GET_EVENTS, and MPI_T_CATEGORY_GET_CATEGORIES. Starting from array index 0, each function writes up to len elements into the array. If the category contains more than len elements, the function returns an arbitrary subset of size len. Otherwise, the entire set of elements is returned in the beginning entries of the array, and any remaining array entries are not modified.