[Mpi3-tools] draft MPIT hierarchy query function text

[Dave Goodell]

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.").