tools.diff

Index: chap-tools/prof.tex
===================================================================
--- chap-tools/prof.tex	(revision 1772)
+++ chap-tools/prof.tex	(revision 1911)
@@ -20,8 +20,8 @@
 supplied and work as expected, but it is not possible to replace at 
 link time the \mpiskipfunc{MPI\_} version with a user-defined version.
  
-For Fortran, the different support methods cause several linker names.
-Therefore, several profiling routines (with these linker names)
+For Fortran, the different support methods cause several specific procedure names.
+Therefore, several profiling routines (with these specific procedure names)
 are needed for each Fortran \MPI/ routine, as described in
 \sectionref{sec:f90:linker-names}.
 
@@ -140,7 +140,7 @@
 \funcarg{\IN}{level}{Profiling level (integer)}
 \end{funcdef}
 \mpibind{MPI\_Pcontrol(const~int~level, \ldots)}
-\mpifnewbind{MPI\_Pcontrol(level) BIND(C) \fargs INTEGER, INTENT(IN) :: level}
+\mpifnewbind{MPI\_Pcontrol(level) \fargs INTEGER, INTENT(IN) :: level}
 \mpifbind{MPI\_PCONTROL(LEVEL)\fargs INTEGER LEVEL}
 \mpicppemptybind{MPI::Pcontrol(const int~level, \ldots)}{void}
 
@@ -368,7 +368,7 @@
 The different Fortran support methods and possible options
 for the support of subarrays (depending on whether the compiler
 can support \code{TYPE(*), DIMENSION(..)} choice buffers)
-imply different linker names for the same Fortran \MPI/ routine.
+imply different specific procedure names for the same Fortran \MPI/ routine.
 The rules and implications for the profiling interface are
 described in 
 \sectionref{sec:f90:linker-names}.
Index: chap-tools/mpit.tex
===================================================================
--- chap-tools/mpit.tex	(revision 1772)
+++ chap-tools/mpit.tex	(revision 1911)
@@ -29,6 +29,24 @@
 descriptions about their meaning, and to access and, if appropriate, to alter
 their values.
 
+Variables and categories across connected processes with equivalent names are 
+required to have the same meaning (see the definition of ``equivalent'' as related
+to strings in Section \ref{sec:mpit:strings}). 
+Furthermore, enumerations with equivalent names across connected processes are required to have the same meaning, but are allowed to comprise different enumeration items.
+Enumeration items that have equivalent names across connected processes in enumerations with the same meaning must also have the same meaning.
+In order for variables and categories to have the same meaning,  routines in the tools information interface that return details for those variables and categories have requirements on what parameters 
+must be identical. 
+These requirements are specified in 
+their respective sections.
+
+\begin{rationale}
+The intent of requiring the same meaning for entities with equivalent names is to enforce consistency 
+across connected processes.
+For example, variables describing the number of packets sent
+on different types of network devices should have different names to reflect their
+potentially different meanings.
+\end{rationale}
+
 The \MPI/ tool information interface can be used independently from 
 the \MPI/ communication functionality. In particular, the routines of this interface can be called 
 before \mpifunc{MPI\_INIT} (or equivalent) and after \mpifunc{MPI\_FINALIZE}.
@@ -48,10 +66,11 @@
 Since the \MPI/ tool information interface primarily focuses on tools and 
 support libraries,
 \MPI/ implementations are only required to provide C bindings
-for functions introduced in this section.  Except where otherwise noted, all conventions
+for functions and constants
+introduced in this section.  Except where otherwise noted, all conventions
 and principles governing the C bindings of the \MPI/ API also apply to
 the \MPI/ tool information interface, which is available by including
-the \code{mpi.h} header file. All routines in this interface have local semantics.
+the {\sf mpi.h} header file. All routines in this interface have local semantics.
 
 \begin{users}
 The number and type of control variables and performance variables can
@@ -58,10 +77,9 @@
 vary between \MPI/ implementations, platforms and different
 builds of the same implementation on the same platform as well as
 between runs. Hence, any
-application relying on a particular variable will not be portable. Further,
-there is no guarantee that number of variables, variable indices, 
-and variable names are the
-same across processes.
+application relying on a particular variable will not be portable. 
+Further, there is no guarantee that the number of variables and 
+variable indices are the same across connected processes.
 
 This interface is primarily intended for performance monitoring tools,
 support tools, and libraries controlling the application's
@@ -172,11 +190,13 @@
 
 \subsection{Convention for Returning Strings}
 \label{sec:mpit:strings}
+
 Several \MPI/ tool information interface functions return one or more 
-strings. These functions
-have two arguments for each string to be returned: an OUT parameter
+strings. 
+These functions
+have two arguments for each string to be returned: an \OUT\ parameter
 that identifies a pointer to the buffer in which the string will be
-returned, and an IN/OUT parameter to pass the length of the buffer.
+returned, and an \IN/\OUT\ parameter to pass the length of the buffer.
 The user is responsible for the memory allocation of the buffer and
 must pass the size of the buffer ($n$) as the length argument.  Let
 $n$ be the length value specified to the function.  On return, the
@@ -192,7 +212,15 @@
 argument, the buffer argument is ignored and nothing is returned.
 
 
+\MPI/ implementations behave as if they have an internal character 
+array that is copied to the output character array supplied by the user.  
+Such output strings are defined to be equivalent if their notional 
+source-internal character arrays are identical (up to and including 
+the null terminator), even if the output string is truncated due 
+to a small input length parameter $n$.
 
+
+
 \subsection{Initialization and Finalization}
 \label{sec:mpit:init}
 
@@ -229,13 +257,13 @@
 Section~\ref{sec:ei-threads}.
 
 The \MPI/ specification does not require all \MPI/ processes to exist 
-before the call to \mpifunc{MPI\_INIT}.  If the \MPI/ tool information 
+before the call to \func{MPI\_INIT}.  If the \MPI/ tool information 
 interface is used before 
-\mpifunc{MPI\_INIT} has been 
+\func{MPI\_INIT} has been 
 called, 
 the user is responsible for ensuring that the \MPI/ tool information interface is initialized on all processes it is used in.
 Processes created by the \MPI/ implementation during
-\mpifunc{MPI\_INIT} inherit the status of the \MPI/ tool information interface 
+\func{MPI\_INIT} inherit the status of the \MPI/ tool information interface 
 (whether it is
 initialized or not as well as all active sessions and handles) from the process
 from which they are created.
@@ -285,8 +313,8 @@
 to \mpifunc{MPI\_T\_INIT\_THREAD}.
 
 At the end of the program execution, unless \mpifunc{MPI\_ABORT} is
-called, an application must have called \mpifunc{MPI\_T\_INIT\_THREAD}
-and \mpifunc{MPI\_T\_FINALIZE} an equal number of times. 
+called, an application must have called \func{MPI\_T\_INIT\_THREAD}
+and \func{MPI\_T\_FINALIZE} an equal number of times. 
 
 
 
@@ -300,12 +328,12 @@
 initialization of the \MPI/ tool information interface is separate 
 from the initialization of
 \MPI/, \MPI/ tool information interface routines can be called before 
-\mpifunc{MPI\_INIT}. Consequently, these routines can
-also use \MPI/ datatypes before \mpifunc{MPI\_INIT}. Therefore,
+\func{MPI\_INIT}. Consequently, these routines can
+also use \MPI/ datatypes before \func{MPI\_INIT}. Therefore,
 within the context of the \MPI/ tool information interface, it is 
 permissible to use a subset of
 \MPI/ datatypes as specified below before a call to
-\mpifunc{MPI\_INIT} (or equivalent).
+\func{MPI\_INIT} (or equivalent).
 
 
 
@@ -340,17 +368,27 @@
 \end{rationale}
 
 The \MPI/ tool information interface only relies on a subset of the basic \MPI/
-datatypes and does not use any derived \MPI/ datatypes.
+datatypes and does not use any derived \MPI/ datatypes. 
 Table~\ref{table:tools:mpit:datatypes} lists all \MPI/ datatypes that
 can be returned by the \MPI/ tool information interface to represent 
 its variables.
 
+The use of the datatype \const{MPI\_CHAR} in the \MPI/ tool information
+interface implies a null-terminated character array, i.e., a string in the C 
+language. 
+If a variable has type \const{MPI\_CHAR}, the value of the \mpiarg{count} 
+parameter returned by 
+\mpifunc{MPI\_T\_CVAR\_HANDLE\_ALLOC} and \mpifunc{MPI\_T\_PVAR\_HANDLE\_ALLOC} 
+must  be large enough to include any valid value, including its terminating null
+character.
+The contents of returned \const{MPI\_CHAR} arrays are only defined from index 0 through
+the location of the first null character.
 
 \begin{rationale}
 The \MPI/ tool information interface requires a significantly simpler
 type system than \MPI/ itself. Therefore, only its required subset
 must be present before
-\mpifunc{MPI\_INIT} (or equivalent) and \MPI/ implementations 
+\func{MPI\_INIT} (or equivalent) and \MPI/ implementations 
 do not need to initialize the complete \MPI/
 datatype system.
 \end{rationale}
@@ -363,8 +401,8 @@
 We refer to
 this information in the following as an enumeration.  In this case, the respective
 calls that provide additional metadata for each control or performance
-variable, i.e., \mpifunc{MPI\_T\_CVAR\_GET\_INFO}
-(Section~\ref{sec:mpit:cvar}) and \mpifunc{MPI\_T\_PVAR\_GET\_INFO}
+variable, i.e., \func{MPI\_T\_CVAR\_GET\_INFO}
+(Section~\ref{sec:mpit:cvar}) and \func{MPI\_T\_PVAR\_GET\_INFO}
 (Section~\ref{sec:mpit:pvar}), return a handle of type
 \type{MPI\_T\_enum}\cdeclmainindex{MPI\_T\_enum} 
 that can be passed to the following functions to
@@ -497,7 +535,9 @@
 information. An \MPI/ implementation is not allowed to alter any of
 the returned values.
 
+If any \gtype{\OUT} parameter to \mpifunc{MPI\_T\_CVAR\_GET\_INFO} is a \consti{NULL} pointer, the implementation will ignore the parameter and not return a value for the parameter.
 
+
 \textoutdesc{name}{the name of the control variable}
 
 If completed successfully, the routine is required to return a name of
@@ -526,7 +566,7 @@
 \textoutdesc{desc}{a description of the control variable}
 
 Returning a description is optional. If an \mpi/ implementation
-does not to return a description, the first character for
+does not return a description, the first character for
 \mpiarg{desc} must be set to the null character and \mpiarg{desc\_len}
 must be set to one at the return of this call.
 
@@ -554,6 +594,10 @@
 \mpiarg{scope} will be set to one of the constants listed in
 Table~\ref{table:tools:mpit:scopes}.
 
+If the name of a control variable is equivalent across connected processes, 
+the following \mpiarg{OUT}  parameters must be identical: \mpiarg{verbosity}, 
+\mpiarg{datatype}, \mpiarg{enumtype}, \mpiarg{bind}, and \mpiarg{scope}. 
+The returned description must be equivalent.
 
 \begin{table}[h]
 \begin{center}
@@ -585,7 +629,34 @@
 \end{users}
 
 
+\begin{funcdef}{MPI\_T\_CVAR\_GET\_INDEX(name, cvar\_index)}
+\funcarg{\IN}{name}{name of the control variable (string)}
+\funcarg{\OUT}{cvar\_index}{index of the control variable (integer)}
+\end{funcdef}
 
+\mpibind{MPI\_T\_cvar\_get\_index(const char *name, int *cvar\_index)}
+
+\mpifunc{MPI\_T\_CVAR\_GET\_INDEX} is a function for retrieving 
+the index of a control variable given a known variable name. The 
+\mpiarg{name} parameter is provided by the caller, and \mpiarg{cvar\_index} 
+is returned by the \MPI/ implementation. The \mpiarg{name} parameter is a string 
+terminated with a null character.
+
+This routine returns \const{MPI\_SUCCESS} on success and returns 
+\const{MPI\_T\_ERR\_INVALID\_NAME} if \mpiarg{name} does not match the name of 
+any control variable provided by the implementation at the time of the call.
+
+\begin{rationale}
+This routine is provided to enable fast retrieval of control variables by a tool, 
+assuming it knows the name of the variable for which it is looking. 
+The number of variables exposed by the implementation can change over time, 
+so it is not possible for the tool to simply iterate over the list of variables 
+once at initialization. Although using \MPI/ implementation specific variable 
+names is not portable across \MPI/ implementations, tool developers may choose to 
+take this route for lower overhead at runtime because the tool will not have to 
+iterate over the entire set of variables to find a specific one. 
+\end{rationale}
+
 \subsubsection{Example: Printing All Control Variables}
 
 \begin{example}
@@ -622,7 +693,7 @@
             &verbose, &datatype, NULL,
             NULL, NULL, /*no description */
             &bind, &scope);
-    if (err!=MPI_SUCCESS) return err;
+    if (err!=MPI_SUCCESS || err!=MPI_T_ERR_INVALID_INDEX) return err;
     printf("Var %i: %s\n", i, name);
   }
   
@@ -686,14 +757,10 @@
 
 The value of \mpiarg{cvar\_index} should 
 be in the range $0$ to $num\_cvar-1$, where $num\_cvar$ is the number of available control 
-variables as determined from a prior call to \mpifunc{MPI\_T\_CVAR\_GET\_NUM}.  
+variables as determined from a prior call to \func{MPI\_T\_CVAR\_GET\_NUM}.  
 The type of the \MPI/ object it references must be consistent with the type 
-returned in the \mpiarg{bind} argument in a prior call to \mpifunc{MPI\_T\_CVAR\_GET\_INFO}.
+returned in the \mpiarg{bind} argument in a prior call to \func{MPI\_T\_CVAR\_GET\_INFO}.
 
-In the case that the \mpiarg{bind} argument returned by
-\mpifunc{MPI\_T\_CVAR\_GET\_INFO} equals \const{MPI\_T\_BIND\_NO\_OBJECT}, the argument
-\mpiarg{obj\_handle} is ignored.
-
 \begin{funcdef}{MPI\_T\_CVAR\_HANDLE\_FREE(handle)}
 \funcarg{\INOUT}{handle}{handle to be freed (handle)}
 \end{funcdef}
@@ -702,7 +769,7 @@
 \mpibind{MPI\_T\_cvar\_handle\_free(MPI\_T\_cvar\_handle *handle)}
 
 When a handle is no longer needed, a user of the \MPI/ tool information interface should call
-\mpifunc{MPI\_T\_CVAR\_HANDLE\_FREE} to free the handle and the
+\func{MPI\_T\_CVAR\_HANDLE\_FREE} to free the handle and the
 associated resources in the \MPI/ implementation.  On a successful
 return, \MPI/ sets the handle to \const{MPI\_T\_CVAR\_HANDLE\_NULL}.
 
@@ -717,9 +784,10 @@
 \cdeclindex{MPI\_T\_cvar\_handle}
 \mpibind{MPI\_T\_cvar\_read(MPI\_T\_cvar\_handle handle, void* buf)}
 
-This routine queries the value of the control
+This routine queries the value of a control
 variable identified by the argument \mpiarg{handle} and stores the
-result in the buffer identified by the parameter \mpiarg{buf}.  The
+result in the buffer identified by the parameter \mpiarg{buf}.  
+The
 user must ensure that the buffer is of the appropriate
 size to hold the entire value of the control variable (based on the
 returned datatype and count from prior corresponding calls to
@@ -735,7 +803,8 @@
 
 This routine sets the value of the control variable
 identified by the argument \mpiarg{handle} to the data stored in the
-buffer identified by the parameter \mpiarg{buf}.  The user must ensure that the
+buffer identified by the parameter \mpiarg{buf}.  
+The user must ensure that the
 buffer is of the appropriate size to
 hold the entire value of the control variable (based on the returned
 datatype and count from prior corresponding calls to
@@ -761,7 +830,6 @@
 \const{MPI\_T\_ERR\_CVAR\_SET\_NEVER}, if the variable cannot be set for the
 remainder of the application's execution.
 
-
 \subsubsection{Example: Reading the Value of a Control Variable}
 
 \begin{example}
@@ -807,7 +875,7 @@
 performance variables provided by the \MPI/
 implementation. Performance variables provide insight into \MPI/
 implementation specific internals and can represent information such
-as the state of the \MPI/ implementation (e.g., waiting blocked,
+as the state of the MPI implementation (e.g., waiting blocked,
 receiving, not active), aggregated timing data for submodules, or
 queue sizes and lengths. 
 
@@ -827,7 +895,7 @@
 Each performance variable is associated with a class that describes 
 its basic semantics, possible datatypes, basic behavior, its starting value, whether it can
 overflow, and when and 
-how an \MPI/ implementation can change the variable's value.  The starting value is 
+how an MPI implementation can change the variable's value.  The starting value is 
 the value that is assigned to the variable the first time that it is used or 
 whenever it is reset.
 
@@ -868,14 +936,16 @@
 value is set.  \MPI/ implementations must ensure that variables of this class cannot overflow.
 
 \item \const{MPI\_T\_PVAR\_CLASS\_SIZE}\\
-A performance variable in this class represents a value that is the fixed
-size of  a resource.  Values returned from variables in
+A performance variable in this class represents a value that is the 
+size of a resource.  Values returned from variables in
 this class are non-negative and represented by one of the following
 datatypes: \const{MPI\_UNSIGNED}, \const{MPI\_UNSIGNED\_LONG}, \const{MPI\_UNSIGNED\_LONG\_LONG}, \const{MPI\_DOUBLE}.  The starting
-value is the current utilization level of the resource at the time that the
+value is the current size of the 
+resource at the time that the
 starting value is set.  \MPI/ implementations must ensure that variables of this class cannot overflow.
 
 
+
 \item \const{MPI\_T\_PVAR\_CLASS\_PERCENTAGE}\\
 The value of a performance variable in this class represents the
 percentage utilization of a finite resource.  The value of a variable
@@ -893,7 +963,7 @@
 the variable.  It can be represented by one of the
 following datatypes: \const{MPI\_UNSIGNED}, \const{MPI\_UNSIGNED\_LONG}, \const{MPI\_UNSIGNED\_LONG\_LONG}, \const{MPI\_DOUBLE}.  The
 starting value is the current utilization level of the resource at the
-time that the starting value is set.  \MPI/ implementations must ensure that variables of this class cannot
+time that the variable is started or reset.  \MPI/ implementations must ensure that variables of this class cannot
 overflow.
 
 \item \const{MPI\_T\_PVAR\_CLASS\_LOWWATERMARK}\\
@@ -903,7 +973,7 @@
 of the variable.  It can be represented by one of
 the following datatypes: \const{MPI\_UNSIGNED}, \const{MPI\_UNSIGNED\_LONG}, \const{MPI\_UNSIGNED\_LONG\_LONG}, \const{MPI\_DOUBLE}.  The
 starting value is the current utilization level of the resource at the
-time that the starting value is set.  \MPI/ implementations must ensure that variables of this class cannot
+time that the variable is started or reset.  \MPI/ implementations must ensure that variables of this class cannot
 overflow.
 
 \item \const{MPI\_T\_PVAR\_CLASS\_COUNTER}\\
@@ -941,7 +1011,7 @@
 one of the following datatypes: \const{MPI\_UNSIGNED}, \const{MPI\_UNSIGNED\_LONG}, \const{MPI\_UNSIGNED\_LONG\_LONG},
 \const{MPI\_DOUBLE}.  The starting value for variables of this class is 0.
 If the type \const{MPI\_DOUBLE} is used, the units that represent time
-in this datatype must match the units used by \mpifunc{MPI\_WTIME}.
+in this datatype must match the units used by \func{MPI\_WTIME}.
 Otherwise, the time units should be documented, e.g., in the description
 returned by \mpifunc{MPI\_T\_PVAR\_GET\_INFO}.
 Variables of this class can overflow.
@@ -996,7 +1066,7 @@
 \funcarg{\OUT}{enumtype}{optional descriptor for enumeration information (handle)}
 \textoutargs{desc}{a description of the performance variable}
 \funcarg{OUT}{bind}{type of \MPI/ object to which this variable must be bound (integer)}
-\funcarg{\OUT}{readonly}{flag indicating whether the variable can be\flushline % fix for margin
+\funcarg{\OUT}{readonly}{flag indicating whether the variable can be\hfill\hbox{}\linebreak % fix for margin
 written/reset (integer)}
 \funcarg{\OUT}{continuous}{flag indicating whether the variable can be started and stopped or is continuously active (integer)}
 \funcarg{\OUT}{atomic}{flag indicating whether the variable can be atomically read and reset (integer)}
@@ -1012,6 +1082,7 @@
 information. An \MPI/ implementation is not allowed to alter any of
 the returned values.
 
+If any \gtype{\OUT} parameter to \mpifunc{MPI\_T\_PVAR\_GET\_INFO} is a \consti{NULL} pointer, the implementation will ignore the parameter and not return a value for the parameter.
 
 \textoutdesc{name}{the name of the performance variable}
 If completed successfully, the routine is required to return a name of
@@ -1045,10 +1116,10 @@
 be used to gather more information as described in Section~\ref{sec:types}.
 Otherwise, \mpiarg{enumtype} is set to \const{MPI\_T\_ENUM\_NULL}.
 If the datatype is not \const{MPI\_INT} or the argument \mpiarg{enumtype} is the 
-null pointer, no emumeration type is returned.
+null pointer, no enumeration type is returned.
 
 Returning a description is optional. If an \mpi/ implementation
-does not to return a description, the first character for
+does not return a description, the first character for
 \mpiarg{desc} must be set to the null character and \mpiarg{desc\_len}
 must be set to one at the return from this function.
 
@@ -1071,7 +1142,45 @@
 which the call sets \mpiarg{atomic} to one can be used in
 a call to \mpifunc{MPI\_T\_PVAR\_READRESET}.
 
+If a performance variable has an equivalent name
+and has the same class across connected processes,
+the following \mpiarg{OUT}  parameters must be identical: \mpiarg{verbosity},
+\mpiarg{varclass}, 
+\mpiarg{datatype}, \mpiarg{enumtype}, 
+\mpiarg{bind}, \mpiarg{readonly}, \mpiarg{continuous}, and \mpiarg{atomic}. 
+The returned description must be equivalent.
 
+\begin{funcdef}{MPI\_T\_PVAR\_GET\_INDEX(name, var\_class, pvar\_index)}
+\funcarg{\IN}{name}{the name of the performance variable (string)}
+\funcarg{\IN}{var\_class}{the class of the performance variable (integer)}
+\funcarg{\OUT}{pvar\_index}{the index of the performance variable (integer)}
+\end{funcdef}
+
+\mpibind{MPI\_T\_pvar\_get\_index(const char *name, int var\_class, int *pvar\_index)}
+
+\mpifunc{MPI\_T\_PVAR\_GET\_INDEX} is a function for retrieving 
+the index of a performance variable given a known variable name and class. The 
+\mpiarg{name} and \mpiarg{var\_class} parameters are provided by the caller, and \mpiarg{pvar\_index} 
+is returned by the \MPI/ implementation. The \mpiarg{name} parameter is a string 
+terminated with a null character.
+
+This routine returns \const{MPI\_SUCCESS} on success and returns 
+\const{MPI\_T\_ERR\_INVALID\_NAME} if \mpiarg{name} does not match the 
+name of any performance variable provided by the implementation 
+at the time of the call.
+
+\begin{rationale}
+This routine is provided to enable fast retrieval of performance 
+variables by a tool, assuming it knows the name of the variable for 
+which it is looking. The number of variables exposed by the implementation 
+can change over time, so it is not possible for the tool to simply iterate 
+over the list of variables once at initialization. Although using \MPI/ 
+implementation specific variable names is not portable across \MPI/ 
+implementations, tool developers may choose to take this route for lower 
+overhead at runtime because the tool will not have to iterate over the 
+entire set of variables to find a specific one. 
+\end{rationale}
+
 \subsubsection{Performance Experiment Sessions}
 \label{sec:mpit:sessions}
 
@@ -1153,14 +1262,16 @@
 The value of index
 should be in the range $0$ to $\mpiarg{num\_pvar}-1$, where $\mpishortarg{num\_pvar}$ is the number of
 available performance variables as determined from a prior call to
-\mpifunc{MPI\_T\_PVAR\_GET\_NUM}.  The type of the \MPI/ object it references must be consistent with the type 
-returned in the \mpiarg{bind} argument in a prior call to \mpifunc{MPI\_T\_PVAR\_GET\_INFO}.
+\func{MPI\_T\_PVAR\_GET\_NUM}.  The type of the \MPI/ object it references must be consistent with the type 
+returned in the \mpiarg{bind} argument in a prior call to \func{MPI\_T\_PVAR\_GET\_INFO}.
 
-In the case the \mpiarg{bind} argument equals \const{MPI\_T\_BIND\_NO\_OBJECT}, the argument
-\mpiarg{obj\_handle} is ignored.
+For all routines in the rest of this section that take both \mpiarg{handle}
+and \mpiarg{session} as \IN\ arguments, if the \mpiarg{handle} argument passed in is not associated with the \mpiarg{session} argument, 
+\const{MPI\_T\_ERR\_INVALID\_HANDLE} is returned.
 
 
 
+
 \begin{funcdef}{MPI\_T\_PVAR\_HANDLE\_FREE(session, handle)}
 \funcarg{\IN}{session}{identifier of performance experiment session (handle)}
 \funcarg{\INOUT}{handle}{handle to be freed (handle)}
@@ -1171,7 +1282,7 @@
 \mpibind{MPI\_T\_pvar\_handle\_free(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle *handle)}
 
 When 
-a handle is no longer needed, a user of the \MPI/ tool information interface should call \mpifunc{MPI\_T\_PVAR\_HANDLE\_FREE}
+a handle is no longer needed, a user of the \MPI/ tool information interface should call \func{MPI\_T\_PVAR\_HANDLE\_FREE}
 to free the handle in the session identified
 by the parameter \mpiarg{session}
 and the associated resources in the \MPI/  implementation.
@@ -1195,7 +1306,7 @@
 
 \cdeclindex{MPI\_T\_pvar\_handle}
 \cdeclindex{MPI\_T\_pvar\_session} 
-\mpibind{MPI\_T\_pvar\_start(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle handle)}
+ \mpibind{MPI\_T\_pvar\_start(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle handle)}
 
 This functions starts the performance variable with the handle
 identified by the parameter \mpiarg{handle} in the session identified
@@ -1205,8 +1316,10 @@
 \mpiarg{handle}, the \MPI/ implementation attempts to start all variables 
 within the session identified by the parameter \mpiarg{session} for
 which handles have been allocated.  In this case, the routine returns
-\const{MPI\_SUCCESS} if all variables are started successfully,
-otherwise \const{MPI\_T\_ERR\_PVAR\_NO\_STARTSTOP} is returned. Continuous
+\const{MPI\_SUCCESS} if all variables are started successfully
+(even if there are no non-continuous variables to be started),
+otherwise \const{MPI\_T\_ERR\_PVAR\_NO\_STARTSTOP} is returned. 
+Continuous
 variables and variables that are already started are ignored when
 \const{MPI\_T\_PVAR\_ALL\_HANDLES} is specified.
 
@@ -1229,8 +1342,10 @@
 variables within the session identified by the parameter
 \mpiarg{session} for which handles have been allocated.  In this case,
 the routine returns \const{MPI\_SUCCESS} if all variables are stopped
-successfully, otherwise \const{MPI\_T\_ERR\_PVAR\_NO\_STARTSTOP} is
-returned. Continuous variables and variables that are already stopped
+successfully 
+(even if there are no non-continuous variables to be stopped),
+otherwise \const{MPI\_T\_ERR\_PVAR\_NO\_STARTSTOP} is returned. 
+Continuous variables and variables that are already stopped
 are ignored when \const{MPI\_T\_PVAR\_ALL\_HANDLES} is specified.
 
 
@@ -1246,10 +1361,11 @@
 \cdeclindex{MPI\_T\_pvar\_session}
 \mpibind{MPI\_T\_pvar\_read(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle handle, void* buf)}
 
-The \mpifunc{MPI\_T\_PVAR\_READ} call queries the value of the
+The \func{MPI\_T\_PVAR\_READ} call queries the value of the
 performance variable with the handle \mpiarg{handle} in the session
 identified by the parameter \mpiarg{session} and stores the result in
-the buffer identified by the parameter \mpiarg{buf}.  The user is
+the buffer identified by the parameter \mpiarg{buf}.  
+The user is
 responsible to ensure that the buffer is of the appropriate size to
 hold the entire value of the performance variable (based on the
 datatype and count returned by the corresponding previous calls to 
@@ -1257,7 +1373,7 @@
 
 The 
 constant \const{MPI\_T\_PVAR\_ALL\_HANDLES} cannot be used as an argument
-for the  function \mpifunc{MPI\_T\_PVAR\_READ}.
+for the  function \func{MPI\_T\_PVAR\_READ}.
 
 \begin{funcdef}{MPI\_T\_PVAR\_WRITE(session,handle, buf)}
 \funcarg{\IN}{session}{identifier of performance experiment session (handle)}
@@ -1270,10 +1386,11 @@
 \mpibind{MPI\_T\_pvar\_write(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle handle, const void* buf)}
 
 
-The \mpifunc{MPI\_T\_PVAR\_WRITE} call attempts to write the value of the
+The \func{MPI\_T\_PVAR\_WRITE} call attempts to write the value of the
 performance variable with the handle identified by the parameter
 \mpiarg{handle} in the session identified by the parameter
-\mpiarg{session}. The value to be written is passed in the buffer
+\mpiarg{session}. 
+The value to be written is passed in the buffer
 identified by the parameter \mpiarg{buf}.  The user must
 ensure that the buffer is of the appropriate size to hold the entire
 value of the performance variable (based on the
@@ -1285,9 +1402,8 @@
 \const{MPI\_T\_ERR\_PVAR\_NO\_WRITE}.
 
 The constant \const{MPI\_T\_PVAR\_ALL\_HANDLES} cannot be used as an argument
-for the  function \mpifunc{MPI\_T\_PVAR\_WRITE}.
+for the  function \func{MPI\_T\_PVAR\_WRITE}.
 
-
 \begin{funcdef}{MPI\_T\_PVAR\_RESET(session, handle)}
 \funcarg{\IN}{session}{identifier of performance experiment session (handle)}
 \funcarg{\IN}{handle}{handle of a performance variable (handle)}
@@ -1298,7 +1414,7 @@
 \mpibind{MPI\_T\_pvar\_reset(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle handle)}
 
 
-The \mpifunc{MPI\_T\_PVAR\_RESET} call sets the performance variable with
+The \func{MPI\_T\_PVAR\_RESET} call sets the performance variable with
 the handle identified by the parameter \mpiarg{handle} to its starting
 value specified in Section~\ref{sec:tools:mpit:classes}. If it is not
 possible to change the variable, the function returns
@@ -1308,8 +1424,10 @@
 \MPI/ implementation attempts to reset all variables 
 within the session identified by the parameter \mpiarg{session} for
 which handles have been allocated.  In this case, the routine returns
-\const{MPI\_SUCCESS} if all variables are reset successfully,
-otherwise \const{MPI\_T\_ERR\_PVAR\_NO\_WRITE} is returned. Read-only variables
+\const{MPI\_SUCCESS} if all variables are reset successfully
+(even if there are no valid handles or all are read-only),
+otherwise \const{MPI\_T\_ERR\_PVAR\_NO\_WRITE} is returned. 
+Read-only variables
 are ignored when \const{MPI\_T\_PVAR\_ALL\_HANDLES} is specified.
 
 
@@ -1323,28 +1441,27 @@
 \cdeclindex{MPI\_T\_pvar\_session}
 \mpibind{MPI\_T\_pvar\_readreset(MPI\_T\_pvar\_session session, MPI\_T\_pvar\_handle handle, void* buf)}
 
-This call atomically combines the functionality of \mpifunc{MPI\_T\_PVAR\_READ} and
-\mpifunc{MPI\_T\_PVAR\_RESET} with the same semantics as if these two
-calls were called separately. If atomic operations on this variable are not
+This call atomically combines the functionality of \func{MPI\_T\_PVAR\_READ} and
+\func{MPI\_T\_PVAR\_RESET} with the same semantics as if these two
+calls were called separately. 
+If atomic operations on this variable are not
 supported, this routine returns \const{MPI\_T\_ERR\_PVAR\_NO\_ATOMIC}.
 
 The constant \const{MPI\_T\_PVAR\_ALL\_HANDLES} cannot be used as an
-argument for the  function \mpifunc{MPI\_T\_PVAR\_READRESET}.
+argument for the  function \func{MPI\_T\_PVAR\_READRESET}.
 
-
-
 \begin{implementors}
-Sampling-based tools rely on the ability to call the \MPI/
+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
+MPI implementations should strive, if possible in their particular
 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. An \MPI/ implementation should clearly
+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
+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
@@ -1370,7 +1487,7 @@
 The following example shows a sample tool to identify receive
 operations that occur during times with long message queues.  This examples
 assumes that the \MPI/ implementation exports a variable with the name
-\code{MPI\_T\_UMQ\_LENGTH} to represent the current length of
+``\texttt{MPI\_T\_UMQ\_LENGTH}'' to represent the current length of
 the unexpected message queue. The tool is implemented as a
 PMPI tool using the \MPI/ profiling interface.
 
@@ -1383,7 +1500,7 @@
 would have to be extended to have similar wrappers for all
 receive operations.
 
-\paragraph{Part 1 --- Initialization:}
+\paragraph{Part 1--- Initialization:}
 
 During initialization, the tool searches for the variable and, once
 the right index is found, allocates a session and a handle for the
@@ -1555,7 +1672,7 @@
 categories, but they are not allowed to remove variables from
 categories or change the order in which they are returned.
 
-The following function can be used to query the number of control variables,
+The following function can be used to query the number of categories,
 $N$.
 
 \begin{funcdef}{MPI\_T\_CATEGORY\_GET\_NUM(num\_cat)}
@@ -1585,6 +1702,9 @@
 name must be unique with respect to all other names for 
 categories used by the \MPI/ implementation.
 
+If any \gtype{\OUT} parameter to \mpifunc{MPI\_T\_CATEGORY\_GET\_INFO} is a \consti{NULL} pointer, the implementation will ignore the parameter and not return a value for the parameter.
+
+
 \textoutdesc{desc}{the description of the category}
 
 Returning a description is optional. If an \mpi/ implementation
@@ -1598,7 +1718,39 @@
 \mpiarg{num\_pvars}, and \mpiarg{num\_categories},
 respectively.
 
+If the name of a category is equivalent across connected
+processes, then the returned description must be equivalent.
 
+\begin{funcdef}{MPI\_T\_CATEGORY\_GET\_INDEX(name, cat\_index)}
+\funcarg{\IN}{name}{the name of the category (string)}
+\funcarg{\OUT}{cat\_index}{the index of the category (integer)}
+\end{funcdef}
+
+\mpibind{MPI\_T\_category\_get\_index(const char *name, int *cat\_index)}
+
+\mpifunc{MPI\_T\_CATEGORY\_GET\_INDEX} is a function for 
+retrieving the index of a category given a known category name. The 
+\mpiarg{name} parameter is provided by the caller, and \mpiarg{cat\_index} 
+is returned by the \MPI/ implementation. The \mpiarg{name} parameter 
+is a string terminated with a null character.
+
+This routine returns \const{MPI\_SUCCESS} on success and returns 
+\const{MPI\_T\_ERR\_INVALID\_NAME} if \mpiarg{name} does not match the 
+name of any category provided by the implementation at the time of the call.
+
+\begin{rationale}
+This routine is provided to enable fast retrieval of a category index by 
+a tool, assuming it knows the name of the category for which it is looking. 
+The number of categories exposed by the implementation can change over time, 
+so it is not possible for the tool to simply iterate over the list of 
+categories once at initialization. Although using \MPI/ implementation 
+specific category names is not portable across \MPI/ implementations, 
+tool developers may choose to take this route for lower overhead at runtime 
+because the tool will not have to iterate over the entire set of categories to 
+find a specific one.
+\end{rationale}
+
+
 \begin{funcdef}{MPI\_T\_CATEGORY\_GET\_CVARS(cat\_index, len, indices)}
 \funcarg{\IN}{cat\_index}{index of the category to be queried, in the range $[0,N-1]$ (integer)}
 \funcarg{\IN}{len}{the length of the indices array (integer)}
@@ -1702,11 +1854,11 @@
 and cannot overlap with any other error codes or error
 classes returned by the \MPI/ implementation. Further, they shall be
 treated as \MPI/ error classes as defined in 
-\sectionref{sec:ei-error-classes} and follow
+Section~\ref{sec:ei-error-classes} on page~\pageref{sec:ei-error-classes} and follow
 the same rules and restrictions. In particular, they must satisfy:
 
 $$
-0 = \const{MPI\_SUCCESS} < \const{MPI\_T\_ERR\_\ldots} \leq \const{MPI\_ERR\_LASTCODE}.
+0 = \const{MPI\_SUCCESS} < \const{MPI\_T\_ERR\_...} \leq \const{MPI\_ERR\_LASTCODE}.
 $$
 
 \begin{rationale}
@@ -1725,6 +1877,7 @@
 \multicolumn{2}{|l|}{Return Codes for All Functions in the \MPI/ Tool Information Interface}\\
 \hline
 \const{MPI\_SUCCESS} & Call completed successfully\\
+\const{MPI\_T\_ERR\_INVALID} & Invalid use of the interface or bad parameter value(s) \\
 \const{MPI\_T\_ERR\_MEMORY} & Out of memory\\
 \const{MPI\_T\_ERR\_NOT\_INITIALIZED} & Interface not initialized\\
 \const{MPI\_T\_ERR\_CANNOT\_INIT} & Interface not in the state to be initialized\\ 
@@ -1735,22 +1888,25 @@
 \mpifuncindex{MPI\_T\_ENUM\_GET\_ITEM}%
 }\\
 \hline
-\const{MPI\_T\_ERR\_INVALID\_INDEX} & The enumeration index is invalid or has \\
-                                    & been deleted.\\
-\const{MPI\_T\_ERR\_INVALID\_ITEM}  & The item index queried is out of range\\
-                                  & (for \mpifunc{MPI\_T\_ENUM\_GET\_ITEM} only)\\
+\const{MPI\_T\_ERR\_INVALID\_INDEX} & The enumeration index is invalid  \\
+\const{MPI\_T\_ERR\_INVALID\_ITEM}  & The item index queried is out of range \\
+& (for \mpifunc{MPI\_T\_ENUM\_GET\_ITEM} only) \\
 \hline
 \hline
-\multicolumn{2}{|l|}{Return Codes for variable and category query functions: {\mpiskipfunc{MPI\_T\_*\_GET\_INFO}}
+\multicolumn{2}{|l|}{Return Codes for Variable and Category Query Functions: {\mpiskipfunc{MPI\_T\_*\_GET\_*}}
 \mpifuncindex{MPI\_T\_PVAR\_GET\_INFO}%
 \mpifuncindex{MPI\_T\_CVAR\_GET\_INFO}%
 \mpifuncindex{MPI\_T\_CATEGORY\_GET\_INFO}%
+\mpifuncindex{MPI\_T\_CVAR\_GET\_INDEX}%
+\mpifuncindex{MPI\_T\_PVAR\_GET\_INDEX}%
+\mpifuncindex{MPI\_T\_CATEGORY\_GET\_INDEX}%
 }\\
 \hline
 \const{MPI\_T\_ERR\_INVALID\_INDEX} & The variable or category index is invalid\\ 
+\const{MPI\_T\_ERR\_INVALID\_NAME} & The variable or category name is invalid\\ 
 \hline
 \hline
-%% BRONIS: Changed to use mpiskipfunc to be consistent with other chapters
+
 \multicolumn{2}{|l|}{Return Codes for Handle Functions: {\mpiskipfunc{MPI\_T\_*\_\textrm{\{}ALLOC$|$FREE\textrm{\}}}}
 \mpifuncindex{MPI\_T\_PVAR\_HANDLE\_ALLOC}%
 \mpifuncindex{MPI\_T\_CVAR\_HANDLE\_ALLOC}%
@@ -1758,7 +1914,7 @@
 \mpifuncindex{MPI\_T\_CVAR\_HANDLE\_FREE}%
 }\\
 \hline
-\const{MPI\_T\_ERR\_INVALID\_INDEX} & The variable index is invalid or has been deleted\\ 
+\const{MPI\_T\_ERR\_INVALID\_INDEX} & The variable index is invalid \\ 
 \const{MPI\_T\_ERR\_INVALID\_HANDLE} & The handle is invalid\\ 
 \const{MPI\_T\_ERR\_OUT\_OF\_HANDLES} & No more handles available\\ 
 \hline
@@ -1781,7 +1937,7 @@
 \hline
 \hline
 \multicolumn{2}{|l|}{Return Codes for Performance Variable Access and Control:}\\
-%% BRONIS: Changed to use mpiskipfunc to be consistent with other chapters
+
 \multicolumn{2}{|l|}{\mpiskipfunc{MPI\_T\_PVAR\_\textrm{\{}START$|$STOP$|$READ$|$WRITE$|$RESET$|$READREST\textrm{\}}}
 \mpifuncindex{MPI\_T\_PVAR\_START}%
 \mpifuncindex{MPI\_T\_PVAR\_STOP}%
@@ -1793,11 +1949,9 @@
 \hline
 \const{MPI\_T\_ERR\_INVALID\_HANDLE} & The handle is invalid\\ 
 \const{MPI\_T\_ERR\_INVALID\_SESSION} & Session argument is not a valid session\\
-%% BRONIS Changed ``can not'' to ``cannot''
 \const{MPI\_T\_ERR\_PVAR\_NO\_STARTSTOP} & Variable cannot be started or stopped\\
                                  & (for \mpifunc{MPI\_T\_PVAR\_START} and\\
                                  & \mpifunc{MPI\_T\_PVAR\_STOP})\\
-%% BRONIS Changed ``can not'' to ``cannot''
 \const{MPI\_T\_ERR\_PVAR\_NO\_WRITE} & Variable cannot be written or reset\\
                              & (for \mpifunc{MPI\_T\_PVAR\_WRITE} and\\
                              & \mpifunc{MPI\_T\_PVAR\_RESET}) \\