18.2.376. MPI_T_category_get_index

MPI_T_category_get_index — Query the index of a category from its name

18.2.376.1. SYNTAX

18.2.376.1.1. C Syntax

int MPI_T_category_get_index(const char* name, int* cat_index)

18.2.376.2. INPUT PARAMETERS

name: Name of the category to query.

18.2.376.3. OUTPUT PARAMETERS

cat_index: Index of the category.

18.2.376.4. DESCRIPTION

MPI_T_category_get_index can be used to retrieve the index of a category given its name. The name argument is provided by the caller as a null-terminated string, and the matching index is returned in cat_index. The returned index can then be passed to other MPI tool information interface routines, such as MPI_T_category_get_info.

This routine allows a tool to look up a category by name without iterating over the entire set of categories. Because the number of categories exposed by the implementation can change over time, this is both more convenient and lower overhead than enumerating all of the categories to find a particular one.

18.2.376.5. NOTES

Category names are implementation-specific. Looking a category up by name is therefore not portable across MPI implementations, but may be the preferred approach for a tool that targets Open MPI specifically.

18.2.376.6. ERRORS

MPI_T_category_get_index will fail if:

MPI_T_ERR_NOT_INITIALIZED: The MPI Tools interface is not initialized.
MPI_T_ERR_INVALID: name or cat_index is NULL.
MPI_T_ERR_INVALID_NAME: name does not match the name of any category provided by the implementation at the time of the call.