Skip to content

Commit 3b6e1f5

Browse files
jjhurseyjjhursey
authored
Merge pull request #318 from rhc54/rfc/lists
Add macros for construction of pmix_info_t lists
2 parents d35f8b3 + be03dc8 commit 3b6e1f5

File tree

2 files changed

+127
-12
lines changed

2 files changed

+127
-12
lines changed

‎Chap_API_Struct.tex‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1294,6 +1294,116 @@ \subsubsection{Info structure support macros}
12941294
\item the structure reports a type of \refconst{PMIX_BOOL} and the data flag is \code{true}
12951295
\end{compactitemize}
12961296

1297+
%%%%%%%%%%%
1298+
\subsubsection{Info structure list macros}
1299+
Constructing an array of \refstruct{pmix_info_t} is a fairly common operation. The following macros are provided to simplify this construction.
1300+
1301+
%%%%%%%%%%%
1302+
\littleheader{Start a list of \refstruct{pmix_info_t} structures}
1303+
\declaremacro{PMIX_INFO_LIST_START}
1304+
1305+
Initialize a list of \refstruct{pmix_info_t} structures. The actual list is opaque to the caller and is implementation-dependent.
1306+
1307+
\versionMarker{4.0}
1308+
\cspecificstart
1309+
\begin{codepar}
1310+
PMIX_INFO_LIST_START(m)
1311+
\end{codepar}
1312+
\cspecificend
1313+
1314+
\begin{arglist}
1315+
\argin{m}{A \code{void*} pointer (handle)}
1316+
\end{arglist}
1317+
1318+
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.
1319+
1320+
%%%%%%%%%%%
1321+
\littleheader{Add a \refstruct{pmix_info_t} structure to a list}
1322+
\declaremacro{PMIX_INFO_LIST_ADD}
1323+
1324+
Add a \refstruct{pmix_info_t} structure containing the specified value to the provided list.
1325+
1326+
\versionMarker{4.0}
1327+
\cspecificstart
1328+
\begin{codepar}
1329+
PMIX_INFO_LIST_ADD(rc, m, k, d, t)
1330+
\end{codepar}
1331+
\cspecificend
1332+
1333+
\begin{arglist}
1334+
\arginout{rc}{Return status for the operation (\refstruct{pmix_status_t})}
1335+
\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
1336+
\argin{k}{String key to be loaded - must be less than or equal to \refconst{PMIX_MAX_KEYLEN} in length (handle)}
1337+
\argin{d}{Pointer to the data value to be loaded (handle)}
1338+
\argin{t}{Type of the provided data value (\refstruct{pmix_data_type_t})}
1339+
\end{arglist}
1340+
1341+
\adviceuserstart
1342+
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.
1343+
\adviceuserend
1344+
1345+
%%%%%%%%%%%
1346+
\littleheader{Transfer a \refstruct{pmix_info_t} structure to a list}
1347+
\declaremacro{PMIX_INFO_LIST_XFER}
1348+
1349+
Transfer the information in a \refstruct{pmix_info_t} structure to the provided list.
1350+
1351+
\versionMarker{4.0}
1352+
\cspecificstart
1353+
\begin{codepar}
1354+
PMIX_INFO_LIST_XFER(rc, m, s)
1355+
\end{codepar}
1356+
\cspecificend
1357+
1358+
\begin{arglist}
1359+
\arginout{rc}{Return status for the operation (\refstruct{pmix_status_t})}
1360+
\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
1361+
\argin{s}{Pointer to the source \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
1362+
\end{arglist}
1363+
1364+
\adviceuserstart
1365+
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.
1366+
\adviceuserend
1367+
1368+
%%%%%%%%%%%
1369+
\littleheader{Convert a \refstruct{pmix_info_t} list to an array}
1370+
\declaremacro{PMIX_INFO_LIST_CONVERT}
1371+
1372+
Transfer the information in the provided \refstruct{pmix_info_t} list to a \refstruct{pmix_data_array_t} array
1373+
1374+
\versionMarker{4.0}
1375+
\cspecificstart
1376+
\begin{codepar}
1377+
PMIX_INFO_LIST_CONVERT(rc, m, d)
1378+
\end{codepar}
1379+
\cspecificend
1380+
1381+
\begin{arglist}
1382+
\arginout{rc}{Return status for the operation (\refstruct{pmix_status_t})}
1383+
\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
1384+
\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})}
1385+
\end{arglist}
1386+
1387+
%%%%%%%%%%%
1388+
\littleheader{Release a \refstruct{pmix_info_t} list}
1389+
\declaremacro{PMIX_INFO_LIST_RELEASE}
1390+
1391+
Release the provided \refstruct{pmix_info_t} list
1392+
1393+
\versionMarker{4.0}
1394+
\cspecificstart
1395+
\begin{codepar}
1396+
PMIX_INFO_LIST_RELEASE(m)
1397+
\end{codepar}
1398+
\cspecificend
1399+
1400+
\begin{arglist}
1401+
\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
1402+
\end{arglist}
1403+
1404+
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.
1405+
1406+
12971407
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12981408
\subsection{Info Type Directives}
12991409
\declarestruct{pmix_info_directives_t}

‎Chap_Revisions.tex‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -474,7 +474,7 @@ \subsection{Deprecated attributes}
474474

475475
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
476476
%%%%%%%%%% History: Version 4.0
477-
\section{Version 4.0: Nov. 2020}
477+
\section{Version 4.0: Dec. 2020}
478478

479479
NOTE: The PMIx Standard document has undergone significant reorganization in an
480480
effort to become more user-friendly. Highlights include:
@@ -537,21 +537,21 @@ \section{Version 4.0: Nov. 2020}
537537

538538
\item Server \acp{API}
539539
\begin{compactitemize}
540-
\item \refapi{PMIx_server_generate_locality_string}
541-
\item \refapi{PMIx_Register_attributes}
542-
\item \refapi{PMIx_server_define_process_set}, \refapi{PMIx_server_delete_process_set}
543-
\item \refapi{pmix_server_grp_fn_t}, \refapi{pmix_server_fabric_fn_t}
544-
\item \refapi{pmix_server_client_connected2_fn_t}
545-
\item \refapi{PMIx_server_generate_cpuset_string}
546-
\item \refapi{PMIx_server_register_resources}, \refapi{PMIx_server_deregister_resources}
540+
\item \refapi{PMIx_server_generate_locality_string}
541+
\item \refapi{PMIx_Register_attributes}
542+
\item \refapi{PMIx_server_define_process_set}, \refapi{PMIx_server_delete_process_set}
543+
\item \refapi{pmix_server_grp_fn_t}, \refapi{pmix_server_fabric_fn_t}
544+
\item \refapi{pmix_server_client_connected2_fn_t}
545+
\item \refapi{PMIx_server_generate_cpuset_string}
546+
\item \refapi{PMIx_server_register_resources}, \refapi{PMIx_server_deregister_resources}
547547
\end{compactitemize}
548548

549549
\item Tool \acp{API}
550550
\begin{compactitemize}
551-
\item \refapi{PMIx_tool_disconnect}
552-
\item \refapi{PMIx_tool_set_server}
553-
\item \refapi{PMIx_tool_attach_to_server}
554-
\item \refapi{PMIx_tool_get_servers}
551+
\item \refapi{PMIx_tool_disconnect}
552+
\item \refapi{PMIx_tool_set_server}
553+
\item \refapi{PMIx_tool_attach_to_server}
554+
\item \refapi{PMIx_tool_get_servers}
555555
\end{compactitemize}
556556

557557
\item Data types
@@ -879,6 +879,11 @@ \subsection{Added Environmental Variables}
879879
\subsection{Added Macros}
880880
%
881881
\refmacro{PMIX_CHECK_RESERVED_KEY}
882+
\refmacro{PMIX_INFO_LIST_START}
883+
\refmacro{PMIX_INFO_LIST_ADD}
884+
\refmacro{PMIX_INFO_LIST_XFER}
885+
\refmacro{PMIX_INFO_LIST_CONVERT}
886+
\refmacro{PMIX_INFO_LIST_RELEASE}
882887
%
883888
%
884889
\subsection{Deprecated \acp{API}}

0 commit comments

Comments
 (0)