Merge pull request #332 from rhc54/rfc4.1/data

Add four missing data management functions

Chap_API_Data_Mgmt.tex

@@ -420,4 +420,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
+
+\versionMarker{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
+
+\versionMarker{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
+
+\versionMarker{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
+
+\versionMarker{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.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%