MPIT Taxonomic Information Proposal =================================== All text is relative to the 2010-02-21 draft of the MPIT chapter. Author: Dave Goodell Date: 2010-04-21 ------8<------ %% Comes after the current "Performance Variables" section. %% Subsubsection 1.3.5 should be deleted. \section{Performance Variable Taxonomic Information} MPI implementations can optionally provide information that describes the relationship of performance and configuration variables to each other. For this, an MPI implementation can define names that represent sets of variables and then associate each performance/configuration variable with zero or more sets. Sets may contain zero or more performance/configuration variables and zero or more other sets. Sets may not contain themselves either directly or indirectly. Said another way, these sets and performance/configuration variables form a directed acyclic graph (DAG). This information is accessible via several interrogative routines. MPIT_TAXON_QUERY_SET_SETS(iterator, setname, name, namelen, type) INOUT iterator IN setname OUT name OUT namelen OUT type int MPIT_Taxon_query_set_sets(MPIT_Taxonquery_iterator *iterator, char *setname, char *name, int *namelen, int *type); Iterate over all sets contained in the set identified by "setname". A unique identifying name for the contained set is returned in "name" and "namelen" is set to the number of characters written. The value of "namelen" cannot be larger than MPIT_MAX_SET_NAME-1. The set of all root sets (sets that no other set contains) available in the implementation can be queried by using a "setname" of "MPIT_ROOT_SETS". The "type" parameter is set to MPIT_TYPE_CONFIG if the variable is a configuration variable and to MPIT_TYPE_PERFORMANCE if it is a performance variable. On the first call to MPIT_TAXON_QUERY_SET_SETS, the caller must initialize a variable to MPIT_TAXONQUERY_START and pass this variable as the "iter" parameter. Subsequent calls require the user to pass the returned value "iter" to query further taxonomic information. Once all taxonomic information is returned, the call to MPIT_TAXON_QUERY_SET_SETS returns MPIT_END and sets "iter" to MPIT_TAXONQUERY_END. MPIT_TAXON_QUERY_VARIABLE_SETS(iterator, varname, name, namelen, type) INOUT iterator IN varname OUT name OUT namelen OUT type int MPIT_Taxon_query_variable_sets(MPIT_Taxonquery_iterator *iterator, char *varname, char *name, int *namelen, int *type); Iterate over all sets that contain the performance/configuration variable identified by "varname". A unique identifying name for the set is returned in "name" and "namelen" is set to the number of characters written. The value of "namelen" cannot be larger than MPIT_MAX_SET_NAME-1. The "type" parameter is set to MPIT_TYPE_CONFIG if the variable is a configuration variable and to MPIT_TYPE_PERFORMANCE if it is a performance variable. On the first call to MPIT_TAXON_QUERY_VARIABLE_SETS, the caller must initialize a variable to MPIT_TAXONQUERY_START and pass this variable as the "iter" parameter. Subsequent calls require the user to pass the returned value "iter" to query further taxonomic information. Once all taxonomic information is returned, the call to MPIT_TAXON_QUERY_VARIABLE_SETS returns MPIT_END and sets "iter" to MPIT_TAXONQUERY_END. MPIT_TAXON_QUERY_SET_VARIABLES(iterator, setname, name, namelen, type) INOUT iterator IN setname OUT name OUT namelen OUT type int MPIT_Taxon_query_set_variables(MPIT_Taxonquery_iterator *iterator, char *setname, char *name, int *namelen, int *type); Iterate over all variables contained in the set identified by "setname". A unique identifying name for the variable is returned in "name" and "namelen" is set to the number of characters written. The value of "namelen" cannot be larger than MPIT_MAX_SET_NAME-1. The "type" parameter is set to MPIT_TYPE_CONFIG if the variable is a configuration variable and to MPIT_TYPE_PERFORMANCE if it is a performance variable. On the first call to MPIT_TAXON_QUERY_SET_VARIABLES, the caller must initialize a variable to MPIT_TAXONQUERY_START and pass this variable as the "iter" parameter. Subsequent calls require the user to pass the returned value "iter" to query further taxonomic information. Once all taxonomic information is returned, the call to MPIT_TAXON_QUERY_SET_VARIABLES returns MPIT_END and sets "iter" to MPIT_TAXONQUERY_END. MPIT_TAXON_CHANGED(flag) OUT flag int MPIT_Taxon_changed(int *flag); This routine returns true in the flag argument if the list of available performance/configuration variables or sets has changed since the last time the user has called any of the MPIT_TAXON_QUERY_ routines with the argument MPIT_TAXONQUERY_START as the first argument. If the user has not yet called any such routines, the argument flag will contain the value true. MPIT_TAXON_DESCRIBE_SET(name, desc, desclen) IN name OUT desc OUT desclen int MPIT_Taxon_describe_set(char *name, char *desc, int desclen); Retrieve the description for the set identified by "name" and store it in "desc". The "desclen" parameter is set to the number of characters written. The value of "desclen" cannot be larger than MPIT_MAX_SET_DESC-1. \paragraph{Set and Variable Names} MPI does not specify the character encoding of strings in the MPIT interface. The only requirement is that strings are terminated with a null character. MPI reserves all set and variable names with the prefixes "MPI_" and "MPIT_" for its own use. ------8<------ Also, delete the "sets" and "setslen" parameters to MPIT_PERFORMANCE_INFO. Delete the paragraphs contained in lines 7-16 of page 19 ("The argument sets ... setslen must be set to zero.").