From e58af28ca5f4c554543f262ea0127c910a05c385 Mon Sep 17 00:00:00 2001 From: Ken Raffenetti Date: Mon, 22 Aug 2022 15:18:34 -0500 Subject: [PATCH 1/5] Add revision information for v5 Signed-off-by: Ken Raffenetti Co-authored-by: David Solt Co-authored-by: Joshua Hursey --- Chap_Revisions.tex | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index d3e09a90..d283f4dd 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -1433,15 +1433,36 @@ \subsection{Added Attributes (Provisional)} %%%%%%%%%% History: Version 5.0 \section{Version 5.0: TBD} -%\begin{compactitemize} -% \item ... -%\end{compactitemize} +\begin{compactitemize} + \item First release prepared using procedures defined in the PMIx + Governance v1.7 document\footnote{\url{https://github.com/pmix/governance/releases/tag/v1.7}}. + \item Add specific values to constant definitions to ensure + consistency across implementations. + \item Add Use-Cases appendix with descriptions for Business Card + Exchange, Debugging, Hybrid Applications, MPI Sessions, and + Cross-Version Compatibility. + \item Add guidance on how PMIx defines an Application Binary Interface (ABI). + \item Add ABI query attributes. + \item Clarify three roles of consumers of the PMIx interface (client, server, tool). + \item Clarify when \refattr{PMIX_PARENT_ID} attribute is provided. + \item Clarify the value of \refattr{PMIX_CMD_LINE} attribute in spawn case. + \item Clarifications to Terms and Conventions chapter and addition of additional term definitions. + \item Re-organize the presentation of data access, syncronization, reserved keys and non-reserved keys. + \item Make presentation of return values consistent across APIs. + \item Attributes supported by PRRTE are no longer color coded. Refer to PRRTE documentation to see what is supported for a particular PRRTE version. +\end{compactitemize} + % %\subsection{Added \acp{API}} % %\subsection{Added Constants} % -%\subsection{Added Attributes} +\subsection{Added Attributes} + +\littleheader{ABI attributes} +\pasteAttributeItem{PMIX_QUERY_STABLE_ABI_VERSION} +\pasteAttributeItem{PMIX_QUERY_PROVISIONAL_ABI_VERSION} + % %\subsection{Added Macros} % From 3d6890eca00436ac362da4a2dfca2dc06fa461d7 Mon Sep 17 00:00:00 2001 From: Ken Raffenetti Date: Mon, 22 Aug 2022 15:21:42 -0500 Subject: [PATCH 2/5] Remove NEW markers from declarations After discussion at the 2022 Q3 ASC meeting, it was proposed to remove all "new" markings from declarations. The reasoning behind the proposal: 1. These markings are error prone and not consistently updated when new versions are released. 2. Information on which items are new can be found in the revision history chapter. Signed-off-by: Ken Raffenetti --- Chap_API_Event.tex | 6 +-- Chap_API_Fabric.tex | 82 ++++++++++++++++++------------------- Chap_API_Job_Mgmt.tex | 6 +-- Chap_API_Proc_Mgmt.tex | 76 +++++++++++++++++----------------- Chap_API_Publish.tex | 8 ++-- Chap_API_Query.tex | 34 +++++++-------- Chap_API_Reserved_Keys.tex | 22 +++++----- Chap_API_Server.tex | 36 ++++++++-------- Chap_API_Sets_Groups.tex | 68 +++++++++++++++--------------- Chap_API_Sharing_Basics.tex | 6 +-- Chap_API_Struct.tex | 68 +++++++++++++++--------------- Chap_API_Sync.tex | 4 +- Chap_API_Tools.tex | 80 ++++++++++++++++++------------------ pmix.sty | 27 ------------ 14 files changed, 248 insertions(+), 275 deletions(-) diff --git a/Chap_API_Event.tex b/Chap_API_Event.tex index 61878bfb..a3a7d4a7 100644 --- a/Chap_API_Event.tex +++ b/Chap_API_Event.tex @@ -174,10 +174,10 @@ \subsection{System events} \declareconstitemvalue{PMIX_EVENT_SYS_BASE}{-230} Mark the beginning of a dedicated range of constants for system event reporting. % -\declareconstitemvalueNEW{PMIX_EVENT_NODE_DOWN}{-231} +\declareconstitemvalue{PMIX_EVENT_NODE_DOWN}{-231} A node has gone down - the identifier of the affected node will be included in the notification. % -\declareconstitemvalueNEW{PMIX_EVENT_NODE_OFFLINE}{-232} +\declareconstitemvalue{PMIX_EVENT_NODE_OFFLINE}{-232} A node has been marked as \emph{offline} - the identifier of the affected node will be included in the notification. % \declareconstitemvalue{PMIX_EVENT_SYS_OTHER}{-330} @@ -276,7 +276,7 @@ \subsection{Event handler registration and notification attributes} Text message suitable for output by recipient - e.g., describing the cause of the event. } % -\declareAttributeNEW{PMIX_EVENT_TIMESTAMP}{"pmix.evtstamp"}{time_t}{ +\declareAttribute{PMIX_EVENT_TIMESTAMP}{"pmix.evtstamp"}{time_t}{ System time when the associated event occurred. } diff --git a/Chap_API_Fabric.tex b/Chap_API_Fabric.tex index d5c52ea0..cc007343 100644 --- a/Chap_API_Fabric.tex +++ b/Chap_API_Fabric.tex @@ -81,13 +81,13 @@ \section{Fabric Support Events} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_FABRIC_UPDATE_PENDING}{-176} +\declareconstitemvalue{PMIX_FABRIC_UPDATE_PENDING}{-176} The \ac{PMIx} server library has been alerted to a change in the fabric that requires updating of one or more registered \refstruct{pmix_fabric_t} objects. % -\declareconstitemvalueNEW{PMIX_FABRIC_UPDATED}{-175} +\declareconstitemvalue{PMIX_FABRIC_UPDATED}{-175} The \ac{PMIx} server library has completed updating the entries of all affected \refstruct{pmix_fabric_t} objects registered with the library. Access to the entries of those objects may now resume. % -\declareconstitemvalueNEW{PMIX_FABRIC_UPDATE_ENDPOINTS}{-113} +\declareconstitemvalue{PMIX_FABRIC_UPDATE_ENDPOINTS}{-113} Endpoint assignments have been updated, usually in response to migration or restart of a process. Clients should use \refapi{PMIx_Get} to update any internally cached connections. @@ -416,13 +416,13 @@ \subsection{Fabric Coordinate Views} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_COORD_VIEW_UNDEF}{0x00} +\declareconstitemvalue{PMIX_COORD_VIEW_UNDEF}{0x00} The coordinate view has not been defined. % -\declareconstitemvalueNEW{PMIX_COORD_LOGICAL_VIEW}{0x01} +\declareconstitemvalue{PMIX_COORD_LOGICAL_VIEW}{0x01} The coordinates are provided in a \emph{logical} view, typically given in Cartesian (x,y,z) dimensions, that describes the data flow in the fabric as defined by the arrangement of the hierarchical addressing scheme, fabric segmentation, routing domains, and other similar factors employed by that fabric. % -\declareconstitemvalueNEW{PMIX_COORD_PHYSICAL_VIEW}{0x02} +\declareconstitemvalue{PMIX_COORD_PHYSICAL_VIEW}{0x02} The coordinates are provided in a \emph{physical} view based on the actual wiring diagram of the fabric - i.e., values along each axis reflect the relative position of that interface on the specific fabric cabling. % \end{constantdesc} @@ -443,13 +443,13 @@ \subsection{Fabric Link State} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_LINK_STATE_UNKNOWN}{0} +\declareconstitemvalue{PMIX_LINK_STATE_UNKNOWN}{0} The port state is unknown or not applicable. % -\declareconstitemvalueNEW{PMIX_LINK_DOWN}{1} +\declareconstitemvalue{PMIX_LINK_DOWN}{1} The port is inactive. % -\declareconstitemvalueNEW{PMIX_LINK_UP}{2} +\declareconstitemvalue{PMIX_LINK_UP}{2} The port is active. % \end{constantdesc} @@ -463,10 +463,10 @@ \subsection{Fabric Operation Constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_FABRIC_REQUEST_INFO}{0} +\declareconstitemvalue{PMIX_FABRIC_REQUEST_INFO}{0} Request information on a specific fabric - if the fabric isn't specified as per \refapi{PMIx_Fabric_register}, then return information on the default fabric of the overall system. Information to be returned is described in \refstruct{pmix_fabric_t}. % -\declareconstitemvalueNEW{PMIX_FABRIC_UPDATE_INFO}{1} +\declareconstitemvalue{PMIX_FABRIC_UPDATE_INFO}{1} Update information on a specific fabric - the index of the fabric (\refattr{PMIX_FABRIC_INDEX}) to be updated must be provided. % \end{constantdesc} @@ -576,19 +576,19 @@ \section{Fabric Support Attributes} The following attributes may be returned in response to fabric-specific \acp{API} or queries (e.g., \refapi{PMIx_Get} or \refapi{PMIx_Query_info}). These attributes are not related to a specific \refterm{data realm} (as described in Section \ref{api:struct:attributes:retrieval}) - the \refapi{PMIx_Get} function shall therefore ignore the value in its \refarg{proc} process identifier argument when retrieving these values. % -\declareAttributeNEW{PMIX_FABRIC_COST_MATRIX}{"pmix.fab.cm"}{pointer}{ +\declareAttribute{PMIX_FABRIC_COST_MATRIX}{"pmix.fab.cm"}{pointer}{ Pointer to a two-dimensional square array of point-to-point relative communication costs expressed as \code{uint16_t} values. } % -\declareAttributeNEW{PMIX_FABRIC_GROUPS}{"pmix.fab.grps"}{string}{ +\declareAttribute{PMIX_FABRIC_GROUPS}{"pmix.fab.grps"}{string}{ A string delineating the group membership of nodes in the overall system, where each fabric group consists of the group number followed by a colon and a comma-delimited list of nodes in that group, with the groups delimited by semi-colons (e.g., \code{0:node000,node002,node004,node006;\allowbreak 1:node001,node003,\allowbreak node005,node007}) } % -\declareAttributeNEW{PMIX_FABRIC_PLANE}{"pmix.fab.plane"}{string}{ +\declareAttribute{PMIX_FABRIC_PLANE}{"pmix.fab.plane"}{string}{ ID string of a fabric plane (e.g., CIDR for Ethernet). When used as a modifier in a request for information, specifies the plane whose information is to be returned. When used directly as a key in a request, returns a \refstruct{pmix_data_array_t} of string identifiers for all fabric planes in the overall system. } % -\declareAttributeNEW{PMIX_FABRIC_SWITCH}{"pmix.fab.switch"}{string}{ +\declareAttribute{PMIX_FABRIC_SWITCH}{"pmix.fab.switch"}{string}{ ID string of a fabric switch. When used as a modifier in a request for information, specifies the switch whose information is to be returned. When used directly as a key in a request, returns a \refstruct{pmix_data_array_t} of string identifiers for all fabric switches in the overall system. } % @@ -596,31 +596,31 @@ \section{Fabric Support Attributes} The following attributes may be returned in response to queries (e.g., \refapi{PMIx_Get} or \refapi{PMIx_Query_info}). A qualifier (e.g., \refattr{PMIX_FABRIC_INDEX}) identifying the fabric whose value is being referenced must be provided for queries on systems supporting more than one fabric when values for the non-default fabric are requested. These attributes are not related to a specific \refterm{data realm} (as described in Section \ref{api:struct:attributes:retrieval}) - the \refapi{PMIx_Get} function shall therefore ignore the value in its \refarg{proc} process identifier argument when retrieving these values. % -\declareAttributeNEW{PMIX_FABRIC_VENDOR}{"pmix.fab.vndr"}{string}{ +\declareAttribute{PMIX_FABRIC_VENDOR}{"pmix.fab.vndr"}{string}{ Name of the vendor (e.g., Amazon, Mellanox, HPE, Intel) for the specified fabric. } % -\declareAttributeNEW{PMIX_FABRIC_IDENTIFIER}{"pmix.fab.id"}{string}{ +\declareAttribute{PMIX_FABRIC_IDENTIFIER}{"pmix.fab.id"}{string}{ An identifier for the specified fabric (e.g., MgmtEthernet, Slingshot-11, OmniPath-1). } % -\declareAttributeNEW{PMIX_FABRIC_INDEX}{"pmix.fab.idx"}{size_t}{ +\declareAttribute{PMIX_FABRIC_INDEX}{"pmix.fab.idx"}{size_t}{ The index of the fabric as returned in \refstruct{pmix_fabric_t}. } % -\declareAttributeNEW{PMIX_FABRIC_NUM_DEVICES}{"pmix.fab.nverts"}{size_t}{ +\declareAttribute{PMIX_FABRIC_NUM_DEVICES}{"pmix.fab.nverts"}{size_t}{ Total number of fabric devices in the overall system - corresponds to the number of rows or columns in the cost matrix. } % -\declareAttributeNEW{PMIX_FABRIC_DIMS}{"pmix.fab.dims"}{uint32_t}{ +\declareAttribute{PMIX_FABRIC_DIMS}{"pmix.fab.dims"}{uint32_t}{ Number of dimensions in the specified fabric plane/view. If no plane is specified in a request, then the dimensions of all planes in the overall system will be returned as a \refstruct{pmix_data_array_t} containing an array of \code{uint32_t} values. Default is to provide dimensions in \emph{logical} view. } % -\declareAttributeNEW{PMIX_FABRIC_SHAPE}{"pmix.fab.shape"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_FABRIC_SHAPE}{"pmix.fab.shape"}{pmix_data_array_t*}{ The size of each dimension in the specified fabric plane/view, returned in a \refstruct{pmix_data_array_t} containing an array of \code{uint32_t} values. The size is defined as the number of elements present in that dimension - e.g., the number of devices in one dimension of a physical view of a fabric plane. If no plane is specified, then the shape of each plane in the overall system will be returned in a \refstruct{pmix_data_array_t} array where each element is itself a two-element array containing the \refattr{PMIX_FABRIC_PLANE} followed by that plane's fabric shape. Default is to provide the shape in \emph{logical} view. } % -\declareAttributeNEW{PMIX_FABRIC_SHAPE_STRING}{"pmix.fab.shapestr"}{string}{ +\declareAttribute{PMIX_FABRIC_SHAPE_STRING}{"pmix.fab.shapestr"}{string}{ Network shape expressed as a string (e.g., \code{"10x12x2"}). If no plane is specified, then the shape of each plane in the overall system will be returned in a \refstruct{pmix_data_array_t} array where each element is itself a two-element array containing the \refattr{PMIX_FABRIC_PLANE} followed by that plane's fabric shape string. Default is to provide the shape in \emph{logical} view. } % @@ -629,71 +629,71 @@ \section{Fabric Support Attributes} The following attributes are related to the \emph{node realm} (as described in Section \ref{chap:api_rsvd_keys:nrealm}) and are retrieved according to those rules. % -\declareAttributeNEW{PMIX_FABRIC_DEVICES}{"pmix.fab.devs"}{pmix_data_array_t}{ +\declareAttribute{PMIX_FABRIC_DEVICES}{"pmix.fab.devs"}{pmix_data_array_t}{ Array of \refstruct{pmix_info_t} containing information for all devices on the specified node. Each element of the array will contain a \refattr{PMIX_FABRIC_DEVICE} entry, which in turn will contain an array of information on a given device. } % -\declareAttributeNEW{PMIX_FABRIC_COORDINATES}{"pmix.fab.coords"}{pmix_data_array_t}{ +\declareAttribute{PMIX_FABRIC_COORDINATES}{"pmix.fab.coords"}{pmix_data_array_t}{ Array of \refstruct{pmix_geometry_t} fabric coordinates for devices on the specified node. The array will contain the coordinates of all devices on the node, including values for all supported coordinate views. The information for devices on the local node shall be provided if the node is not specified in the request. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE}{"pmix.fabdev"}{\refstruct{pmix_data_array_t}}{ +\declareAttribute{PMIX_FABRIC_DEVICE}{"pmix.fabdev"}{\refstruct{pmix_data_array_t}}{ An array of \refstruct{pmix_info_t} describing a particular fabric device using one or more of the attributes defined below. The first element in the array shall be the \refattr{PMIX_DEVICE_ID} of the device. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_INDEX}{"pmix.fabdev.idx"}{uint32_t}{ +\declareAttribute{PMIX_FABRIC_DEVICE_INDEX}{"pmix.fabdev.idx"}{uint32_t}{ Index of the device within an associated communication cost matrix. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_NAME}{"pmix.fabdev.nm"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_NAME}{"pmix.fabdev.nm"}{string}{ The operating system name associated with the device. This may be a logical fabric interface name (e.g. "eth0" or "eno1") or an absolute filename. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_VENDOR}{"pmix.fabdev.vndr"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_VENDOR}{"pmix.fabdev.vndr"}{string}{ Indicates the name of the vendor that distributes the device. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_BUS_TYPE}{"pmix.fabdev.btyp"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_BUS_TYPE}{"pmix.fabdev.btyp"}{string}{ The type of bus to which the device is attached (e.g., "PCI", "GEN-Z"). } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_VENDORID}{"pmix.fabdev.vendid"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_VENDORID}{"pmix.fabdev.vendid"}{string}{ This is a vendor-provided identifier for the device or product. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_DRIVER}{"pmix.fabdev.driver"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_DRIVER}{"pmix.fabdev.driver"}{string}{ The name of the driver associated with the device. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_FIRMWARE}{"pmix.fabdev.fmwr"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_FIRMWARE}{"pmix.fabdev.fmwr"}{string}{ The device’s firmware version. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_ADDRESS}{"pmix.fabdev.addr"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_ADDRESS}{"pmix.fabdev.addr"}{string}{ The primary link-level address associated with the device, such as a \ac{MAC} address. If multiple addresses are available, only one will be reported. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_COORDINATES}{"pmix.fab.coord"}{pmix_geometry_t}{ +\declareAttribute{PMIX_FABRIC_DEVICE_COORDINATES}{"pmix.fab.coord"}{pmix_geometry_t}{ The \refstruct{pmix_geometry_t} fabric coordinates for the device, including values for all supported coordinate views. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_MTU}{"pmix.fabdev.mtu"}{size_t}{ +\declareAttribute{PMIX_FABRIC_DEVICE_MTU}{"pmix.fabdev.mtu"}{size_t}{ The maximum transfer unit of link level frames or packets, in bytes. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_SPEED}{"pmix.fabdev.speed"}{size_t}{ +\declareAttribute{PMIX_FABRIC_DEVICE_SPEED}{"pmix.fabdev.speed"}{size_t}{ The active link data rate, given in bits per second. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_STATE}{"pmix.fabdev.state"}{\refstruct{pmix_link_state_t}}{ +\declareAttribute{PMIX_FABRIC_DEVICE_STATE}{"pmix.fabdev.state"}{\refstruct{pmix_link_state_t}}{ The last available physical port state for the specified device. Possible values are \refconst{PMIX_LINK_STATE_UNKNOWN}, \refconst{PMIX_LINK_DOWN}, and \refconst{PMIX_LINK_UP}, to indicate if the port state is unknown or not applicable (unknown), inactive (down), or active (up). } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_TYPE}{"pmix.fabdev.type"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_TYPE}{"pmix.fabdev.type"}{string}{ Specifies the type of fabric interface currently active on the device, such as Ethernet or InfiniBand. } % -\declareAttributeNEW{PMIX_FABRIC_DEVICE_PCI_DEVID}{"pmix.fabdev.pcidevid"}{string}{ +\declareAttribute{PMIX_FABRIC_DEVICE_PCI_DEVID}{"pmix.fabdev.pcidevid"}{string}{ A node-level unique identifier for a \ac{PCI} device. Provided only if the device is located on a \ac{PCI} bus. The identifier is constructed as a four-part tuple delimited by colons comprised of the \ac{PCI} 16-bit domain, 8-bit bus, 8-bit device, and 8-bit function IDs, each expressed in zero-extended hexadecimal form. Thus, an example identifier might be "abc1:0f:23:01". The combination of node identifier (\refattr{PMIX_HOSTNAME} or \refattr{PMIX_NODEID}) and \refattr{PMIX_FABRIC_DEVICE_PCI_DEVID} shall be unique within the overall system. } % @@ -701,7 +701,7 @@ \section{Fabric Support Attributes} The following attributes are related to the \emph{process realm} (as described in Section \ref{chap:api_rsvd_keys:prealm}) and are retrieved according to those rules. % -\declareAttributeNEW{PMIX_FABRIC_ENDPT}{"pmix.fab.endpt"}{pmix_data_array_t}{ +\declareAttribute{PMIX_FABRIC_ENDPT}{"pmix.fab.endpt"}{pmix_data_array_t}{ Fabric endpoints for a specified process. As multiple endpoints may be assigned to a given process (e.g., in the case where multiple devices are associated with a package to which the process is bound), the returned values will be provided in a \refstruct{pmix_data_array_t} of \refstruct{pmix_endpoint_t} elements. } % @@ -709,7 +709,7 @@ \section{Fabric Support Attributes} The following attributes are related to the \emph{job realm} (as described in Section \ref{chap:api_rsvd_keys:jrealm}) and are retrieved according to those rules. Note that distances to fabric devices are retrieved using the \refattr{PMIX_DEVICE_DISTANCES} key with the appropriate \refstruct{pmix_device_type_t} qualifier. % -\declareAttributeNEW{PMIX_SWITCH_PEERS}{"pmix.speers"}{pmix_data_array_t}{ +\declareAttribute{PMIX_SWITCH_PEERS}{"pmix.speers"}{pmix_data_array_t}{ Peer ranks that share the same switch as the process specified in the call to \refapi{PMIx_Get}. Returns a \refstruct{pmix_data_array_t} array of \refstruct{pmix_info_t} results, each element containing the \refattr{PMIX_SWITCH_PEERS} key with a three-element \refstruct{pmix_data_array_t} array of \refstruct{pmix_info_t} containing the \refattr{PMIX_DEVICE_ID} of the local fabric device, the \refattr{PMIX_FABRIC_SWITCH} identifying the switch to which it is connected, and a comma-delimited string of peer ranks sharing the switch to which that device is connected. } diff --git a/Chap_API_Job_Mgmt.tex b/Chap_API_Job_Mgmt.tex index df1416a2..27b1aa1d 100644 --- a/Chap_API_Job_Mgmt.tex +++ b/Chap_API_Job_Mgmt.tex @@ -189,11 +189,11 @@ \subsection{Job Allocation attributes} User-provided string identifier for this allocation request which can later be used to query status of the request. } % -\declareAttributeNEW{PMIX_ALLOC_ID}{"pmix.alloc.id"}{char*}{ +\declareAttribute{PMIX_ALLOC_ID}{"pmix.alloc.id"}{char*}{ A string identifier (provided by the host environment) for the resulting allocation which can later be used to reference the allocated resources in, for example, a call to \refapi{PMIx_Spawn}. } % -\declareAttributeNEW{PMIX_ALLOC_QUEUE}{"pmix.alloc.queue"}{char*}{ +\declareAttribute{PMIX_ALLOC_QUEUE}{"pmix.alloc.queue"}{char*}{ Name of the \ac{WLM} queue to which the allocation request is to be directed, or the queue being referenced in a query. } % @@ -477,7 +477,7 @@ \subsection{Job control constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_ERR_CONFLICTING_CLEANUP_DIRECTIVES}{-51} +\declareconstitemvalue{PMIX_ERR_CONFLICTING_CLEANUP_DIRECTIVES}{-51} Conflicting directives given for job/process cleanup. \end{constantdesc} diff --git a/Chap_API_Proc_Mgmt.tex b/Chap_API_Proc_Mgmt.tex index b1eb1bff..a7898d47 100644 --- a/Chap_API_Proc_Mgmt.tex +++ b/Chap_API_Proc_Mgmt.tex @@ -311,19 +311,19 @@ \subsection{Spawn-specific constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_ERR_JOB_ALLOC_FAILED}{-188} +\declareconstitemvalue{PMIX_ERR_JOB_ALLOC_FAILED}{-188} The job request could not be executed due to failure to obtain the specified allocation % -\declareconstitemvalueNEW{PMIX_ERR_JOB_APP_NOT_EXECUTABLE}{-177} +\declareconstitemvalue{PMIX_ERR_JOB_APP_NOT_EXECUTABLE}{-177} The specified application executable either could not be found, or lacks execution privileges. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_NO_EXE_SPECIFIED}{-178} +\declareconstitemvalue{PMIX_ERR_JOB_NO_EXE_SPECIFIED}{-178} The job request did not specify an executable. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_FAILED_TO_MAP}{-179} +\declareconstitemvalue{PMIX_ERR_JOB_FAILED_TO_MAP}{-179} The launcher was unable to map the processes for the specified job request. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_FAILED_TO_LAUNCH}{-181} +\declareconstitemvalue{PMIX_ERR_JOB_FAILED_TO_LAUNCH}{-181} One or more processes in the job request failed to launch % \declareconstitemProvisional{PMIX_ERR_JOB_EXE_NOT_FOUND} @@ -427,7 +427,7 @@ \subsection{Spawn attributes} Direct output (both stdout and stderr) into files of form \code{".rank"} - can be assigned to the entire job (by including attribute in the \refarg{job_info} array) or on a per-application basis in the \refarg{info} array for each \refstruct{pmix_app_t}. } % -\declareAttributeNEW{PMIX_OUTPUT_TO_DIRECTORY}{"pmix.outdir"}{char*}{ +\declareAttribute{PMIX_OUTPUT_TO_DIRECTORY}{"pmix.outdir"}{char*}{ Direct output into files of form \code{"/\allowbreak /\allowbreak rank./\allowbreak stdout[err]"} - can be assigned to the entire job (by including attribute in the \refarg{job_info} array) or on a per-application basis in the \refarg{info} array for each \refstruct{pmix_app_t}. } % @@ -471,15 +471,15 @@ \subsection{Spawn attributes} Indicate that the job being spawned is a tool. } % -\declareAttributeNEW{PMIX_TIMEOUT_STACKTRACES}{"pmix.tim.stack"}{bool}{ +\declareAttribute{PMIX_TIMEOUT_STACKTRACES}{"pmix.tim.stack"}{bool}{ Include process stacktraces in timeout report from a job. } % -\declareAttributeNEW{PMIX_TIMEOUT_REPORT_STATE}{"pmix.tim.state"}{bool}{ +\declareAttribute{PMIX_TIMEOUT_REPORT_STATE}{"pmix.tim.state"}{bool}{ Report process states in timeout report from a job. } % -\declareAttributeNEW{PMIX_NOTIFY_JOB_EVENTS}{"pmix.note.jev"}{bool}{ +\declareAttribute{PMIX_NOTIFY_JOB_EVENTS}{"pmix.note.jev"}{bool}{ Requests that the launcher generate the \refconst{PMIX_EVENT_JOB_START}, \refconst{PMIX_LAUNCH_COMPLETE}, and \refconst{PMIX_EVENT_JOB_END} events. Each event is to include at least the @@ -504,34 +504,34 @@ \subsection{Spawn attributes} within a default event handler. } % -\declareAttributeNEW{PMIX_NOTIFY_PROC_TERMINATION}{"pmix.noteproc"}{bool}{ +\declareAttribute{PMIX_NOTIFY_PROC_TERMINATION}{"pmix.noteproc"}{bool}{ Requests that the launcher generate the \refconst{PMIX_EVENT_PROC_TERMINATED} event whenever a process either normally or abnormally terminates. } % -\declareAttributeNEW{PMIX_NOTIFY_PROC_ABNORMAL_TERMINATION}{"pmix.noteabproc"}{bool}{ +\declareAttribute{PMIX_NOTIFY_PROC_ABNORMAL_TERMINATION}{"pmix.noteabproc"}{bool}{ Requests that the launcher generate the \refconst{PMIX_EVENT_PROC_TERMINATED} event only when a process abnormally terminates. } % -\declareAttributeNEW{PMIX_LOG_PROC_TERMINATION}{"pmix.logproc"}{bool}{ +\declareAttribute{PMIX_LOG_PROC_TERMINATION}{"pmix.logproc"}{bool}{ Requests that the launcher log the \refconst{PMIX_EVENT_PROC_TERMINATED} event whenever a process either normally or abnormally terminates. } % -\declareAttributeNEW{PMIX_LOG_PROC_ABNORMAL_TERMINATION}{"pmix.logabproc"}{bool}{ +\declareAttribute{PMIX_LOG_PROC_ABNORMAL_TERMINATION}{"pmix.logabproc"}{bool}{ Requests that the launcher log the \refconst{PMIX_EVENT_PROC_TERMINATED} event only when a process abnormally terminates. } % -\declareAttributeNEW{PMIX_LOG_JOB_EVENTS}{"pmix.log.jev"}{bool}{ +\declareAttribute{PMIX_LOG_JOB_EVENTS}{"pmix.log.jev"}{bool}{ Requests that the launcher log the \refconst{PMIX_EVENT_JOB_START}, \refconst{PMIX_LAUNCH_COMPLETE}, and \refconst{PMIX_EVENT_JOB_END} events using \refapi{PMIx_Log}, subject to the logging attributes of Section \ref{api:struct:attributes:log}. } % -\declareAttributeNEW{PMIX_LOG_COMPLETION}{"pmix.logcomp"}{bool}{ +\declareAttribute{PMIX_LOG_COMPLETION}{"pmix.logcomp"}{bool}{ Requests that the launcher log the \refconst{PMIX_EVENT_JOB_END} event for normal or abnormal termination of the spawned job using \refapi{PMIx_Log}, subject to the logging attributes of Section @@ -586,7 +586,7 @@ \subsection{Spawn attributes} Append the given value to the specified environmental value using the given separator character, creating the variable if it doesn't already exist } % -\declareAttributeNEW{PMIX_FIRST_ENVAR}{"pmix.envar.first"}{pmix_envar_t*}{ +\declareAttribute{PMIX_FIRST_ENVAR}{"pmix.envar.first"}{pmix_envar_t*}{ Ensure the given value appears first in the specified envar using the separator character, creating the envar if it doesn't already exist } @@ -1242,34 +1242,34 @@ \subsubsection{Relative locality of two processes} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_LOCALITY_UNKNOWN}{0x0000} +\declareconstitemvalue{PMIX_LOCALITY_UNKNOWN}{0x0000} All bits are set to zero, indicating that the relative locality of the two processes is unknown % -\declareconstitemvalueNEW{PMIX_LOCALITY_NONLOCAL}{0x0000} +\declareconstitemvalue{PMIX_LOCALITY_NONLOCAL}{0x0000} The two processes do not share any common locations % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_HWTHREAD}{0x0001} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_HWTHREAD}{0x0001} The two processes share at least one hardware thread % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_CORE}{0x0002} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_CORE}{0x0002} The two processes share at least one core % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_L1CACHE}{0x0004} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_L1CACHE}{0x0004} The two processes share at least an L1 cache % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_L2CACHE}{0x0008} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_L2CACHE}{0x0008} The two processes share at least an L2 cache % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_L3CACHE}{0x0010} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_L3CACHE}{0x0010} The two processes share at least an L3 cache % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_PACKAGE}{0x0020} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_PACKAGE}{0x0020} The two processes share at least a package % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_NUMA}{0x0040} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_NUMA}{0x0040} The two processes share at least one \ac{NUMA} region % -\declareconstitemvalueNEW{PMIX_LOCALITY_SHARE_NODE}{0x4000} +\declareconstitemvalue{PMIX_LOCALITY_SHARE_NODE}{0x4000} The two processes are executing on the same node % \end{constantdesc} @@ -1368,10 +1368,10 @@ \subsubsection{Binding envelope} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_CPUBIND_PROCESS}{0} +\declareconstitemvalue{PMIX_CPUBIND_PROCESS}{0} Use the location of all threads in the possibly multi-threaded process. % -\declareconstitemvalueNEW{PMIX_CPUBIND_THREAD}{1} +\declareconstitemvalue{PMIX_CPUBIND_THREAD}{1} Use only the location of the thread calling the \ac{API}. % \end{constantdesc} @@ -1512,25 +1512,25 @@ \subsection{Device type} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_DEVTYPE_UNKNOWN}{0x00} +\declareconstitemvalue{PMIX_DEVTYPE_UNKNOWN}{0x00} The device is of an unknown type - will not be included in returned device distances. % -\declareconstitemvalueNEW{PMIX_DEVTYPE_BLOCK}{0x01} +\declareconstitemvalue{PMIX_DEVTYPE_BLOCK}{0x01} Operating system block device, or non-volatile memory device (e.g., "sda" or "dax2.0" on Linux). % -\declareconstitemvalueNEW{PMIX_DEVTYPE_GPU}{0x02} +\declareconstitemvalue{PMIX_DEVTYPE_GPU}{0x02} Operating system \ac{GPU} device (e.g., "card0" for a Linux \ac{DRM} device). % -\declareconstitemvalueNEW{PMIX_DEVTYPE_NETWORK}{0x04} +\declareconstitemvalue{PMIX_DEVTYPE_NETWORK}{0x04} Operating system network device (e.g., the "eth0" interface on Linux). % -\declareconstitemvalueNEW{PMIX_DEVTYPE_OPENFABRICS}{0x08} +\declareconstitemvalue{PMIX_DEVTYPE_OPENFABRICS}{0x08} Operating system OpenFabrics device (e.g., an "mlx4_0" InfiniBand \ac{HCA}, or "hfi1_0" Omni-Path interface on Linux). % -\declareconstitemvalueNEW{PMIX_DEVTYPE_DMA}{0x10} +\declareconstitemvalue{PMIX_DEVTYPE_DMA}{0x10} Operating system \ac{DMA} engine device (e.g., the "dma0chan0" \ac{DMA} channel on Linux). % -\declareconstitemvalueNEW{PMIX_DEVTYPE_COPROC}{0x20} +\declareconstitemvalue{PMIX_DEVTYPE_COPROC}{0x20} Operating system co-processor device (e.g., "mic0" for a Xeon Phi on Linux, "opencl0d0" for a OpenCL device, or "cuda0" for a \ac{CUDA} device). % \end{constantdesc} @@ -1644,15 +1644,15 @@ \subsection{Device distance attributes} The following attributes can be used to retrieve device distances from the \ac{PMIx} data store. Note that distances stored by the host environment are based on the process location at the time of start of execution and may not reflect changes to location imposed by the process itself. % -\declareAttributeNEW{PMIX_DEVICE_DISTANCES}{"pmix.dev.dist"}{pmix_data_array_t}{ +\declareAttribute{PMIX_DEVICE_DISTANCES}{"pmix.dev.dist"}{pmix_data_array_t}{ Return an array of \refstruct{pmix_device_distance_t} containing the minimum and maximum distances of the given process location to all devices of the specified type on the local node. } % -\declareAttributeNEW{PMIX_DEVICE_TYPE}{"pmix.dev.type"}{pmix_device_type_t}{ +\declareAttribute{PMIX_DEVICE_TYPE}{"pmix.dev.type"}{pmix_device_type_t}{ Bitmask specifying the type(s) of device(s) whose information is being requested. Only used as a directive/qualifier. } % -\declareAttributeNEW{PMIX_DEVICE_ID}{"pmix.dev.id"}{string}{ +\declareAttribute{PMIX_DEVICE_ID}{"pmix.dev.id"}{string}{ System-wide \ac{UUID} or node-local \ac{OS} name of a particular device. } diff --git a/Chap_API_Publish.tex b/Chap_API_Publish.tex index 894c57b7..6d802baa 100644 --- a/Chap_API_Publish.tex +++ b/Chap_API_Publish.tex @@ -141,7 +141,7 @@ \section{Publish-specific constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_ERR_DUPLICATE_KEY}{-53} +\declareconstitemvalue{PMIX_ERR_DUPLICATE_KEY}{-53} The provided key has already been published on the same data range. % \end{constantdesc} @@ -162,15 +162,15 @@ \section{Publish-specific attributes} Declare how long the datastore shall retain the provided data. The datastore is to delete the data upon reaching the persistence criterion. } % -\declareAttributeNEW{PMIX_ACCESS_PERMISSIONS}{"pmix.aperms"}{pmix_data_array_t}{ +\declareAttribute{PMIX_ACCESS_PERMISSIONS}{"pmix.aperms"}{pmix_data_array_t}{ Define access permissions for the published data. The value shall contain an array of \refstruct{pmix_info_t} structs containing the specified permissions. } % -\declareAttributeNEW{PMIX_ACCESS_USERIDS}{"pmix.auids"}{pmix_data_array_t}{ +\declareAttribute{PMIX_ACCESS_USERIDS}{"pmix.auids"}{pmix_data_array_t}{ Array of effective \acp{UID} that are allowed to access the published data. } % -\declareAttributeNEW{PMIX_ACCESS_GRPIDS}{"pmix.agids"}{pmix_data_array_t}{ +\declareAttribute{PMIX_ACCESS_GRPIDS}{"pmix.agids"}{pmix_data_array_t}{ Array of effective \acp{GID} that are allowed to access the published data. } diff --git a/Chap_API_Query.tex b/Chap_API_Query.tex index aa1190a5..e3376df0 100644 --- a/Chap_API_Query.tex +++ b/Chap_API_Query.tex @@ -292,7 +292,7 @@ \subsection{Query keys} Returns comma-delimited list of keys supported by the query function. NO QUALIFIERS. } % -\declareAttributeNEW{PMIX_QUERY_SUPPORTED_QUALIFIERS}{"pmix.qry.quals"}{char*}{ +\declareAttribute{PMIX_QUERY_SUPPORTED_QUALIFIERS}{"pmix.qry.quals"}{char*}{ Return comma-delimited list of qualifiers supported by a query on the provided key, instead of actually performing the query on the key. NO QUALIFIERS. } % @@ -300,7 +300,7 @@ \subsection{Query keys} Request a comma-delimited list of active namespaces. NO QUALIFIERS. } % -\declareAttributeNEW{PMIX_QUERY_NAMESPACE_INFO}{"pmix.qry.nsinfo"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_QUERY_NAMESPACE_INFO}{"pmix.qry.nsinfo"}{pmix_data_array_t*}{ Return an array of active namespace information - each element will itself contain an array including the namespace plus the command line of the application executing within it. OPTIONAL QUALIFIERS: \refattr{PMIX_NSPACE} of specific namespace whose info is being requested. } % @@ -340,7 +340,7 @@ \subsection{Query keys} Query number of seconds (\code{uint32_t}) remaining in allocation for the specified namespace. OPTIONAL QUALIFIERS: \refattr{PMIX_NSPACE} of the namespace whose info is being requested (defaults to allocation containing the caller). } % -\declareAttributeNEW{PMIX_QUERY_ATTRIBUTE_SUPPORT}{"pmix.qry.attrs"}{bool}{ +\declareAttribute{PMIX_QUERY_ATTRIBUTE_SUPPORT}{"pmix.qry.attrs"}{bool}{ Query list of supported attributes for specified \acp{API}. REQUIRED QUALIFIERS: one or more of \refattr{PMIX_CLIENT_FUNCTIONS}, \refattr{PMIX_SERVER_FUNCTIONS}, \refattr{PMIX_TOOL_FUNCTIONS}, and \refattr{PMIX_HOST_FUNCTIONS}. } % @@ -350,17 +350,17 @@ \subsection{Query keys} % \pasteAttributeItem{PMIX_QUERY_PSET_MEMBERSHIP} % -\declareAttributeNEW{PMIX_QUERY_AVAIL_SERVERS}{"pmix.qry.asrvrs"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_QUERY_AVAIL_SERVERS}{"pmix.qry.asrvrs"}{pmix_data_array_t*}{ Return an array of \refstruct{pmix_info_t}, each element itself containing a \refattr{PMIX_SERVER_INFO_ARRAY} entry holding all available data for a server on this node to which the caller might be able to connect. } % -\declareAttributeNEW{PMIX_QUERY_STABLE_ABI_VERSION}{"pmix.qry.stabiver"}{char *}{ +\declareAttribute{PMIX_QUERY_STABLE_ABI_VERSION}{"pmix.qry.stabiver"}{char *}{ Query the PMIx Standard Stable \ac{ABI} version(s) supported by the \ac{PMIx} library. The version returned will be of the form \code{"MAJOR.MINOR"}. If multiple versions are supported then a comma-separated list of version numbers will be returned. See Section~\ref{chap:intro:abi:versioning} for versioning advice. NO QUALIFIERS. } % -\declareAttributeNEW{PMIX_QUERY_PROVISIONAL_ABI_VERSION}{"pmix.qry.prabiver"}{char *}{ +\declareAttribute{PMIX_QUERY_PROVISIONAL_ABI_VERSION}{"pmix.qry.prabiver"}{char *}{ Query the PMIx Standard Provisional \ac{ABI} version(s) supported by the \ac{PMIx} library. The version returned will be of the form \code{"MAJOR.MINOR"}. If multiple versions are supported then a comma-separated list of version numbers will be returned. See Section~\ref{chap:intro:abi:versioning} for versioning advice. NO QUALIFIERS. @@ -387,11 +387,11 @@ \subsection{Query attributes} Attributes used to direct behavior of the \refapi{PMIx_Query_info} and \refapi{PMIx_Query_info_nb} \acp{API}: -\declareAttributeNEW{PMIX_QUERY_RESULTS}{"pmix.qry.res"}{pmix_data_array_t}{ +\declareAttribute{PMIX_QUERY_RESULTS}{"pmix.qry.res"}{pmix_data_array_t}{ Contains an array of query results for a given \refstruct{pmix_query_t} passed to the \refapi{PMIx_Query_info} \acp{API}. If qualifiers were included in the query, then the first element of the array shall be the \refattr{PMIX_QUERY_QUALIFIERS} attribute containing those qualifiers. Each of the remaining elements of the array is a \refstruct{pmix_info_t} containing the query key and the corresponding value returned by the query. This attribute is solely for reporting purposes and cannot be used in \refapi{PMIx_Get} or other query operations. } % -\declareAttributeNEW{PMIX_QUERY_QUALIFIERS}{"pmix.qry.quals"}{pmix_data_array_t}{ +\declareAttribute{PMIX_QUERY_QUALIFIERS}{"pmix.qry.quals"}{pmix_data_array_t}{ Contains an array of qualifiers that were included in the query that produced the provided results. This attribute is solely for reporting purposes and cannot be used in \refapi{PMIx_Get} or other query operations. } % @@ -415,41 +415,41 @@ \subsection{Query attributes} String identifier of the allocation whose status is being requested. NO QUALIFIERS. } % -\declareAttributeNEW{PMIX_SERVER_INFO_ARRAY}{"pmix.srv.arr"}{pmix_data_array_t}{ +\declareAttribute{PMIX_SERVER_INFO_ARRAY}{"pmix.srv.arr"}{pmix_data_array_t}{ Array of \refstruct{pmix_info_t} about a given server, starting with its \refattr{PMIX_NSPACE} and including at least one of the rendezvous-required pieces of information. } \vspace{\baselineskip} The following attributes are used as qualifiers in queries regarding attribute support within the \ac{PMIx} implementation and/or the host environment: % -\declareAttributeNEW{PMIX_CLIENT_FUNCTIONS}{"pmix.client.fns"}{bool}{ +\declareAttribute{PMIX_CLIENT_FUNCTIONS}{"pmix.client.fns"}{bool}{ Request a list of functions supported by the \ac{PMIx} client library. } % -\declareAttributeNEW{PMIX_CLIENT_ATTRIBUTES}{"pmix.client.attrs"}{bool}{ +\declareAttribute{PMIX_CLIENT_ATTRIBUTES}{"pmix.client.attrs"}{bool}{ Request attributes supported by the \ac{PMIx} client library. } % -\declareAttributeNEW{PMIX_SERVER_FUNCTIONS}{"pmix.srvr.fns"}{bool}{ +\declareAttribute{PMIX_SERVER_FUNCTIONS}{"pmix.srvr.fns"}{bool}{ Request a list of functions supported by the \ac{PMIx} server library. } % -\declareAttributeNEW{PMIX_SERVER_ATTRIBUTES}{"pmix.srvr.attrs"}{bool}{ +\declareAttribute{PMIX_SERVER_ATTRIBUTES}{"pmix.srvr.attrs"}{bool}{ Request attributes supported by the \ac{PMIx} server library. } % -\declareAttributeNEW{PMIX_HOST_FUNCTIONS}{"pmix.srvr.fns"}{bool}{ +\declareAttribute{PMIX_HOST_FUNCTIONS}{"pmix.srvr.fns"}{bool}{ Request a list of functions supported by the host environment. } % -\declareAttributeNEW{PMIX_HOST_ATTRIBUTES}{"pmix.host.attrs"}{bool}{ +\declareAttribute{PMIX_HOST_ATTRIBUTES}{"pmix.host.attrs"}{bool}{ Request attributes supported by the host environment. } % -\declareAttributeNEW{PMIX_TOOL_FUNCTIONS}{"pmix.tool.fns"}{bool}{ +\declareAttribute{PMIX_TOOL_FUNCTIONS}{"pmix.tool.fns"}{bool}{ Request a list of functions supported by the \ac{PMIx} tool library. } % -\declareAttributeNEW{PMIX_TOOL_ATTRIBUTES}{"pmix.setup.env"}{bool}{ +\declareAttribute{PMIX_TOOL_ATTRIBUTES}{"pmix.setup.env"}{bool}{ Request attributes supported by the \ac{PMIx} tool library functions. } diff --git a/Chap_API_Reserved_Keys.tex b/Chap_API_Reserved_Keys.tex index 8aabc29d..128db089 100644 --- a/Chap_API_Reserved_Keys.tex +++ b/Chap_API_Reserved_Keys.tex @@ -122,7 +122,7 @@ \subsection{Session realm attributes} \refattr{PMIX_TMPDIR}. } % -\declareAttributeNEW{PMIX_HOSTNAME_KEEP_FQDN}{"pmix.fqdn"}{bool}{ +\declareAttribute{PMIX_HOSTNAME_KEEP_FQDN}{"pmix.fqdn"}{bool}{ \acp{FQDN} are being retained by the \ac{PMIx} library. } % @@ -143,7 +143,7 @@ \subsection{Session realm attributes} Comma-delimited list or regular expression of all nodes in the specified realm regardless of whether or not they currently host processes. Defaults to the \refterm{job} realm. } % -\declareAttributeNEW{PMIX_NUM_ALLOCATED_NODES}{"pmix.num.anodes"}{uint32_t}{ +\declareAttribute{PMIX_NUM_ALLOCATED_NODES}{"pmix.num.anodes"}{uint32_t}{ Number of nodes in the specified realm regardless of whether or not they currently host processes. Defaults to the \refterm{job} realm. } % @@ -163,7 +163,7 @@ \subsection{Session realm attributes} it is included in the \ac{PMIx} Standard for historical reasons. Defaults to the \refterm{job} realm. } % -\declareAttributeNEW{PMIX_NUM_NODES}{"pmix.num.nodes"}{uint32_t}{ +\declareAttribute{PMIX_NUM_NODES}{"pmix.num.nodes"}{uint32_t}{ Number of nodes currently hosting processes in the specified realm. Defaults to the \refterm{job} realm. } @@ -172,7 +172,7 @@ \subsection{Session realm attributes} Regular expression of nodes currently hosting processes in the specified realm - see \ref{cptr:api_server:noderegex} for an explanation of its generation. Defaults to the \refterm{job} realm. } % -\declareAttributeNEW{PMIX_NODE_MAP_RAW}{"pmix.nmap.raw"}{char*}{ +\declareAttribute{PMIX_NODE_MAP_RAW}{"pmix.nmap.raw"}{char*}{ Comma-delimited list of nodes containing procs within the specified realm. Defaults to the \refterm{job} realm. } % @@ -180,7 +180,7 @@ \subsection{Session realm attributes} Regular expression describing processes on each node in the specified realm - see \ref{cptr:api_server:ppnregex} for an explanation of its generation. Defaults to the \refterm{job} realm. } % -\declareAttributeNEW{PMIX_PROC_MAP_RAW}{"pmix.pmap.raw"}{char*}{ +\declareAttribute{PMIX_PROC_MAP_RAW}{"pmix.pmap.raw"}{char*}{ Semi-colon delimited list of strings, each string containing a comma-delimited list of ranks on the corresponding node within the specified realm. Defaults to the \refterm{job} realm. } % @@ -254,7 +254,7 @@ \subsection{Job realm attributes} process mapping in Argonne National Laboratory's PMI-1/PMI-2 notation of the processes in the specified job. \pasteAttributeItemEnd{} % -\declareAttributeNEW{PMIX_CMD_LINE}{"pmix.cmd.line"}{char*}{ +\declareAttribute{PMIX_CMD_LINE}{"pmix.cmd.line"}{char*}{ Command line used to execute the specified job (e.g., "mpirun -n 2 --map-by foo ./myapp : -n 4 ./myapp2"). If the job was created by a call to \refapi{PMIx_Spawn}, the string is an inorder concatenation of the @@ -325,7 +325,7 @@ \subsection{Application realm attributes} Number of processes in the specified application, regardless of their execution state - i.e., this number may include processes that either failed to start or have already terminated. } % -\declareAttributeNEW{PMIX_APP_ARGV}{"pmix.app.argv"}{char*}{ +\declareAttribute{PMIX_APP_ARGV}{"pmix.app.argv"}{char*}{ Consolidated argv passed to the spawn command for the given application (e.g., "./myapp arg1 arg2 arg3"). } % @@ -445,7 +445,7 @@ \subsection{Process realm attributes} Rank of the specified process on its node spanning all jobs- refers to the numerical location (starting from zero) of the process on its node when counting all processes (regardless of job) that share the node, ordered by their overall rank within the job. The value represents a snapshot in time when the specified process was started on its node and is not dynamically adjusted as processes from other jobs are started or terminated on the node. } % -\declareAttributeNEW{PMIX_PACKAGE_RANK}{"pmix.pkgrank"}{uint16_t}{ +\declareAttribute{PMIX_PACKAGE_RANK}{"pmix.pkgrank"}{uint16_t}{ Rank of the specified process on the \refterm{package} where this process resides - refers to the numerical location (starting from zero) of the process on its package when counting only those processes from the same job that share the package, ordered by their overall rank within that job. Note that processes that are not bound to \acp{PU} within a single specific package cannot have a package rank. } % @@ -461,7 +461,7 @@ \subsection{Process realm attributes} A string representation of the \ac{PU} binding bitmap applied to the process upon launch. The string shall begin with the name of the library that generated it (e.g., "hwloc") followed by a colon and the bitmap string itself. } % -\declareAttributeNEW{PMIX_CPUSET_BITMAP}{"pmix.bitmap"}{pmix_cpuset_t*}{ +\declareAttribute{PMIX_CPUSET_BITMAP}{"pmix.bitmap"}{pmix_cpuset_t*}{ Bitmap applied to the process upon launch. } % @@ -473,7 +473,7 @@ \subsection{Process realm attributes} \code{true} if this process resulted from a call to \refapi{PMIx_Spawn}. Lack of inclusion (i.e., a return status of \refconst{PMIX_ERR_NOT_FOUND}) corresponds to a value of \code{false} for this attribute. } % -\declareAttributeNEW{PMIX_REINCARNATION}{"pmix.reinc"}{uint32_t}{ +\declareAttribute{PMIX_REINCARNATION}{"pmix.reinc"}{uint32_t}{ Number of times this process has been re-instantiated - i.e, a value of zero indicates that the process has never been restarted. } @@ -506,7 +506,7 @@ \subsection{Node realm keys} Name of the host, as returned by the \code{gethostname} utility or its equivalent. } % -\declareAttributeNEW{PMIX_HOSTNAME_ALIASES}{"pmix.alias"}{char*}{ +\declareAttribute{PMIX_HOSTNAME_ALIASES}{"pmix.alias"}{char*}{ Comma-delimited list of names by which the target node is known. } % diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index c087932e..0b26eba3 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -153,12 +153,12 @@ \subsection{Server Initialization Attributes} These attributes are used to direct the configuration and operation of the \ac{PMIx} server library by passing them into \refapi{PMIx_server_init}. % -\declareAttributeNEW{PMIX_TOPOLOGY2}{"pmix.topo2"}{pmix_topology_t}{ +\declareAttribute{PMIX_TOPOLOGY2}{"pmix.topo2"}{pmix_topology_t}{ Provide a pointer to an implementation-specific description of the local node topology. } % -\declareAttributeNEW{PMIX_SERVER_SHARE_TOPOLOGY}{"pmix.srvr.share"}{bool}{ +\declareAttribute{PMIX_SERVER_SHARE_TOPOLOGY}{"pmix.srvr.share"}{bool}{ The \ac{PMIx} server is to share its copy of the local node topology (whether given to it or self-discovered) with any clients. } % @@ -186,11 +186,11 @@ \subsection{Server Initialization Attributes} The host \ac{RM} wants to declare itself as being the local system server for PMIx connection requests. } % -\declareAttributeNEW{PMIX_SERVER_SESSION_SUPPORT}{"pmix.srvr.sess"}{bool}{ +\declareAttribute{PMIX_SERVER_SESSION_SUPPORT}{"pmix.srvr.sess"}{bool}{ The host \ac{RM} wants to declare itself as being the local session server for PMIx connection requests. } % -\declareAttributeNEW{PMIX_SERVER_START_TIME}{"pmix.srvr.strtime"}{char*}{ +\declareAttribute{PMIX_SERVER_START_TIME}{"pmix.srvr.strtime"}{char*}{ Time when the server started - i.e., when the server created it's rendezvous file (given in ctime string format). } % @@ -218,15 +218,15 @@ \subsection{Server Initialization Attributes} Server is acting as a gateway for PMIx requests that cannot be serviced on backend nodes (e.g., logging to email). } % -\declareAttributeNEW{PMIX_SERVER_SCHEDULER}{"pmix.srv.sched"}{bool}{ +\declareAttribute{PMIX_SERVER_SCHEDULER}{"pmix.srv.sched"}{bool}{ Server is supporting system scheduler and desires access to appropriate \ac{WLM}-supporting features. Indicates that the library is to be initialized for scheduler support. } % -\declareAttributeNEW{PMIX_EXTERNAL_PROGRESS}{"pmix.evext"}{bool}{ +\declareAttribute{PMIX_EXTERNAL_PROGRESS}{"pmix.evext"}{bool}{ The host shall progress the \ac{PMIx} library via calls to \refapi{PMIx_Progress} } % -\declareAttributeNEW{PMIX_HOMOGENEOUS_SYSTEM}{"pmix.homo"}{bool}{ +\declareAttribute{PMIX_HOMOGENEOUS_SYSTEM}{"pmix.homo"}{bool}{ The nodes comprising the session are homogeneous - i.e., they each contain the same number of identical packages, fabric interfaces, \acp{GPU}, and other devices. } % @@ -570,19 +570,19 @@ \subsubsection{Namespace registration attributes} Provide an array of \refstruct{pmix_info_t} containing session-realm information. The \refattr{PMIX_SESSION_ID} attribute is required to be included in the array. } % -\declareAttributeNEW{PMIX_JOB_INFO_ARRAY}{"pmix.job.arr"}{pmix_data_array_t}{ +\declareAttribute{PMIX_JOB_INFO_ARRAY}{"pmix.job.arr"}{pmix_data_array_t}{ Provide an array of \refstruct{pmix_info_t} containing job-realm information. The \refattr{PMIX_SESSION_ID} attribute of the \refterm{session} containing the \refterm{job} is required to be included in the array whenever the \ac{PMIx} server library may host multiple sessions (e.g., when executing with a host \ac{RM} daemon). As information is registered one job (aka namespace) at a time via the \refapi{PMIx_server_register_nspace} \ac{API}, there is no requirement that the array contain either the \refattr{PMIX_NSPACE} or \refattr{PMIX_JOBID} attributes when used in that context (though either or both of them may be included). At least one of the job identifiers must be provided in all other contexts where the job being referenced is ambiguous. } % -\declareAttributeNEW{PMIX_APP_INFO_ARRAY}{"pmix.app.arr"}{pmix_data_array_t}{ +\declareAttribute{PMIX_APP_INFO_ARRAY}{"pmix.app.arr"}{pmix_data_array_t}{ Provide an array of \refstruct{pmix_info_t} containing application-realm information. The \refattr{PMIX_NSPACE} or \refattr{PMIX_JOBID} attributes of the \refterm{job} containing the application, plus its \refattr{PMIX_APPNUM} attribute, must to be included in the array when the array is \textit{not} included as part of a call to \refapi{PMIx_server_register_nspace} - i.e., when the job containing the application is ambiguous. The job identification is otherwise optional. } % -\declareAttributeNEW{PMIX_PROC_INFO_ARRAY}{"pmix.pdata"}{pmix_data_array_t}{ +\declareAttribute{PMIX_PROC_INFO_ARRAY}{"pmix.pdata"}{pmix_data_array_t}{ Provide an array of \refstruct{pmix_info_t} containing process-realm information. The \refattr{PMIX_RANK} and \refattr{PMIX_NSPACE} attributes, or the \refattr{PMIX_PROCID} attribute, are required to be included in the array when the array is not included as part of a call to \refapi{PMIx_server_register_nspace} - i.e., when the job containing the process is ambiguous. All three may be included if desired. When the array is included in some broader structure that identifies the job, then only the \refattr{PMIX_RANK} or the \refattr{PMIX_PROCID} attribute must be included (the others are optional). } % -\declareAttributeNEW{PMIX_NODE_INFO_ARRAY}{"pmix.node.arr"}{pmix_data_array_t}{ +\declareAttribute{PMIX_NODE_INFO_ARRAY}{"pmix.node.arr"}{pmix_data_array_t}{ Provide an array of \refstruct{pmix_info_t} containing node-realm information. At a minimum, either the \refattr{PMIX_NODEID} or \refattr{PMIX_HOSTNAME} attribute is required to be included in the array, though both may be included. } @@ -1350,7 +1350,7 @@ \subsubsection{Attribute registration constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_ERR_REPEAT_ATTR_REGISTRATION}{-171} +\declareconstitemvalue{PMIX_ERR_REPEAT_ATTR_REGISTRATION}{-171} The attributes for an identical function have already been registered at the specified level (host, server, or client). % \end{constantdesc} @@ -1394,15 +1394,15 @@ \subsubsection{Attribute registration structure descriptive attributes} The following attributes relate to the nature of the values being reported in the \refstruct{pmix_regattr_t} structures. -\declareAttributeNEW{PMIX_MAX_VALUE}{"pmix.descr.maxval"}{varies}{ +\declareAttribute{PMIX_MAX_VALUE}{"pmix.descr.maxval"}{varies}{ Used in \refstruct{pmix_regattr_t} to describe the maximum valid value for the associated attribute. } % -\declareAttributeNEW{PMIX_MIN_VALUE}{"pmix.descr.minval"}{varies}{ +\declareAttribute{PMIX_MIN_VALUE}{"pmix.descr.minval"}{varies}{ Used in \refstruct{pmix_regattr_t} to describe the minimum valid value for the associated attribute. } % -\declareAttributeNEW{PMIX_ENUM_VALUE}{"pmix.descr.enum"}{char*}{ +\declareAttribute{PMIX_ENUM_VALUE}{"pmix.descr.enum"}{char*}{ Used in \refstruct{pmix_regattr_t} to describe accepted values for the associated attribute. Numerical values shall be presented in a form convertible to the attribute's declared data type. Named values (i.e., values defined by constant names via a typical C-language enum declaration) must be provided as their numerical equivalent. } @@ -2421,7 +2421,7 @@ \subsection{\code{pmix_server_dmodex_req_fn_t}} \subsubsection{Dmodex attributes} % -\declareAttributeNEW{PMIX_REQUIRED_KEY}{"pmix.req.key"}{char*}{ +\declareAttribute{PMIX_REQUIRED_KEY}{"pmix.req.key"}{char*}{ Identifies a key that must be included in the requested information. If the specified key is not already available, then the \ac{PMIx} servers are required to delay response to the dmodex request until either the key becomes available or the request times out. } @@ -4152,10 +4152,10 @@ \subsubsection{Group Operation Constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_GROUP_CONSTRUCT}{0} +\declareconstitemvalue{PMIX_GROUP_CONSTRUCT}{0} Construct a group composed of the specified processes - used by a \ac{PMIx} server library to direct host operation. % -\declareconstitemvalueNEW{PMIX_GROUP_DESTRUCT}{1} +\declareconstitemvalue{PMIX_GROUP_DESTRUCT}{1} Destruct the specified group - used by a \ac{PMIx} server library to direct host operation. % \end{constantdesc} diff --git a/Chap_API_Sets_Groups.tex b/Chap_API_Sets_Groups.tex index 6385f050..ec9c72b9 100644 --- a/Chap_API_Sets_Groups.tex +++ b/Chap_API_Sets_Groups.tex @@ -83,10 +83,10 @@ \subsection{Process Set Constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_PROCESS_SET_DEFINE}{-55} +\declareconstitemvalue{PMIX_PROCESS_SET_DEFINE}{-55} The host environment has defined a new process set - the event will include the process set name (\refattr{PMIX_PSET_NAME}) and the membership (\refattr{PMIX_PSET_MEMBERS}). % -\declareconstitemvalueNEW{PMIX_PROCESS_SET_DELETE}{-56} +\declareconstitemvalue{PMIX_PROCESS_SET_DELETE}{-56} The host environment has deleted a process set - the event will include the process set name (\refattr{PMIX_PSET_NAME}). % \end{constantdesc} @@ -99,17 +99,17 @@ \subsection{Process Set Attributes} Several attributes are provided for querying the system regarding process sets using the \refapi{PMIx_Query_info} \acp{API}. % -\declareAttributeNEW{PMIX_QUERY_NUM_PSETS}{"pmix.qry.psetnum"}{size_t}{ +\declareAttribute{PMIX_QUERY_NUM_PSETS}{"pmix.qry.psetnum"}{size_t}{ Return the number of process sets defined in the specified range (defaults to \refconst{PMIX_RANGE_SESSION}). } % -\declareAttributeNEW{PMIX_QUERY_PSET_NAMES}{"pmix.qry.psets"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_QUERY_PSET_NAMES}{"pmix.qry.psets"}{pmix_data_array_t*}{ Return a \refstruct{pmix_data_array_t} containing an array of strings of the process set names defined in the specified range (defaults to \refconst{PMIX_RANGE_SESSION}). } % -\declareAttributeNEW{PMIX_QUERY_PSET_MEMBERSHIP}{"pmix.qry.pmems"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_QUERY_PSET_MEMBERSHIP}{"pmix.qry.pmems"}{pmix_data_array_t*}{ Return an array of \refstruct{pmix_proc_t} containing the members of the specified process set. } @@ -118,11 +118,11 @@ \subsection{Process Set Attributes} \vspace{\baselineskip} The \refconst{PMIX_PROCESS_SET_DEFINE} event shall include the name of the newly defined process set and its members: % -\declareAttributeNEW{PMIX_PSET_NAME}{"pmix.pset.nm"}{char*}{ +\declareAttribute{PMIX_PSET_NAME}{"pmix.pset.nm"}{char*}{ The name of the newly defined process set. } % -\declareAttributeNEW{PMIX_PSET_MEMBERS}{"pmix.pset.mems"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_PSET_MEMBERS}{"pmix.pset.mems"}{pmix_data_array_t*}{ An array of \refstruct{pmix_proc_t} containing the members of the newly defined process set. } @@ -131,7 +131,7 @@ \subsection{Process Set Attributes} In addition, a process can request (via \refapi{PMIx_Get}) the process sets to which a given process (including itself) belongs: % -\declareAttributeNEW{PMIX_PSET_NAMES}{"pmix.pset.nms"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_PSET_NAMES}{"pmix.pset.nms"}{pmix_data_array_t*}{ Returns an array of \code{char*} string names of the process sets in which the given process is a member. } @@ -183,40 +183,40 @@ \subsection{Process Group Events} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_GROUP_INVITED}{-159} +\declareconstitemvalue{PMIX_GROUP_INVITED}{-159} The process has been invited to join a \ac{PMIx} Group - the identifier of the group and the ID's of other invited (or already joined) members will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_LEFT}{-160} +\declareconstitemvalue{PMIX_GROUP_LEFT}{-160} A process has asynchronously left a \ac{PMIx} Group - the process identifier of the departing process will in included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_MEMBER_FAILED}{-170} +\declareconstitemvalue{PMIX_GROUP_MEMBER_FAILED}{-170} A member of a \ac{PMIx} Group has abnormally terminated (i.e., without formally leaving the group prior to termination) - the process identifier of the failed process will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_INVITE_ACCEPTED}{-161} +\declareconstitemvalue{PMIX_GROUP_INVITE_ACCEPTED}{-161} A process has accepted an invitation to join a \ac{PMIx} Group - the identifier of the group being joined will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_INVITE_DECLINED}{-162} +\declareconstitemvalue{PMIX_GROUP_INVITE_DECLINED}{-162} A process has declined an invitation to join a \ac{PMIx} Group - the identifier of the declined group will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_INVITE_FAILED}{-163} +\declareconstitemvalue{PMIX_GROUP_INVITE_FAILED}{-163} An invited process failed or terminated prior to responding to the invitation - the identifier of the failed process will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_MEMBERSHIP_UPDATE}{-164} +\declareconstitemvalue{PMIX_GROUP_MEMBERSHIP_UPDATE}{-164} The membership of a \ac{PMIx} group has changed - the identifiers of the revised membership will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_CONSTRUCT_ABORT}{-165} +\declareconstitemvalue{PMIX_GROUP_CONSTRUCT_ABORT}{-165} Any participant in a \ac{PMIx} group construct operation that returns \refconst{PMIX_GROUP_CONSTRUCT_ABORT} from the \emph{leader failed} event handler will cause all participants to receive an event notifying them of that status. Similarly, the leader may elect to abort the procedure by either returning this error code from the handler assigned to the \refconst{PMIX_GROUP_INVITE_ACCEPTED} or \refconst{PMIX_GROUP_INVITE_DECLINED} codes, or by generating an event for the abort code. Abort events will be sent to all invited or existing members of the group. % -\declareconstitemvalueNEW{PMIX_GROUP_CONSTRUCT_COMPLETE}{-166} +\declareconstitemvalue{PMIX_GROUP_CONSTRUCT_COMPLETE}{-166} The group construct operation has completed - the final membership will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_LEADER_FAILED}{-168} +\declareconstitemvalue{PMIX_GROUP_LEADER_FAILED}{-168} The current \emph{leader} of a group including this process has abnormally terminated - the group identifier will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_LEADER_SELECTED}{-167} +\declareconstitemvalue{PMIX_GROUP_LEADER_SELECTED}{-167} A new \emph{leader} of a group including this process has been selected - the identifier of the new leader will be included in the notification. % -\declareconstitemvalueNEW{PMIX_GROUP_CONTEXT_ID_ASSIGNED}{-169} +\declareconstitemvalue{PMIX_GROUP_CONTEXT_ID_ASSIGNED}{-169} A new \ac{PGCID} has been assigned by the host environment to a group that includes this process - the group identifier will be included in the notification. % \end{constantdesc} @@ -228,17 +228,17 @@ \subsection{Process Group Attributes} Attributes for querying the system regarding process groups include: % -\declareAttributeNEW{PMIX_QUERY_NUM_GROUPS}{"pmix.qry.pgrpnum"}{size_t}{ +\declareAttribute{PMIX_QUERY_NUM_GROUPS}{"pmix.qry.pgrpnum"}{size_t}{ Return the number of process groups defined in the specified range (defaults to session). OPTIONAL QUALIFERS: \refattr{PMIX_RANGE}. } % -\declareAttributeNEW{PMIX_QUERY_GROUP_NAMES}{"pmix.qry.pgrp"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_QUERY_GROUP_NAMES}{"pmix.qry.pgrp"}{pmix_data_array_t*}{ Return a \refstruct{pmix_data_array_t} containing an array of string names of the process groups defined in the specified range (defaults to session). OPTIONAL QUALIFERS: \refattr{PMIX_RANGE}. } % -\declareAttributeNEW{PMIX_QUERY_GROUP_MEMBERSHIP}{"pmix.qry.pgrpmems"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_QUERY_GROUP_MEMBERSHIP}{"pmix.qry.pgrpmems"}{pmix_data_array_t*}{ Return a \refstruct{pmix_data_array_t} of \refstruct{pmix_proc_t} containing the members of the specified process group. REQUIRED QUALIFIERS: \refattr{PMIX_GROUP_ID}. } @@ -247,36 +247,36 @@ \subsection{Process Group Attributes} \vspace{\baselineskip} The following attributes are used as directives in \ac{PMIx} Group operations: -\declareAttributeNEW{PMIX_GROUP_ID}{"pmix.grp.id"}{char*}{ +\declareAttribute{PMIX_GROUP_ID}{"pmix.grp.id"}{char*}{ User-provided group identifier - as the group identifier may be used in \ac{PMIx} operations, the user is required to ensure that the provided ID is unique within the scope of the host environment (e.g., by including some user-specific or application-specific prefix or suffix to the string). } % -\declareAttributeNEW{PMIX_GROUP_LEADER}{"pmix.grp.ldr"}{bool}{ +\declareAttribute{PMIX_GROUP_LEADER}{"pmix.grp.ldr"}{bool}{ This process is the leader of the group. } % -\declareAttributeNEW{PMIX_GROUP_OPTIONAL}{"pmix.grp.opt"}{bool}{ +\declareAttribute{PMIX_GROUP_OPTIONAL}{"pmix.grp.opt"}{bool}{ Participation is optional - do not return an error if any of the specified processes terminate without having joined. The default is \code{false}. } % -\declareAttributeNEW{PMIX_GROUP_NOTIFY_TERMINATION}{"pmix.grp.notterm"}{bool}{ +\declareAttribute{PMIX_GROUP_NOTIFY_TERMINATION}{"pmix.grp.notterm"}{bool}{ Notify remaining members when another member terminates without first leaving the group. } % -\declareAttributeNEW{PMIX_GROUP_FT_COLLECTIVE}{"pmix.grp.ftcoll"}{bool}{ +\declareAttribute{PMIX_GROUP_FT_COLLECTIVE}{"pmix.grp.ftcoll"}{bool}{ Adjust internal tracking on-the-fly for terminated processes during a \ac{PMIx} group collective operation. } % -\declareAttributeNEW{PMIX_GROUP_MEMBERSHIP}{"pmix.grp.mbrs"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_GROUP_MEMBERSHIP}{"pmix.grp.mbrs"}{pmix_data_array_t*}{ Array \refstruct{pmix_proc_t} identifiers identifying the members of the specified group. } % -\declareAttributeNEW{PMIX_GROUP_ASSIGN_CONTEXT_ID}{"pmix.grp.actxid"}{bool}{ +\declareAttribute{PMIX_GROUP_ASSIGN_CONTEXT_ID}{"pmix.grp.actxid"}{bool}{ Requests that the \ac{RM} assign a new context identifier to the newly created group. The identifier is an unsigned, \code{size_t} value that the \ac{RM} guarantees to be unique across the range specified in the request. Thus, the value serves as a means of identifying the group within that range. If no range is specified, then the request defaults to \refconst{PMIX_RANGE_SESSION}. } % -\declareAttributeNEW{PMIX_GROUP_LOCAL_ONLY}{"pmix.grp.lcl"}{bool}{ +\declareAttribute{PMIX_GROUP_LOCAL_ONLY}{"pmix.grp.lcl"}{bool}{ Group operation only involves local processes. \ac{PMIx} implementations are \textit{required} to automatically scan an array of group members for local vs remote processes - if only local processes are detected, the implementation need not execute a global collective for the operation unless a context ID has been requested from the host environment. This can result in significant time savings. This attribute can be used to optimize the operation by indicating whether or not only local processes are represented, thus allowing the implementation to bypass the scan. } @@ -284,11 +284,11 @@ \subsection{Process Group Attributes} The following attributes are used to return information at the conclusion of a \ac{PMIx} Group operation and/or in event notifications: % -\declareAttributeNEW{PMIX_GROUP_CONTEXT_ID}{"pmix.grp.ctxid"}{size_t}{ +\declareAttribute{PMIX_GROUP_CONTEXT_ID}{"pmix.grp.ctxid"}{size_t}{ Context identifier assigned to the group by the host \ac{RM}. } % -\declareAttributeNEW{PMIX_GROUP_ENDPT_DATA}{"pmix.grp.endpt"}{pmix_byte_object_t}{ +\declareAttribute{PMIX_GROUP_ENDPT_DATA}{"pmix.grp.endpt"}{pmix_byte_object_t}{ Data collected during group construction to ensure communication between group members is supported upon completion of the operation. } @@ -296,7 +296,7 @@ \subsection{Process Group Attributes} In addition, a process can request (via \refapi{PMIx_Get}) the process groups to which a given process (including itself) belongs: % -\declareAttributeNEW{PMIX_GROUP_NAMES}{"pmix.pgrp.nm"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_GROUP_NAMES}{"pmix.pgrp.nm"}{pmix_data_array_t*}{ Returns an array of \code{char*} string names of the process groups in which the given process is a member. } diff --git a/Chap_API_Sharing_Basics.tex b/Chap_API_Sharing_Basics.tex index a52a948b..943ec657 100644 --- a/Chap_API_Sharing_Basics.tex +++ b/Chap_API_Sharing_Basics.tex @@ -590,15 +590,15 @@ \subsection{Retrieval attributes} Specified operation should immediately return an error from the \ac{PMIx} server if the requested data cannot be found - do not request it from the host \ac{RM}. } % -\declareAttributeNEW{PMIX_GET_POINTER_VALUES}{"pmix.get.pntrs"}{bool}{ +\declareAttribute{PMIX_GET_POINTER_VALUES}{"pmix.get.pntrs"}{bool}{ Request that any pointers in the returned value point directly to values in the key-value store. The user \emph{must not} release any returned data pointers. } % -\declareAttributeNEW{PMIX_GET_STATIC_VALUES}{"pmix.get.static"}{bool}{ +\declareAttribute{PMIX_GET_STATIC_VALUES}{"pmix.get.static"}{bool}{ Request that the data be returned in the provided storage location. The caller is responsible for destructing the \refstruct{pmix_value_t} using the \refmacro{PMIX_VALUE_DESTRUCT} macro when done. } % -\declareAttributeNEW{PMIX_GET_REFRESH_CACHE}{"pmix.get.refresh"}{bool}{ +\declareAttribute{PMIX_GET_REFRESH_CACHE}{"pmix.get.refresh"}{bool}{ When retrieving data for a remote process, refresh the existing local data cache for the process in case new values have been put and committed by the process since the last refresh. Local process information is assumed to be automatically updated upon posting by the process. A \code{NULL} key will cause all values associated with the process to be refreshed - otherwise, only the indicated key will be updated. A process rank of \refconst{PMIX_RANK_WILDCARD} can be used to update job-related information in dynamic environments. The user is responsible for subsequently updating refreshed values they may have cached in their own local memory. } % diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex index 4e9d93f7..89f6ca68 100644 --- a/Chap_API_Struct.tex +++ b/Chap_API_Struct.tex @@ -63,7 +63,7 @@ \section{Constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_APP_WILDCARD}{UINT32_MAX} +\declareconstitemvalue{PMIX_APP_WILDCARD}{UINT32_MAX} 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} @@ -102,11 +102,11 @@ \subsection{PMIx Return Status Constants} \declareconstitemvalue{PMIX_ERROR}{-1} General Error. % -\declareconstitemvalueNEW{PMIX_ERR_EXISTS}{-11} +\declareconstitemvalue{PMIX_ERR_EXISTS}{-11} The requested operation would overwrite an existing value - typically returned when an operation would overwrite an existing file or directory. % -\declareconstitemvalueNEW{PMIX_ERR_EXISTS_OUTSIDE_SCOPE}{-62} +\declareconstitemvalue{PMIX_ERR_EXISTS_OUTSIDE_SCOPE}{-62} The requested key exists, but was posted in a \emph{scope} (see Section \ref{api:nres:scope}) that does not include the requester % \declareconstitemvalue{PMIX_ERR_INVALID_CRED}{-12} @@ -153,7 +153,7 @@ \subsection{PMIx Return Status Constants} \declareconstitemvalue{PMIX_ERR_BAD_PARAM}{-27} 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}. % -\declareconstitemvalueNEW{PMIX_ERR_EMPTY}{-60} +\declareconstitemvalue{PMIX_ERR_EMPTY}{-60} An array or list was given that has no members in it - i.e., the object is empty. % \declareconstitemvalue{PMIX_ERR_RESOURCE_BUSY}{-28} @@ -177,14 +177,14 @@ \subsection{PMIx Return Status Constants} The requested operation is not supported by either the \ac{PMIx} implementation or the host environment. % -\declareconstitemvalueNEW{PMIX_ERR_PARAM_VALUE_NOT_SUPPORTED}{-59} +\declareconstitemvalue{PMIX_ERR_PARAM_VALUE_NOT_SUPPORTED}{-59} 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. % \declareconstitemvalue{PMIX_ERR_COMM_FAILURE}{-49} Communication failure - a message failed to be sent or received, but the connection remains intact. % -\declareconstitemvalueNEW{PMIX_ERR_LOST_CONNECTION}{-61} +\declareconstitemvalue{PMIX_ERR_LOST_CONNECTION}{-61} Lost connection between server and client or tool. % \declareconstitemvalue{PMIX_ERR_INVALID_OPERATION}{-158} @@ -197,7 +197,7 @@ \subsection{PMIx Return Status Constants} \declareconstitemvalue{PMIX_OPERATION_SUCCEEDED}{-157} The requested operation was performed atomically - no callback function will be executed. % -\declareconstitemvalueNEW{PMIX_ERR_PARTIAL_SUCCESS}{-52} +\declareconstitemvalue{PMIX_ERR_PARTIAL_SUCCESS}{-52} 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} @@ -738,13 +738,13 @@ \subsection{Process State Structure} \declareconstitemvalue{PMIX_PROC_STATE_COMM_FAILED}{56} Process communication has failed. % -\declareconstitemvalueNEW{PMIX_PROC_STATE_SENSOR_BOUND_EXCEEDED}{57} +\declareconstitemvalue{PMIX_PROC_STATE_SENSOR_BOUND_EXCEEDED}{57} Process exceeded a specified sensor limit. % \declareconstitemvalue{PMIX_PROC_STATE_CALLED_ABORT}{58} Process called \refapi{PMIx_Abort}. % -\declareconstitemvalueNEW{PMIX_PROC_STATE_HEARTBEAT_FAILED}{59} +\declareconstitemvalue{PMIX_PROC_STATE_HEARTBEAT_FAILED}{59} Frocess failed to send heartbeat within specified time limit. % \declareconstitemvalue{PMIX_PROC_STATE_MIGRATING}{60} @@ -892,22 +892,22 @@ \subsection{Job State Structure} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_JOB_STATE_UNDEF}{0} +\declareconstitemvalue{PMIX_JOB_STATE_UNDEF}{0} Undefined job state. % -\declareconstitemvalueNEW{PMIX_JOB_STATE_AWAITING_ALLOC}{1} +\declareconstitemvalue{PMIX_JOB_STATE_AWAITING_ALLOC}{1} Job is waiting for resources to be allocated to it. % -\declareconstitemvalueNEW{PMIX_JOB_STATE_LAUNCH_UNDERWAY}{2} +\declareconstitemvalue{PMIX_JOB_STATE_LAUNCH_UNDERWAY}{2} Job launch is underway. % -\declareconstitemvalueNEW{PMIX_JOB_STATE_RUNNING}{3} +\declareconstitemvalue{PMIX_JOB_STATE_RUNNING}{3} All processes in the job have been spawned and are executing. % -\declareconstitemvalueNEW{PMIX_JOB_STATE_SUSPENDED}{4} +\declareconstitemvalue{PMIX_JOB_STATE_SUSPENDED}{4} All processes in the job have been suspended. % -\declareconstitemvalueNEW{PMIX_JOB_STATE_CONNECTED}{5} +\declareconstitemvalue{PMIX_JOB_STATE_CONNECTED}{5} All processes in the job have connected to their \ac{PMIx} server. % \declareconstitemvalue{PMIX_JOB_STATE_UNTERMINATED}{15} @@ -1561,13 +1561,13 @@ \subsection{Info Type Directives} \declareconstitemvalue{PMIX_INFO_REQD}{0x00000001} The behavior defined in the \refstruct{pmix_info_t} array is required, and not optional. This is a bit-mask value. % -\declareconstitemvalueNEW{PMIX_INFO_REQD_PROCESSED}{0x00000004} +\declareconstitemvalue{PMIX_INFO_REQD_PROCESSED}{0x00000004} 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. % \declareconstitemvalue{PMIX_INFO_ARRAY_END}{0x00000002} 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. % -\declareconstitemvalueNEW{PMIX_INFO_DIR_RESERVED}{0xffff0000} +\declareconstitemvalue{PMIX_INFO_DIR_RESERVED}{0xffff0000} A bit-mask identifying the bits reserved for internal use by implementers - these currently are set as \code{0xffff0000}. % \end{constantdesc} @@ -2347,7 +2347,7 @@ \section{Generalized Data Types Used for Packing/Unpacking} \declareconstitemvalue{PMIX_PROC_RANK}{40} Process rank (\refstruct{pmix_rank_t}). % -\declareconstitemvalueNEW{PMIX_PROC_NSPACE}{60} +\declareconstitemvalue{PMIX_PROC_NSPACE}{60} Process namespace (\refstruct{pmix_nspace_t}). \% \declareconstitemvalue{PMIX_QUERY}{41} @@ -2368,52 +2368,52 @@ \section{Generalized Data Types Used for Packing/Unpacking} \declareconstitemvalue{PMIX_ENVAR}{46} Environmental variable structure (\refstruct{pmix_envar_t}). % -\declareconstitemvalueNEW{PMIX_COORD}{47} +\declareconstitemvalue{PMIX_COORD}{47} Structure containing fabric coordinates (\refstruct{pmix_coord_t}). % -\declareconstitemvalueNEW{PMIX_REGATTR}{48} +\declareconstitemvalue{PMIX_REGATTR}{48} Structure supporting attribute registrations (\refstruct{pmix_regattr_t}). % -\declareconstitemvalueNEW{PMIX_REGEX}{49} +\declareconstitemvalue{PMIX_REGEX}{49} Regular expressions - can be a valid NULL-terminated string or an arbitrary array of bytes. % -\declareconstitemvalueNEW{PMIX_JOB_STATE}{50} +\declareconstitemvalue{PMIX_JOB_STATE}{50} Job state (\refstruct{pmix_job_state_t}). % -\declareconstitemvalueNEW{PMIX_LINK_STATE}{51} +\declareconstitemvalue{PMIX_LINK_STATE}{51} Link state (\refstruct{pmix_link_state_t}). % -\declareconstitemvalueNEW{PMIX_PROC_CPUSET}{52} +\declareconstitemvalue{PMIX_PROC_CPUSET}{52} Structure containing the binding bitmap of a process (\refstruct{pmix_cpuset_t}). % -\declareconstitemvalueNEW{PMIX_GEOMETRY}{53} +\declareconstitemvalue{PMIX_GEOMETRY}{53} Geometry structure containing the fabric coordinates of a specified device.(\refstruct{pmix_geometry_t}). % -\declareconstitemvalueNEW{PMIX_DEVICE_DIST}{54} +\declareconstitemvalue{PMIX_DEVICE_DIST}{54} Structure containing the minimum and maximum relative distance from the caller to a given fabric device. (\refstruct{pmix_device_distance_t}). % -\declareconstitemvalueNEW{PMIX_ENDPOINT}{55} +\declareconstitemvalue{PMIX_ENDPOINT}{55} Structure containing an assigned endpoint for a given fabric device. (\refstruct{pmix_endpoint_t}). % -\declareconstitemvalueNEW{PMIX_TOPO}{56} +\declareconstitemvalue{PMIX_TOPO}{56} Structure containing the topology for a given node. (\refstruct{pmix_topology_t}). % -\declareconstitemvalueNEW{PMIX_DEVTYPE}{57} +\declareconstitemvalue{PMIX_DEVTYPE}{57} Bitmask containing the types of devices being referenced. (\refstruct{pmix_device_type_t}). % -\declareconstitemvalueNEW{PMIX_LOCTYPE}{58} +\declareconstitemvalue{PMIX_LOCTYPE}{58} Bitmask describing the relative location of another process. (\refstruct{pmix_locality_t}). % -\declareconstitemvalueNEW{PMIX_STOR_MEDIUM}{66} +\declareconstitemvalue{PMIX_STOR_MEDIUM}{66} Bitmask specifying different types of storage mediums. (\refstruct{pmix_storage_medium_t}). % -\declareconstitemvalueNEW{PMIX_STOR_ACCESS}{67} +\declareconstitemvalue{PMIX_STOR_ACCESS}{67} Bitmask specifying different levels of storage accessibility (i.e,. from where a storage system may be accessed). (\refstruct{pmix_storage_accessibility_t}). % -\declareconstitemvalueNEW{PMIX_STOR_PERSIST}{68} +\declareconstitemvalue{PMIX_STOR_PERSIST}{68} Bitmask specifying different levels of persistence for a particular storage system. (\refstruct{pmix_storage_persistence_t}). % -\declareconstitemvalueNEW{PMIX_STOR_ACCESS_TYPE}{69} +\declareconstitemvalue{PMIX_STOR_ACCESS_TYPE}{69} Bitmask specifying different storage system access types. (\refstruct{pmix_storage_access_type_t}). % \declareconstitemvalue{PMIX_DATA_TYPE_MAX}{500} diff --git a/Chap_API_Sync.tex b/Chap_API_Sync.tex index 21cc2882..9f309d38 100644 --- a/Chap_API_Sync.tex +++ b/Chap_API_Sync.tex @@ -183,11 +183,11 @@ \subsection{Fence-related attributes} The PMIx server is allowed to pass \refconst{PMIX_SUCCESS} using this attribute, but is not required to do so. PMIx implementations may choose to only report errors in this manner. The lack of an included status shall therefore be taken to indicate that the collective operation locally succeeded. \advicermend % -\declareAttributeNEW{PMIX_COLLECT_GENERATED_JOB_INFO}{"pmix.collect.gen"}{bool}{ +\declareAttribute{PMIX_COLLECT_GENERATED_JOB_INFO}{"pmix.collect.gen"}{bool}{ Collect all job-level information (i.e., reserved keys) that was locally generated by \ac{PMIx} servers. Some job-level information (e.g., distance between processes and fabric devices) is best determined on a distributed basis as it primarily pertains to local processes. Should remote processes need to access the information, it can either be obtained collectively using the \refapi{PMIx_Fence} operation with this directive, or can be retrieved one peer at a time using \refapi{PMIx_Get} without first having performed the job-wide collection. } % -\declareAttributeNEW{PMIX_ALL_CLONES_PARTICIPATE}{"pmix.clone.part"}{bool}{ +\declareAttribute{PMIX_ALL_CLONES_PARTICIPATE}{"pmix.clone.part"}{bool}{ All \refterm{clones} of the calling process must participate in the collective operation. } diff --git a/Chap_API_Tools.tex b/Chap_API_Tools.tex index 2113e185..1fc4bb3b 100644 --- a/Chap_API_Tools.tex +++ b/Chap_API_Tools.tex @@ -175,15 +175,15 @@ \subsection{Tool initialization environmental variables} The following environmental variables are used during \refapi{PMIx_tool_init} and \refapi{PMIx_server_init} to control various rendezvous-related operations when the process is started manually (e.g., on a command line) or by a fork/exec-like operation. % -\declareEnvarNEW{PMIX_LAUNCHER_RNDZ_URI}{ +\declareEnvar{PMIX_LAUNCHER_RNDZ_URI}{ The spawned tool is to be connected back to the spawning tool using the given \ac{URI} so that the spawning tool can provide directives (e.g., a \refapi{PMIx_Spawn} command) to it. } % -\declareEnvarNEW{PMIX_LAUNCHER_RNDZ_FILE}{ +\declareEnvar{PMIX_LAUNCHER_RNDZ_FILE}{ If the specified file does not exist, this variable contains the absolute path of the file where the spawned tool is to store its connection information so that the spawning tool can connect to it. If the file does exist, it contains the information specifying the server to which the spawned tool is to connect. } % -\declareEnvarNEW{PMIX_KEEPALIVE_PIPE}{ +\declareEnvar{PMIX_KEEPALIVE_PIPE}{ An integer \code{read}-end of a POSIX pipe that the tool should monitor for closure, thereby indicating that the parent tool has terminated. Used. for example, when a tool fork/exec's an intermediate launcher that should self-terminate if the originating tool exits. } % @@ -229,23 +229,23 @@ \subsection{Tool connection attributes} The tool wants to use internal \ac{PMIx} support, but does not want to connect to a \ac{PMIx} server. } % -\declareAttributeNEW{PMIX_TOOL_CONNECT_OPTIONAL}{"pmix.tool.conopt"}{bool}{ +\declareAttribute{PMIX_TOOL_CONNECT_OPTIONAL}{"pmix.tool.conopt"}{bool}{ The tool shall connect to a server if available, but otherwise continue to operate unconnected. } % -\declareAttributeNEW{PMIX_TOOL_ATTACHMENT_FILE}{"pmix.tool.attach"}{char*}{ +\declareAttribute{PMIX_TOOL_ATTACHMENT_FILE}{"pmix.tool.attach"}{char*}{ Pathname of file containing connection information to be used for attaching to a specific server. } % -\declareAttributeNEW{PMIX_LAUNCHER_RENDEZVOUS_FILE}{"pmix.tool.lncrnd"}{char*}{ +\declareAttribute{PMIX_LAUNCHER_RENDEZVOUS_FILE}{"pmix.tool.lncrnd"}{char*}{ Pathname of file where the launcher is to store its connection information so that the spawning tool can connect to it. } % -\declareAttributeNEW{PMIX_PRIMARY_SERVER}{"pmix.pri.srvr"}{bool}{ +\declareAttribute{PMIX_PRIMARY_SERVER}{"pmix.pri.srvr"}{bool}{ The server to which the tool is connecting shall be designated the \emph{primary} server once connection has been accomplished. } % -\declareAttributeNEW{PMIX_WAIT_FOR_CONNECTION}{"pmix.wait.conn"}{bool}{ +\declareAttribute{PMIX_WAIT_FOR_CONNECTION}{"pmix.wait.conn"}{bool}{ Wait until the specified process has connected to the requesting tool or server, or the operation times out (if the \refattr{PMIX_TIMEOUT} directive is included in the request). } @@ -504,23 +504,23 @@ \subsection{Tool spawn-related attributes} output. } % -\declareAttributeNEW{PMIX_NOHUP}{"pmix.nohup"}{bool}{ +\declareAttribute{PMIX_NOHUP}{"pmix.nohup"}{bool}{ Any processes started on behalf of the calling tool (or the specified namespace, if such specification is included in the list of attributes) should continue after the tool disconnects from its server. } % -\declareAttributeNEW{PMIX_LAUNCHER_DAEMON}{"pmix.lnch.dmn"}{char*}{ +\declareAttribute{PMIX_LAUNCHER_DAEMON}{"pmix.lnch.dmn"}{char*}{ Path to executable that is to be used as the backend daemon for the launcher. This replaces the launcher's own daemon with the specified executable. Note that the user is therefore responsible for ensuring compatibility of the specified executable and the host launcher. } % -\declareAttributeNEW{PMIX_FORKEXEC_AGENT}{"pmix.frkex.agnt"}{char*}{ +\declareAttribute{PMIX_FORKEXEC_AGENT}{"pmix.frkex.agnt"}{char*}{ Path to executable that the launcher's backend daemons are to fork/exec in place of the actual application processes. The fork/exec agent shall connect back (as a \ac{PMIx} tool) to the launcher's daemon to receive its spawn instructions, and is responsible for starting the actual application process it replaced. See Section \ref{api:tools:debugger:agent} for details. } % -\declareAttributeNEW{PMIX_EXEC_AGENT}{"pmix.exec.agnt"}{char*}{ +\declareAttribute{PMIX_EXEC_AGENT}{"pmix.exec.agnt"}{char*}{ Path to executable that the launcher's backend daemons are to fork/exec in place of the actual application processes. The launcher's daemon shall pass the full command line of the application on the command line of the exec agent, which shall not connect back to the launcher's daemon. The exec agent is responsible for exec'ing the specified application process in its own place. See Section \ref{api:tools:debugger:agent} for details. } % -\declareAttributeNEW{PMIX_LAUNCH_DIRECTIVES}{"pmix.lnch.dirs"}{pmix_data_array_t*}{ +\declareAttribute{PMIX_LAUNCH_DIRECTIVES}{"pmix.lnch.dirs"}{pmix_data_array_t*}{ Array of \refstruct{pmix_info_t} containing directives for the launcher - a convenience attribute for retrieving all directives with a single call to \refapi{PMIx_Get}. } @@ -532,7 +532,7 @@ \subsection{Tool rendezvous-related events} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_LAUNCHER_READY}{-155} +\declareconstitemvalue{PMIX_LAUNCHER_READY}{-155} An application launcher (e.g., \emph{mpiexec}) shall generate this event to signal a tool that started it that the launcher is ready to receive directives/commands (e.g., \refapi{PMIx_Spawn}). This is only used when the initiator is able to parse the command line itself, or the launcher is started as a persistent \ac{DVM}. % \end{constantdesc} @@ -684,10 +684,10 @@ \subsection{IO Forwarding constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_ERR_IOF_FAILURE}{-172} +\declareconstitemvalue{PMIX_ERR_IOF_FAILURE}{-172} An \ac{IO} forwarding operation failed - the affected channel will be included in the notification. % -\declareconstitemvalueNEW{PMIX_ERR_IOF_COMPLETE}{-173} +\declareconstitemvalue{PMIX_ERR_IOF_COMPLETE}{-173} \ac{IO} forwarding of the standard input for this process has completed - i.e., the stdin file descriptor has closed. % \end{constantdesc} @@ -751,15 +751,15 @@ \subsection{IO Forwarding attributes} Requests that output be formatted in \ac{XML}. } % -\declareAttributeNEW{PMIX_IOF_PUSH_STDIN}{"pmix.iof.stdin"}{bool}{ +\declareAttribute{PMIX_IOF_PUSH_STDIN}{"pmix.iof.stdin"}{bool}{ Requests that the \ac{PMIx} library collect the \code{stdin} of the requester and forward it to the processes specified in the \refapi{PMIx_IOF_push} call. All collected data is sent to the same targets until \code{stdin} is closed, or a subsequent call to \refapi{PMIx_IOF_push} is made that includes the \refattr{PMIX_IOF_COMPLETE} attribute indicating that forwarding of \code{stdin} is to be terminated. } % -\declareAttributeNEW{PMIX_IOF_COPY}{"pmix.iof.cpy"}{bool}{ +\declareAttribute{PMIX_IOF_COPY}{"pmix.iof.cpy"}{bool}{ Requests that the host environment deliver a copy of the specified output stream(s) to the tool, letting the stream(s) continue to also be delivered to the default location. This allows the tool to tap into the output stream(s) without redirecting it from its current final destination. } % -\declareAttributeNEW{PMIX_IOF_REDIRECT}{"pmix.iof.redir"}{bool}{ +\declareAttribute{PMIX_IOF_REDIRECT}{"pmix.iof.redir"}{bool}{ Requests that the host environment intercept the specified output stream(s) and deliver it to the requesting tool instead of its current final destination. This might be used, for example, during a debugging procedure to avoid injection of debugger-related output into the application’s results file. The original output stream(s) destination is restored upon termination of the tool. } % @@ -1004,19 +1004,19 @@ \subsubsection{Job lifecycle events} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_EVENT_JOB_START}{-191} +\declareconstitemvalue{PMIX_EVENT_JOB_START}{-191} The first process in the job has been spawned - includes \refattr{PMIX_EVENT_TIMESTAMP} as well as the \refattr{PMIX_JOBID} and/or \refattr{PMIX_NSPACE} of the job. % -\declareconstitemvalueNEW{PMIX_LAUNCH_COMPLETE}{-174} +\declareconstitemvalue{PMIX_LAUNCH_COMPLETE}{-174} All processes in the job have been spawned - includes \refattr{PMIX_EVENT_TIMESTAMP} as well as the \refattr{PMIX_JOBID} and/or \refattr{PMIX_NSPACE} of the job. % -\declareconstitemvalueNEW{PMIX_EVENT_JOB_END}{-145} +\declareconstitemvalue{PMIX_EVENT_JOB_END}{-145} All processes in the job have terminated - includes \refattr{PMIX_EVENT_TIMESTAMP} when the last process terminated as well as the \refattr{PMIX_JOBID} and/or \refattr{PMIX_NSPACE} of the job. % -\declareconstitemvalueNEW{PMIX_EVENT_SESSION_START}{-192} +\declareconstitemvalue{PMIX_EVENT_SESSION_START}{-192} The allocation has been instantiated and is ready for use - includes \refattr{PMIX_EVENT_TIMESTAMP} as well as the \refattr{PMIX_SESSION_ID} of the allocation. This event is issued after any system-controlled prologue has completed, but before any user-specified actions are taken. % -\declareconstitemvalueNEW{PMIX_EVENT_SESSION_END}{-193} +\declareconstitemvalue{PMIX_EVENT_SESSION_END}{-193} The allocation has terminated - includes \refattr{PMIX_EVENT_TIMESTAMP} as well as the \refattr{PMIX_SESSION_ID} of the allocation. This event is issued after any user-specified actions have completed, but before any system-controlled epilogue is performed. % \end{constantdesc} @@ -1031,7 +1031,7 @@ \subsubsection{Job lifecycle events} \refarg{info} array of the notification. Note that a request for individual process events can generate a significant event volume from large-scale jobs. % -\declareconstitemvalueNEW{PMIX_ERR_PROC_TERM_WO_SYNC}{-200} +\declareconstitemvalue{PMIX_ERR_PROC_TERM_WO_SYNC}{-200} Process terminated without calling \refapi{PMIx_Finalize}, or was a member of an assemblage formed via \refapi{PMIx_Connect} and terminated or called \refapi{PMIx_Finalize} without first calling \refapi{PMIx_Disconnect} (or its non-blocking form) from that assemblage. % \end{constantdesc} @@ -1043,28 +1043,28 @@ \subsubsection{Job lifecycle events} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_ERR_JOB_CANCELED}{-180} +\declareconstitemvalue{PMIX_ERR_JOB_CANCELED}{-180} The job was canceled by the host environment. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_ABORTED}{-182} +\declareconstitemvalue{PMIX_ERR_JOB_ABORTED}{-182} One or more processes in the job called abort, causing the job to be terminated. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_KILLED_BY_CMD}{-183} +\declareconstitemvalue{PMIX_ERR_JOB_KILLED_BY_CMD}{-183} The job was killed by user command. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_ABORTED_BY_SIG}{-184} +\declareconstitemvalue{PMIX_ERR_JOB_ABORTED_BY_SIG}{-184} The job was aborted due to receipt of an error signal (e.g., SIGKILL). % -\declareconstitemvalueNEW{PMIX_ERR_JOB_TERM_WO_SYNC}{-185} +\declareconstitemvalue{PMIX_ERR_JOB_TERM_WO_SYNC}{-185} The job was terminated due to at least one process terminating without calling \refapi{PMIx_Finalize}, or was a member of an assemblage formed via \refapi{PMIx_Connect} and terminated or called \refapi{PMIx_Finalize} without first calling \refapi{PMIx_Disconnect} (or its non-blocking form) from that assemblage. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_SENSOR_BOUND_EXCEEDED}{-186} +\declareconstitemvalue{PMIX_ERR_JOB_SENSOR_BOUND_EXCEEDED}{-186} The job was terminated due to one or more processes exceeding a specified sensor limit. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_NON_ZERO_TERM}{-187} +\declareconstitemvalue{PMIX_ERR_JOB_NON_ZERO_TERM}{-187} The job was terminated due to one or more processes exiting with a non-zero status. % -\declareconstitemvalueNEW{PMIX_ERR_JOB_ABORTED_BY_SYS_EVENT}{-189} +\declareconstitemvalue{PMIX_ERR_JOB_ABORTED_BY_SYS_EVENT}{-189} The job was aborted due to receipt of a system event. % \end{constantdesc} @@ -1093,10 +1093,10 @@ \subsection{Debugger-related constants} \begin{constantdesc} % -\declareconstitemvalueNEW{PMIX_READY_FOR_DEBUG}{-58} +\declareconstitemvalue{PMIX_READY_FOR_DEBUG}{-58} Event indicating a job (or specified set of processes) is ready for debug - includes identification of the target processes as well as the \refattr{PMIX_BREAKPOINT} indicating where the target is waiting % -\declareconstitemvalueNEW{PMIX_DEBUGGER_RELEASE}{-3} +\declareconstitemvalue{PMIX_DEBUGGER_RELEASE}{-3} Release a tool that is paused during \refapi{PMIx_tool_init}. % \end{constantdesc} @@ -1116,7 +1116,7 @@ \subsection{Debugger attributes} Included in either the \refstruct{pmix_info_t} array in a \refstruct{pmix_app_t} description (if the directive applies only to that application) or in the \emph{job_info} array if it applies to all applications in the given spawn request. Indicates that the specified application is being spawned under a debugger. The \ac{PMIx} client library in each resulting application process shall notify its \ac{PMIx} server that it is pausing and then pause during \refapi{PMIx_Init} of the spawned processes until either released by debugger modification of an appropriate variable or receipt of the \refconst{PMIX_DEBUGGER_RELEASE} event. The launcher (\ac{RM} or \ac{IL}) is responsible for generating the \refconst{PMIX_READY_FOR_DEBUG} event (stipulating a breakpoint of \"pmix-init\") when all processes have reached the pause point. } % -\declareAttributeNEW{PMIX_DEBUG_STOP_IN_APP}{"pmix.dbg.notify"}{varies}{ +\declareAttribute{PMIX_DEBUG_STOP_IN_APP}{"pmix.dbg.notify"}{varies}{ Direct specified ranks to stop at application-specific point and notify they are ready-to-debug. The attribute's value can be any of three data types: \begin{compactitemize} @@ -1128,11 +1128,11 @@ \subsection{Debugger attributes} the \refconst{PMIX_READY_FOR_DEBUG} event) when they reach some application-determined location - the event shall include the \refattr{PMIX_BREAKPOINT} attribute indicating where the application has stopped. The application shall pause at that point until released by debugger modification of an appropriate variable. The launcher (\ac{RM} or \ac{IL}) is responsible for generating the \refconst{PMIX_READY_FOR_DEBUG} event when all processes have indicated they are at the pause point. } % -\declareAttributeNEW{PMIX_BREAKPOINT}{"pmix.brkpnt"}{char*}{ +\declareAttribute{PMIX_BREAKPOINT}{"pmix.brkpnt"}{char*}{ String ID of the breakpoint where the process(es) is(are) waiting. } % -\declareAttributeNEW{PMIX_DEBUG_TARGET}{"pmix.dbg.tgt"}{pmix_proc_t*}{ +\declareAttribute{PMIX_DEBUG_TARGET}{"pmix.dbg.tgt"}{pmix_proc_t*}{ Identifier of process(es) to be debugged - a rank of \refconst{PMIX_RANK_WILDCARD} indicates that all processes in the specified namespace are to be included. } % @@ -1144,7 +1144,7 @@ \subsection{Debugger attributes} Designated application is to be spawned as a disconnected job - i.e., the launcher shall not include the application in any of the job-level values (e.g., \refattr{PMIX_RANK} within the job) provided to any other application process generated by the same spawn request. Typically used to cospawn debugger daemons alongside an application. } % -\declareAttributeNEW{PMIX_DEBUG_DAEMONS_PER_PROC}{"pmix.dbg.dpproc"}{uint16_t}{ +\declareAttribute{PMIX_DEBUG_DAEMONS_PER_PROC}{"pmix.dbg.dpproc"}{uint16_t}{ Number of debugger daemons to be spawned per application process. The launcher is to pass the identifier of the namespace to be debugged by including the \refattr{PMIX_DEBUG_TARGET} attribute in the daemon's job-level information. The debugger daemons spawned on a given node are responsible for @@ -1153,7 +1153,7 @@ \subsection{Debugger attributes} corresponding \refattr{PMIX_LOCAL_RANK} of the target processes on the node. } % -\declareAttributeNEW{PMIX_DEBUG_DAEMONS_PER_NODE}{"pmix.dbg.dpnd"}{uint16_t}{ +\declareAttribute{PMIX_DEBUG_DAEMONS_PER_NODE}{"pmix.dbg.dpnd"}{uint16_t}{ Number of debugger daemons to be spawned on each node where the target job is executing. The launcher is to pass the identifier of the namespace to be debugged by including the \refattr{PMIX_DEBUG_TARGET} attribute in the daemon's diff --git a/pmix.sty b/pmix.sty index 6eae4aeb..ee23bc3c 100644 --- a/pmix.sty +++ b/pmix.sty @@ -429,11 +429,9 @@ % % \declareconstitem Declare Attribute % \declareconstitemProvisional Declare Constant - Provisional -% \declareconstitemNEW Declare Constant - New % \declareconstitemDEP Declare Constant - Deprecated % \declareconstitemRM Declare Constant - Removed % \declareconstitemvalue Declare Constant Value -% \declareconstitemvalueNEW Declare Constant Value - NEW % % \pasteAttributeItem Paste a copy of the Attribute declaration % \pasteAttributeItemBegin Paste a copy of the Attribute declaration @@ -456,11 +454,6 @@ \index[index_const]{#1|indexfmt} \label{const:#1}% \hspace{0.25em} \code{#2} \hspace{1em}% } -\newcommand{\declareconstitemvalueNEW}[2]{% - \item[\color{magenta}\code{#1}]% - \index[index_const]{#1|indexfmt} \label{const:#1}% - \hspace{0.25em} \code{#2} \hspace{1em}% -} \newcommand{\declareconstitemProvisional}[1]{% \item[\hl{\code{#1}}] \provisionalMarker{}% @@ -473,12 +466,6 @@ \hspace{1em} \code{#2} \hspace{1em}% } -\newcommand{\declareconstitemNEW}[1]{% - \item[\color{magenta}\code{#1}]% - \index[index_const]{#1|indexfmt} \label{const:#1}% - \hspace{1em}% -} - \newcommand{\declareconstitemDEP}[1]{% \item[\color{green!80!black}\code{#1}]% \index[index_const]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{const:#1} @@ -499,7 +486,6 @@ % % \declareEnvar Declare Envar % \declareEnvarProvisional Declare Envar - Provisional -% \declareEnvarNEW Declare Envar - New % \declareEnvarDEP Declare Envar - Deprecated % \declareEnvarRM Declare Envar - Removed % @@ -525,12 +511,6 @@ \InternaldeclareEnvar{#1}{#2}% } -\newcommand{\declareEnvarNEW}[2]{% - {\color{magenta}\code{#1}}% - \index[index_envars]{#1|indexfmt} \label{envar:#1}% - \InternaldeclareEnvar{#1}{#2}% -} - \newcommand{\declareEnvarDEP}[2]{% {\color{green!80!black}\code{#1}}% \index[index_envars]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{envar:#1}% @@ -551,7 +531,6 @@ % % \declareAttribute Declare Attribute % \declareAttributeProvisional Declare Attribute - Provisional -% \declareAttributeNEW Declare Attribute - New % \declareAttributeDEP Declare Attribute - Deprecated % \declareAttributeRM Declare Attribute - Removed % @@ -584,12 +563,6 @@ \InternaldeclareAttributeBody{#1}{#2}{#3}{#4}% } -\newcommand{\declareAttributeNEW}[4]{% - {\color{magenta}\code{#1}} ~~\code{#2}~~(\code{#3})% - \index[index_attribute]{#1|indexfmt} \label{attr:#1}% - \InternaldeclareAttributeBody{#1}{#2}{#3}{#4}% -} - \newcommand{\declareAttributeDEP}[4]{% {\color{green!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% \index[index_attribute]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{attr:#1}% From 47d957880c0d93875dd93792fd86b16fc963017d Mon Sep 17 00:00:00 2001 From: Ken Raffenetti Date: Mon, 24 Oct 2022 16:27:30 -0500 Subject: [PATCH 3/5] Fix typo in v5 revision section Signed-off-by: Ken Raffenetti --- Chap_Revisions.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index d283f4dd..44d2c350 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -1447,7 +1447,7 @@ \section{Version 5.0: TBD} \item Clarify when \refattr{PMIX_PARENT_ID} attribute is provided. \item Clarify the value of \refattr{PMIX_CMD_LINE} attribute in spawn case. \item Clarifications to Terms and Conventions chapter and addition of additional term definitions. - \item Re-organize the presentation of data access, syncronization, reserved keys and non-reserved keys. + \item Re-organize the presentation of data access, synchronization, reserved keys and non-reserved keys. \item Make presentation of return values consistent across APIs. \item Attributes supported by PRRTE are no longer color coded. Refer to PRRTE documentation to see what is supported for a particular PRRTE version. \end{compactitemize} From cd89797a916f9ad51ce35b780870f126d1f4d93e Mon Sep 17 00:00:00 2001 From: Ken Raffenetti Date: Mon, 7 Nov 2022 11:49:58 -0600 Subject: [PATCH 4/5] Add \nameref to Use-Cases appendix Signed-off-by: Ken Raffenetti --- Chap_Revisions.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 44d2c350..02c050b1 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -1438,7 +1438,7 @@ \section{Version 5.0: TBD} Governance v1.7 document\footnote{\url{https://github.com/pmix/governance/releases/tag/v1.7}}. \item Add specific values to constant definitions to ensure consistency across implementations. - \item Add Use-Cases appendix with descriptions for Business Card + \item Add \nameref{app:use-cases} appendix with descriptions for Business Card Exchange, Debugging, Hybrid Applications, MPI Sessions, and Cross-Version Compatibility. \item Add guidance on how PMIx defines an Application Binary Interface (ABI). From c1c35b465c2634224a011c198b3d3a9262c3739a Mon Sep 17 00:00:00 2001 From: Ken Raffenetti Date: Mon, 7 Nov 2022 11:50:41 -0600 Subject: [PATCH 5/5] Add removal of NEW markers to 5.0 revision history Signed-off-by: Ken Raffenetti --- Chap_Revisions.tex | 1 + 1 file changed, 1 insertion(+) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 02c050b1..8692bda1 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -1450,6 +1450,7 @@ \section{Version 5.0: TBD} \item Re-organize the presentation of data access, synchronization, reserved keys and non-reserved keys. \item Make presentation of return values consistent across APIs. \item Attributes supported by PRRTE are no longer color coded. Refer to PRRTE documentation to see what is supported for a particular PRRTE version. + \item NEW markers are removed from item declarations. Refer to \nameref{chap:revisions} to see when something was added. \end{compactitemize} %