[Mpi3-tools] MPIT chapter review

[Marty.Itzkowitz at Sun.COM]

[Sorry it's taken me so long; as you might imagine, life at Sun, now a 
wholly owned
subsidiary of Oracle, and soon to disappear as an independent company, has
been "interesting."]

I've reviewed it, and I've had two of our MPI folks, and one other tools 
person
review it, too.  The aggregated comments are below.

    Marty

 From Marty Itzkowitz:

I dislike the use of the feminine pronouns by default.  Either rewrite 
so that neither
    masculine nor feminine pronouns are needed, or always use "he or she",
    "his or her."

p5, line 47.  The meaning does not get more complex, the interpretation 
does.

p22, line 7, reads better as "*safely *callable from *asynchronous* 
signal handlers to allow
    their use in sampling-based tools."

 From Terry Dontje:
1.  What does MPIT_GET_SETINFO really do?  I guess my problem is it 
takes a "set name" but where does one get the set name and how does that 
differ from the out parameter "name of the set".  I read the section 
preceding the function description and I still just don't get it.

2.  Seems like a lot of functions for the performance accessors.  So to 
do the MPI state acquisition you will need to do the following:

a.  Loop on MPIT_PERFORMANCE_QUERY until you find the state performance 
variable.
b.  Call MPIT_PERFORMANCE_INFO with the state performance variable name 
to get the appropriate info you need (specifically datatype/count).
c.  Call MPIT_PERFORMANCE_GETHANDLE on the state performance variable name.
d.  Call MPIT_PERFORMANCE_START on the state performance handle to 
activate the use of the state code.
e.  Periodically call MPIT_PERFORMANCE_READ using the state performance 
handle while the MPI code is running
f.  Once the MPI code finishes call MPIT_PERFORMANCE_FREEHANDLE

I guess it isn't that bad we're just adding 4 additional calls which are 
necessary in order to have more than one performance variable.  Just 
seems like a lot on paper (in the spec).

 From Eugene Loh:

Have the MPIT interfaces been prototyped by anyone?  [Yukon Maruyama 
asked the
same question.  None of us feels confident we can understand the issues 
before we see
a prototype.]

Since the returned information is so implementation-dependent, it's hard 
for me to imagine that there could be (m)any MPIT-based tools that make 
sense for multiple MPI implementations.  Meanwhile, if a tool makes 
sense for only one MPI implementation, it should be part of the 
implementation itself.  In general, I'm still scratching my head over 
this MPIT stuff.

And some nits:
 page 6, line 47:

   All identifier covered by this interface carry
->
   All identifiers covered by this interface carry

page 7, line 1:

   all conventions and principle governing
->
   all conventions and principles governing

page 7, line 33:

   must contain exactly one call to the MPIT initialization routine
->
   must execute exactly one call to the MPIT initialization routine

page 8, lines 17 and 26:

   before MPIT_INIT and after MPIT_FINALIZE
->
   before MPIT_INIT or after MPIT_FINALIZE

page 12, line 42:  The table of legal "scope" values seems to be 
misplaced to the top of page 13.

page 12, line 44:

   it is not a guarantee that can be changed.
Is there a typo in that line?
[Marty]  I'm not quite sure what this line is saying.  Does it mean that 
even if the
scope says that a variable is changeable, the call to change it is not 
guaranteed to
succeed?  If that's so, what can the tool implementor rely on?