Merge pull request #318 from rhc54/rfc/lists

Add macros for construction of pmix_info_t lists
pmix · Dec 15, 2020 · 3b6e1f5 · 3b6e1f5
2 parents d35f8b3 + be03dc8
commit 3b6e1f5
Show file tree

Hide file tree

Showing 2 changed files with 127 additions and 12 deletions.
diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex
@@ -1294,6 +1294,116 @@ \subsubsection{Info structure support macros}
     \item the structure reports a type of \refconst{PMIX_BOOL} and the data flag is \code{true}
 \end{compactitemize}
 
+%%%%%%%%%%%
+\subsubsection{Info structure list macros}
+Constructing an array of \refstruct{pmix_info_t} is a fairly common operation. The following macros are provided to simplify this construction.
+
+%%%%%%%%%%%
+\littleheader{Start a list of \refstruct{pmix_info_t} structures}
+\declaremacro{PMIX_INFO_LIST_START}
+
+Initialize a list of \refstruct{pmix_info_t} structures. The actual list is opaque to the caller and is implementation-dependent.
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_LIST_START(m)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{m}{A \code{void*} pointer (handle)}
+\end{arglist}
+
+Note that the pointer will be initialized to an opaque structure whose elements are implementation-dependent. The caller must not modify or dereference the object.
+
+%%%%%%%%%%%
+\littleheader{Add a \refstruct{pmix_info_t} structure to a list}
+\declaremacro{PMIX_INFO_LIST_ADD}
+
+Add a \refstruct{pmix_info_t} structure containing the specified value to the provided list.
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_LIST_ADD(rc, m, k, d, t)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\arginout{rc}{Return status for the operation (\refstruct{pmix_status_t})}
+\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
+\argin{k}{String key to be loaded - must be less than or equal to \refconst{PMIX_MAX_KEYLEN} in length (handle)}
+\argin{d}{Pointer to the data value to be loaded (handle)}
+\argin{t}{Type of the provided data value (\refstruct{pmix_data_type_t})}
+\end{arglist}
+
+\adviceuserstart
+Both key and data will be copied into the \refstruct{pmix_info_t} on the list - thus, the key and any data stored in the source value can be modified or free'd without affecting the copied data once the macro has completed.
+\adviceuserend
+
+%%%%%%%%%%%
+\littleheader{Transfer a \refstruct{pmix_info_t} structure to a list}
+\declaremacro{PMIX_INFO_LIST_XFER}
+
+Transfer the information in a \refstruct{pmix_info_t} structure to the provided list.
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_LIST_XFER(rc, m, s)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\arginout{rc}{Return status for the operation (\refstruct{pmix_status_t})}
+\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
+\argin{s}{Pointer to the source \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
+\end{arglist}
+
+\adviceuserstart
+All data (including key, value, and directives) will be copied into the destination \refstruct{pmix_info_t} on the list - thus, the source \refstruct{pmix_info_t} may be free'd without affecting the copied data once the macro has completed.
+\adviceuserend
+
+%%%%%%%%%%%
+\littleheader{Convert a \refstruct{pmix_info_t} list to an array}
+\declaremacro{PMIX_INFO_LIST_CONVERT}
+
+Transfer the information in the provided \refstruct{pmix_info_t} list to a \refstruct{pmix_data_array_t} array
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_LIST_CONVERT(rc, m, d)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\arginout{rc}{Return status for the operation (\refstruct{pmix_status_t})}
+\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
+\argin{d}{Pointer to an instantiated \refstruct{pmix_data_array_t} structure where the \refstruct{pmix_info_t} array is to be stored (pointer to \refstruct{pmix_data_array_t})}
+\end{arglist}
+
+%%%%%%%%%%%
+\littleheader{Release a \refstruct{pmix_info_t} list}
+\declaremacro{PMIX_INFO_LIST_RELEASE}
+
+Release the provided \refstruct{pmix_info_t} list
+
+\versionMarker{4.0}
+\cspecificstart
+\begin{codepar}
+PMIX_INFO_LIST_RELEASE(m)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
+\end{arglist}
+
+Information contained in the \refstruct{pmix_info_t} on the list shall be released in addition to whatever backing storage the implementation may have allocated to support construction of the list.
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Info Type Directives}
 \declarestruct{pmix_info_directives_t}

diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex
@@ -474,7 +474,7 @@ \subsection{Deprecated attributes}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%% History: Version 4.0
-\section{Version 4.0: Nov. 2020}
+\section{Version 4.0: Dec. 2020}
 
 NOTE: The PMIx Standard document has undergone significant reorganization in an
 effort to become more user-friendly. Highlights include:
@@ -537,21 +537,21 @@ \section{Version 4.0: Nov. 2020}
 
     \item Server \acp{API}
     \begin{compactitemize}
-    \item \refapi{PMIx_server_generate_locality_string}
-    \item \refapi{PMIx_Register_attributes}
-    \item \refapi{PMIx_server_define_process_set}, \refapi{PMIx_server_delete_process_set}
-    \item \refapi{pmix_server_grp_fn_t}, \refapi{pmix_server_fabric_fn_t}
-    \item \refapi{pmix_server_client_connected2_fn_t}
-    \item \refapi{PMIx_server_generate_cpuset_string}
-    \item \refapi{PMIx_server_register_resources}, \refapi{PMIx_server_deregister_resources}
+        \item \refapi{PMIx_server_generate_locality_string}
+        \item \refapi{PMIx_Register_attributes}
+        \item \refapi{PMIx_server_define_process_set}, \refapi{PMIx_server_delete_process_set}
+        \item \refapi{pmix_server_grp_fn_t}, \refapi{pmix_server_fabric_fn_t}
+        \item \refapi{pmix_server_client_connected2_fn_t}
+        \item \refapi{PMIx_server_generate_cpuset_string}
+        \item \refapi{PMIx_server_register_resources}, \refapi{PMIx_server_deregister_resources}
     \end{compactitemize}
 
     \item Tool \acp{API}
     \begin{compactitemize}
-    \item \refapi{PMIx_tool_disconnect}
-    \item \refapi{PMIx_tool_set_server}
-    \item \refapi{PMIx_tool_attach_to_server}
-    \item \refapi{PMIx_tool_get_servers}
+        \item \refapi{PMIx_tool_disconnect}
+        \item \refapi{PMIx_tool_set_server}
+        \item \refapi{PMIx_tool_attach_to_server}
+        \item \refapi{PMIx_tool_get_servers}
     \end{compactitemize}
 
     \item Data types
@@ -879,6 +879,11 @@ \subsection{Added Environmental Variables}
 \subsection{Added Macros}
 %
 \refmacro{PMIX_CHECK_RESERVED_KEY}
+\refmacro{PMIX_INFO_LIST_START}
+\refmacro{PMIX_INFO_LIST_ADD}
+\refmacro{PMIX_INFO_LIST_XFER}
+\refmacro{PMIX_INFO_LIST_CONVERT}
+\refmacro{PMIX_INFO_LIST_RELEASE}
 %
 %
 \subsection{Deprecated \acp{API}}