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, N.
| MPI_T_CATEGORY_GET_NUM(num_cat) | |
| OUT num_cat | current number of categories (integer) |
int MPI_T_category_get_num(int *num_cat)
Individual category information can then be queried by calling the following function:
int MPI_T_category_get_info(int cat_index, char *name, int *name_len, char *desc, int *desc_len, int *num_cvars, int *num_pvars, int *num_categories)
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 a 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 processes, then the returned description must be equivalent.
| 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) |
int MPI_T_category_get_index(const char *name, int *cat_index)
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 [0,N-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) |
int MPI_T_category_get_cvars(int cat_index, int len, int indices[])
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 [0,N-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) |
int MPI_T_category_get_pvars(int cat_index, int len, int indices[])
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_CATEGORIES(cat_index, len, indices) | |
| IN cat_index | index of the category to be queried, in the range [0,N-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) |
int MPI_T_category_get_categories(int cat_index, int len, int indices[])
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 a virtual timestamp. This timestamp is monotonically increasing during the execution and is returned by the following function:
| MPI_T_CATEGORY_CHANGED(stamp) | |
| OUT stamp | a virtual time stamp to indicate the last change to the categories (integer) |
int MPI_T_category_changed(int *stamp)
If two subsequent calls to this routine return the same timestamp, it is guaranteed that the category information has not changed between the two calls. If the timestamp retrieved from the second call is higher, then some categories have been added or expanded.
Advice to users.
The timestamp value is purely virtual and only intended to check for changes in
the category information. It should not be used for any other purpose.
( End of advice to users.)
The index values returned in indices by
MPI_T_CATEGORY_GET_CVARS,
MPI_T_CATEGORY_GET_PVARS and
MPI_T_CATEGORY_GET_CATEGORIES
can be used as input to MPI_T_CVAR_GET_INFO,
MPI_T_PVAR_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 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.