Chap_API_Struct.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter: Data Structures
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Data Structures and Types}
\label{chap:struct}

This chapter defines \ac{PMIx} standard data structures (along with macros for convenient use), types, and constants.
These apply to all consumers of the \ac{PMIx} interface.
Where necessary for clarification, the description of, for example, an attribute may be copied from this chapter into a section where it is used.

A PMIx implementation may define additional attributes beyond those specified in this document.

\adviceimplstart
Structures, types, and macros in the \ac{PMIx} Standard are defined in terms of the C-programming language. Implementers wishing to support other languages should provide the equivalent definitions in a language-appropriate manner.

If a PMIx implementation chooses to define additional attributes they should avoid using the \code{"PMIX"} prefix in their name or starting the attribute string with a \code{"pmix"} prefix.
This helps the end user distinguish between what is defined by the PMIx standard and what is specific to that PMIx implementation, and avoids potential conflicts with attributes defined by the Standard.
\adviceimplend

\adviceuserstart
Use of increment/decrement operations on indices inside \ac{PMIx} macros is discouraged due to unpredictable behavior. For example, the following sequence:

\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
\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
generate an error as the static string had not been allocated.

\adviceuserend

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Constants}
\label{chap:struct:const}

\ac{PMIx} defines a few values that are used throughout the standard to set the size of fixed arrays or as a means of identifying values with special meaning.
The community makes every attempt to minimize the number of such definitions.
The constants defined in this section may be used before calling any \ac{PMIx} library initialization routine.
Additional constants associated with specific data structures or types are defined in the section describing that data structure or type.

\begin{constantdesc}
%
\declareconstitem{PMIX_MAX_NSLEN}
Maximum namespace string length as an integer.
\end{constantdesc}

\adviceimplstart
\refconst{PMIX_MAX_NSLEN} should have a minimum value of 63 characters. Namespace arrays in \ac{PMIx} defined structures must reserve
a space of size \refconst{PMIX_MAX_NSLEN}+1 to allow room for the \code{NULL} terminator
\adviceimplend

\begin{constantdesc}
%
\declareconstitem{PMIX_MAX_KEYLEN}
Maximum key string length as an integer.
\end{constantdesc}

\adviceimplstart
\refconst{PMIX_MAX_KEYLEN} should have a minimum value of 63 characters. Key arrays in \ac{PMIx} defined structures must reserve
a space of size \refconst{PMIX_MAX_KEYLEN}+1 to allow room for the \code{NULL} terminator
\adviceimplend

\begin{constantdesc}
%
\declareconstitemNEW{PMIX_APP_WILDCARD}
A value to indicate that the user wants the data for the given key from every application that posted that key, or that the given value applies to all applications within the given namespace.
\end{constantdesc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{PMIx Return Status Constants}
\label{api:struct:errors}
\declarestruct{pmix_status_t}

The \refstruct{pmix_status_t} structure is an \code{int} type for return status. The tables shown in this section define the possible values for \refstruct{pmix_status_t}.
PMIx errors are required to always be negative, with \code{0} reserved for \refconst{PMIX_SUCCESS}. Values in the list that were deprecated in later standards are denoted as such. Values added to the list in this version of the standard are shown in \textbf{\color{magenta}magenta}.

\adviceimplstart
A PMIx implementation must define all of the constants defined in this section, even if they will never return the specific value to the caller.
\adviceimplend

\adviceuserstart
Other than \refconst{PMIX_SUCCESS} (which is required to be zero), the actual value of any \ac{PMIx} error constant is left to the \ac{PMIx} library implementer. Thus, users are advised to always refer to constant by name, and not a specific implementation's value, for portability between implementations and compatibility across library versions.
\adviceuserend

The following values are general constants used in a variety of places.

\begin{constantdesc}
%
\declareconstitem{PMIX_SUCCESS}
Success.
%
\declareconstitem{PMIX_ERROR}
General Error.
%
\declareconstitemNEW{PMIX_ERR_EXISTS}
Requested operation would overwrite an existing value - typically returned
when an operation would overwrite an existing file or directory.
%
\declareconstitemNEW{PMIX_ERR_EXISTS_OUTSIDE_SCOPE}
The requested key exists, but was posted in a \emph{scope} (see Section \ref{api:nres:scope}) that does not include the requester
%
\declareconstitem{PMIX_ERR_INVALID_CRED}
Invalid security credentials.
%
\declareconstitem{PMIX_ERR_WOULD_BLOCK}
Operation would block.
%
\declareconstitem{PMIX_ERR_UNKNOWN_DATA_TYPE}
The data type specified in an input to the \ac{PMIx} library is not recognized
by the implementation.
%
\declareconstitem{PMIX_ERR_TYPE_MISMATCH}
The data type found in an object does not match the expected data type
as specified in the \ac{API} call - e.g., a request to unpack a
\refconst{PMIX_BOOL} value from a buffer that does not contain a value of
that type in the current unpack location.
%
\declareconstitem{PMIX_ERR_UNPACK_INADEQUATE_SPACE}
Inadequate space to unpack data - the number of values in the buffer exceeds
the specified number to unpack.
%
\declareconstitem{PMIX_ERR_UNPACK_READ_PAST_END_OF_BUFFER}
Unpacking past the end of the provided buffer - the number of values in the
buffer is less than the specified number to unpack, or a request was made to
unpack a buffer beyond the buffer's end.
%
\declareconstitem{PMIX_ERR_UNPACK_FAILURE}
The unpack operation failed for an unspecified reason.
%
\declareconstitem{PMIX_ERR_PACK_FAILURE}
The pack operation failed for an unspecified reason.
%
\declareconstitem{PMIX_ERR_NO_PERMISSIONS}
The user lacks permissions to execute the specified operation.
%
\declareconstitem{PMIX_ERR_TIMEOUT}
Either a user-specified or system-internal timeout expired.
%
\declareconstitem{PMIX_ERR_UNREACH}
The specified target server or client process is not reachable - i.e., a
suitable connection either has not been or can not be made.
%
\declareconstitem{PMIX_ERR_BAD_PARAM}
One or more incorrect parameters (e.g., passing an attribute with a value of the wrong type), or multiple parameters containing conflicting directives (e.g., multiple instances of the same attribute with different values, or different attributes specifying conflicting behaviors), were passed to a \ac{PMIx} \ac{API}.
%
\declareconstitemNEW{PMIX_ERR_EMPTY}
An array or list was given that has no members in it - i.e., the object is empty.
%
\declareconstitem{PMIX_ERR_RESOURCE_BUSY}
Resource busy - typically seen when an attempt to establish a connection
to another process (e.g., a \ac{PMIx} server) cannot be made due to a
communication failure.
%
\declareconstitem{PMIX_ERR_OUT_OF_RESOURCE}
Resource exhausted.
%
\declareconstitem{PMIX_ERR_INIT}
Error during initialization.
%
\declareconstitem{PMIX_ERR_NOMEM}
Out of memory.
%
\declareconstitem{PMIX_ERR_NOT_FOUND}
The requested information was not found.
%
\declareconstitem{PMIX_ERR_NOT_SUPPORTED}
The requested operation is not supported by either the \ac{PMIx} implementation
or the host environment.
%
\declareconstitemNEW{PMIX_ERR_PARAM_VALUE_NOT_SUPPORTED}
The requested operation is supported by the \ac{PMIx} implementation and (if applicable) the host environment. However, at least one supplied parameter was given an unsupported value, and the operation cannot therefore be executed as requested.
%
\declareconstitem{PMIX_ERR_COMM_FAILURE}
Communication failure - a message failed to be sent or received, but the
connection remains intact.
%
\declareconstitemNEW{PMIX_ERR_LOST_CONNECTION}
Lost connection between server and client or tool.
%
\declareconstitem{PMIX_ERR_INVALID_OPERATION}
The requested operation is supported by the implementation and host environment, but fails to meet a requirement (e.g., requesting to \textit{disconnect} from processes without first \textit{connecting} to them, inclusion of conflicting directives, or a request to perform an operation that conflicts with an ongoing one).
%
\declareconstitem{PMIX_OPERATION_IN_PROGRESS}
A requested operation is already in progress - the duplicate request
shall therefore be ignored.
%
\declareconstitem{PMIX_OPERATION_SUCCEEDED}
The requested operation was performed atomically - no callback function will be executed.
%
\declareconstitemNEW{PMIX_ERR_PARTIAL_SUCCESS}
The operation is considered successful but not all elements of the operation were concluded (e.g., some members of a group construct operation chose not to participate).
%
\end{constantdesc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{User-Defined Error and Event Constants}
\label{api:struct:usererrors}

\ac{PMIx} establishes a boundary for constants defined in the \ac{PMIx} standard. Negative values larger (i.e., more negative) than this (and any positive values greater than zero) are guaranteed not to conflict with \ac{PMIx} values.

\begin{constantdesc}
%
\declareconstitem{PMIX_EXTERNAL_ERR_BASE}
A starting point for user-level defined error and event constants.
Negative values that are more negative than the defined constant are guaranteed not to conflict with \ac{PMIx} values.
Definitions should always be based on the \refconst{PMIX_EXTERNAL_ERR_BASE} constant and not a specific value as the value of the constant may change.
%
\end{constantdesc}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Data Types}

This section defines various data types used by the \ac{PMIx} APIs. The version of the standard in which a particular data type was introduced is shown in the margin.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Key Structure}
\declarestruct{pmix_key_t}

The \refstruct{pmix_key_t} structure is a statically defined character array of length \refconst{PMIX_MAX_KEYLEN}+1, thus supporting keys of maximum length \refconst{PMIX_MAX_KEYLEN} while preserving space for a mandatory \code{NULL} terminator.

\copySignature{pmix_key_t}{2.0}{
typedef char pmix_key_t[PMIX_MAX_KEYLEN+1];
}

Characters in the key must be standard alphanumeric values supported by common utilities such as \textit{strcmp}.

\adviceuserstart
References to keys in \ac{PMIx} v1 were defined simply as an array of characters of size \code{PMIX_MAX_KEYLEN+1}. The \refstruct{pmix_key_t} type definition was introduced in version 2 of the standard. The two definitions are code-compatible and thus do not represent a break in backward compatibility.

Passing a \refstruct{pmix_key_t} value to the standard \textit{sizeof} utility can result in compiler warnings of incorrect returned value. Users are advised to avoid using \textit{sizeof(pmix_key_t)} and instead rely on the \refconst{PMIX_MAX_KEYLEN} constant.
\adviceuserend

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Key support macros}

The following macros are provided for convenience when working with \ac{PMIx} keys.

\littleheader{Check key macro}
\declaremacro{PMIX_CHECK_KEY}

Compare the key in a \refstruct{pmix_info_t} to a given value.

\copySignature{PMIX_CHECK_KEY}{3.0}{
PMIX_CHECK_KEY(a, b)
}

\begin{arglist}
\argin{a}{Pointer to the structure whose key is to be checked (pointer to \refstruct{pmix_info_t})}
\argin{b}{String value to be compared against (\code{char*})}
\end{arglist}

Returns \code{true} if the key matches the given value

\littleheader{Check reserved key macro}
\declaremacro{PMIX_CHECK_RESERVED_KEY}

Check if the given key is a \ac{PMIx} \emph{reserved} key as described in Chapter \ref{chap:api_rsvd_keys}.

\copySignature{PMIX_CHECK_RESERVED_KEY}{4.0}{
PMIX_CHECK_RESERVED_KEY(a)
}

\begin{arglist}
\argin{a}{String value to be checked (\code{char*})}
\end{arglist}

Returns \code{true} if the key is reserved by the Standard.

\littleheader{Load key macro}
\declaremacro{PMIX_LOAD_KEY}

Load a key into a \refstruct{pmix_info_t}.

\copySignature{PMIX_LOAD_KEY}{4.0}{
PMIX_LOAD_KEY(a, b)
}

\begin{arglist}
\argin{a}{Pointer to the structure whose key is to be loaded (pointer to \refstruct{pmix_info_t})}
\argin{b}{String value to be loaded (\code{char*})}
\end{arglist}

No return value.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Namespace Structure}
\declarestruct{pmix_nspace_t}

The \refstruct{pmix_nspace_t} structure is a statically defined character array of length \refconst{PMIX_MAX_NSLEN}+1, thus supporting namespaces of maximum length \refconst{PMIX_MAX_NSLEN} while preserving space for a mandatory \code{NULL} terminator.

\copySignature{pmix_nspace_t}{2.0}{
typedef char pmix_nspace_t[PMIX_MAX_NSLEN+1];
}

Characters in the namespace must be standard alphanumeric values supported by common utilities such as \textit{strcmp}.

\adviceuserstart
References to namespace values in \ac{PMIx} v1 were defined simply as an array of characters of size \code{PMIX_MAX_NSLEN+1}. The \refstruct{pmix_nspace_t} type definition was introduced in version 2 of the standard. The two definitions are code-compatible and thus do not represent a break in backward compatibility.

Passing a \refstruct{pmix_nspace_t} value to the standard \textit{sizeof} utility can result in compiler warnings of incorrect returned value. Users are advised to avoid using \textit{sizeof(pmix_nspace_t)} and instead rely on the \refconst{PMIX_MAX_NSLEN} constant.
\adviceuserend

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Namespace support macros}

The following macros are provided for convenience when working with \ac{PMIx} namespace structures.

\littleheader{Check namespace macro}
\declaremacro{PMIX_CHECK_NSPACE}

Compare the string in a \refstruct{pmix_nspace_t} to a given value.

\copySignature{PMIX_CHECK_NSPACE}{3.0}{
PMIX_CHECK_NSPACE(a, b)
}

\begin{arglist}
\argin{a}{Pointer to the structure whose value is to be checked (pointer to \refstruct{pmix_nspace_t})}
\argin{b}{String value to be compared against (\code{char*})}
\end{arglist}

Returns \code{true} if the namespace matches the given value

\littleheader{Load namespace macro}
\declaremacro{PMIX_LOAD_NSPACE}

Load a namespace into a \refstruct{pmix_nspace_t}.

\copySignature{PMIX_LOAD_NSPACE}{4.0}{
PMIX_LOAD_NSPACE(a, b)
}

\begin{arglist}
\argin{a}{Pointer to the target structure (pointer to \refstruct{pmix_nspace_t})}
\argin{b}{String value to be loaded - if \code{NULL} is given, then the target structure will be initialized to zero's (\code{char*})}
\end{arglist}

No return value.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Rank Structure}
\declarestruct{pmix_rank_t}

The \refstruct{pmix_rank_t} structure is a \code{uint32_t} type for rank values.

\copySignature{pmix_rank_t}{1.0}{
typedef uint32_t pmix_rank_t;
}

The following constants can be used to set a variable of the type \refstruct{pmix_rank_t}. All definitions were introduced in version 1 of the standard unless otherwise marked. Valid rank values start at zero.

\begin{constantdesc}
%
\declareconstitem{PMIX_RANK_UNDEF}
A value to request job-level data where the information itself is not associated with any specific rank, or when passing a \refstruct{pmix_proc_t} identifier to an operation that only references the namespace field of that structure.
%
\declareconstitem{PMIX_RANK_WILDCARD}
A value to indicate that the user wants the data for the given key from every rank that posted that key.
%
\declareconstitem{PMIX_RANK_LOCAL_NODE}
Special rank value used to define groups of ranks.
This constant defines the group of all ranks on a local node.
%
\declareconstitem{PMIX_RANK_LOCAL_PEERS}
Special rank value used to define groups of ranks.
This constant defines the group of all ranks on a local node within the same namespace as the current process.
%
\declareconstitem{PMIX_RANK_INVALID}
An invalid rank value.
%
\declareconstitem{PMIX_RANK_VALID}
Define an upper boundary for valid rank values.
%
\end{constantdesc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Rank support macros}

The following macros are provided for convenience when working with \ac{PMIx} ranks.

\littleheader{Check rank macro}
\declaremacro{PMIX_CHECK_RANK}

Check two ranks for equality, taking into account wildcard values

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_CHECK_RANK(a, b)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{a}{Rank to be checked (\refstruct{pmix_rank_t})}
\argin{b}{Rank to be checked (\refstruct{pmix_rank_t})}
\end{arglist}

Returns \code{true} if the ranks are equal, or at least one of the ranks is \refconst{PMIX_RANK_WILDCARD}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Process Structure}
\declarestruct{pmix_proc_t}

The \refstruct{pmix_proc_t} structure is used to identify a single process in the PMIx universe.
It contains a reference to the namespace and the \refstruct{pmix_rank_t} within that namespace.

\copySignature{pmix_proc_t}{1.0}{
typedef struct pmix_proc \{ \\
\hspace*{4\sigspace}pmix_nspace_t nspace; \\
\hspace*{4\sigspace}pmix_rank_t rank; \\
\} pmix_proc_t;
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Process structure support macros}
The following macros are provided to support the \refstruct{pmix_proc_t} structure.

\littleheader{Initialize the proc structure}
\declaremacro{PMIX_PROC_CONSTRUCT}

Initialize the \refstruct{pmix_proc_t} fields.

\copySignature{PMIX_PROC_CONSTRUCT}{1.0}{
PMIX_PROC_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_proc_t})}
\end{arglist}

\littleheader{Destruct the proc structure}
\declaremacro{PMIX_PROC_DESTRUCT}

Destruct the \refstruct{pmix_proc_t} fields.

\cspecificstart
\begin{codepar}
PMIX_PROC_DESTRUCT(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_proc_t})}
\end{arglist}

There is nothing to release here as the fields in \refstruct{pmix_proc_t} are either a statically-declared array (the namespace) or a single value (the rank). However, the macro is provided for symmetry in the code and for future-proofing should some allocated field be included some day.

\littleheader{Create a proc array}
\declaremacro{PMIX_PROC_CREATE}

Allocate and initialize an array of \refstruct{pmix_proc_t} structures.

\copySignature{PMIX_PROC_CREATE}{1.0}{
PMIX_PROC_CREATE(m, n)
}

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_proc_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}


\littleheader{Free a proc structure}
\declaremacro{PMIX_PROC_RELEASE}

Release a \refstruct{pmix_proc_t} structure.

\copySignature{PMIX_PROC_RELEASE}{4.0}{
PMIX_PROC_RELEASE(m)
}

\begin{arglist}
\argin{m}{Pointer to a \refstruct{pmix_proc_t} structure (handle)}
\end{arglist}

\littleheader{Free a proc array}
\declaremacro{PMIX_PROC_FREE}

Release an array of \refstruct{pmix_proc_t} structures.

\copySignature{PMIX_PROC_FREE}{1.0}{
PMIX_PROC_FREE(m, n)
}

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_proc_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

\littleheader{Load a proc structure}
\declaremacro{PMIX_PROC_LOAD}

Load values into a \refstruct{pmix_proc_t}.

\copySignature{PMIX_PROC_LOAD}{2.0}{
PMIX_PROC_LOAD(m, n, r)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be loaded (pointer to \refstruct{pmix_proc_t})}
\argin{n}{Namespace to be loaded (\refstruct{pmix_nspace_t})}
\argin{r}{Rank to be assigned (\refstruct{pmix_rank_t})}
\end{arglist}

No return value. Deprecated in favor of \refmacro{PMIX_LOAD_PROCID}

\littleheader{Compare identifiers}
\declaremacro{PMIX_CHECK_PROCID}

Compare two \refstruct{pmix_proc_t} identifiers.

\copySignature{PMIX_CHECK_PROCID}{3.0}{
PMIX_CHECK_PROCID(a, b)
}

\begin{arglist}
\argin{a}{Pointer to a structure whose ID is to be compared (pointer to \refstruct{pmix_proc_t})}
\argin{b}{Pointer to a structure whose ID is to be compared (pointer to \refstruct{pmix_proc_t})}
\end{arglist}

Returns \code{true} if the two structures contain matching namespaces and:

\begin{itemize}
    \item the ranks are the same value
    \item one of the ranks is \refconst{PMIX_RANK_WILDCARD}
\end{itemize}


\littleheader{Load a procID structure}
\declaremacro{PMIX_LOAD_PROCID}

Load values into a \refstruct{pmix_proc_t}.

\copySignature{PMIX_LOAD_PROCID}{4.0}{
PMIX_LOAD_PROCID(m, n, r)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be loaded (pointer to \refstruct{pmix_proc_t})}
\argin{n}{Namespace to be loaded (\refstruct{pmix_nspace_t})}
\argin{r}{Rank to be assigned (\refstruct{pmix_rank_t})}
\end{arglist}

\littleheader{Construct a multi-cluster namespace}
\declaremacro{PMIX_MULTICLUSTER_NSPACE_CONSTRUCT}

Construct a multi-cluster identifier containing a cluster ID and a namespace.

\copySignature{PMIX_MULTICLUSTER_NSPACE_CONSTRUCT}{4.0}{
PMIX_MULTICLUSTER_NSPACE_CONSTRUCT(m, n, r)
}

\begin{arglist}
\argin{m}{\refstruct{pmix_nspace_t} structure that will contain the multi-cluster identifier (\refstruct{pmix_nspace_t})}
\argin{n}{Cluster identifier (\code{char*})}
\argin{n}{Namespace to be loaded (\refstruct{pmix_nspace_t})}
\end{arglist}

Combined length of the cluster identifier and namespace must be less than \refconst{PMIX_MAX_NSLEN}-2.

\littleheader{Parse a multi-cluster namespace}
\declaremacro{PMIX_MULTICLUSTER_NSPACE_PARSE}

Parse a multi-cluster identifier into its cluster ID and namespace parts.

\copySignature{PMIX_MULTICLUSTER_NSPACE_PARSE}{4.0}{
PMIX_MULTICLUSTER_NSPACE_PARSE(m, n, r)
}

\begin{arglist}
\argin{m}{\refstruct{pmix_nspace_t} structure containing the multi-cluster identifier (pointer to \refstruct{pmix_nspace_t})}
\argin{n}{Location where the cluster ID is to be stored (\refstruct{pmix_nspace_t})}
\argin{n}{Location where the namespace is to be stored (\refstruct{pmix_nspace_t})}
\end{arglist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Process State Structure}
\label{api:struct:processstate}
\declarestruct{pmix_proc_state_t}

\versionMarker{2.0}
The \refstruct{pmix_proc_state_t} structure is a \code{uint8_t} type for process state values. The following constants can be used to set a variable of the type \refstruct{pmix_proc_state_t}.

\adviceuserstart
The fine-grained nature of the following constants may exceed the ability of an \ac{RM} to provide updated process state values during the process lifetime. This is particularly true of states for short-lived processes.
\adviceuserend

\begin{constantdesc}
%
\declareconstitem{PMIX_PROC_STATE_UNDEF}
Undefined process state.
%
\declareconstitem{PMIX_PROC_STATE_PREPPED}
Process is ready to be launched.
%
\declareconstitem{PMIX_PROC_STATE_LAUNCH_UNDERWAY}
Process launch is underway.
%
\declareconstitem{PMIX_PROC_STATE_RESTART}
Process is ready for restart.
%
\declareconstitem{PMIX_PROC_STATE_TERMINATE}
Process is marked for termination.
%
\declareconstitem{PMIX_PROC_STATE_RUNNING}
Process has been locally \code{fork}'ed by the \ac{RM}.
%
\declareconstitem{PMIX_PROC_STATE_CONNECTED}
Process has connected to PMIx server.
%
\declareconstitem{PMIX_PROC_STATE_UNTERMINATED}
Define a ``boundary'' between the terminated states and \refconst{PMIX_PROC_STATE_CONNECTED} so users can easily and quickly determine if a process is still running or not.
Any value less than this constant means that the process has not terminated.
%
\declareconstitem{PMIX_PROC_STATE_TERMINATED}
Process has terminated and is no longer running.
%
\declareconstitem{PMIX_PROC_STATE_ERROR}
Define a boundary so users can easily and quickly determine if a process abnormally terminated.
Any value above this constant means that the process has terminated abnormally.
%
\declareconstitem{PMIX_PROC_STATE_KILLED_BY_CMD}
Process was killed by a command.
%
\declareconstitem{PMIX_PROC_STATE_ABORTED}
Process was aborted by a call to \refapi{PMIx_Abort}.
%
\declareconstitem{PMIX_PROC_STATE_FAILED_TO_START}
Process failed to start.
%
\declareconstitem{PMIX_PROC_STATE_ABORTED_BY_SIG}
Process aborted by a signal.
%
\declareconstitem{PMIX_PROC_STATE_TERM_WO_SYNC}
Process exited without calling \refapi{PMIx_Finalize}.
%
\declareconstitem{PMIX_PROC_STATE_COMM_FAILED}
Process communication has failed.
%
\declareconstitemNEW{PMIX_PROC_STATE_SENSOR_BOUND_EXCEEDED}
Process exceeded a specified sensor limit.
%
\declareconstitem{PMIX_PROC_STATE_CALLED_ABORT}
Process called \refapi{PMIx_Abort}.
%
\declareconstitemNEW{PMIX_PROC_STATE_HEARTBEAT_FAILED}
Frocess failed to send heartbeat within specified time limit.
%
\declareconstitem{PMIX_PROC_STATE_MIGRATING}
Process failed and is waiting for resources before restarting.
%
\declareconstitem{PMIX_PROC_STATE_CANNOT_RESTART}
Process failed and cannot be restarted.
%
\declareconstitem{PMIX_PROC_STATE_TERM_NON_ZERO}
Process exited with a non-zero status.
%
\declareconstitem{PMIX_PROC_STATE_FAILED_TO_LAUNCH}
Unable to launch process.
%
\end{constantdesc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Process Information Structure}
\declarestruct{pmix_proc_info_t}

The \refstruct{pmix_proc_info_t} structure defines a set of information about a specific process including it's name, location, and state.

\copySignature{pmix_proc_info_t}{2.0}{
typedef struct pmix_proc_info \{ \\
\hspace*{4\sigspace}/** Process structure */ \\
\hspace*{4\sigspace}pmix_proc_t proc; \\
\hspace*{4\sigspace}/** Hostname where process resides */ \\
\hspace*{4\sigspace}char *hostname; \\
\hspace*{4\sigspace}/** Name of the executable */ \\
\hspace*{4\sigspace}char *executable_name; \\
\hspace*{4\sigspace}/** Process ID on the host */ \\
\hspace*{4\sigspace}pid_t pid; \\
\hspace*{4\sigspace}/** Exit code of the process. Default: 0 */ \\
\hspace*{4\sigspace}int exit_code; \\
\hspace*{4\sigspace}/** Current state of the process */ \\
\hspace*{4\sigspace}pmix_proc_state_t state; \\
\} pmix_proc_info_t;
}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Process information structure support macros}

The following macros are provided to support the \refstruct{pmix_proc_info_t} structure.

%%%%
\littleheader{Initialize the process information structure}
\declaremacro{PMIX_PROC_INFO_CONSTRUCT}

Initialize the \refstruct{pmix_proc_info_t} fields.

\copySignature{PMIX_PROC_INFO_CONSTRUCT}{2.0}{
PMIX_PROC_INFO_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_proc_info_t})}
\end{arglist}

%%%%
\littleheader{Destruct the process information structure}
\declaremacro{PMIX_PROC_INFO_DESTRUCT}

Destruct the \refstruct{pmix_proc_info_t} fields.

\copySignature{PMIX_PROC_INFO_DESTRUCT}{2.0}{
PMIX_PROC_INFO_DESTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_proc_info_t})}
\end{arglist}

%%%%
\littleheader{Create a process information array}
\declaremacro{PMIX_PROC_INFO_CREATE}

Allocate and initialize a \refstruct{pmix_proc_info_t} array.

\copySignature{PMIX_PROC_INFO_CREATE}{2.0}{
PMIX_PROC_INFO_CREATE(m, n)
}

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_proc_info_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}

%%%%
\littleheader{Free a process information structure}
\declaremacro{PMIX_PROC_INFO_RELEASE}

Release a \refstruct{pmix_proc_info_t} structure.

\copySignature{PMIX_PROC_INFO_RELEASE}{2.0}{
PMIX_PROC_INFO_RELEASE(m)
}

\begin{arglist}
\argin{m}{Pointer to a \refstruct{pmix_proc_info_t} structure (handle)}
\end{arglist}

%%%%
\littleheader{Free a process information array}
\declaremacro{PMIX_PROC_INFO_FREE}

Release an array of \refstruct{pmix_proc_info_t} structures.

\copySignature{PMIX_PROC_INFO_FREE}{2.0}{
PMIX_PROC_INFO_FREE(m, n)
}

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_proc_info_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Job State Structure}
\label{api:struct:jobstate}
\declarestruct{pmix_job_state_t}

\versionMarker{4.0}
The \refstruct{pmix_job_state_t} structure is a \code{uint8_t} type for job state values. The following constants can be used to set a variable of the type \refstruct{pmix_job_state_t}.

\adviceuserstart
The fine-grained nature of the following constants may exceed the ability of an \ac{RM} to provide updated job state values during the job lifetime. This is particularly true for short-lived jobs.
\adviceuserend

\begin{constantdesc}
%
\declareconstitemNEW{PMIX_JOB_STATE_UNDEF}
Undefined job state.
%
\declareconstitemNEW{PMIX_JOB_STATE_AWAITING_ALLOC}
Job is waiting for resources to be allocated to it.
%
\declareconstitemNEW{PMIX_JOB_STATE_LAUNCH_UNDERWAY}
Job launch is underway.
%
\declareconstitemNEW{PMIX_JOB_STATE_RUNNING}
All processes in the job have been spawned and are executing.
%
\declareconstitemNEW{PMIX_JOB_STATE_SUSPENDED}
All processes in the job have been suspended.
%
\declareconstitemNEW{PMIX_JOB_STATE_CONNECTED}
All processes in the job have connected to their \ac{PMIx} server.
%
\declareconstitemNEW{PMIX_JOB_STATE_UNTERMINATED}
Define a ``boundary'' between the terminated states and \refconst{PMIX_JOB_STATE_TERMINATED} so users can easily and quickly determine if a job is still running or not.
Any value less than this constant means that the job has not terminated.
%
\declareconstitemNEW{PMIX_JOB_STATE_TERMINATED}
All processes in the job have terminated and are no longer running - typically will be accompanied by the job exit status in response to a query.
%
\declareconstitemNEW{PMIX_JOB_STATE_TERMINATED_WITH_ERROR}
Define a boundary so users can easily and quickly determine if a job abnormally terminated - typically will be accompanied by a job-related error code in response to a query
Any value above this constant means that the job terminated abnormally.
%
\end{constantdesc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Value Structure}
\declarestruct{pmix_value_t}

The \refstruct{pmix_value_t} structure is used to represent the value passed to \refapi{PMIx_Put} and retrieved by \refapi{PMIx_Get}, as well as many of the other \ac{PMIx} functions.

A collection of values may be specified under a single key by passing a \refstruct{pmix_value_t} containing an array of type \refstruct{pmix_data_array_t}, with each array element containing its own object. All members shown below were introduced in version 1 of the standard unless otherwise marked.

\copySignature{pmix_value_t}{1.0}{
typedef struct pmix_value \{ \\
\hspace*{4\sigspace}pmix_data_type_t type; \\
\hspace*{4\sigspace}union \{ \\
\hspace*{8\sigspace}bool flag; \\
\hspace*{8\sigspace}uint8_t byte; \\
\hspace*{8\sigspace}char *string; \\
\hspace*{8\sigspace}size_t size; \\
\hspace*{8\sigspace}pid_t pid; \\
\hspace*{8\sigspace}int integer; \\
\hspace*{8\sigspace}int8_t int8; \\
\hspace*{8\sigspace}int16_t int16; \\
\hspace*{8\sigspace}int32_t int32; \\
\hspace*{8\sigspace}int64_t int64; \\
\hspace*{8\sigspace}unsigned int uint; \\
\hspace*{8\sigspace}uint8_t uint8; \\
\hspace*{8\sigspace}uint16_t uint16; \\
\hspace*{8\sigspace}uint32_t uint32; \\
\hspace*{8\sigspace}uint64_t uint64; \\
\hspace*{8\sigspace}float fval; \\
\hspace*{8\sigspace}double dval; \\
\hspace*{8\sigspace}struct timeval tv; \\
\hspace*{8\sigspace}time_t time;                    // version 2.0 \\
\hspace*{8\sigspace}pmix_status_t status;           // version 2.0 \\
\hspace*{8\sigspace}pmix_rank_t rank;               // version 2.0 \\
\hspace*{8\sigspace}pmix_proc_t *proc;              // version 2.0 \\
\hspace*{8\sigspace}pmix_byte_object_t bo; \\
\hspace*{8\sigspace}pmix_persistence_t persist;     // version 2.0 \\
\hspace*{8\sigspace}pmix_scope_t scope;             // version 2.0 \\
\hspace*{8\sigspace}pmix_data_range_t range;        // version 2.0 \\
\hspace*{8\sigspace}pmix_proc_state_t state;        // version 2.0 \\
\hspace*{8\sigspace}pmix_proc_info_t *pinfo;        // version 2.0 \\
\hspace*{8\sigspace}pmix_data_array_t *darray;      // version 2.0 \\
\hspace*{8\sigspace}void *ptr;                      // version 2.0 \\
\hspace*{8\sigspace}pmix_alloc_directive_t adir;    // version 2.0 \\
\hspace*{4\sigspace}\} data; \\
\} pmix_value_t;
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Value structure support macros}
The following macros are provided to support the \refstruct{pmix_value_t} structure.

\littleheader{Initialize the value structure}
\declaremacro{PMIX_VALUE_CONSTRUCT}

Initialize the \refstruct{pmix_value_t} fields.

\copySignature{PMIX_VALUE_CONSTRUCT}{1.0}{
PMIX_VALUE_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_value_t})}
\end{arglist}

\littleheader{Destruct the value structure}
\declaremacro{PMIX_VALUE_DESTRUCT}

Destruct the \refstruct{pmix_value_t} fields.

\copySignature{PMIX_VALUE_DESTRUCT}{1.0}{
PMIX_VALUE_DESTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_value_t})}
\end{arglist}

%%%%%%%%%%%
\littleheader{Create a value array}
\declaremacro{PMIX_VALUE_CREATE}

Allocate and initialize an array of \refstruct{pmix_value_t} structures.

\copySignature{PMIX_VALUE_CREATE}{1.0}{
PMIX_VALUE_CREATE(m, n)
}

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_value_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}


%%%%%%%%%%%
\littleheader{Free a value structure}
\declaremacro{PMIX_VALUE_RELEASE}

Release a \refstruct{pmix_value_t} structure.

\copySignature{PMIX_VALUE_RELEASE}{4.0}{
PMIX_VALUE_RELEASE(m)
}

\begin{arglist}
\argin{m}{Pointer to a \refstruct{pmix_value_t} structure (handle)}
\end{arglist}

%%%%%%%%%%%
\littleheader{Free a value array}
\declaremacro{PMIX_VALUE_FREE}

Release an array of \refstruct{pmix_value_t} structures.

\copySignature{PMIX_VALUE_FREE}{1.0}{
PMIX_VALUE_FREE(m, n)
}

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_value_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

%%%%%%%%%%%
\littleheader{Load a value structure}
\declaremacro{PMIX_VALUE_LOAD}

Load data into a \refstruct{pmix_value_t} structure.

\copySignature{PMIX_VALUE_LOAD}{2.0}{
PMIX_VALUE_LOAD(v, d, t);
}

\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})}
\end{arglist}

This macro simplifies the loading of data into a \refstruct{pmix_value_t} by correctly assigning values to the structure's fields.

\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

%%%%%%%%%%%
\littleheader{Unload a value structure}
\declaremacro{PMIX_VALUE_UNLOAD}

Unload data from a \refstruct{pmix_value_t} structure.

\copySignature{PMIX_VALUE_UNLOAD}{2.2}{
PMIX_VALUE_UNLOAD(r, v, d, t);
}

\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)}
\end{arglist}

This macro simplifies the unloading of data from a \refstruct{pmix_value_t}.

\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.
\adviceuserend

%%%%%%%%%%%
\littleheader{Transfer data between value structures}
\declaremacro{PMIX_VALUE_XFER}

Transfer the data value between two \refstruct{pmix_value_t} structures.

\copySignature{PMIX_VALUE_XFER}{2.0}{
PMIX_VALUE_XFER(r, d, s);
}

\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)}
\end{arglist}

This macro simplifies the transfer of data between two \refstruct{pmix_value_t} structures, ensuring that all fields are properly copied.

\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

%%%%%%%%%%%
\littleheader{Retrieve a numerical value from a value struct}
\declaremacro{PMIX_VALUE_GET_NUMBER}

Retrieve a numerical value from a \refstruct{pmix_value_t} structure.

\copySignature{PMIX_VALUE_GET_NUMBER}{3.0}{
PMIX_VALUE_GET_NUMBER(s, m, n, t)
}

\begin{arglist}
\argout{s}{Status code for the request (\refstruct{pmix_status_t})}
\argin{m}{Pointer to the\refstruct{pmix_value_t} structure (handle)}
\argout{n}{Variable to be set to the value (match expected type)}
\argin{t}{Type of number expected in \refarg{m} (\refstruct{pmix_data_type_t})}
\end{arglist}

Sets the provided variable equal to the numerical value contained in the given \refstruct{pmix_value_t}, returning success if the data type of the value matches the expected type and \refconst{PMIX_ERR_BAD_PARAM} if it doesn't

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Info Structure}
\label{chap:struct:info}
\declarestruct{pmix_info_t}

The \refstruct{pmix_info_t} structure defines a key/value pair with associated directive. All fields were defined in version 1.0 unless otherwise marked.

\copySignature{pmix_info_t}{1.0}{
typedef struct pmix_info_t \{ \\
\hspace*{4\sigspace}pmix_key_t key; \\
\hspace*{4\sigspace}pmix_info_directives_t flags;    // version 2.0 \\
\hspace*{4\sigspace}pmix_value_t value; \\
\} pmix_info_t;
}

%%%%%%%%%%%
\subsubsection{Info structure support macros}
The following macros are provided to support the \refstruct{pmix_info_t} structure.

\littleheader{Initialize the info structure}
\declaremacro{PMIX_INFO_CONSTRUCT}

Initialize the \refstruct{pmix_info_t} fields.

\copySignature{PMIX_INFO_CONSTRUCT}{1.0}{
PMIX_INFO_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_info_t})}
\end{arglist}

\littleheader{Destruct the info structure}
\declaremacro{PMIX_INFO_DESTRUCT}

Destruct the \refstruct{pmix_info_t} fields.

\copySignature{PMIX_INFO_DESTRUCT}{1.0}{
PMIX_INFO_DESTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_info_t})}
\end{arglist}

%%%%%%%%%%%
\littleheader{Create an info array}
\declaremacro{PMIX_INFO_CREATE}

Allocate and initialize an array of info structures.

\copySignature{PMIX_INFO_CREATE}{1.0}{
PMIX_INFO_CREATE(m, n)
}

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_info_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}


%%%%%%%%%%%
\littleheader{Free an info array}
\declaremacro{PMIX_INFO_FREE}

Release an array of \refstruct{pmix_info_t} structures.

\copySignature{PMIX_INFO_FREE}{1.0}{
PMIX_INFO_FREE(m, n)
}

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_info_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

%%%%%%%%%%%
\littleheader{Load key and value data into a info struct}
\declaremacro{PMIX_INFO_LOAD}

\copySignature{PMIX_INFO_LOAD}{1.0}{
PMIX_INFO_LOAD(v, k, d, t);
}

\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})}
\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.

\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

%%%%%%%%%%%
\littleheader{Copy data between info structures}
\declaremacro{PMIX_INFO_XFER}

Copy all data (including key, value, and directives) between two \refstruct{pmix_info_t} structures.

\copySignature{PMIX_INFO_XFER}{2.0}{
PMIX_INFO_XFER(d, s);
}

\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})}
\end{arglist}

This macro simplifies the transfer of data between two\refstruct{pmix_info_t} structures.

\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


%%%%%%%%%%%
\littleheader{Test a boolean info struct}
\declaremacro{PMIX_INFO_TRUE}

A special macro for checking if a boolean \refstruct{pmix_info_t} is \code{true}.

\copySignature{PMIX_INFO_TRUE}{2.0}{
PMIX_INFO_TRUE(m)
}

\begin{arglist}
\argin{m}{Pointer to a \refstruct{pmix_info_t} structure (handle)}
\end{arglist}

A \refstruct{pmix_info_t} structure is considered to be of type \refconst{PMIX_BOOL} and value \code{true} if:

\begin{compactitemize}
    \item the structure reports a type of \refconst{PMIX_UNDEF}, or
    \item the structure reports a type of \refconst{PMIX_BOOL} and the data flag is \code{true}
\end{compactitemize}

%%%%%%%%%%%
\subsubsection{Info structure list macros}
Constructing an array of \refstruct{pmix_info_t} is a fairly common operation. The following macros are provided to simplify this construction.

%%%%%%%%%%%
\littleheader{Start a list of \refstruct{pmix_info_t} structures}
\declaremacro{PMIX_INFO_LIST_START}

Initialize a list of \refstruct{pmix_info_t} structures. The actual list is opaque to the caller and is implementation-dependent.

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_LIST_START(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{A \code{void*} pointer (handle)}
\end{arglist}

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.

%%%%%%%%%%%
\littleheader{Add a \refstruct{pmix_info_t} structure to a list}
\declaremacro{PMIX_INFO_LIST_ADD}

Add a \refstruct{pmix_info_t} structure containing the specified value to the provided list.

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_LIST_ADD(rc, m, k, d, t)
\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})}
\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

%%%%%%%%%%%
\littleheader{Transfer a \refstruct{pmix_info_t} structure to a list}
\declaremacro{PMIX_INFO_LIST_XFER}

Transfer the information in a \refstruct{pmix_info_t} structure to the provided list.

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_LIST_XFER(rc, m, s)
\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})}
\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

%%%%%%%%%%%
\littleheader{Convert a \refstruct{pmix_info_t} list to an array}
\declaremacro{PMIX_INFO_LIST_CONVERT}

Transfer the information in the provided \refstruct{pmix_info_t} list to a \refstruct{pmix_data_array_t} array

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_LIST_CONVERT(rc, m, d)
\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})}
\end{arglist}

%%%%%%%%%%%
\littleheader{Release a \refstruct{pmix_info_t} list}
\declaremacro{PMIX_INFO_LIST_RELEASE}

Release the provided \refstruct{pmix_info_t} list

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_LIST_RELEASE(m)
\end{codepar}
\cspecificend

\begin{arglist}
\argin{m}{A \code{void*} pointer initialized via \refmacro{PMIX_INFO_LIST_START} (handle)}
\end{arglist}

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.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Info Type Directives}
\declarestruct{pmix_info_directives_t}
\label{api:struct:infodirs}

\versionMarker{2.0}
The \refstruct{pmix_info_directives_t} structure is a \code{uint32_t} type that defines the behavior of command directives via \refstruct{pmix_info_t} arrays.
By default, the values in the \refstruct{pmix_info_t} array passed to a PMIx are \emph{optional}.

\adviceuserstart
A PMIx implementation or PMIx-enabled \ac{RM} may ignore any \refstruct{pmix_info_t} value passed to a \ac{PMIx} \ac{API} that it does not support or does not recognize if it is not explicitly marked as \refconst{PMIX_INFO_REQD}.
This is because the values specified default to optional, meaning they can be ignored in such circumstances.
This may lead to unexpected behavior when porting between environments or \ac{PMIx} implementations if the user is relying on the behavior specified by the \refstruct{pmix_info_t} value.
Users relying on the behavior defined by the \refstruct{pmix_info_t} are advised to set the \refconst{PMIX_INFO_REQD} flag using the \refmacro{PMIX_INFO_REQUIRED} macro.
\adviceuserend

\adviceimplstart
The top 16-bits of the \refstruct{pmix_info_directives_t} are reserved for internal use by \ac{PMIx} library implementers - the \ac{PMIx} standard will \textit{not} specify their intent, leaving them for customized use by implementers. Implementers are advised to use the provided \refmacro{PMIX_INFO_IS_REQUIRED} macro for testing this flag, and must return \refconst{PMIX_ERR_NOT_SUPPORTED} as soon as possible to the caller if the required behavior is not supported.
\adviceimplend

The following constants were introduced in version 2.0 (unless otherwise marked) and can be used to set a variable of the type \refstruct{pmix_info_directives_t}.

\begin{constantdesc}
%
\declareconstitem{PMIX_INFO_REQD}
The behavior defined in the \refstruct{pmix_info_t} array is required, and not optional. This is a bit-mask value.
%
\declareconstitemNEW{PMIX_INFO_REQD_PROCESSED}
Mark that this required attribute has been processed. A required attribute can be handled at any level - the \ac{PMIx} client library might take care of it, or it may be resolved by the \ac{PMIx} server library, or it may pass up to the host environment for handling. If a level does not recognize or support the required attribute, it is required to pass it upwards to give the next level an opportunity to process it. Thus, the host environment (or the server library if the host does not support the given operation) must know if a lower level has handled the requirement so it can return a \refconst{PMIX_ERR_NOT_SUPPORTED} error status if the host itself cannot meet the request. Upon processing the request, the level must therefore mark the attribute with this directive to alert any subsequent levels that the requirement has been met.
%
\declareconstitem{PMIX_INFO_ARRAY_END}
Mark that this \refstruct{pmix_info_t} struct is at the end of an array created by the \refmacro{PMIX_INFO_CREATE} macro. This is a bit-mask value.
%
\declareconstitemNEW{PMIX_INFO_DIR_RESERVED}
A bit-mask identifying the bits reserved for internal use by implementers - these currently are set as \code{0xffff0000}.
%
\end{constantdesc}

\advicermstart
Host environments are advised to use the provided \refmacro{PMIX_INFO_IS_REQUIRED} macro for testing this flag and must return \refconst{PMIX_ERR_NOT_SUPPORTED} as soon as possible to the caller if the required behavior is not supported.
\advicermend


\subsubsection{Info Directive support macros}

The following macros are provided to support the setting and testing of \refstruct{pmix_info_t} directives.

%%%%
\littleheader{Mark an info structure as required}
\declaremacro{PMIX_INFO_REQUIRED}

Set the \refconst{PMIX_INFO_REQD} flag in a \refstruct{pmix_info_t} structure.

\copySignature{PMIX_INFO_REQUIRED}{2.0}{
PMIX_INFO_REQUIRED(info);
}

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

This macro simplifies the setting of the \refconst{PMIX_INFO_REQD} flag in \refstruct{pmix_info_t} structures.

%%%%
\littleheader{Mark an info structure as optional}
\declaremacro{PMIX_INFO_OPTIONAL}

Unsets the \refconst{PMIX_INFO_REQD} flag in a \refstruct{pmix_info_t} structure.

\copySignature{PMIX_INFO_OPTIONAL}{2.0}{
PMIX_INFO_OPTIONAL(info);
}

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

This macro simplifies marking a \refstruct{pmix_info_t} structure as \textit{optional}.

%%%%%%%%%%%
\littleheader{Test an info structure for \textit{required} directive}
\declaremacro{PMIX_INFO_IS_REQUIRED}

Test the \refconst{PMIX_INFO_REQD} flag in a \refstruct{pmix_info_t} structure, returning \code{true} if the flag is set.

\copySignature{PMIX_INFO_IS_REQUIRED}{2.0}{
PMIX_INFO_IS_REQUIRED(info);
}

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

This macro simplifies the testing of the required flag in \refstruct{pmix_info_t} structures.

%%%%%%%%%%%
\littleheader{Test an info structure for \textit{optional} directive}
\declaremacro{PMIX_INFO_IS_OPTIONAL}

Test a \refstruct{pmix_info_t} structure, returning \code{true} if the structure is \textit{optional}.

\copySignature{PMIX_INFO_IS_OPTIONAL}{2.0}{
PMIX_INFO_IS_OPTIONAL(info);
}

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

Test the \refconst{PMIX_INFO_REQD} flag in a \refstruct{pmix_info_t} structure, returning \code{true} if the flag is \textit{not} set.

%%%%%%%%%%%
\littleheader{Mark a required attribute as processed}
\declaremacro{PMIX_INFO_PROCESSED}

Mark that a required \refstruct{pmix_info_t} structure has been processed.

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_PROCESSED(info);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

Set the \refconst{PMIX_INFO_REQD_PROCESSED} flag in a \refstruct{pmix_info_t} structure indicating that is has been processed.

%%%%%%%%%%%
\littleheader{Test if a required attribute has been processed}
\declaremacro{PMIX_INFO_WAS_PROCESSED}

Test that a required \refstruct{pmix_info_t} structure has been processed.

\versionMarker{4.0}
\cspecificstart
\begin{codepar}
PMIX_INFO_WAS_PROCESSED(info);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

Test the \refconst{PMIX_INFO_REQD_PROCESSED} flag in a \refstruct{pmix_info_t} structure.

%%%%%%%%%%%
\littleheader{Test an info structure for \textit{end of array} directive}
\declaremacro{PMIX_INFO_IS_END}

Test a \refstruct{pmix_info_t} structure, returning \code{true} if the structure is at the end of an array created by the \refmacro{PMIX_INFO_CREATE} macro.

\copySignature{PMIX_INFO_IS_END}{2.2}{
PMIX_INFO_IS_END(info);
}

\begin{arglist}
\argin{info}{Pointer to the \refstruct{pmix_info_t} (pointer to \refstruct{pmix_info_t})}
\end{arglist}

This macro simplifies the testing of the end-of-array flag in \refstruct{pmix_info_t} structures.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Environmental Variable Structure}
\declarestruct{pmix_envar_t}

\versionMarker{3.0}
Define a structure for specifying environment variable modifications.
Standard environment variables (e.g., \code{PATH}, \code{LD_LIBRARY_PATH}, and \code{LD_PRELOAD})
take multiple arguments separated by delimiters. Unfortunately, the delimiters
depend upon the variable itself - some use semi-colons, some colons, etc. Thus,
the operation requires not only the name of the variable to be modified and
the value to be inserted, but also the separator to be used when composing
the aggregate value.

\cspecificstart
\begin{codepar}
typedef struct \{
    char *envar;
    char *value;
    char separator;
\} pmix_envar_t;
\end{codepar}
\cspecificend

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Environmental variable support macros}

The following macros are provided to support the \refstruct{pmix_envar_t} structure.

\littleheader{Initialize the envar structure}
\declaremacro{PMIX_ENVAR_CONSTRUCT}

Initialize the \refstruct{pmix_envar_t} fields.

\copySignature{PMIX_ENVAR_CONSTRUCT}{3.0}{
PMIX_ENVAR_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_envar_t})}
\end{arglist}

\littleheader{Destruct the envar structure}
\declaremacro{PMIX_ENVAR_DESTRUCT}

Clear the \refstruct{pmix_envar_t} fields.

\copySignature{PMIX_ENVAR_DESTRUCT}{3.0}{
PMIX_ENVAR_DESTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_envar_t})}
\end{arglist}


\littleheader{Create an envar array}
\declaremacro{PMIX_ENVAR_CREATE}

Allocate and initialize an array of \refstruct{pmix_envar_t} structures.

\copySignature{PMIX_ENVAR_CREATE}{3.0}{
PMIX_ENVAR_CREATE(m, n)
}

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_envar_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}


\littleheader{Free an envar array}
\declaremacro{PMIX_ENVAR_FREE}

Release an array of \refstruct{pmix_envar_t} structures.

\copySignature{PMIX_ENVAR_FREE}{3.0}{
PMIX_ENVAR_FREE(m, n)
}

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_envar_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

\littleheader{Load an envar structure}
\declaremacro{PMIX_ENVAR_LOAD}

Load values into a \refstruct{pmix_envar_t}.

\copySignature{PMIX_ENVAR_LOAD}{2.0}{
PMIX_ENVAR_LOAD(m, e, v, s)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be loaded (pointer to \refstruct{pmix_envar_t})}
\argin{e}{Environmental variable name (\code{char*})}
\argin{v}{Value of variable (\code{char*})}
\argin{v}{Separator character (\code{char})}
\end{arglist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Byte Object Type}
\declarestruct{pmix_byte_object_t}

The \refstruct{pmix_byte_object_t} structure describes a raw byte sequence.

\copySignature{pmix_byte_object_t}{1.0}{
typedef struct pmix_byte_object \{ \\
\hspace*{4\sigspace}char *bytes; \\
\hspace*{4\sigspace}size_t size; \\
\} pmix_byte_object_t;
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Byte object support macros}
The following macros support the \refstruct{pmix_byte_object_t} structure.

\littleheader{Initialize the byte object structure}
\declaremacro{PMIX_BYTE_OBJECT_CONSTRUCT}

Initialize the \refstruct{pmix_byte_object_t} fields.

\copySignature{PMIX_BYTE_OBJECT_CONSTRUCT}{2.0}{
PMIX_BYTE_OBJECT_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_byte_object_t})}
\end{arglist}

\littleheader{Destruct the byte object structure}
\declaremacro{PMIX_BYTE_OBJECT_DESTRUCT}

Clear the \refstruct{pmix_byte_object_t} fields.

\copySignature{PMIX_BYTE_OBJECT_DESTRUCT}{2.0}{
PMIX_BYTE_OBJECT_DESTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_byte_object_t})}
\end{arglist}

\littleheader{Create a byte object structure}
\declaremacro{PMIX_BYTE_OBJECT_CREATE}

Allocate and intitialize an array of \refstruct{pmix_byte_object_t} structures.

\copySignature{PMIX_BYTE_OBJECT_CREATE}{2.0}{
PMIX_BYTE_OBJECT_CREATE(m, n)
}

\begin{arglist}
\arginout{m}{Address where the pointer to the array of \refstruct{pmix_byte_object_t} structures shall be stored (handle)}
\argin{n}{Number of structures to be allocated (\code{size_t})}
\end{arglist}

\littleheader{Free a byte object array}
\declaremacro{PMIX_BYTE_OBJECT_FREE}

Release an array of \refstruct{pmix_byte_object_t} structures.

\copySignature{PMIX_BYTE_OBJECT_FREE}{2.0}{
PMIX_BYTE_OBJECT_FREE(m, n)
}

\begin{arglist}
\argin{m}{Pointer to the array of \refstruct{pmix_byte_object_t} structures (handle)}
\argin{n}{Number of structures in the array (\code{size_t})}
\end{arglist}

\littleheader{Load a byte object structure}
\declaremacro{PMIX_BYTE_OBJECT_LOAD}

Load values into a \refstruct{pmix_byte_object_t}.

\copySignature{PMIX_BYTE_OBJECT_LOAD}{2.0}{
PMIX_BYTE_OBJECT_LOAD(b, d, s)
}

\begin{arglist}
\argin{b}{Pointer to the structure to be loaded (pointer to \refstruct{pmix_byte_object_t})}
\argin{d}{Pointer to the data to be loaded (\code{char*})}
\argin{s}{Number of bytes in the data array (\code{size_t})}
\end{arglist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Data Array Structure}
\declarestruct{pmix_data_array_t}

The \refstruct{pmix_data_array_t} structure defines an array data structure.

\copySignature{pmix_data_array_t}{2.0}{
typedef struct pmix_data_array \{ \\
\hspace*{4\sigspace}pmix_data_type_t type; \\
\hspace*{4\sigspace}size_t size; \\
\hspace*{4\sigspace}void *array; \\
\} pmix_data_array_t;
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Data array support macros}
The following macros support the \refstruct{pmix_data_array_t} structure.

\littleheader{Initialize a data array structure}
\declaremacro{PMIX_DATA_ARRAY_CONSTRUCT}

Initialize the \refstruct{pmix_data_array_t} fields, allocating memory for the array of the indicated type.

\copySignature{PMIX_DATA_ARRAY_CONSTRUCT}{2.2}{
PMIX_DATA_ARRAY_CONSTRUCT(m, n, t)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be initialized (pointer to \refstruct{pmix_data_array_t})}
\argin{n}{Number of elements in the array (\code{size_t})}
\argin{t}{\ac{PMIx} data type of the array elements (\refstruct{pmix_data_type_t})}
\end{arglist}


\littleheader{Destruct a data array structure}
\declaremacro{PMIX_DATA_ARRAY_DESTRUCT}

Destruct the \refstruct{pmix_data_array_t}, releasing the memory in the array.

\copySignature{PMIX_DATA_ARRAY_CONSTRUCT}{2.2}{
PMIX_DATA_ARRAY_CONSTRUCT(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be destructed (pointer to \refstruct{pmix_data_array_t})}
\end{arglist}


\littleheader{Create a data array structure}
\declaremacro{PMIX_DATA_ARRAY_CREATE}

Allocate memory for the \refstruct{pmix_data_array_t} object itself, and then allocate memory for the array of the indicated type.

\copySignature{PMIX_DATA_ARRAY_CREATE}{2.2}{
PMIX_DATA_ARRAY_CREATE(m, n, t)
}

\begin{arglist}
\arginout{m}{Variable to be set to the address of the structure (pointer to \refstruct{pmix_data_array_t})}
\argin{n}{Number of elements in the array (\code{size_t})}
\argin{t}{\ac{PMIx} data type of the array elements (\refstruct{pmix_data_type_t})}
\end{arglist}


\littleheader{Free a data array structure}
\declaremacro{PMIX_DATA_ARRAY_FREE}

Release the memory in the array, and then release the \refstruct{pmix_data_array_t} object itself.

\copySignature{PMIX_DATA_ARRAY_FREE}{2.2}{
PMIX_DATA_ARRAY_FREE(m)
}

\begin{arglist}
\argin{m}{Pointer to the structure to be released (pointer to \refstruct{pmix_data_array_t})}
\end{arglist}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Argument Array Macros}

The following macros support the construction and release of \code{NULL}-terminated argv arrays of strings.

%%%%
\littleheader{Argument array extension}
\declaremacro{PMIX_ARGV_APPEND}

Append a string to a NULL-terminated, argv-style array of strings.

\cspecificstart
\begin{codepar}
PMIX_ARGV_APPEND(r, a, b);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{r}{Status code indicating success or failure of the operation (\refstruct{pmix_status_t})}
\arginout{a}{Argument list (pointer to NULL-terminated array of strings)}
\argin{b}{Argument to append to the list (string)}
\end{arglist}

This function helps the caller build the \code{argv} portion of \refstruct{pmix_app_t} structure, arrays of keys for querying, or other places where argv-style string arrays are required.

\adviceuserstart
The provided argument is copied into the destination array - thus, the source string can be free'd without affecting the array once the macro has completed.
\adviceuserend

%%%%
\littleheader{Argument array prepend}
\declaremacro{PMIX_ARGV_PREPEND}

Prepend a string to a NULL-terminated, argv-style array of strings.

\cspecificstart
\begin{codepar}
PMIX_ARGV_PREPEND(r, a, b);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{r}{Status code indicating success or failure of the operation (\refstruct{pmix_status_t})}
\arginout{a}{Argument list (pointer to NULL-terminated array of strings)}
\argin{b}{Argument to append to the list (string)}
\end{arglist}

This function helps the caller build the \code{argv} portion of \refstruct{pmix_app_t} structure, arrays of keys for querying, or other places where argv-style string arrays are required.

\adviceuserstart
The provided argument is copied into the destination array - thus, the source string can be free'd without affecting the array once the macro has completed.
\adviceuserend

%%%%%%%%%%%
\littleheader{Argument array extension - unique}
\declaremacro{PMIX_ARGV_APPEND_UNIQUE}

Append a string to a NULL-terminated, argv-style array of strings, but only if the provided argument doesn't already exist somewhere in the array.

\cspecificstart
\begin{codepar}
PMIX_ARGV_APPEND_UNIQUE(r, a, b);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{r}{Status code indicating success or failure of the operation (\refstruct{pmix_status_t})}
\arginout{a}{Argument list (pointer to NULL-terminated array of strings)}
\argin{b}{Argument to append to the list (string)}
\end{arglist}

This function helps the caller build the \code{argv} portion of \refstruct{pmix_app_t} structure, arrays of keys for querying, or other places where argv-style string arrays are required.

\adviceuserstart
The provided argument is copied into the destination array - thus, the source string can be free'd without affecting the array once the macro has completed.
\adviceuserend

%%%%%%%%%%%
\littleheader{Argument array release}
\declaremacro{PMIX_ARGV_FREE}

Free an argv-style array and all of the strings that it contains.

\cspecificstart
\begin{codepar}
PMIX_ARGV_FREE(a);
\end{codepar}
\cspecificend

\begin{arglist}
\argin{a}{Argument list (pointer to NULL-terminated array of strings)}
\end{arglist}

This function releases the array and all of the strings it contains.

%%%%%%%%%%%
\littleheader{Argument array split}
\declaremacro{PMIX_ARGV_SPLIT}

Split a string into a NULL-terminated argv array.

\cspecificstart
\begin{codepar}
PMIX_ARGV_SPLIT(a, b, c);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{a}{Resulting argv-style array (\code{char**})}
\argin{b}{String to be split (\code{char*})}
\argin{c}{Delimiter character (\code{char})}
\end{arglist}

Split an input string into a NULL-terminated argv array. Do not include empty strings in the resulting array.

\adviceuserstart
All strings are inserted into the argv array by value; the newly-allocated array makes no references to the src_string argument (i.e., it can be freed after calling this function without invalidating the output argv array)
\adviceuserend

%%%%%%%%%%%
\littleheader{Argument array join}
\declaremacro{PMIX_ARGV_JOIN}

Join all the elements of an argv array into a single newly-allocated string.

\cspecificstart
\begin{codepar}
PMIX_ARGV_JOIN(a, b, c);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{a}{Resulting string (\code{char*})}
\argin{b}{Argv-style array to be joined (\code{char**})}
\argin{c}{Delimiter character (\code{char})}
\end{arglist}

Join all the elements of an argv array into a single newly-allocated string.

%%%%%%%%%%%
\littleheader{Argument array count}
\declaremacro{PMIX_ARGV_COUNT}

Return the length of a NULL-terminated argv array.

\cspecificstart
\begin{codepar}
PMIX_ARGV_COUNT(r, a);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{r}{Number of strings in the array (integer)}
\argin{a}{Argv-style array (\code{char**})}
\end{arglist}

Count the number of elements in an argv array

%%%%%%%%%%%
\littleheader{Argument array copy}
\declaremacro{PMIX_ARGV_COPY}

Copy an argv array, including copying all of its strings.

\cspecificstart
\begin{codepar}
PMIX_ARGV_COPY(a, b);
\end{codepar}
\cspecificend

\begin{arglist}
\argout{a}{New argv-style array (\code{char**})}
\argin{b}{Argv-style array (\code{char**})}
\end{arglist}

Copy an argv array, including copying all of its strings.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Set Environment Variable}
\declaremacro{PMIX_SETENV}

%%%%
\summary

Set an environment variable in a \code{NULL}-terminated, env-style array.

\cspecificstart
\begin{codepar}
PMIX_SETENV(r, name, value, env);
\end{codepar}
\cspecificend


\begin{arglist}
\argout{r}{Status code indicating success or failure of the operation (\refstruct{pmix_status_t})}
\argin{name}{Argument name (string)}
\argin{value}{Argument value (string)}
\arginout{env}{Environment array to update (pointer to array of strings)}
\end{arglist}

%%%%
\descr

Similar to \code{setenv} from the C API, this allows the caller to set an environment variable in the specified \code{env} array, which could then be passed to the \refstruct{pmix_app_t} structure or any other destination.

\adviceuserstart
The provided name and value are copied into the destination environment array - thus, the source strings can be free'd without affecting the array once the macro has completed.
\adviceuserend


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Generalized Data Types Used for Packing/Unpacking}
\declarestruct{pmix_data_type_t}

The \refstruct{pmix_data_type_t} structure is a \code{uint16_t} type for identifying the data type for packing/unpacking purposes. New data type values introduced in this version of the Standard are shown in \textbf{\color{magenta}magenta}.

\adviceimplstart
The following constants can be used to set a variable of the type \refstruct{pmix_data_type_t}. Data types in the \ac{PMIx} Standard are defined in terms of the C-programming language. Implementers wishing to support other languages should provide the equivalent definitions in a language-appropriate manner. Additionally, a PMIx implementation may choose to add additional types.
\adviceimplend

\begin{constantdesc}
%
\declareconstitem{PMIX_UNDEF}
Undefined.
%
\declareconstitem{PMIX_BOOL}
Boolean (converted to/from native \code{true}/\code{false}) (\code{bool}).
%
\declareconstitem{PMIX_BYTE}
A byte of data (\code{uint8_t}).
%
\declareconstitem{PMIX_STRING}
\code{NULL} terminated string (\code{char*}).
%
\declareconstitem{PMIX_SIZE}
Size \code{size_t}.
%
\declareconstitem{PMIX_PID}
Operating \ac{PID} (\code{pid_t}).
%
\declareconstitem{PMIX_INT}
Integer (\code{int}).
%
\declareconstitem{PMIX_INT8}
8-byte integer (\code{int8_t}).
%
\declareconstitem{PMIX_INT16}
16-byte integer (\code{int16_t}).
%
\declareconstitem{PMIX_INT32}
32-byte integer (\code{int32_t}).
%
\declareconstitem{PMIX_INT64}
64-byte integer (\code{int64_t}).
%
\declareconstitem{PMIX_UINT}
Unsigned integer (\code{unsigned int}).
%
\declareconstitem{PMIX_UINT8}
Unsigned 8-byte integer (\code{uint8_t}).
%
\declareconstitem{PMIX_UINT16}
Unsigned 16-byte integer (\code{uint16_t}).
%
\declareconstitem{PMIX_UINT32}
Unsigned 32-byte integer (\code{uint32_t}).
%
\declareconstitem{PMIX_UINT64}
Unsigned 64-byte integer (\code{uint64_t}).
%
\declareconstitem{PMIX_FLOAT}
Float (\code{float}).
%
\declareconstitem{PMIX_DOUBLE}
Double (\code{double}).
%
\declareconstitem{PMIX_TIMEVAL}
Time value (\code{struct timeval}).
%
\declareconstitem{PMIX_TIME}
Time (\code{time_t}).
%
\declareconstitem{PMIX_STATUS}
Status code {\refstruct{pmix_status_t}}.
%
\declareconstitem{PMIX_VALUE}
Value (\refstruct{pmix_value_t}).
%
\declareconstitem{PMIX_PROC}
Process (\refstruct{pmix_proc_t}).
%
\declareconstitem{PMIX_APP}
Application context.
%
\declareconstitem{PMIX_INFO}
Info object.
%
\declareconstitem{PMIX_PDATA}
Pointer to data.
%
\declareconstitem{PMIX_BUFFER}
Buffer.
%
\declareconstitem{PMIX_BYTE_OBJECT}
Byte object (\refstruct{pmix_byte_object_t}).
%
\declareconstitem{PMIX_KVAL}
Key/value pair.
%
\declareconstitem{PMIX_PERSIST}
Persistance (\refstruct{pmix_persistence_t}).
%
\declareconstitem{PMIX_POINTER}
Pointer to an object (\code{void*}).
%
\declareconstitem{PMIX_SCOPE}
Scope (\refstruct{pmix_scope_t}).
%
\declareconstitem{PMIX_DATA_RANGE}
Range for data (\refstruct{pmix_data_range_t}).
%
\declareconstitem{PMIX_COMMAND}
PMIx command code (used internally).
%
\declareconstitem{PMIX_INFO_DIRECTIVES}
Directives flag for \refstruct{pmix_info_t} (\refstruct{pmix_info_directives_t}).
%
\declareconstitem{PMIX_DATA_TYPE}
Data type code (\refstruct{pmix_data_type_t}).
%
\declareconstitem{PMIX_PROC_STATE}
Process state (\refstruct{pmix_proc_state_t}).
%
\declareconstitem{PMIX_PROC_INFO}
Process information (\refstruct{pmix_proc_info_t}).
%
\declareconstitem{PMIX_DATA_ARRAY}
Data array (\refstruct{pmix_data_array_t}).
%
\declareconstitem{PMIX_PROC_RANK}
Process rank (\refstruct{pmix_rank_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}
Byte object whose bytes have been compressed with zlib (\code{pmix_byte_object_t}).
%
\declareconstitem{PMIX_ALLOC_DIRECTIVE}
Allocation directive (\refstruct{pmix_alloc_directive_t}).
%
\declareconstitem{PMIX_IOF_CHANNEL}
Input/output forwarding channel (\refstruct{pmix_iof_channel_t}).
%
\declareconstitem{PMIX_ENVAR}
Environmental variable structure (\refstruct{pmix_envar_t}).
%
\declareconstitemNEW{PMIX_COORD}
Structure containing fabric coordinates (\refstruct{pmix_coord_t}).
%
\declareconstitemNEW{PMIX_REGATTR}
Structure supporting attribute registrations (\refstruct{pmix_regattr_t}).
%
\declareconstitemNEW{PMIX_REGEX}
Regular expressions - can be a valid NULL-terminated string or an arbitrary array of bytes.
%
\declareconstitemNEW{PMIX_JOB_STATE}
Job state (\refstruct{pmix_job_state_t}).
%
\declareconstitemNEW{PMIX_LINK_STATE}
Link state (\refstruct{pmix_link_state_t}).
%
\declareconstitemNEW{PMIX_PROC_CPUSET}
Structure containing the binding bitmap of a process (\refstruct{pmix_cpuset_t}).
%
\declareconstitemNEW{PMIX_GEOMETRY}
Geometry structure containing the fabric coordinates of a specified device.(\refstruct{pmix_geometry_t}).
%
\declareconstitemNEW{PMIX_DEVICE_DIST}
Structure containing the minimum and maximum relative distance from the caller to a given fabric device. (\refstruct{pmix_device_distance_t}).
%
\declareconstitemNEW{PMIX_ENDPOINT}
Structure containing an assigned endpoint for a given fabric device. (\refstruct{pmix_endpoint_t}).
%
\declareconstitemNEW{PMIX_TOPO}
Structure containing the topology for a given node. (\refstruct{pmix_topology_t}).
%
\declareconstitemNEW{PMIX_DEVTYPE}
Bitmask containing the types of devices being referenced. (\refstruct{pmix_device_type_t}).
%
\declareconstitemNEW{PMIX_LOCTYPE}
Bitmask describing the relative location of another process. (\refstruct{pmix_locality_t}).
%
\declareconstitemNEW{PMIX_DATA_TYPE_MAX}
A starting point for implementer-specific data types.
Values above this are guaranteed not to conflict with \ac{PMIx} values.
Definitions should always be based on the \refconst{PMIX_DATA_TYPE_MAX} constant and not a specific value as the value of the constant may change.
%
\end{constantdesc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{General Callback Functions}

PMIx provides blocking and nonblocking versions of most APIs.
In the nonblocking versions, a callback is activated upon completion of the the operation.
This section describes many of those callbacks.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Release Callback Function}
\declareapi{pmix_release_cbfunc_t}

%%%%
\summary

The \refapi{pmix_release_cbfunc_t} is used by the \refapi{pmix_modex_cbfunc_t} and \refapi{pmix_info_cbfunc_t} operations to indicate that the callback data may be reclaimed/freed by the caller.

%%%%
\format

\copySignature{pmix_release_cbfunc_t}{1.0}{
typedef void (*pmix_release_cbfunc_t) \\
\hspace*{4\sigspace}(void *cbdata);
}

\begin{arglist}
\arginout{cbdata}{Callback data passed to original API call (memory reference)}
\end{arglist}

%%%%
\descr

Since the data is ``owned'' by the host server, provide a callback function to notify the host server that we are done with the data so it can be released.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Op Callback Function}
\declareapi{pmix_op_cbfunc_t}

%%%%
\summary

The \refapi{pmix_op_cbfunc_t} is used by operations that simply return a status.

\copySignature{pmix_op_cbfunc_t}{1.0}{
typedef void (*pmix_op_cbfunc_t) \\
\hspace*{4\sigspace}(pmix_status_t status, void *cbdata);
}

\begin{arglist}
\argin{status}{Status associated with the operation (handle)}
\argin{cbdata}{Callback data passed to original API call (memory reference)}
\end{arglist}

%%%%
\descr

Used by a wide range of \ac{PMIx} API's including \refapi{PMIx_Fence_nb}, \refapi{pmix_server_client_connected2_fn_t}, \refapi{PMIx_server_register_nspace}.
This callback function is used to return a status to an often nonblocking operation.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Value Callback Function}
\declareapi{pmix_value_cbfunc_t}

%%%%
\summary

The \refapi{pmix_value_cbfunc_t} is used by \refapi{PMIx_Get_nb} to return data.

\copySignature{pmix_value_cbfunc_t}{1.0}{
typedef void (*pmix_value_cbfunc_t) \\
\hspace*{4\sigspace}(pmix_status_t status, \\
\hspace*{5\sigspace}pmix_value_t *kv, void *cbdata);
}

\begin{arglist}
\argin{status}{Status associated with the operation (handle)}
\argin{kv}{Key/value pair representing the data (\refstruct{pmix_value_t})}
\argin{cbdata}{Callback data passed to original API call (memory reference)}
\end{arglist}


%%%%
\descr

A callback function for calls to \refapi{PMIx_Get_nb}.
The \refarg{status} indicates if the requested data was found or not.
A pointer to the \refstruct{pmix_value_t} structure containing the found data is returned.
The pointer will be \code{NULL} if the requested data was not found.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Info Callback Function}
\declareapi{pmix_info_cbfunc_t}

%%%%
\summary

The \refapi{pmix_info_cbfunc_t} is a general information callback used by various APIs.

\copySignature{pmix_info_cbfunc_t}{2.0}{
typedef void (*pmix_info_cbfunc_t) \\
\hspace*{4\sigspace}(pmix_status_t status, \\
\hspace*{5\sigspace}pmix_info_t info[], size_t ninfo, \\
\hspace*{5\sigspace}void *cbdata, \\
\hspace*{5\sigspace}pmix_release_cbfunc_t release_fn, \\
\hspace*{5\sigspace}void *release_cbdata);
}

\begin{arglist}
\argin{status}{Status associated with the operation (\refstruct{pmix_status_t})}
\argin{info}{Array of \refstruct{pmix_info_t} returned by the operation (pointer)}
\argin{ninfo}{Number of elements in the \argref{info} array (\code{size_t})}
\argin{cbdata}{Callback data passed to original API call (memory reference)}
\argin{release_fn}{Function to be called when done with the \argref{info} data (function pointer)}
\argin{release_cbdata}{Callback data to be passed to \argref{release_fn} (memory reference)}
\end{arglist}


%%%%
\descr

The \refarg{status} indicates if requested data was found or not.
An array of \refstruct{pmix_info_t} will contain the key/value pairs.

%%%%%%%%%%%
\subsection{Handler registration callback function}
\declareapi{pmix_hdlr_reg_cbfunc_t}

%%%%
\summary

Callback function for calls to register handlers, e.g., event notification and IOF requests.

%%%%
\format

\copySignature{pmix_hdlr_reg_cbfunc_t}{3.0}{
typedef void (*pmix_hdlr_reg_cbfunc_t) \\
\hspace*{4\sigspace}(pmix_status_t status, \\
\hspace*{5\sigspace}size_t refid, \\
\hspace*{5\sigspace}void *cbdata);
}

\begin{arglist}
\argin{status}{\refconst{PMIX_SUCCESS} or an appropriate error constant (\refstruct{pmix_status_t})}
\argin{refid}{reference identifier assigned to the handler by PMIx, used to deregister the handler (\code{size_t})}
\argin{cbdata}{object provided to the registration call (pointer)}
\end{arglist}

%%%%
\descr

Callback function for calls to register handlers, e.g., event notification and IOF requests.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{PMIx Datatype Value String Representations}

Provide a string representation for several types of values.
Note that the provided string is statically defined and must NOT be \code{free}'d.

%%%%
\summary
\declareapi{PMIx_Error_string}

String representation of a \refstruct{pmix_status_t}.

\copySignature{PMIx_Error_string}{1.0}{
const char* \\
PMIx_Error_string(pmix_status_t status);
}

%%%%
\summary
\declareapi{PMIx_Proc_state_string}

String representation of a \refstruct{pmix_proc_state_t}.

\copySignature{PMIx_Proc_state_string}{2.0}{
const char* \\
PMIx_Proc_state_string(pmix_proc_state_t state);
}

%%%%
\summary
\declareapi{PMIx_Scope_string}

String representation of a \refstruct{pmix_scope_t}.

\copySignature{PMIx_Scope_string}{2.0}{
const char* \\
PMIx_Scope_string(pmix_scope_t scope);
}

%%%%
\summary
\declareapi{PMIx_Persistence_string}

String representation of a \refstruct{pmix_persistence_t}.

\copySignature{PMIx_Persistence_string}{2.0}{
const char* \\
PMIx_Persistence_string(pmix_persistence_t persist);
}

%%%%
\summary
\declareapi{PMIx_Data_range_string}

String representation of a \refstruct{pmix_data_range_t}.

\copySignature{PMIx_Data_range_string}{2.0}{
const char* \\
PMIx_Data_range_string(pmix_data_range_t range);
}

%%%%
\summary
\declareapi{PMIx_Info_directives_string}

String representation of a \refstruct{pmix_info_directives_t}.

\copySignature{PMIx_Info_directives_string}{2.0}{
const char* \\
PMIx_Info_directives_string(pmix_info_directives_t directives);
}

%%%%
\summary
\declareapi{PMIx_Data_type_string}

String representation of a \refstruct{pmix_data_type_t}.

\copySignature{PMIx_Data_type_string}{2.0}{
const char* \\
PMIx_Data_type_string(pmix_data_type_t type);
}

%%%%
\summary
\declareapi{PMIx_Alloc_directive_string}

String representation of a \refstruct{pmix_alloc_directive_t}.

\copySignature{PMIx_Alloc_directive_string}{2.0}{
const char* \\
PMIx_Alloc_directive_string(pmix_alloc_directive_t directive);
}

%%%%
\summary
\declareapi{PMIx_IOF_channel_string}

String representation of a \refstruct{pmix_iof_channel_t}.

\copySignature{PMIx_IOF_channel_string}{3.0}{
const char* \\
PMIx_IOF_channel_string(pmix_iof_channel_t channel);
}

%%%%
\summary
\declareapi{PMIx_Job_state_string}

String representation of a \refstruct{pmix_job_state_t}.

\copySignature{PMIx_Job_state_string}{4.0}{
const char* \\
PMIx_Job_state_string(pmix_job_state_t state);
}

%%%%
\summary
\declareapi{PMIx_Get_attribute_string}

String representation of a \ac{PMIx} attribute.

\copySignature{PMIx_Get_attribute_string}{4.0}{
const char* \\
PMIx_Get_attribute_string(char *attributename);
}

%%%%
\summary
\declareapi{PMIx_Get_attribute_name}

Return the \ac{PMIx} attribute name corresponding to the given attribute string.

\copySignature{PMIx_Get_attribute_name}{4.0}{
const char* \\
PMIx_Get_attribute_name(char *attributestring);
}

%%%%
\summary
\declareapi{PMIx_Link_state_string}

String representation of a \refstruct{pmix_link_state_t}.

\copySignature{PMIx_Link_state_string}{4.0}{
const char* \\
PMIx_Link_state_string(pmix_link_state_t state);
}

%%%%
\summary
\declareapi{PMIx_Device_type_string}

String representation of a \refstruct{pmix_device_type_t}.

\copySignature{PMIx_Device_type_string}{4.0}{
const char* \\
PMIx_Device_type_string(pmix_device_type_t type);
}


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