This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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