Merge pull request #351 from jjhursey/cp-v4-items

Cherry-pick of v4 Provisional and Errata

Chap_API_Data_Mgmt.tex

@@ -384,4 +384,201 @@ \subsection{\code{PMIx_Data_copy_payload}}
 This function will append a copy of the payload in one buffer into another buffer. Note that this is \textit{not} a destructive procedure --- the source buffer's payload will remain intact, as will any pre-existing payload in the destination's buffer. Only the unpacked portion of the source payload will be copied.
 
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\code{PMIx_Data_load}}
+\declareapi{PMIx_Data_load}
+
+%%%%
+\summary
+
+Load a buffer with the provided payload
+
+%%%%
+\format
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+pmix_status_t
+PMIx_Data_load(pmix_data_buffer_t *dest,
+               pmix_byte_object_t *src);
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{dest}{Pointer to the destination \refstruct{pmix_data_buffer_t} (handle)}
+\argin{src}{Pointer to the source \refstruct{pmix_byte_object_t} (handle)}
+\end{arglist}
+
+Returns one of the following:
+\begin{constantdesc}
+\item \refconst{PMIX_SUCCESS} The data has been loaded as requested
+\item \refconst{PMIX_ERR_BAD_PARAM} The \refarg{dest} structure pointer is \code{NULL}
+\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
+\end{constantdesc}
+
+%%%%
+\descr
+
+The load function allows the caller to transfer the contents of the \refarg{src}
+\refstruct{pmix_byte_object_t} to the \refarg{dest} target buffer. If a payload
+already exists in the buffer, the function will "free" the existing data to
+release it, and then replace the data payload with the one provided
+by the caller.
+
+\adviceuserstart
+The buffer must be allocated or constructed in advance - failing to do so
+will cause the load function to return an error code.
+
+The caller is responsible for pre-packing the provided
+payload. For example, the load function cannot convert to network byte order
+any data contained in the provided payload.
+\adviceuserend
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{\code{PMIx_Data_unload}}
+\declareapi{PMIx_Data_unload}
+
+%%%%
+\summary
+
+Unload a buffer into a byte object
+
+%%%%
+\format
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+pmix_status_t
+PMIx_Data_unload(pmix_data_buffer_t *src,
+                 pmix_byte_object_t *dest);
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{src}{Pointer to the source \refstruct{pmix_data_buffer_t} (handle)}
+\argin{dest}{Pointer to the destination \refstruct{pmix_byte_object_t} (handle)}
+\end{arglist}
+
+Returns one of the following:
+\begin{constantdesc}
+\item \refconst{PMIX_SUCCESS} The data has been copied as requested
+\item \refconst{PMIX_ERR_BAD_PARAM} The destination and/or source pointer is \code{NULL}
+\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
+\end{constantdesc}
+
+%%%%
+\descr
+
+The unload function provides the caller with a pointer to the
+portion of the data payload within the buffer that has not yet been
+unpacked, along with the size of that region. Any portion of
+the payload that was previously unpacked using the \refapi{PMIx_Data_unpack}
+routine will be ignored. This allows the user to directly access the payload.
+
+\adviceuserstart
+This is a destructive operation. While the payload returned in the
+destination \refstruct{pmix_byte_object_t} is
+undisturbed, the function will clear the \refarg{src}'s pointers to the
+payload. Thus, the \refarg{src} and the payload are completely separated,
+leaving the caller able to free or destruct the \refarg{src}.
+\adviceuserend
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{\code{PMIx_Data_compress}}
+\declareapi{PMIx_Data_compress}
+
+%%%%
+\summary
+
+Perform a lossless compression on the provided data
+
+%%%%
+\format
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+bool
+PMIx_Data_compress(const uint8_t *inbytes, size_t size,
+                   uint8_t **outbytes, size_t *nbytes);
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{inbytes}{Pointer to the source data (handle)}
+\argin{size}{Number of bytes in the source data region (\code{size_t})}
+\argout{outbytes}{Address where the pointer to the compressed data region is to be returned (handle)}
+\argout{nbytes}{Address where the number of bytes in the compressed data region is to be returned (handle)}
+\end{arglist}
+
+Returns one of the following:
+\begin{itemize}
+\item \code{True} The data has been compressed as requested
+\item \code{False} The data has not been compressed
+\end{itemize}
+
+%%%%
+\descr
+
+Compress the provided data block. Destination memory
+will be allocated if operation is successfully concluded. Caller
+is responsible for release of the allocated region. The input
+data block will remain unaltered.
+
+Note: the compress function will return \code{False} if the operation
+would not result in a smaller data block.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{\code{PMIx_Data_decompress}}
+\declareapi{PMIx_Data_decompress}
+
+%%%%
+\summary
+
+Decompress the provided data
+
+%%%%
+\format
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+bool
+PMIx_Data_decompress(const uint8_t *inbytes, size_t size,
+                     uint8_t **outbytes, size_t *nbytes,);
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argout{outbytes}{Address where the pointer to the decompressed data region is to be returned (handle)}
+\argout{nbytes}{Address where the number of bytes in the decompressed data region is to be returned (handle)}
+\argin{inbytes}{Pointer to the source data (handle)}
+\argin{size}{Number of bytes in the source data region (\code{size_t})}
+\end{arglist}
+
+Returns one of the following:
+\begin{itemize}
+\item \code{True} The data has been decompressed as requested
+\item \code{False} The data has not been decompressed
+\end{itemize}
+
+%%%%
+\descr
+
+Decompress the provided data block. Destination memory
+will be allocated if operation is successfully concluded. Caller
+is responsible for release of the allocated region. The input
+data block will remain unaltered.
+
+Only data compressed by the \refapi{PMIx_Data_compress} \ac{API}
+can be decompressed by this function. Passing data that has not
+been compressed by \refapi{PMIx_Data_compress} will lead to
+unexpected and potentially catastrophic results.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Chap_API_Event.tex

@@ -43,7 +43,7 @@ \section{Notification and Management}
 %
 \end{itemize}
 
-Users can specify the callback order of a handler within its category at the time of registration. Ordering can be specified either by providing the relevant returned event handler registration ID or using event handler names, if the user specified an event handler name when registering the corresponding event. Thus, users can specify that a given handler be executed before or after another handler should both handlers appear in an event chain (the ordering is ignored if the other handler isn't included). Note that ordering does not imply immediate relationships. For example, multiple handlers registered to be serviced after event handler \textit{A} will all be executed after \textit{A}, but are not guaranteed to be executed in any particular order amongst themselves.
+Users can specify the callback order of a handler within its category at the time of registration. Ordering can be specified by providing the relevant event handler names, if the user specified an event handler name when registering the corresponding event. Thus, users can specify that a given handler be executed before or after another handler should both handlers appear in an event chain (the ordering is ignored if the other handler isn't included). Note that ordering does not imply immediate relationships. For example, multiple handlers registered to be serviced after event handler \textit{A} will all be executed after \textit{A}, but are not guaranteed to be executed in any particular order amongst themselves.
 
 In addition, one event handler can be declared as the \textit{first} handler to be executed in the chain. This handler will \textit{always} be called prior to any other handler, regardless of category, provided the incoming event matches both the specified range and event code. Only one handler can be so designated --- attempts to designate additional handlers as \textit{first} will return an error. Deregistration of the declared \textit{first} handler will re-open the position for subsequent assignment.
 

Chap_API_Struct.tex

@@ -353,6 +353,24 @@ \subsubsection{Namespace support macros}
 
 Returns \code{true} if the namespace matches the given value
 
+\littleheader{Check invalid namespace macro}
+\declaremacro{PMIX_NSPACE_INVALID}
+
+Check if the provided \refstruct{pmix_nspace_t} is invalid.
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+PMIX_NSPACE_INVALID(a)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{a}{Pointer to the structure whose value is to be checked (pointer to \refstruct{pmix_nspace_t})}
+\end{arglist}
+
+Returns \code{true} if the namespace is invalid (i.e., starts with a \code{NULL} resulting in a zero-length string value)
+
 \littleheader{Load namespace macro}
 \declaremacro{PMIX_LOAD_NSPACE}
 
@@ -431,6 +449,24 @@ \subsubsection{Rank support macros}
 
 Returns \code{true} if the ranks are equal, or at least one of the ranks is \refconst{PMIX_RANK_WILDCARD}
 
+\littleheader{Check rank is valid macro}
+\declaremacro{PMIX_RANK_IS_VALID}
+
+Check if the given rank is a valid value
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+PMIX_RANK_IS_VALID(a)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{a}{Rank to be checked (\refstruct{pmix_rank_t})}
+\end{arglist}
+
+Returns \code{true} if the given rank is valid (i.e., less than \refconst{PMIX_RANK_VALID})
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Process Structure}
 \declarestruct{pmix_proc_t}
@@ -559,6 +595,23 @@ \subsubsection{Process structure support macros}
     \item one of the ranks is \refconst{PMIX_RANK_WILDCARD}
 \end{itemize}
 
+\littleheader{Check if a process identifier is valid}
+\declaremacro{PMIX_PROCID_INVALID}
+
+Check for invalid namespace or rank value
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+PMIX_PROCID_INVALID(a)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{a}{Pointer to a structure whose ID is to be checked (pointer to \refstruct{pmix_proc_t})}
+\end{arglist}
+
+Returns \code{true} if the process identifier contains either an empty (i.e., invalid) \refarg{nspace} field or a \refarg{rank} field of \refconst{PMIX_RANK_INVALID}
 
 \littleheader{Load a procID structure}
 \declaremacro{PMIX_LOAD_PROCID}
@@ -575,6 +628,23 @@ \subsubsection{Process structure support macros}
 \argin{r}{Rank to be assigned (\refstruct{pmix_rank_t})}
 \end{arglist}
 
+\littleheader{Transfer a procID structure}
+\declaremacro{PMIX_PROCID_XFER}
+
+Transfer contents of one \refstruct{pmix_proc_t} value to another \refstruct{pmix_proc_t}.
+
+\versionMarkerProvisional{4.1}
+\cspecificstart
+\begin{codepar}
+PMIX_PROCID_XFER(d, s)
+\end{codepar}
+\cspecificend
+
+\begin{arglist}
+\argin{d}{Pointer to the target structure (pointer to \refstruct{pmix_proc_t})}
+\argin{s}{Pointer to the source structure (pointer to \refstruct{pmix_proc_t})}
+\end{arglist}
+
 \littleheader{Construct a multi-cluster namespace}
 \declaremacro{PMIX_MULTICLUSTER_NSPACE_CONSTRUCT}
 
@@ -2076,13 +2146,16 @@ \section{Generalized Data Types Used for Packing/Unpacking}
 \declareconstitem{PMIX_PROC_RANK}
 Process rank (\refstruct{pmix_rank_t}).
 %
+\declareconstitemNEW{PMIX_PROC_NSPACE}
+Process namespace (\refstruct{pmix_nspace_t}).
+\%
 \declareconstitem{PMIX_QUERY}
 Query structure (\refstruct{pmix_query_t}).
 %
 \declareconstitem{PMIX_COMPRESSED_STRING}
 String compressed with zlib (\code{char*}).
 %
-\declareconstitemNEW{PMIX_COMPRESSED_BYTE_OBJECT}
+\declareconstitemProvisional{PMIX_COMPRESSED_BYTE_OBJECT}
 Byte object whose bytes have been compressed with zlib (\code{pmix_byte_object_t}).
 %
 \declareconstitem{PMIX_ALLOC_DIRECTIVE}

pmix.sty

@@ -236,6 +236,9 @@
 \newcommand{\versionMarker}[1]{%
   \textInMargin{\textit{PMIx v#1}}%
 }
+\newcommand{\versionMarkerProvisional}[1]{%
+  \textInMargin{\small{\hl{\textit{Provisional v#1}}}}%
+}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % PMIx Standard Process markers