Merge pull request #294 from rhc54/rfc/v4fix

Final touchups to PMIx_Get and PMIx_server_init attributes

Author: jjhursey

Chap_API_Server.tex

@@ -106,6 +106,7 @@ \subsection{\code{PMIx_server_init}}
 memory backing files or cached key-value pairs) at library finalize.
 \pasteAttributeItemEnd{}
 \pasteAttributeItem{PMIX_SERVER_ENABLE_MONITORING}
+\pasteAttributeItem{PMIX_HOMOGENEOUS_SYSTEM}
 
 \optattrend
 
@@ -228,6 +229,10 @@ \subsection{Server Initialization Attributes}
 \declareAttributeNEW{PMIX_EXTERNAL_PROGRESS}{"pmix.evext"}{bool}{
 The host shall progress the \ac{PMIx} library via calls to \refapi{PMIx_Progress}
 }
+%
+\declareAttributeNEW{PMIX_HOMOGENEOUS_SYSTEM}{"pmix.homo"}{bool}{
+The nodes comprising the session are homogeneous - i.e., they each contain the same number of identical packages, fabric interfaces, \acp{GPU}, and other devices.
+}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Chap_API_Sync_Access.tex

@@ -208,11 +208,9 @@ \section{\code{PMIx_Get}}
 Returns one of the following:
 
 \begin{itemize}
-\item \refconst{PMIX_SUCCESS} The requested data has been returned.
+\item \refconst{PMIX_SUCCESS} The requested data has been returned in the manner requested (i.e., in a provided static memory location )
+\item \refconst{PMIX_ERR_BAD_PARAM} A bad parameter was passed to the function call - e.g., the request included the \refattr{PMIX_GET_STATIC_VALUES} directive, but the provided storage location was \code{NULL}
 \item \refconst{PMIX_ERR_NOT_FOUND} The requested data was not available.
-\item \refconst{PMIX_ERR_GET_MALLOC_REQD} Indicating that the returned value
-involves dynamically allocated memory instead of pointing to a static location
-as requested (only applies if \refattr{PMIX_GET_STATIC_VALUES} was included in the request).
 \item a non-zero \ac{PMIx} error constant indicating a reason for the request's failure.
 \end{itemize}
 
@@ -227,6 +225,7 @@ \section{\code{PMIx_Get}}
 \pasteAttributeItem{PMIX_APP_INFO}
 \pasteAttributeItem{PMIX_NODE_INFO}
 \pasteAttributeItem{PMIX_GET_STATIC_VALUES}
+\pasteAttributeItem{PMIX_GET_POINTER_VALUES}
 
 \reqattrend
 
@@ -240,7 +239,13 @@ \section{\code{PMIx_Get}}
 %%%%
 \descr
 
-Retrieve information for the specified \refarg{key} associated with the process identified in the given \refstruct{pmix_proc_t}, returning a pointer to the \refstruct{pmix_value_t} containing the result in the given address. See Chapters \ref{chap:api_rsvd_keys} and \ref{chap:nrkeys} for details on rules governing retrieval of information.
+Retrieve information for the specified \refarg{key} associated with the process identified in the given \refstruct{pmix_proc_t}. See Chapters \ref{chap:api_rsvd_keys} and \ref{chap:nrkeys} for details on rules governing retrieval of information. Information will be returned according to provided directives:
+
+\begin{itemize}
+    \item In the absence of any directive, the returned \refstruct{pmix_value_t} shall be an allocated memory object. The caller is responsible for releasing the object when done.
+    \item If \refattr{PMIX_GET_POINTER_VALUES} is given, then the function shall return a pointer to a \refstruct{pmix_value_t} in the \ac{PMIx} library's memory that contains the requested information.
+    \item If \refattr{PMIX_GET_STATIC_VALUES} is given, then the function shall return the information in the provided \refstruct{pmix_value_t} pointer. In this case, the caller must provide storage for the structure and pass the pointer to that storage in the \refarg{val} parameter.
+\end{itemize}
 
 This is a blocking operation - the caller will block until the retrieval rules of Chapters \ref{chap:api_rsvd_keys} or \ref{chap:nrkeys} are met.
 
@@ -290,9 +295,6 @@ \subsection{\code{PMIx_Get_nb}}
 \begin{itemize}
 \item \refconst{PMIX_SUCCESS} The requested data has been returned.
 \item \refconst{PMIX_ERR_NOT_FOUND} The requested data was not available.
-\item \refconst{PMIX_ERR_GET_MALLOC_REQD} Indicating that the returned value
-involves dynamically allocated memory instead of pointing to a static location
-as requested  (only applies if \refattr{PMIX_GET_STATIC_VALUES} was included in the request).
 \item a non-zero \ac{PMIx} error constant indicating a reason for the request's failure.
 \end{itemize}
 
@@ -306,7 +308,7 @@ \subsection{\code{PMIx_Get_nb}}
 \pasteAttributeItem{PMIX_JOB_INFO}
 \pasteAttributeItem{PMIX_APP_INFO}
 \pasteAttributeItem{PMIX_NODE_INFO}
-\pasteAttributeItem{PMIX_GET_STATIC_VALUES}
+\pasteAttributeItem{PMIX_GET_POINTER_VALUES}
 \pasteAttributeItem{PMIX_GET_REFRESH_CACHE}
 
 \divider
@@ -328,20 +330,7 @@ \subsection{\code{PMIx_Get_nb}}
 \descr
 
 The callback function will be executed once the retrieval rules of Chapters \ref{chap:api_rsvd_keys} or \ref{chap:nrkeys} are met.
-See \refapi{PMIx_Get} for a full description.
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Retrieval-specific constants}
-
-The following constants are defined for use by retrieval \acp{API}:
-
-\begin{constantdesc}
-%
-\declareconstitemNEW{PMIX_ERR_GET_MALLOC_REQD}
-The data returned by \refapi{PMIx_Get} contains values that include dynamic memory allocations (i.e., "malloc"), despite a request for static pointers to the values in the key-value store. User is responsible for releasing the memory when done with the information.
-%
-\end{constantdesc}
+See \refapi{PMIx_Get} for a full description. Note that the non-blocking form of this function cannot support the \refattr{PMIX_GET_STATIC_VALUES} attribute as the user cannot pass in the required pointer to storage for the result.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -359,8 +348,12 @@ \subsection{Retrieval attributes}
 Specified operation should immediately return an error from the \ac{PMIx} server if the requested data cannot be found - do not request it from the host \ac{RM}.
 }
 %
+\declareAttributeNEW{PMIX_GET_POINTER_VALUES}{"pmix.get.pntrs"}{bool}{
+Request that any pointers in the returned value point directly to values in the key-value store. The user \emph{must not} release any returned data pointers.
+}
+%
 \declareAttributeNEW{PMIX_GET_STATIC_VALUES}{"pmix.get.static"}{bool}{
-Request that any pointers in the returned value point directly to values in the key-value store. The user \emph{must not} release any returned data pointers. Note that a return status of \refconst{PMIX_ERR_GET_MALLOC_REQD} indicates that direct pointers could not be supported - in which case, the returned data contains allocated memory that the user must release.
+Request that the data be returned in the provided storage location. The caller is responsible for destructing the \refstruct{pmix_value_t} using the \refmacro{PMIX_VALUE_DESTRUCT} macro when done.
 }
 %
 \declareAttributeNEW{PMIX_GET_REFRESH_CACHE}{"pmix.get.refresh"}{bool}{

Chap_Revisions.tex

@@ -428,9 +428,6 @@ \subsection{Added Constants}
 \refconst{PMIX_LOCTYPE}
 \refconst{PMIX_DATA_TYPE_MAX}
 
-\littleheader{Query constants}
-\refconst{PMIX_ERR_GET_MALLOC_REQD}
-%
 %
 \littleheader{Server constants}
 \refconst{PMIX_ERR_REPEAT_ATTR_REGISTRATION}
@@ -530,6 +527,7 @@ \subsection{Added Attributes}
 %
 \pasteAttributeItem{PMIX_COLLECT_GENERATED_JOB_INFO}
 \pasteAttributeItem{PMIX_ALL_CLONES_PARTICIPATE}
+\pasteAttributeItem{PMIX_GET_POINTER_VALUES}
 \pasteAttributeItem{PMIX_GET_STATIC_VALUES}
 \pasteAttributeItem{PMIX_GET_REFRESH_CACHE}
 \pasteAttributeItem{PMIX_QUERY_RESULTS}
@@ -564,6 +562,7 @@ \subsection{Added Attributes}
 \pasteAttributeItem{PMIX_MAX_VALUE}
 \pasteAttributeItem{PMIX_MIN_VALUE}
 \pasteAttributeItem{PMIX_ENUM_VALUE}
+\pasteAttributeItem{PMIX_HOMOGENEOUS_SYSTEM}
 %
 %
 \littleheader{Job-Mgmt attributes}

Chap_Terms.tex

@@ -34,8 +34,6 @@ \chapter{PMIx Terms and Conventions}
 
 \item \declaretermAlt{clone}{clones} refers to a process that was directly started by a \ac{PMIx} client (e.g., using \emph{fork/exec}) and calls \refapi{PMIx_Init}, thus connecting to its local \ac{PMIx} server using the same namespace and rank as its parent process.
 
-\item \declaretermAlt{slot}{slots} refers to an allocated entry for a process. \acp{WLM} frequently allocate entire nodes to a \emph{session}, but can also be configured to define the maximum number of processes that can simultaneously be executed on each node. This often corresponds to the number of hardware \acp{PU} (typically cores, but can also be defined as hardware threads) on the node. However, the correlation between hardware \acp{PU} and slot allocations strictly depends upon system configuration.
-
 \item \declareterm{rank} refers to the numerical location (starting from zero) of a process within the defined scope. Thus, \emph{job rank} is the rank of a process within its \emph{job} and is synonymous with its unqualified \emph{rank}, while \emph{application rank} is the rank of that process within its \emph{application}.
 
 \item \declaretermAlt{peer}{peers} refers to another process within the same \refterm{job}.