Merge pull request #383 from rhc54/rfc/macrm

Convert several macros to APIs

App_Python.tex

@@ -111,8 +111,8 @@ \subsection{Example}
 
 pmix_info_t info[2];
 
-PMIX_INFO_LOAD(&info[0], PMIX_PROGRAMMING_MODEL, "TEST", PMIX_STRING)
-PMIX_INFO_LOAD(&info[1], PMIX_MODEL_LIBRARY_NAME, "PMIX", PMIX_STRING)
+PMIx_Info_load(&info[0], PMIX_PROGRAMMING_MODEL, "TEST", PMIX_STRING)
+PMIx_Info_load(&info[1], PMIX_MODEL_LIBRARY_NAME, "PMIX", PMIX_STRING)
 
 rc = PMIx_Init(&myproc, info, 2);
 

Chap_API_Proc_Mgmt.tex

@@ -1243,22 +1243,33 @@ \subsubsection{Topology support macros}
 \end{arglist}
 
 
-\littleheader{Destruct the topology structure}
-\declaremacro{PMIX_TOPOLOGY_DESTRUCT}
+\littleheader{Destruct a topology structure}
+\declareapi{PMIx_Topology_destruct}
 
-Destruct the \refstruct{pmix_topology_t} fields
+%%%%
+\summary
 
-\versionMarker{4.0}
+Destruct a \refstruct{pmix_topology_t} fields
+
+%%%%
+\format
+
+\versionMarker{4.2}
 \cspecificstart
 \begin{codepar}
-PMIX_TOPOLOGY_DESTRUCT(m)
+void
+PMIx_Topology_destruct(pmix_topology_t *topo);
 \end{codepar}
 \cspecificend
 
 \begin{arglist}
-\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_topology_t})}
+\argin{topo}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_topology_t})}
 \end{arglist}
 
+%%%%
+\descr
+
+Release any memory storage held by the \refstruct{pmix_topology_t} structure
 
 \littleheader{Create a topology array}
 \declaremacro{PMIX_TOPOLOGY_CREATE}
@@ -1278,24 +1289,6 @@ \subsubsection{Topology support macros}
 \end{arglist}
 
 
-\littleheader{Release a topology array}
-\declaremacro{PMIX_TOPOLOGY_FREE}
-
-Release a \refstruct{pmix_topology_t} array.
-
-\versionMarker{4.0}
-\cspecificstart
-\begin{codepar}
-PMIX_TOPOLOGY_FREE(m, n)
-\end{codepar}
-\cspecificend
-
-\begin{arglist}
-\arginout{m}{Address of the array of \refstruct{pmix_topology_t} structures to be released (handle)}
-\argin{n}{Number of structures in the array (size_t)}
-\end{arglist}
-
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Relative locality of two processes}
 \declarestruct{pmix_locality_t}

Chap_API_Reserved_Keys.tex

@@ -572,7 +572,7 @@ \subsubsection{Session-level information}
 rc = PMIx_Get(&wildcard, PMIX_UNIV_SIZE, NULL, 0, &value);
 
 /* get the #nodes in our session */
-PMIX_INFO_LOAD(&info, PMIX_SESSION_INFO, NULL, PMIX_BOOL);
+PMIx_Info_load(&info, PMIX_SESSION_INFO, NULL, PMIX_BOOL);
 rc = PMIx_Get(&wildcard, PMIX_NUM_NODES, &info, 1, &value);
 \end{codepar}
 \cspecificend
@@ -592,8 +592,8 @@ \subsubsection{Session-level information}
 
 /* get the #nodes in a different session */
 sid = 12345;
-PMIX_INFO_LOAD(&info[0], PMIX_SESSION_INFO, NULL, PMIX_BOOL);
-PMIX_INFO_LOAD(&info[1], PMIX_SESSION_ID, &sid, PMIX_UINT32);
+PMIx_Info_load(&info[0], PMIX_SESSION_INFO, NULL, PMIX_BOOL);
+PMIx_Info_load(&info[1], PMIX_SESSION_ID, &sid, PMIX_UINT32);
 rc = PMIx_Get(NULL, PMIX_NUM_NODES, info, 2, &value);
 \end{codepar}
 \cspecificend
@@ -619,7 +619,7 @@ \subsubsection{Job-level information}
 rc = PMIx_Get(&wildcard, PMIX_JOB_NUM_APPS, NULL, 0, &value);
 
 /* get the #nodes in our job */
-PMIX_INFO_LOAD(&info, PMIX_JOB_INFO, NULL, PMIX_BOOL);
+PMIx_Info_load(&info, PMIX_JOB_INFO, NULL, PMIX_BOOL);
 rc = PMIx_Get(&wildcard, PMIX_NUM_NODES, &info, 1, &value);
 \end{codepar}
 \cspecificend
@@ -655,7 +655,7 @@ \subsubsection{Application-level information}
 /* Since "otherproc" refers to a process in the second application,
  * we can simply mark that we want the info for this key from the
  * application realm */
-PMIX_INFO_LOAD(&info, PMIX_APP_INFO, NULL, PMIX_BOOL);
+PMIx_Info_load(&info, PMIX_APP_INFO, NULL, PMIX_BOOL);
 rc = PMIx_Get(&otherproc, PMIX_NUM_NODES, &info, 1, &value);
 
 /* alternatively, we can directly ask for the #nodes in
@@ -664,8 +664,8 @@ \subsubsection{Application-level information}
  * for application realm information about a specific appnum
  * within our own namespace, the process identifier can be NULL */
 appnum = 1;
-PMIX_INFO_LOAD(&appinfo[0], PMIX_APP_INFO, NULL, PMIX_BOOL);
-PMIX_INFO_LOAD(&appinfo[1], PMIX_APPNUM, &appnum, PMIX_UINT32);
+PMIx_Info_load(&appinfo[0], PMIX_APP_INFO, NULL, PMIX_BOOL);
+PMIx_Info_load(&appinfo[1], PMIX_APPNUM, &appnum, PMIX_UINT32);
 rc = PMIx_Get(NULL, PMIX_NUM_NODES, appinfo, 2, &value);
 \end{codepar}
 \cspecificend
@@ -697,8 +697,8 @@ \subsubsection{Node-level information}
 rc = PMIx_Get(&myproc, PMIX_NODE_SIZE, NULL, 0, &value);
 
 /* get the #slots on another node */
-PMIX_INFO_LOAD(&info[0], PMIX_NODE_INFO, NULL, PMIX_BOOL);
-PMIX_INFO_LOAD(&info[1], PMIX_HOSTNAME, "remotehost", PMIX_STRING);
+PMIx_Info_load(&info[0], PMIX_NODE_INFO, NULL, PMIX_BOOL);
+PMIx_Info_load(&info[1], PMIX_HOSTNAME, "remotehost", PMIX_STRING);
 rc = PMIx_Get(NULL, PMIX_MAX_PROCS, info, 2, &value);
 
 /* get the total #procs on the remote node - note that we don't

Chap_API_Server.tex

@@ -620,7 +620,7 @@ \subsubsection{Assembling the registration information}
 The following description is not intended to represent the actual layout of information in a given \ac{PMIx} library. Instead, it is describes how information provided in the \refarg{info} parameter of the \refapi{PMIx_server_register_nspace} shall be organized for proper processing by a \ac{PMIx} server library. The ordering of the various information elements is arbitrary - they are presented in a top-down hierarchical form solely for clarity in reading.
 
 \advicermstart
-Creating the \refarg{info} array of data requires knowing in advance the number of elements required for the array. This can be difficult to compute and somewhat fragile in practice. One method for resolving the problem is to create a linked list of objects, each containing a single \refstruct{pmix_info_t} structure. Allocation and manipulation of the list can then be accomplished using existing standard methods. Upon completion, the final \refarg{info} array can be allocated based on the number of elements on the list, and then the values in the list object \refstruct{pmix_info_t} structures transferred to the corresponding array element utilizing the \refmacro{PMIX_INFO_XFER} macro.
+Creating the \refarg{info} array of data requires knowing in advance the number of elements required for the array. This can be difficult to compute and somewhat fragile in practice. One method for resolving the problem is to create a linked list of objects, each containing a single \refstruct{pmix_info_t} structure. Allocation and manipulation of the list can then be accomplished using existing standard methods. Upon completion, the final \refarg{info} array can be allocated based on the number of elements on the list, and then the values in the list object \refstruct{pmix_info_t} structures transferred to the corresponding array element utilizing the \refapi{PMIx_Info_xfer} \ac{API}.
 \advicermend
 
 \label{cptr:api_server:noderegex}A common building block used in several areas is the construction of a regular expression identifying the nodes involved in that area - e.g., the nodes in a \refterm{session} or \refterm{job}. \ac{PMIx} provides several tools to facilitate this operation, beginning by constructing an argv-like array of node names. This array is then passed to the \refapi{PMIx_generate_regex} function to create a regular expression parseable by the \ac{PMIx} server library, as shown below:
@@ -656,7 +656,7 @@ \subsubsection{Assembling the registration information}
 free(nodelist);
 
 /* pass the regex as the value to the PMIX_NODE_MAP key */
-PMIX_INFO_LOAD(&info, PMIX_NODE_MAP, regex, PMIX_REGEX);
+PMIx_Info_load(&info, PMIX_NODE_MAP, regex, PMIX_REGEX);
 /* release the regex */
 free(regex);
 \end{codepar}
@@ -713,7 +713,7 @@ \subsubsection{Assembling the registration information}
 free(ppn);
 
 /* pass the regex as the value to the PMIX_PROC_MAP key */
-PMIX_INFO_LOAD(&info, PMIX_PROC_MAP, regex, PMIX_REGEX);
+PMIx_Info_load(&info, PMIX_PROC_MAP, regex, PMIX_REGEX);
 /* release the regex */
 free(regex);
 \end{codepar}
@@ -809,7 +809,7 @@ \subsubsection{Assembling the registration information}
 PMIX_ARGV_FREE(ndppn);
 
 /* pass the string as the value to the PMIX_LOCAL_PEERS key */
-PMIX_INFO_LOAD(&info, PMIX_LOCAL_PEERS, localranks, PMIX_STRING);
+PMIx_Info_load(&info, PMIX_LOCAL_PEERS, localranks, PMIX_STRING);
 
 /* release the list */
 free(localranks);
@@ -838,7 +838,7 @@ \subsubsection{Assembling the registration information}
 PMIX_ARGV_FREE(ndcpus);
 
 /* pass the string as the value to the PMIX_LOCAL_CPUSETS key */
-PMIX_INFO_LOAD(&info, PMIX_LOCAL_CPUSETS, localcpus, PMIX_STRING);
+PMIx_Info_load(&info, PMIX_LOCAL_CPUSETS, localcpus, PMIX_STRING);
 
 /* release the list */
 free(localcpus);