Enclosed is alternative text for the MPIT draft. This text replaces the "Set and Hierarchy Information" \subsubsection in 1.3.5 in the current draft PDF (md5sum: 4fa7d0f3a25cabce8c2f5ef95bb41599). My motivation for this alternative interface is to avoid pushing the burden of text parsing onto all tools that which to utilize hierarchy information. As I mentioned at the last concall, I believe that few or no tools will want to work with the text format directly and will instead always access this information through a functional interface. The text below has many "...MORE TEXT HERE..." points indicating where the text should be expanded in a fashion consistent with the rest of the MPIT text. I'm happy to finish writing this text but I wanted to get the rough shape of the proposal out for comment before I take the time to fill in the non-essential details. If I've omitted too much in a particular area, please ask and I'll clarify what I had in mind. Discussion items: * function names: did we decide that iterative functions should be named _ITER or similar? * function names: most of these are listed as starting with MPIT_TAXA (as in taxonomy) in order to avoid verb/noun confusion with the word "SET". I am open to alternative names, such as MPIT_TAXONOMY, MPIT_HIERARCHY, MPIT_CLASSIFICATION, MPIT_GROUP. (the first three are long, the last has potential for confusion with MPI_Group) Maybe MPIT_VARGROUP? * iteration order: does the topological order requirement help client code or is it just additional burden for MPI implementors? * I've eliminated the "pretty names" for sets. I'm assuming that the uniquely identifying name is sufficient and that anything that needs to be spelled out more explicitly for humans should go into the description information. If anyone disagrees with this, I can add the pretty names back in. * I think it also makes sense to move the rewritten \subsubsection to after the "Query and Handle Functions" \subsubsection. It is easier to talk about grouping performance variables once the reader knows a bit more about what performance variables actually are. -Dave ------8<------ Performance Variable Taxonomic Information MPI implementations can optionally provide information that describes the relationship of performance variables to each other. For this, an MPI implementation can define names that represent sets of variables and then associate each performance variable with zero or more sets. Sets may contain zero or more performance variables and zero or more other sets. Sets may not contain themselves either directly or indirectly. Said another way, these sets and performance variables form a directed acyclic graph (DAG). This information is accessible via several interrogative routines. MPIT_TAXA_QUERY_ALL_SETS(iterator, name, namelen) INOUT iterator OUT name OUT namelen Iterate over all sets in topological order. 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. ...MORE TEXT HERE... MPIT_TAXA_QUERY_VARIABLE_SETS(iterator, varname, name, namelen) INOUT iterator IN varname OUT name OUT namelen Iterate over all sets that contain the performance variable identified by "varname". ...MORE TEXT HERE... MPIT_TAXA_QUERY_SET_SETS(iterator, setname, name, namelen) INOUT iterator IN setname OUT name OUT namelen Iterate over all sets that contained in the set identified by "setname". ...MORE TEXT HERE... MPIT_TAXA_QUERY_SET_VARIABLES(iterator, setname, name, namelen) Iterate over all variables contained in the set identified by "setname". ...MORE TEXT HERE... MPIT_TAXA_SET_DESCRIBE(name, desc, desclen) IN name OUT desc OUT desclen Retrieve the description for the set identified by "name". ...MORE TEXT HERE... ------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.").