Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sync v4 to master #319

Merged
merged 1 commit into from
Dec 15, 2020
Merged

Sync v4 to master #319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions Chap_API_Struct.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1291,6 +1291,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}
Expand Down
29 changes: 17 additions & 12 deletions Chap_Revisions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -876,6 +876,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}}
Expand Down