[Mpi3-tools] draft MPIT hierarchy query function text

[Dave Goodell]

Feedback on this proposal would be appreciated.  Should I proceed or  
will I be wasting my time?

-Dave

On Mar 2, 2010, at 6:09 PM, Dave Goodell wrote:

> 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.").
>
> _______________________________________________
> Mpi3-tools mailing list
> Mpi3-tools at lists.mpi-forum.org
> http://lists.mpi-forum.org/mailman/listinfo.cgi/mpi3-tools