diff --git a/App_Python.tex b/App_Python.tex index cb0bb36a..e02a1d0b 100644 --- a/App_Python.tex +++ b/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); diff --git a/Chap_API_Proc_Mgmt.tex b/Chap_API_Proc_Mgmt.tex index 4108a183..7cde4a48 100644 --- a/Chap_API_Proc_Mgmt.tex +++ b/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} diff --git a/Chap_API_Reserved_Keys.tex b/Chap_API_Reserved_Keys.tex index a917f800..4305e292 100644 --- a/Chap_API_Reserved_Keys.tex +++ b/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 diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 5b9f4e67..cfbede80 100644 --- a/Chap_API_Server.tex +++ b/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); diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex index 2713fbc3..630204e9 100644 --- a/Chap_API_Struct.tex +++ b/Chap_API_Struct.tex @@ -18,36 +18,10 @@ \chapter{Data Structures and Types} \adviceimplend \adviceuserstart -Use of increment/decrement operations on indices inside \ac{PMIx} macros is discouraged due to unpredictable behavior. For example, the following sequence: +Use of increment/decrement operations on indices inside \ac{PMIx} macros is discouraged due to unpredictable behavior as the index may be cited more than once in +the macro. The \ac{PMIx} standard only governs the existence and syntax of macros - it does not specify their implementation. -\begin{codepar} -PMIX_INFO_LOAD(&array[n++], "mykey", &mystring, PMIX_STRING); -PMIX_INFO_LOAD(&array[n++], "mykey2", &myint, PMIX_INT); -\end{codepar} - -will load the given key-values into incorrect locations if the macro is implemented as: - -\begin{codepar} -define PMIX_INFO_LOAD(m, k, v, t) \textbackslash - do \{ \textbackslash - if (NULL != (k)) \{ \textbackslash - pmix_strncpy((m)->key, (k), PMIX_MAX_KEYLEN); \textbackslash - \} \textbackslash - (m)->flags = 0; \textbackslash - pmix_value_load(&((m)->value), (v), (t)); \textbackslash - \} while (0) -\end{codepar} - -since the index is cited more than once in the macro. The \ac{PMIx} standard only governs the existence and syntax of macros - it does not specify their implementation. Given the freedom of implementation, a safer call sequence might be as follows: - -\begin{codepar} -PMIX_INFO_LOAD(&array[n], "mykey", &mystring, PMIX_STRING); -++n; -PMIX_INFO_LOAD(&array[n], "mykey2", &myint, PMIX_INT); -++n; -\end{codepar} - -Users are also advised to use the macros for creating, loading, and releasing +Users are also advised to use the macros and \acp{API} for creating, loading, and releasing \ac{PMIx} structures to avoid potential issues with release of memory. For example, pointing a \refstruct{pmix_envar_t} element at a static string variable and then using \refmacro{PMIX_ENVAR_DESTRUCT} to clear it would @@ -1065,8 +1039,8 @@ \subsection{Value Structure} \cspecificend %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Value structure support macros} -The following macros are provided to support the \refstruct{pmix_value_t} structure. +\subsubsection{Value structure support} +The following macros and \acp{API} are provided to support the \refstruct{pmix_value_t} structure. %%%% \littleheader{Static initializer for the value structure} @@ -1170,79 +1144,110 @@ \subsubsection{Value structure support macros} %%%%%%%%%%% \littleheader{Load a value structure} -\declaremacro{PMIX_VALUE_LOAD} +\declareapi{PMIx_Value_load} + +%%%% +\summary Load data into a \refstruct{pmix_value_t} structure. -\versionMarker{2.0} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_VALUE_LOAD(v, d, t); +pmix_status_t +PMIx_Value_load(pmix_value_t *val, + const void *data, + pmix_data_type_t type); \end{codepar} \cspecificend \begin{arglist} -\argin{v}{The \refstruct{pmix_value_t} into which the data is to be loaded (pointer to \refstruct{pmix_value_t})} -\argin{d}{Pointer to the data value to be loaded (handle)} -\argin{t}{Type of the provided data value (\refstruct{pmix_data_type_t})} +\argin{val}{The \refstruct{pmix_value_t} into which the data is to be loaded (pointer to \refstruct{pmix_value_t})} +\argin{data}{Pointer to the data value to be loaded (handle)} +\argin{type}{Type of the provided data value (\refstruct{pmix_data_type_t})} \end{arglist} -This macro simplifies the loading of data into a \refstruct{pmix_value_t} by correctly assigning values to the structure's fields. +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. -\adviceuserstart -The data will be copied into the \refstruct{pmix_value_t} - thus, any data stored in the source value can be modified or free'd without affecting the copied data once the macro has completed. -\adviceuserend +%%%% +\descr + +Copy the provided data into the \refstruct{pmix_value_t}. Any data stored in the source value can be modified or free'd without affecting the copied data once the function has completed. %%%%%%%%%%% \littleheader{Unload a value structure} -\declaremacro{PMIX_VALUE_UNLOAD} +\declareapi{PMIx_Value_unload} + +%%%% +\summary Unload data from a \refstruct{pmix_value_t} structure. -\versionMarker{2.2} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_VALUE_UNLOAD(r, v, d, t); +pmix_status_t +PMIx_Value_unload(pmix_value_t *val, + void **data, + size_t *sz); \end{codepar} \cspecificend \begin{arglist} -\argout{r}{Status code indicating result of the operation {\refstruct{pmix_status_t}}} -\argin{v}{The \refstruct{pmix_value_t} from which the data is to be unloaded (pointer to \refstruct{pmix_value_t})} -\arginout{d}{Pointer to the location where the data value is to be returned (handle)} -\arginout{t}{Pointer to return the data type of the unloaded value (handle)} +\argin{val}{The \refstruct{pmix_value_t} from which the data is to be unloaded (pointer to \refstruct{pmix_value_t})} +\arginout{data}{Pointer to the location where the data value is to be returned (handle)} +\arginout{sz}{Pointer to return the size of the unloaded value (handle)} \end{arglist} -This macro simplifies the unloading of data from a \refstruct{pmix_value_t}. +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. + +%%%% +\descr + +Return a copy of the data in the \refstruct{pmix_value_t}. The source value can be modified or free'd without affecting the copied data once the function has completed. \adviceuserstart -Memory will be allocated and the data will be in the \refstruct{pmix_value_t} returned - the source \refstruct{pmix_value_t} will not be altered. +Memory will be allocated and the pointer to that data will be in the \code{data} argument - the source \refstruct{pmix_value_t} will not be altered. The user is responsible for releasing the returned data. \adviceuserend %%%%%%%%%%% \littleheader{Transfer data between value structures} -\declaremacro{PMIX_VALUE_XFER} +\declareapi{PMIx_Value_xfer} + +%%%% +\summary Transfer the data value between two \refstruct{pmix_value_t} structures. -\versionMarker{2.0} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_VALUE_XFER(r, d, s); +pmix_status_t +PMIx_Value_xfer(pmix_value_t *dest, + const pmix_value_t *src); \end{codepar} \cspecificend \begin{arglist} -\argout{r}{Status code indicating success or failure of the transfer (\refstruct{pmix_status_t})} -\argin{d}{Pointer to the \refstruct{pmix_value_t} destination (handle)} -\argin{s}{Pointer to the \refstruct{pmix_value_t} source (handle)} +\argin{dest}{Pointer to the \refstruct{pmix_value_t} destination (handle)} +\argin{src}{Pointer to the \refstruct{pmix_value_t} source (handle)} \end{arglist} -This macro simplifies the transfer of data between two \refstruct{pmix_value_t} structures, ensuring that all fields are properly copied. +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. -\adviceuserstart -The data will be copied into the destination \refstruct{pmix_value_t} - thus, any data stored in the source value can be modified or free'd without affecting the copied data once the macro has completed. -\adviceuserend +%%%% +\descr + +Copy the data in the source \refstruct{pmix_value_t} into the destination \refstruct{pmix_value_t}. The source value can be modified or free'd without affecting the copied data once the function has completed. %%%%%%%%%%% \littleheader{Retrieve a numerical value from a value struct} @@ -1373,52 +1378,73 @@ \subsubsection{Info structure support macros} %%%%%%%%%%% \littleheader{Load key and value data into a info struct} -\declaremacro{PMIX_INFO_LOAD} +\declareapi{PMIx_Info_load} -\versionMarker{1.0} +%%%% +\summary + +Load data into a \refstruct{pmix_info_t} structure. + +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_LOAD(v, k, d, t); +pmix_status_t +PMIx_Info_load(pmix_info_t *info, + const char* key, + const void *data, + pmix_data_type_t type); \end{codepar} \cspecificend \begin{arglist} -\argin{v}{Pointer to the \refstruct{pmix_info_t} into which the key and data are to be loaded (pointer to \refstruct{pmix_info_t})} -\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})} +\argin{info}{The \refstruct{pmix_info_t} into which the data is to be loaded (handle)} +\argin{key}{Pointer to the key to be loaded (handle)} +\argin{data}{Pointer to the data value to be loaded (handle)} +\argin{type}{Type of the provided data value (\refstruct{pmix_data_type_t})} \end{arglist} -This macro simplifies the loading of key and data into a \refstruct{pmix_info_t} by correctly assigning values to the structure's fields. +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. -\adviceuserstart -Both key and data will be copied into the \refstruct{pmix_info_t} - 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 +%%%% +\descr + +Copy the provided data into the \refstruct{pmix_info_t}. Any data stored in the source parameters can be modified or free'd without affecting the copied data once the function has completed. %%%%%%%%%%% \littleheader{Copy data between info structures} -\declaremacro{PMIX_INFO_XFER} +\declareapi{PMIx_Info_xfer} -Copy all data (including key, value, and directives) between two \refstruct{pmix_info_t} structures. +%%%% +\summary -\versionMarker{2.0} +Copy all data between two \refstruct{pmix_info_t} structures. + +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_XFER(d, s); +pmix_status_t +PMIx_Info_xfer(pmix_info_t *dest, + pmix_info_t *src); \end{codepar} \cspecificend \begin{arglist} -\argin{d}{Pointer to the destination \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})} -\argin{s}{Pointer to the source \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})} +\argin{dest}{The \refstruct{pmix_info_t} into which the data is to be copied (handle)} +\argin{src}{The \refstruct{pmix_info_t} from which the data is to be copied (handle)} \end{arglist} -This macro simplifies the transfer of data between two\refstruct{pmix_info_t} structures. +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. -\adviceuserstart -All data (including key, value, and directives) will be copied into the destination \refstruct{pmix_info_t} - thus, the source \refstruct{pmix_info_t} may be free'd without affecting the copied data once the macro has completed. -\adviceuserend +%%%% +\descr +Copy the data in the source \refstruct{pmix_info_t} into the destination. Any data stored in the source structure can be modified or free'd without affecting the copied data once the function has completed. %%%%%%%%%%% \littleheader{Test a boolean info struct} @@ -1450,107 +1476,164 @@ \subsubsection{Info structure list macros} %%%%%%%%%%% \littleheader{Start a list of \refstruct{pmix_info_t} structures} -\declaremacro{PMIX_INFO_LIST_START} +\declareapi{PMIx_Info_list_start} + +%%%% +\summary Initialize a list of \refstruct{pmix_info_t} structures. The actual list is opaque to the caller and is implementation-dependent. -\versionMarker{4.0} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_LIST_START(m) +void* +PMIx_Info_list_start(void); \end{codepar} \cspecificend -\begin{arglist} -\argin{m}{A \code{void*} pointer (handle)} -\end{arglist} +%%%% +\descr -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. +Note that the returned 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} +\declareapi{PMIx_Info_list_add} + +%%%% +\summary Add a \refstruct{pmix_info_t} structure containing the specified value to the provided list. -\versionMarker{4.0} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_LIST_ADD(rc, m, k, d, t) +pmix_status_t +PMIx_Info_list_add(void *ptr, + const char *key, + const void *value, + pmix_data_type_t type); \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})} +\argin{ptr}{A \code{void*} pointer initialized via \refapi{PMIx_Info_list_start} (handle)} +\argin{key}{String key to be loaded - must be less than or equal to \refconst{PMIX_MAX_KEYLEN} in length (handle)} +\argin{value}{Pointer to the data value to be loaded (handle)} +\argin{type}{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 +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. + +%%%% +\descr + +Copy the provided key and data into a \refstruct{pmix_info_t} on the list. The key and any data stored in the source value can be modified or free'd without affecting the copied data once the function has completed. %%%%%%%%%%% \littleheader{Transfer a \refstruct{pmix_info_t} structure to a list} -\declaremacro{PMIX_INFO_LIST_XFER} +\declareapi{PMIx_Info_list_xfer} -Transfer the information in a \refstruct{pmix_info_t} structure to the provided list. +%%%% +\summary -\versionMarker{4.0} +Transfer the information in a \refstruct{pmix_info_t} structure to a structure on the provided list. + +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_LIST_XFER(rc, m, s) +pmix_status_t +PMIx_Info_list_xfer(void *ptr, + const pmix_info_t *src); \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})} +\argin{ptr}{A \code{void*} pointer initialized via \refapi{PMIx_Info_list_start} (handle)} +\argin{src}{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 +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. + +%%%% +\descr + +All data (including key, value, and directives) will be copied into a destination \refstruct{pmix_info_t} on the list. The source \refstruct{pmix_info_t} may be free'd without affecting the copied data once the function has completed. + %%%%%%%%%%% \littleheader{Convert a \refstruct{pmix_info_t} list to an array} -\declaremacro{PMIX_INFO_LIST_CONVERT} +\declareapi{PMIx_Info_list_convert} + +%%%% +\summary Transfer the information in the provided \refstruct{pmix_info_t} list to a \refstruct{pmix_data_array_t} array -\versionMarker{4.0} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_LIST_CONVERT(rc, m, d) +pmix_status_t +PMIx_Info_list_convert(void *ptr, + pmix_data_array_t *par); \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})} +\argin{ptr}{A \code{void*} pointer initialized via \refapi{PMIx_Info_list_start} (handle)} +\argin{par}{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} +Returns \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant. + +%%%% +\descr + +Information collected in the provided list of \refstruct{pmix_info_t} will be transferred to a \refstruct{pmix_data_array_t} containing \refstruct{pmix_info_t} structures. + + %%%%%%%%%%% \littleheader{Release a \refstruct{pmix_info_t} list} -\declaremacro{PMIX_INFO_LIST_RELEASE} +\declareapi{PMIx_Info_list_release} + +%%%% +\summary Release the provided \refstruct{pmix_info_t} list -\versionMarker{4.0} +%%%% +\format + +\versionMarker{4.2} \cspecificstart \begin{codepar} -PMIX_INFO_LIST_RELEASE(m) +void +PMIx_Info_list_release(void *ptr); \end{codepar} \cspecificend + \begin{arglist} -\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)} +\argin{ptr}{A \code{void*} pointer initialized via \refapi{PMIx_Info_list_start} (handle)} \end{arglist} +%%%% +\descr + 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. diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 34574721..86dbc0e3 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -1324,10 +1324,38 @@ \subsection{Deprecated attributes} Renamed to \refattr{PMIX_DEBUG_STOP_IN_APP} } +\subsection{Deprecated macros} + +The following macros were deprecated in v4.2: + +\begin{compactitemize} + \item \declaremacroDEP{PMIX_VALUE_LOAD} Replaced by the \refapi{PMIx_Value_load} \ac{API} + \item \declaremacroDEP{PMIX_VALUE_UNLOAD} Replaced by the \refapi{PMIx_Value_unload} \ac{API} + \item \declaremacroDEP{PMIX_VALUE_XFER} Replaced by the \refapi{PMIx_Value_xfer} \ac{API} + \item \declaremacroDEP{PMIX_INFO_LOAD} Replaced by the \refapi{PMIx_Info_load} \ac{API} + \item \declaremacroDEP{PMIX_INFO_XFER} Replaced by the \refapi{PMIx_Info_xfer} \ac{API} + \item \declaremacroDEP{PMIX_INFO_LIST_START} Replaced by the \refapi{PMIx_Info_list_start} \ac{API} + \item \declaremacroDEP{PMIX_INFO_LIST_ADD} Replaced by the \refapi{PMIx_Info_list_add} \ac{API} + \item \declaremacroDEP{PMIX_INFO_LIST_XFER} Replaced by the \refapi{PMIx_Info_list_xfer} \ac{API} + \item \declaremacroDEP{PMIX_INFO_LIST_CONVERT} Replaced by the \refapi{PMIx_Info_list_convert} \ac{API} + \item \declaremacroDEP{PMIX_INFO_LIST_RELEASE} Replaced by the \refapi{PMIx_Info_list_release} \ac{API} + \item \declaremacroDEP{PMIX_TOPOLOGY_DESTRUCT} Replaced by the \refapi{PMIx_Topology_destruct} \ac{API} + \item \declaremacroDEP{PMIX_TOPOLOGY_FREE} Not replaced. +\end{compactitemize} + \subsection{Added Functions (Provisional)} \begin{compactitemize} \item \refapi{PMIx_Data_embed} + \item \refapi{PMIx_Value_load} + \item \refapi{PMIx_Value_unload} + \item \refapi{PMIx_Value_xfer} + \item \refapi{PMIx_Info_list_start} + \item \refapi{PMIx_Info_list_add} + \item \refapi{PMIx_Info_list_xfer} + \item \refapi{PMIx_Info_list_convert} + \item \refapi{PMIx_Info_list_release} + \item \refapi{PMIx_Topology_destruct} \end{compactitemize} \subsection{Added Macros (Provisional)} diff --git a/pmix.sty b/pmix.sty index 84b318dd..68e1840d 100644 --- a/pmix.sty +++ b/pmix.sty @@ -657,6 +657,16 @@ \newcommand{\refmacro}[1]{\index[index_macro]{#1}\hyperref[macro:#1]{\code{#1}}} +\newcommand{\declaremacroDEPNODISP}[1]{% + \index[index_macro]{Z_#1@#1!\textbf{(Deprecated)}|indexdepfmt} \label{macro:#1}% +} + +\newcommand{\declaremacroDEP}[1]{% + {\color{green!80!black}\code{#1}}% + \declaremacroDEPNODISP{#1}% +} + + %------------------------------- % Terms %