| 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}) \\ |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment