From be03dc8dcb42c331f2303b49f0b1147e337d9ee6 Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Mon, 14 Dec 2020 11:01:52 -0800 Subject: [PATCH] Add macros for construction of pmix_info_t lists Greatly helpful when building pmix_info_t arrays! Update Chap_API_Struct.tex Signed-off-by: Ralph Castain Co-authored-by: Josh Hursey <4259120+jjhursey@users.noreply.github.com> --- Chap_API_Struct.tex | 110 ++++++++++++++++++++++++++++++++++++++++++++ Chap_Revisions.tex | 29 +++++++----- 2 files changed, 127 insertions(+), 12 deletions(-) diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex index 250c067a..5074dd0c 100644 --- 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 index cdb1b770..81cf6ed7 100644 --- 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}}