Chap_API_Data_Mgmt.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter: Data Packing and Unpacking
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Data Packing and Unpacking}
\label{chap:api_data_mgmt}

\ac{PMIx} intentionally does not include support for internode communications in the standard, instead relying on its host \ac{SMS} environment to transfer any needed data and/or requests between nodes. These operations frequently involve PMIx-defined public data structures that include binary data. Many \ac{HPC} clusters are homogeneous, and so transferring the structures can be done rather simply. However, greater effort is required in heterogeneous environments to ensure binary data is correctly transferred. \ac{PMIx} buffer manipulation functions are provided for this purpose via standardized interfaces to ease adoption.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Support Macros}
\label{chap:api_init:macros}

\ac{PMIx} provides a set of convenience macros for creating, initiating, and releasing data buffers.

%%%%%%%%%%%
\subsection{\code{PMIX_DATA_BUFFER_CREATE}}
\declareapi{PMIX_DATA_BUFFER_CREATE}

%%%%
\summary

Allocate memory for a \refstruct{pmix_data_buffer_t} object and initialize it

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
PMIX_DATA_BUFFER_CREATE(buffer);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{buffer}{Variable to be assigned the pointer to the allocated \refstruct{pmix_data_buffer_t} (handle)}
\end{arglist}

%%%%
\descr

This macro uses \textit{calloc} to allocate memory for the buffer and initialize all fields in it


%%%%%%%%%%%
\subsection{\code{PMIX_DATA_BUFFER_RELEASE}}
\declareapi{PMIX_DATA_BUFFER_RELEASE}

%%%%
\summary

Free a \refstruct{pmix_data_buffer_t} object and the data it contains

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
PMIX_DATA_BUFFER_RELEASE(buffer);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} to be released (handle)}
\end{arglist}

%%%%
\descr

Free's the data contained in the buffer, and then free's the buffer itself


%%%%%%%%%%%
\subsection{\code{PMIX_DATA_BUFFER_CONSTRUCT}}
\declareapi{PMIX_DATA_BUFFER_CONSTRUCT}

%%%%
\summary

Initialize a statically declared \refstruct{pmix_data_buffer_t} object

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
PMIX_DATA_BUFFER_CONSTRUCT(buffer);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{buffer}{Pointer to the allocated \refstruct{pmix_data_buffer_t} that is to be initialized (handle)}
\end{arglist}

%%%%
\descr

Initialize a pre-allocated buffer object


%%%%%%%%%%%
\subsection{\code{PMIX_DATA_BUFFER_DESTRUCT}}
\declareapi{PMIX_DATA_BUFFER_DESTRUCT}

%%%%
\summary

Release the data contained in a \refstruct{pmix_data_buffer_t} object

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
PMIX_DATA_BUFFER_DESTRUCT(buffer);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} whose data is to be released (handle)}
\end{arglist}

%%%%
\descr

Free's the data contained in a \refstruct{pmix_data_buffer_t} object


%%%%%%%%%%%
\subsection{\code{PMIX_DATA_BUFFER_LOAD}}
\declareapi{PMIX_DATA_BUFFER_LOAD}

%%%%
\summary

Load a blob into a \refstruct{pmix_data_buffer_t} object

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
PMIX_DATA_BUFFER_LOAD(buffer, data, size);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{buffer}{Pointer to a pre-allocated \refstruct{pmix_data_buffer_t} (handle)}
\argin{data}{Pointer to a blob (\code{char*})}
\argin{size}{Number of bytes in the blob {\code{size_t}}}
\end{arglist}

%%%%
\descr

Load the given data into the provided \refstruct{pmix_data_buffer_t} object, usually done in preparation for unpacking the provided data. Note that the data is \textit{not} copied into the buffer - thus, the blob must not be released until after operations on the buffer have completed.


%%%%%%%%%%%
\subsection{\code{PMIX_DATA_BUFFER_UNLOAD}}
\declareapi{PMIX_DATA_BUFFER_UNLOAD}

%%%%
\summary

Unload the data from a \refstruct{pmix_data_buffer_t} object

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
PMIX_DATA_BUFFER_UNLOAD(buffer, data, size);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{buffer}{Pointer to the \refstruct{pmix_data_buffer_t} whose data is to be extracted (handle)}
\argout{data}{Variable to be assigned the pointer to the extracted blob (\code{void*})}
\argout{size}{Variable to be assigned the number of bytes in the blob {\code{size_t}}}
\end{arglist}

%%%%
\descr

Extract the data in a buffer, assigning the pointer to the data (and the number of bytes in the blob) to the provided variables, usually done to transmit the blob to a remote process for unpacking. The buffer's internal pointer will be set to NULL to protect the data upon buffer destruct or release - thus, the user is responsible for releasing the blob when done with it.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{General Routines}
\label{chap:api_init:general}

The following routines are provided to support internode transfers in heterogeneous environments.

%%%%%%%%%%%
\subsection{\code{PMIx_Data_pack}}
\declareapi{PMIx_Data_pack}

%%%%
\summary

Pack one or more values of a specified type into a buffer, usually for transmission to another process

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Data_pack(const pmix_proc_t *target,
               pmix_data_buffer_t *buffer,
               void *src, int32_t num_vals,
               pmix_data_type_t type);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{target}{Pointer to a \refstruct{pmix_proc_t} containing the nspace/rank of the process that will be unpacking the final buffer. A NULL value may be used to indicate that the target is based on the same \ac{PMIx} version as the caller. Note that only the target's nspace is relevant. (handle)}
\argin{buffer}{Pointer to a \refstruct{pmix_data_buffer_t} where the packed data is to be stored (handle)}
\argin{src}{Pointer to a location where the data resides. Strings are to be passed as (char **) --- i.e., the caller must pass the address of the pointer to the string as the (void*). This allows the caller to pass multiple strings in a single call. (memory reference)}
\argin{num_vals}{Number of elements pointed to by the \refarg{src} pointer. A string value is counted as a single value regardless of length. The values must be contiguous in memory. Arrays of pointers (e.g., string arrays) should be contiguous, although the data pointed to need not be contiguous across array entries.(\code{int32_t})}
\argin{type}{The type of the data to be packed (\refstruct{pmix_data_type_t})}
\end{arglist}

\begin{constantdesc}
\item \refconst{PMIX_SUCCESS} The data has been packed as requested
\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
\item \refconst{PMIX_ERR_BAD_PARAM} The provided buffer or src is \code{NULL}
\item \refconst{PMIX_ERR_UNKNOWN_DATA_TYPE} The specified data type is not known to this implementation
\item \refconst{PMIX_ERR_OUT_OF_RESOURCE} Not enough memory to support the operation
\item \refconst{PMIX_ERROR} General error
\end{constantdesc}

%%%%
\descr

The pack function packs one or more values of a specified type into the specified buffer.  The buffer must have already been
initialized via the \refapi{PMIX_DATA_BUFFER_CREATE} or \refapi{PMIX_DATA_BUFFER_CONSTRUCT}
macros --- otherwise, \refapi{PMIx_Data_pack} will return an error.
Providing an unsupported type flag will likewise be reported as an error.

Note that any data to be packed that is not hard type cast (i.e.,
not type cast to a specific size) may lose precision when unpacked
by a non-homogeneous recipient.  The \refapi{PMIx_Data_pack} function will do its best to deal
with heterogeneity issues between the packer and unpacker in such
cases. Sending a number larger than can be handled by the recipient
will return an error code (generated upon unpacking) ---
the error cannot be detected during packing.

The namespace of the intended recipient of the packed buffer (i.e., the
process that will be unpacking it) is used solely to resolve any data type
differences between \ac{PMIx} versions. The recipient must, therefore, be
known to the user prior to calling the pack function so that the
\ac{PMIx} library is aware of the version the recipient is using. Note that
all processes in a given namespace are \textit{required} to use the same \ac{PMIx}
version --- thus, the caller must only know at least one process from the
target's namespace.


%%%%%%%%%%%
\subsection{\code{PMIx_Data_unpack}}
\declareapi{PMIx_Data_unpack}

%%%%
\summary

Unpack values from a \refstruct{pmix_data_buffer_t}

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Data_unpack(const pmix_proc_t *source,
                 pmix_data_buffer_t *buffer, void *dest,
                 int32_t *max_num_values,
                 pmix_data_type_t type);

\end{codepar}
\cspecificend


\begin{arglist}
\argin{source}{Pointer to a \refstruct{pmix_proc_t} structure containing the nspace/rank of the process that packed the provided buffer. A NULL value may be used to indicate that the source is based on the same \ac{PMIx} version as the caller. Note that only the source's nspace is relevant. (handle)}
\argin{buffer}{A pointer to the buffer from which the value will be extracted. (handle)}
\arginout{dest}{A pointer to the memory location into which the data is to be stored. Note that these values will be stored contiguously in memory. For strings, this pointer must be to (char**) to provide a means of supporting multiple string operations. The unpack function will allocate memory for each string in the array - the caller must only provide adequate memory for the array of pointers. (\code{void*})}
\arginout{max_num_values}{The number of values to be unpacked --- upon completion, the parameter will be set to the actual number of values unpacked. In most cases, this should match the maximum number provided in the parameters --- but in no case will it exceed the value of this parameter.  Note that unpacking fewer values than are actually available will leave the buffer in an unpackable state --- the function will return an error code to warn of this condition.(\code{int32_t})}
\argin{type}{The type of the data to be unpacked --- must be one of the \ac{PMIx} defined data types (\refstruct{pmix_data_type_t})}
\end{arglist}

\begin{constantdesc}
\item \refconst{PMIX_SUCCESS} The data has been unpacked as requested
\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
\item \refconst{PMIX_ERR_BAD_PARAM} The provided buffer or dest is \code{NULL}
\item \refconst{PMIX_ERR_UNKNOWN_DATA_TYPE} The specified data type is not known to this implementation
\item \refconst{PMIX_ERR_OUT_OF_RESOURCE} Not enough memory to support the operation
\item \refconst{PMIX_ERROR} General error
\end{constantdesc}

%%%%
\descr

The unpack function unpacks the next value (or values) of a specified type from the given buffer. The buffer must have already been initialized via an \refapi{PMIX_DATA_BUFFER_CREATE} or \refapi{PMIX_DATA_BUFFER_CONSTRUCT} call (and assumedly filled with some data) --- otherwise, the unpack_value function will return an error. Providing an unsupported type flag will likewise be reported as an error, as will specifying a data type that \textit{does not} match the type of the next item in the buffer. An attempt to read beyond the end of the stored data held in the buffer will also return an error.

NOTE: it is possible for the buffer to be corrupted and that \ac{PMIx} will \textit{think} there is a proper variable type at the beginning of an unpack region --- but that the value is bogus (e.g., just a byte field in a string array that so happens to have a value that matches the specified data type flag). Therefore, the data type error check is \textit{not} completely safe.

Unpacking values is a "nondestructive" process --- i.e., the values are not removed from the buffer. It is therefore possible for the caller to re-unpack a value from the same buffer by resetting the unpack_ptr.

Warning: The caller is responsible for providing adequate memory storage for the requested data. The user must provide a parameter indicating the maximum number of values that can be unpacked into the allocated memory. If more values exist in the buffer than can fit into the memory storage, then the function will unpack what it can fit into that location and return an error code indicating that the buffer was only partially unpacked.

Note that any data that was not hard type cast (i.e., not type cast to a specific size) when packed may lose precision when unpacked by a non-homogeneous recipient. \ac{PMIx} will do its best to deal with heterogeneity issues between the packer and unpacker in such cases. Sending a number larger than can be handled by the recipient will return an error code generated upon unpacking --- these errors cannot be detected during packing.

The namespace of the process that packed the buffer is used solely to resolve any data type
differences between \ac{PMIx} versions. The packer must, therefore, be
known to the user prior to calling the pack function so that the
\ac{PMIx} library is aware of the version the packer is using. Note that
all processes in a given namespace are \textit{required} to use the same \ac{PMIx}
version --- thus, the caller must only know at least one process from the
packer's namespace.


%%%%%%%%%%%
\subsection{\code{PMIx_Data_copy}}
\declareapi{PMIx_Data_copy}

%%%%
\summary

Copy a data value from one location to another.

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Data_copy(void **dest, void *src,
               pmix_data_type_t type);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{dest}{The address of a pointer into which the address of the resulting data is to be stored. (\code{void**})}
\argin{src}{A pointer to the memory location from which the data is to be copied (handle)}
\argin{type}{The type of the data to be copied --- must be one of the PMIx defined data types. (\refstruct{pmix_data_type_t})}
\end{arglist}

\begin{constantdesc}
\item \refconst{PMIX_SUCCESS} The data has been copied as requested
\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
\item \refconst{PMIX_ERR_BAD_PARAM} The provided src or dest is \code{NULL}
\item \refconst{PMIX_ERR_UNKNOWN_DATA_TYPE} The specified data type is not known to this implementation
\item \refconst{PMIX_ERR_OUT_OF_RESOURCE} Not enough memory to support the operation
\item \refconst{PMIX_ERROR} General error
\end{constantdesc}

%%%%
\descr

Since registered data types can be complex structures, the system needs some way to know how to copy the data from one location to another (e.g., for storage in the registry). This function, which can call other copy functions to build up complex data types, defines the method for making a copy of the specified data type.


%%%%%%%%%%%
\subsection{\code{PMIx_Data_print}}
\declareapi{PMIx_Data_print}

%%%%
\summary

Pretty-print a data value.

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Data_print(char **output, char *prefix,
                void *src, pmix_data_type_t type);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{output}{The address of a pointer into which the address of the resulting output is to be stored. (\code{char**})}
\argin{prefix}{String to be prepended to the resulting output (\code{char*})}
\argin{src}{A pointer to the memory location of the data value to be printed (handle)}
\argin{type}{The type of the data value to be printed --- must be one of the PMIx defined data types. (\refstruct{pmix_data_type_t})}
\end{arglist}

\begin{constantdesc}
\item \refconst{PMIX_SUCCESS} The data has been printed as requested
\item \refconst{PMIX_ERR_BAD_PARAM} The provided data type is not recognized.
\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
\end{constantdesc}

%%%%
\descr

Since registered data types can be complex structures, the system needs some way to know how to print them (i.e., convert them to a string representation). Primarily for debug purposes.


%%%%%%%%%%%
\subsection{\code{PMIx_Data_copy_payload}}
\declareapi{PMIx_Data_copy_payload}

%%%%
\summary

Copy a payload from one buffer to another

%%%%
\format

\versionMarker{2.0}
\cspecificstart
\begin{codepar}
pmix_status_t
PMIx_Data_copy_payload(pmix_data_buffer_t *dest,
                       pmix_data_buffer_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_data_buffer_t} (handle)}
\end{arglist}

\begin{constantdesc}
\item \refconst{PMIX_SUCCESS} The data has been copied as requested
\item \refconst{PMIX_ERR_BAD_PARAM} The src and dest \refstruct{pmix_data_buffer_t} types do not match
\item \refconst{PMIX_ERR_NOT_SUPPORTED} The \ac{PMIx} implementation does not support this function.
\end{constantdesc}

%%%%
\descr

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.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%