[Mpi3-tools] Changes to the MPI_T*_ document

[Bronis R. de Supinski]

Martin:

Re:
> - Naming: People didn't like MPI_T_ and wanted something
> more expressive. MPI_Tool_ would be the obvious choice
> and that would be fine with me. Does anyone have a better
> suggestion? We can't spend more than four characters on
> it, though, or we will run into problems with the max. name
> size (even after shortening some names). Also, I would like
> this to be the final name change :).

I still feel that MPI_T is the best choice. No matter
what prefix you choose, someone will not like it.

[snip]

> - We had some lengthy discussion on the thread and async
> signal safety. Below is a suggestion for a rewrite - once I get
> some feedback from our group, I will forward this to Brian,
> since he had the most issues with the current wording.
>
> \begin{implementors}
> Sampling based tools rely on the ability to call the MPI
> tool information interface, in particular routines to start, stop,
> read, write and reset performance variables, from any program
> context, including asynchronous contexts such as signal handlers.
> MPI implementations should strive, if possible in their particular

OK through the above.

> environment, to enable this behavior for all or a subset of the

Which "behavior"? You do not define any behavior above. You
define support for usage scenarios. Change to:

  environment, to enable these usage scenarios for all or a subset of the

> routines mentioned above. If implementing only a subset, the
> read, write, and reset routines are typically the most critical

> for sampling based tools. If an MPI implementation
> is not able to provide such a behavior or if the behavior is only
> guaranteed under certain circumstances (e.g., for certain signals),
> this should be clearly documented, e.g., through the description
> return by {\mpifunc MPI\_T\_Get\_info}.

"such a"? UGH! Poor antecedent for "this". "return by"? Huh?

change to:

  for sampling based tools. An MPI implementation should clearly
  document any restrictions on the program contexts in which
  the MPI tool information interface can be used. Restrictions
  might include guaranteeing usage outside of all signals or
  outside a specific set of signals. Any restrictions could be
  documented, for example, through the description returned by
  {\mpifunc MPI\_T\_Get\_info}.

> \end{implementors}

Bronis