From 84113e9514f60c436324efec6ec231b3977cb373 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Mon, 7 Dec 2020 20:53:26 -0600 Subject: [PATCH 01/11] Cleanup deprecated and removed entries in index * The deprecated items appear after the normative items. * The removed items appear after the deprecated items. * All in their respective indicies. * Fix up `check-attr-refs.py` to check for deprecated and removed items that have references in the document which indicates that they were not completely removed. Signed-off-by: Joshua Hursey (cherry picked from commit afb09d4e275ec5756ea5bba2d33e8ab76e4189ef) --- Chap_Revisions.tex | 113 ++++++++++++++++++++--------------------- bin/check-attr-refs.py | 72 +++++++++++++++++++++++--- pmix.sty | 22 +++++++- 3 files changed, 141 insertions(+), 66 deletions(-) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 67cc9b1b..77184b1e 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -78,7 +78,7 @@ \section{Version 2.0: Sept. 2018} \subsection{Removed/Modified \acp{API}} The \refapi{PMIx_Init} \ac{API} was modified in v2.0 of the standard from its \textit{ad hoc} v1.0 signature to include passing of a \refstruct{pmix_info_t} array for flexibility and ``future-proofing'' of the \ac{API}. -In addition, the PMIx_Notify_error, PMIx_Register_errhandler, and PMIx_Deregister_errhandler \acp{API} were replaced. This pre-dated official adoption of \ac{PMIx} as a Standard. +In addition, the \code{PMIx_Notify_error}, \code{PMIx_Register_errhandler}, and \code{PMIx_Deregister_errhandler} \acp{API} were replaced. This pre-dated official adoption of \ac{PMIx} as a Standard. \subsection{Deprecated constants} @@ -210,7 +210,7 @@ \subsection{Removed constants} The following constants were removed in v3.0: -\refconst{PMIX_MODEX} +\refconst{PMIX_MODEX}\\ \refconst{PMIX_INFO_ARRAY} \subsection{Deprecated attributes} @@ -226,43 +226,43 @@ \subsection{Removed attributes} The following attributes were removed in v3.0: % -\declareAttributeDEP{PMIX_ERROR_NAME}{"pmix.errname"}{pmix_status_t}{ +\declareAttributeRM{PMIX_ERROR_NAME}{"pmix.errname"}{pmix_status_t}{ Specific error to be notified } % -\declareAttributeDEP{PMIX_ERROR_GROUP_COMM}{"pmix.errgroup.comm"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_COMM}{"pmix.errgroup.comm"}{bool}{ Set true to get comm errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_ABORT}{"pmix.errgroup.abort"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_ABORT}{"pmix.errgroup.abort"}{bool}{ Set true to get abort errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_MIGRATE}{"pmix.errgroup.migrate"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_MIGRATE}{"pmix.errgroup.migrate"}{bool}{ Set true to get migrate errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_RESOURCE}{"pmix.errgroup.resource"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_RESOURCE}{"pmix.errgroup.resource"}{bool}{ Set true to get resource errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_SPAWN}{"pmix.errgroup.spawn"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_SPAWN}{"pmix.errgroup.spawn"}{bool}{ Set true to get spawn errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_NODE}{"pmix.errgroup.node"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_NODE}{"pmix.errgroup.node"}{bool}{ Set true to get node status notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_LOCAL}{"pmix.errgroup.local"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_LOCAL}{"pmix.errgroup.local"}{bool}{ Set true to get local errors notification } % -\declareAttributeDEP{PMIX_ERROR_GROUP_GENERAL}{"pmix.errgroup.gen"}{bool}{ +\declareAttributeRM{PMIX_ERROR_GROUP_GENERAL}{"pmix.errgroup.gen"}{bool}{ Set true to get notified of generic errors } % -\declareAttributeDEP{PMIX_ERROR_HANDLER_ID}{"pmix.errhandler.id"}{int}{ +\declareAttributeRM{PMIX_ERROR_HANDLER_ID}{"pmix.errhandler.id"}{int}{ Errhandler reference id of notification being reported } @@ -784,79 +784,79 @@ \subsection{Removed constants} \begin{constantdesc} % -\declareconstitemDEP{PMIX_ERR_HANDSHAKE_FAILED} +\declareconstitemRM{PMIX_ERR_HANDSHAKE_FAILED} Connection handshake failed % -\declareconstitemDEP{PMIX_ERR_READY_FOR_HANDSHAKE} +\declareconstitemRM{PMIX_ERR_READY_FOR_HANDSHAKE} Ready for handshake % -\declareconstitemDEP{PMIX_ERR_IN_ERRNO} +\declareconstitemRM{PMIX_ERR_IN_ERRNO} Error defined in \code{errno} % -\declareconstitemDEP{PMIX_ERR_INVALID_VAL_LENGTH} +\declareconstitemRM{PMIX_ERR_INVALID_VAL_LENGTH} Invalid value length % -\declareconstitemDEP{PMIX_ERR_INVALID_LENGTH} +\declareconstitemRM{PMIX_ERR_INVALID_LENGTH} Invalid argument length % -\declareconstitemDEP{PMIX_ERR_INVALID_NUM_ARGS} +\declareconstitemRM{PMIX_ERR_INVALID_NUM_ARGS} Invalid number of arguments % -\declareconstitemDEP{PMIX_ERR_INVALID_ARGS} +\declareconstitemRM{PMIX_ERR_INVALID_ARGS} Invalid arguments % -\declareconstitemDEP{PMIX_ERR_INVALID_NUM_PARSED} +\declareconstitemRM{PMIX_ERR_INVALID_NUM_PARSED} Invalid number parsed % -\declareconstitemDEP{PMIX_ERR_INVALID_KEYVALP} +\declareconstitemRM{PMIX_ERR_INVALID_KEYVALP} Invalid key/value pair % -\declareconstitemDEP{PMIX_ERR_INVALID_SIZE} +\declareconstitemRM{PMIX_ERR_INVALID_SIZE} Invalid size % -\declareconstitemDEP{PMIX_ERR_PROC_REQUESTED_ABORT} +\declareconstitemRM{PMIX_ERR_PROC_REQUESTED_ABORT} Process is already requested to abort % -\declareconstitemDEP{PMIX_ERR_SERVER_FAILED_REQUEST} +\declareconstitemRM{PMIX_ERR_SERVER_FAILED_REQUEST} Failed to connect to the server % -\declareconstitemDEP{PMIX_ERR_PROC_ENTRY_NOT_FOUND} +\declareconstitemRM{PMIX_ERR_PROC_ENTRY_NOT_FOUND} Process not found % -\declareconstitemDEP{PMIX_ERR_INVALID_ARG} +\declareconstitemRM{PMIX_ERR_INVALID_ARG} Invalid argument % -\declareconstitemDEP{PMIX_ERR_INVALID_KEY} +\declareconstitemRM{PMIX_ERR_INVALID_KEY} Invalid key % -\declareconstitemDEP{PMIX_ERR_INVALID_KEY_LENGTH} +\declareconstitemRM{PMIX_ERR_INVALID_KEY_LENGTH} Invalid key length % -\declareconstitemDEP{PMIX_ERR_INVALID_VAL} +\declareconstitemRM{PMIX_ERR_INVALID_VAL} Invalid value % -\declareconstitemDEP{PMIX_ERR_INVALID_NAMESPACE} +\declareconstitemRM{PMIX_ERR_INVALID_NAMESPACE} Invalid namespace % -\declareconstitemDEP{PMIX_ERR_SERVER_NOT_AVAIL} +\declareconstitemRM{PMIX_ERR_SERVER_NOT_AVAIL} Server is not available % -\declareconstitemDEP{PMIX_ERR_SILENT} +\declareconstitemRM{PMIX_ERR_SILENT} Silent error % -\declareconstitemDEP{PMIX_ERR_PACK_MISMATCH} +\declareconstitemRM{PMIX_ERR_PACK_MISMATCH} Pack mismatch % -\declareconstitemDEP{PMIX_ERR_DATA_VALUE_NOT_FOUND} +\declareconstitemRM{PMIX_ERR_DATA_VALUE_NOT_FOUND} Data value not found % -\declareconstitemDEP{PMIX_ERR_NOT_IMPLEMENTED} +\declareconstitemRM{PMIX_ERR_NOT_IMPLEMENTED} Not implemented % -\declareconstitemDEP{PMIX_GDS_ACTION_COMPLETE} +\declareconstitemRM{PMIX_GDS_ACTION_COMPLETE} The \ac{GDS} action has completed % -\declareconstitemDEP{PMIX_NOTIFY_ALLOC_COMPLETE} +\declareconstitemRM{PMIX_NOTIFY_ALLOC_COMPLETE} Notify that a requested allocation operation is complete - the result of the request will be included in the \refarg{info} array % @@ -928,83 +928,82 @@ \subsection{Removed attributes} description. % -\declareAttributeDEP{PMIX_LOCAL_TOPO}{"pmix.ltopo"}{char*}{ +\declareAttributeRM{PMIX_LOCAL_TOPO}{"pmix.ltopo"}{char*}{ \ac{XML} representation of local node topology. } % -\declareAttributeDEP{PMIX_TOPOLOGY_XML}{"pmix.topo.xml"}{char*}{ +\declareAttributeRM{PMIX_TOPOLOGY_XML}{"pmix.topo.xml"}{char*}{ \ac{XML}-based description of topology } % -\declareAttributeDEP{PMIX_TOPOLOGY_FILE}{"pmix.topo.file"}{char*}{ +\declareAttributeRM{PMIX_TOPOLOGY_FILE}{"pmix.topo.file"}{char*}{ Full path to file containing \ac{XML} topology description } % -\declareAttributeDEP{PMIX_TOPOLOGY_SIGNATURE}{"pmix.toposig"}{char*}{ +\declareAttributeRM{PMIX_TOPOLOGY_SIGNATURE}{"pmix.toposig"}{char*}{ Topology signature string. } % -\declareAttributeDEP{PMIX_HWLOC_SHMEM_ADDR}{"pmix.hwlocaddr"}{size_t}{ +\declareAttributeRM{PMIX_HWLOC_SHMEM_ADDR}{"pmix.hwlocaddr"}{size_t}{ Address of the HWLOC shared memory segment. } % -\declareAttributeDEP{PMIX_HWLOC_SHMEM_SIZE}{"pmix.hwlocsize"}{size_t}{ +\declareAttributeRM{PMIX_HWLOC_SHMEM_SIZE}{"pmix.hwlocsize"}{size_t}{ Size of the HWLOC shared memory segment. } % -\declareAttributeDEP{PMIX_HWLOC_SHMEM_FILE}{"pmix.hwlocfile"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_SHMEM_FILE}{"pmix.hwlocfile"}{char*}{ Path to the HWLOC shared memory file. } % -\declareAttributeDEP{PMIX_HWLOC_XML_V1}{"pmix.hwlocxml1"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_XML_V1}{"pmix.hwlocxml1"}{char*}{ \ac{XML} representation of local topology using HWLOC's v1.x format. } % -\declareAttributeDEP{PMIX_HWLOC_XML_V2}{"pmix.hwlocxml2"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_XML_V2}{"pmix.hwlocxml2"}{char*}{ \ac{XML} representation of local topology using HWLOC's v2.x format. } % -\declareAttributeDEP{PMIX_HWLOC_SHARE_TOPO}{"pmix.hwlocsh"}{bool}{ +\declareAttributeRM{PMIX_HWLOC_SHARE_TOPO}{"pmix.hwlocsh"}{bool}{ Share the HWLOC topology via shared memory } % -\declareAttributeDEP{PMIX_HWLOC_HOLE_KIND}{"pmix.hwlocholek"}{char*}{ +\declareAttributeRM{PMIX_HWLOC_HOLE_KIND}{"pmix.hwlocholek"}{char*}{ Kind of VM ``hole'' HWLOC should use for shared memory } % -\declareAttributeDEP{PMIX_DSTPATH}{"pmix.dstpath"}{char*}{ +\declareAttributeRM{PMIX_DSTPATH}{"pmix.dstpath"}{char*}{ Path to shared memory data storage (dstore) files. Deprecated from Standard as being implementation specific. } % -\declareAttributeDEP{PMIX_COLLECTIVE_ALGO}{"pmix.calgo"}{char*}{ +\declareAttributeRM{PMIX_COLLECTIVE_ALGO}{"pmix.calgo"}{char*}{ Comma-delimited list of algorithms to use for the collective operation. \ac{PMIx} does not impose any requirements on a host environment's collective algorithms. Thus, the acceptable values for this attribute will be environment-dependent - users are encouraged to check their host environment for supported values. } % \pasteAttributeItemBegin{PMIX_COLLECTIVE_ALGO_REQD}This attribute was deprecated in v3.0 \pasteAttributeItemEnd{} % -\declareAttributeDEP{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ +\declareAttributeRM{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ Packed blob of process data. } % -\declareAttributeDEP{PMIX_MAP_BLOB}{"pmix.mblob"}{pmix_byte_object_t}{ +\declareAttributeRM{PMIX_MAP_BLOB}{"pmix.mblob"}{pmix_byte_object_t}{ Packed blob of process location. } % -\declareAttributeDEP{PMIX_MAPPER}{"pmix.mapper"}{char*}{ +\declareAttributeRM{PMIX_MAPPER}{"pmix.mapper"}{char*}{ Mapping mechanism to use for placing spawned processes - when accessed using \refapi{PMIx_Get}, use the \refconst{PMIX_RANK_WILDCARD} value for the rank to discover the mapping mechanism used for the provided namespace. } % -\declareAttributeDEP{PMIX_NON_PMI}{"pmix.nonpmi"}{bool}{ +\declareAttributeRM{PMIX_NON_PMI}{"pmix.nonpmi"}{bool}{ Spawned processes will not call \refapi{PMIx_Init}. } % -\declareAttributeDEP{PMIX_PROC_URI}{"pmix.puri"}{char*}{ +\declareAttributeRM{PMIX_PROC_URI}{"pmix.puri"}{char*}{ \ac{URI} containing contact information for the specified process. } - % -\declareAttributeDEP{PMIX_ARCH}{"pmix.arch"}{uint32_t}{ +\declareAttributeRM{PMIX_ARCH}{"pmix.arch"}{uint32_t}{ Architecture flag. } diff --git a/bin/check-attr-refs.py b/bin/check-attr-refs.py index 1eb68285..c937bd10 100755 --- a/bin/check-attr-refs.py +++ b/bin/check-attr-refs.py @@ -10,8 +10,11 @@ if __name__ == "__main__": count_not_used = 0 + count_dep_refs = 0 + count_rm_refs = 0 attr_declared = {} deprecated_attr = [] + removed_attr = [] index_files = ["pmix-standard.idx", "index_attribute.idx"] # @@ -19,6 +22,7 @@ # parser = argparse.ArgumentParser(description="PMIx Standard Attribute Reference Check") parser.add_argument("-v", "--verbose", help="Verbose output", action="store_true") + parser.add_argument("-f", "--fyi", help="FYI References (not errors)", action="store_true") parser.parse_args() args = parser.parse_args() @@ -27,7 +31,7 @@ # # Verify that we have the necessary files in the current working directory # * pmix-standard.aux - # * pmix-standard.idx + # * index_files - see above # missing_index = False for fname in index_files: @@ -89,7 +93,7 @@ if args.verbose is True: print("Processing Index File: "+fname) - p = subprocess.Popen("grep \"\\|hyperindexformat\" "+fname, + p = subprocess.Popen("grep \"hyperindexformat{\" "+fname+" | sort", stdout=subprocess.PIPE, stderr=subprocess.STDOUT, shell=True, close_fds=True) sout = p.communicate()[0].decode("utf-8").splitlines() @@ -99,6 +103,7 @@ for line in sout: line = line.rstrip() + m = re.match(r'\s*\\indexentry{(\w+)', line) if m is None: print("Error: Failed to extract an attribute on the following line") @@ -107,12 +112,25 @@ else: attr_to_find = m.group(1) + # Some index entries have a prefix on them for sorting order, so + # access the actual printed string not the sorting version of + # the string. + m2 = re.match(r'\s*\\indexentry{(\w+)@(\w+)', line) + if m2 is not None: + attr_to_find = m2.group(2) + # Check to see if this is deprecated - if re.search("indexdepfmt", line) is not None: + if re.search("(Deprecated)", line) is not None: if args.verbose is True: print("Found a Deprecated Attribute: "+attr_to_find) deprecated_attr.insert(0, attr_to_find) + # Check to see if this is removed + if re.search("(Removed)", line) is not None: + if args.verbose is True: + print("Found a Removed Attribute: "+attr_to_find) + removed_attr.insert(0, attr_to_find) + if attr_to_find in attr_declared: attr_declared[attr_to_find] = attr_declared[attr_to_find] + 1 p.wait() @@ -128,6 +146,7 @@ if err_out is True: print("-"*50) print("Number of deprecated attributes: " + str(len(deprecated_attr))) + print("Number of removed attributes : " + str(len(removed_attr))) print("Number of declared attributes : " + str(len(attr_declared))) print("Number of missing attributes : " + str(num_missing)) sys.exit(1) @@ -183,12 +202,51 @@ # for attr in sorted(attr_declared): if attr_declared[attr] <= 0: - if attr not in deprecated_attr and attr != "PMIX_ATTR_UNDEF": + if attr not in deprecated_attr and attr not in removed_attr and attr != "PMIX_ATTR_UNDEF": print("Attribute Missing Reference: "+attr) count_not_used += 1 - elif args.verbose is True and attr != "PMIX_ATTR_UNDEF": - print("=====> Deprecated Attribute Missing Reference: "+attr) + elif attr in deprecated_attr and attr in removed_attr and attr_declared[attr] == 1: + # There is an entry for the deprecation and the removal. This is fine + continue + elif attr in deprecated_attr or attr in removed_attr: + # Allow references within the Chap_Revisions.tex - count them + num_in_chap_revisions = 0 + p = subprocess.Popen("grep \"refattr{"+attr+"}\" Chap_Revisions.tex | wc -l", + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, shell=True, close_fds=True) + sout = p.communicate()[0].decode("utf-8").splitlines() + if p.returncode != 0: + print("Error: Failed to verify declared attribute \""+attr+"\". grep error code "+str(p.returncode)+""); + sys.exit(2) + for line in sout: + line = line.rstrip() + num_in_chap_revisions = int(line) + + # Extra increment for deprecated and removed items + if attr in deprecated_attr and attr in removed_attr: + num_in_chap_revisions += 1 + # If there are other references outside of the Revisions chapter then error out + if attr_declared[attr] - num_in_chap_revisions > 0: + if attr in deprecated_attr: + print("Deprecated Attribute: "+attr+" (Referenced "+str(attr_declared[attr]-num_in_chap_revisions)+" times)") + count_dep_refs += 1 + elif attr in removed_attr: + print("Removed Attribute: "+attr+" (Referenced "+str(attr_declared[attr]-num_in_chap_revisions)+" times)") + count_rm_refs += 1 + # + # Additional analysis for optional, non-error reporting + # + if args.fyi is True: + for attr in sorted(removed_attr): + if attr not in deprecated_attr: + print("Removed attribute that was not deprecated: "+attr); + + # + # Final summary + # print("%3d of %3d Attributes are missing reference" % (count_not_used, len(attr_declared))) - sys.exit(count_not_used) + print("%3d of %3d Deprecated Attributes with references remaining" % (count_dep_refs, len(deprecated_attr))) + print("%3d of %3d Removed Attributes with references remaining" % (count_rm_refs, len(removed_attr))) + + sys.exit(count_not_used + count_dep_refs + count_rm_refs) diff --git a/pmix.sty b/pmix.sty index d89b5bef..ca792ba2 100644 --- a/pmix.sty +++ b/pmix.sty @@ -138,6 +138,8 @@ \newcommand{\indexfmt}[1]{\textbf{\underline{#1}}} % Formatting for deprecated items in the index \newcommand{\indexdepfmt}[1]{\textbf{\underline{#1}}} +% Formatting for removed items in the index +\newcommand{\indexrmfmt}[1]{\textbf{\underline{#1}}} % \url styled in Roman font. @@ -247,8 +249,12 @@ \newcommand{\declareconstitem}[1]{\item[\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} \newcommand{\declareconstitemvalue}[2]{\item[\code{#1}] \index[index_const]{#1|indexfmt} \hspace{0.25em} \code{#2} \hspace{1em}} -\newcommand{\declareconstitemDEP}[1]{\item[\color{green!80!black}\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} +% New in this version \newcommand{\declareconstitemNEW}[1]{\item[\color{magenta}\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} +% Deprecated +\newcommand{\declareconstitemDEP}[1]{\item[\color{green!80!black}\code{#1}] \index[index_const]{Y_#1@\emph{#1} (Deprecated)|indexdepfmt} \label{const:#1} \hspace{1em}} +% Removed +\newcommand{\declareconstitemRM}[1]{\item[\color{red!80!black}\code{#1}] \index[index_const]{Z_#1@\emph{#1} (Removed)|indexrmfmt} \label{const:#1} \hspace{1em}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -428,7 +434,19 @@ \newcommand{\declareAttributeDEP}[4]{% {\color{green!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% - \index[index_attribute]{#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{attr:#1}% + \index[index_attribute]{Y_#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{attr:#1}% + \StdCopy{str:#1}{\code{#2}}% + \StdCopy{attr:#1}{\code{#3}}% + \vspace{-1.3ex}% + \expandafter\begin{adjustwidth}{.95cm}{}% + \StdCopyEcho{#1}{#4}% + \end{adjustwidth}% + \vspace{-1.3ex}% +} + +\newcommand{\declareAttributeRM}[4]{% + {\color{red!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% + \index[index_attribute]{Z_#1@#1 \textbf{(Removed)}|indexdepfmt} \label{attr:#1}% \StdCopy{str:#1}{\code{#2}}% \StdCopy{attr:#1}{\code{#3}}% \vspace{-1.3ex}% From fdd038116f801f35c4be0d5496d053e330589be8 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Mon, 7 Dec 2020 21:25:52 -0600 Subject: [PATCH 02/11] Fix a few removed references * Fix PMIX_COLLECTIVE_ALGO_REQD removal reference * Remove PMIX_MAPPER references * Remove PMIX_NON_PMI references * Remove PMIX_PROC_URI references Signed-off-by: Joshua Hursey (cherry picked from commit 2fb4eb207ee90da9dc109e13b9b74286e704412d) --- Chap_API_Proc_Mgmt.tex | 2 +- Chap_API_Server.tex | 2 -- Chap_API_Sync_Access.tex | 4 ---- Chap_Revisions.tex | 5 +++-- 4 files changed, 4 insertions(+), 9 deletions(-) diff --git a/Chap_API_Proc_Mgmt.tex b/Chap_API_Proc_Mgmt.tex index 330cd075..3cb67919 100644 --- a/Chap_API_Proc_Mgmt.tex +++ b/Chap_API_Proc_Mgmt.tex @@ -335,7 +335,7 @@ \subsection{Spawn-specific constants} \subsection{Spawn attributes} \label{api:struct:attributes:spawn} -Attributes used to describe \refapi{PMIx_Spawn} behavior - they are values passed to the \refapi{PMIx_Spawn} \ac{API} and therefore are not accessed using the \refapi{PMIx_Get} \acp{API} when used in that context. However, some of the attributes defined in this section can be provided by the host environment for other purposes - e.g., the host might provide the \refattr{PMIX_MAPPER} attribute in the job-related information so that an application can use \refapi{PMIx_Get} to discover the layout algorithm used for determining process locations. Multi-use attributes and their respective access reference rank are denoted below. +Attributes used to describe \refapi{PMIx_Spawn} behavior - they are values passed to the \refapi{PMIx_Spawn} \ac{API} and therefore are not accessed using the \refapi{PMIx_Get} \acp{API} when used in that context. However, some of the attributes defined in this section can be provided by the host environment for other purposes - e.g., the host might provide the \refattr{PMIX_MAPBY} attribute in the job-related information so that an application can use \refapi{PMIx_Get} to discover the mapping used for determining process locations. Multi-use attributes and their respective access reference rank are denoted below. % \declareAttribute{PMIX_PERSONALITY}{"pmix.pers"}{char*}{ diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 3f2544a1..9db3ddbc 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -2832,13 +2832,11 @@ \subsection{\code{pmix_server_spawn_fn_t}} \pasteAttributeItem{PMIX_PRELOAD_BIN} \pasteAttributeItem{PMIX_PRELOAD_FILES} \pasteAttributeItem{PMIX_PERSONALITY} -\pasteAttributeItem{PMIX_MAPPER} \pasteAttributeItem{PMIX_DISPLAY_MAP} \pasteAttributeItem{PMIX_PPR} \pasteAttributeItem{PMIX_MAPBY} \pasteAttributeItem{PMIX_RANKBY} \pasteAttributeItem{PMIX_BINDTO} -\pasteAttributeItem{PMIX_NON_PMI} \pasteAttributeItem{PMIX_STDIN_TGT} \pasteAttributeItem{PMIX_FWD_STDIN} \pasteAttributeItem{PMIX_FWD_STDOUT} diff --git a/Chap_API_Sync_Access.tex b/Chap_API_Sync_Access.tex index abb7e0bf..9cd61933 100644 --- a/Chap_API_Sync_Access.tex +++ b/Chap_API_Sync_Access.tex @@ -556,8 +556,6 @@ \subsection{\code{PMIx_Query_info}} \pasteAttributeItem{PMIX_TIME_REMAINING} \pasteAttributeItemBegin{PMIX_SERVER_URI} Requests the URI of the specified \ac{PMIx} server's \ac{PMIx} connection. Defaults to requesting the information for the local \ac{PMIx} server. \pasteAttributeItemEnd -\pasteAttributeItemBegin{PMIX_PROC_URI} Requests the URI of the specified \ac{PMIx} server's out-of-band connection. Defaults to requesting the information for the local \ac{PMIx} server. -\pasteAttributeItemEnd \pasteAttributeItem{PMIX_CLIENT_AVG_MEMORY} \pasteAttributeItem{PMIX_DAEMON_MEMORY} \pasteAttributeItem{PMIX_QUERY_AUTHORIZATIONS} @@ -676,8 +674,6 @@ \subsection{\code{PMIx_Query_info_nb}} \pasteAttributeItem{PMIX_TIME_REMAINING} \pasteAttributeItemBegin{PMIX_SERVER_URI} Requests the URI of the specified \ac{PMIx} server's \ac{PMIx} connection. Defaults to requesting the information for the local \ac{PMIx} server. \pasteAttributeItemEnd -\pasteAttributeItemBegin{PMIX_PROC_URI} Requests the URI of the specified \ac{PMIx} server's out-of-band connection. Defaults to requesting the information for the local \ac{PMIx} server. -\pasteAttributeItemEnd \pasteAttributeItem{PMIX_CLIENT_AVG_MEMORY} \pasteAttributeItem{PMIX_DAEMON_MEMORY} \pasteAttributeItem{PMIX_QUERY_AUTHORIZATIONS} diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 77184b1e..c174ed2a 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -980,8 +980,9 @@ \subsection{Removed attributes} Comma-delimited list of algorithms to use for the collective operation. \ac{PMIx} does not impose any requirements on a host environment's collective algorithms. Thus, the acceptable values for this attribute will be environment-dependent - users are encouraged to check their host environment for supported values. } % -\pasteAttributeItemBegin{PMIX_COLLECTIVE_ALGO_REQD}This attribute was deprecated in v3.0 -\pasteAttributeItemEnd{} +\declareAttributeRM{PMIX_COLLECTIVE_ALGO_REQD}{"pmix.calreqd"}{bool}{ +If \code{true}, indicates that the requested choice of algorithm is mandatory. +} % \declareAttributeRM{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ Packed blob of process data. From 3224807d76fcb1ff79782c3b0823756bac0ba333 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Tue, 8 Dec 2020 10:00:24 -0600 Subject: [PATCH 03/11] Add deprecation markers for v3.2 items removed in v4 Signed-off-by: Joshua Hursey (cherry picked from commit a3ff5eb2c9cb6b2e44484ffba042e65b5010385d) --- Chap_Revisions.tex | 84 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index c174ed2a..9a4f09d2 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -303,6 +303,90 @@ \section{Version 3.2: Oct. 2020} \item Add a new \refconst{PMIX_REGEX} constant that represents a regular expression data type. \end{compactitemize} + +\subsection{Deprecated attributes} + +The following attributes were deprecated in v3.2: + +\declareAttributeDEP{PMIX_ARCH}{"pmix.arch"}{uint32_t}{ +Architecture flag. +} +% +\declareAttributeDEP{PMIX_COLLECTIVE_ALGO}{"pmix.calgo"}{char*}{ +Comma-delimited list of algorithms to use for the collective operation. \ac{PMIx} does not impose any requirements on a host environment's collective algorithms. Thus, the acceptable values for this attribute will be environment-dependent - users are encouraged to check their host environment for supported values. +} +% +\declareAttributeDEP{PMIX_DSTPATH}{"pmix.dstpath"}{char*}{ +Path to shared memory data storage (dstore) files. Deprecated from Standard as being implementation specific. +} +% +\declareAttributeDEP{PMIX_HWLOC_HOLE_KIND}{"pmix.hwlocholek"}{char*}{ +Kind of VM ``hole'' HWLOC should use for shared memory +} +% +\declareAttributeDEP{PMIX_HWLOC_SHARE_TOPO}{"pmix.hwlocsh"}{bool}{ +Share the HWLOC topology via shared memory +} +% +\declareAttributeDEP{PMIX_HWLOC_SHMEM_ADDR}{"pmix.hwlocaddr"}{size_t}{ +Address of the HWLOC shared memory segment. +} +% +\declareAttributeDEP{PMIX_HWLOC_SHMEM_FILE}{"pmix.hwlocfile"}{char*}{ +Path to the HWLOC shared memory file. +} +% +\declareAttributeDEP{PMIX_HWLOC_SHMEM_SIZE}{"pmix.hwlocsize"}{size_t}{ +Size of the HWLOC shared memory segment. +} +% +\declareAttributeDEP{PMIX_HWLOC_XML_V1}{"pmix.hwlocxml1"}{char*}{ +\ac{XML} representation of local topology using HWLOC's v1.x format. +} +% +\declareAttributeDEP{PMIX_HWLOC_XML_V2}{"pmix.hwlocxml2"}{char*}{ +\ac{XML} representation of local topology using HWLOC's v2.x format. +} +% +\declareAttributeDEP{PMIX_LOCAL_TOPO}{"pmix.ltopo"}{char*}{ +\ac{XML} representation of local node topology. +} +% +\declareAttributeDEP{PMIX_MAPPER}{"pmix.mapper"}{char*}{ +Mapping mechanism to use for placing spawned processes - when accessed using \refapi{PMIx_Get}, use the \refconst{PMIX_RANK_WILDCARD} value for the rank to discover the mapping mechanism used for the provided namespace. +} +% +\declareAttributeDEP{PMIX_MAP_BLOB}{"pmix.mblob"}{pmix_byte_object_t}{ +Packed blob of process location. +} +% +\declareAttributeDEP{PMIX_NON_PMI}{"pmix.nonpmi"}{bool}{ +Spawned processes will not call \refapi{PMIx_Init}. +} +% +\declareAttributeDEP{PMIX_PROC_BLOB}{"pmix.pblob"}{pmix_byte_object_t}{ +Packed blob of process data. +} +% +\declareAttributeDEP{PMIX_PROC_URI}{"pmix.puri"}{char*}{ +\ac{URI} containing contact information for the specified process. +} +% +\declareAttributeDEP{PMIX_TOPOLOGY_FILE}{"pmix.topo.file"}{char*}{ +Full path to file containing \ac{XML} topology description +} +% +\declareAttributeDEP{PMIX_TOPOLOGY_SIGNATURE}{"pmix.toposig"}{char*}{ +Topology signature string. +} +% +\declareAttributeDEP{PMIX_TOPOLOGY_XML}{"pmix.topo.xml"}{char*}{ +\ac{XML}-based description of topology +} +% + + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%% History: Version 4.0 \section{Version 4.0: Nov. 2020} From 1f1859c6a1444fb1e2122f9dba570a7aead63f82 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Tue, 8 Dec 2020 10:26:18 -0600 Subject: [PATCH 04/11] Make removed but not deprecated an error state in the check. Signed-off-by: Joshua Hursey (cherry picked from commit 203cb5c9f7ead376d0056a0456593debb2cc8134) --- bin/check-attr-refs.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/bin/check-attr-refs.py b/bin/check-attr-refs.py index c937bd10..93f9c112 100755 --- a/bin/check-attr-refs.py +++ b/bin/check-attr-refs.py @@ -22,7 +22,6 @@ # parser = argparse.ArgumentParser(description="PMIx Standard Attribute Reference Check") parser.add_argument("-v", "--verbose", help="Verbose output", action="store_true") - parser.add_argument("-f", "--fyi", help="FYI References (not errors)", action="store_true") parser.parse_args() args = parser.parse_args() @@ -235,13 +234,13 @@ count_rm_refs += 1 # - # Additional analysis for optional, non-error reporting + # Additional analysis for removed, but not deprecated items # - if args.fyi is True: - for attr in sorted(removed_attr): - if attr not in deprecated_attr: - print("Removed attribute that was not deprecated: "+attr); - + for attr in sorted(removed_attr): + if attr not in deprecated_attr: + print("Removed attribute that was not deprecated: "+attr); + count_rm_refs += 1 + # # Final summary # From 7fec39a72ba855898697940e3b39c534a4942728 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Tue, 8 Dec 2020 12:15:24 -0600 Subject: [PATCH 05/11] Fix grouping of deprecated/removed in the index Signed-off-by: Joshua Hursey (cherry picked from commit 1cb899c1ce0220d8e4a03b7f9e1eac1e9f6213c5) --- bin/check-attr-refs.py | 8 ++++++-- pmix.sty | 20 +++++++++++++++----- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/bin/check-attr-refs.py b/bin/check-attr-refs.py index 93f9c112..44085479 100755 --- a/bin/check-attr-refs.py +++ b/bin/check-attr-refs.py @@ -117,15 +117,19 @@ m2 = re.match(r'\s*\\indexentry{(\w+)@(\w+)', line) if m2 is not None: attr_to_find = m2.group(2) + else: + m2 = re.match(r'\s*\\indexentry{(\w+)@\\emph\s*{(\w+)', line) + if m2 is not None: + attr_to_find = m2.group(2) # Check to see if this is deprecated - if re.search("(Deprecated)", line) is not None: + if re.search("Deprecated", line) is not None: if args.verbose is True: print("Found a Deprecated Attribute: "+attr_to_find) deprecated_attr.insert(0, attr_to_find) # Check to see if this is removed - if re.search("(Removed)", line) is not None: + if re.search("Removed", line) is not None: if args.verbose is True: print("Found a Removed Attribute: "+attr_to_find) removed_attr.insert(0, attr_to_find) diff --git a/pmix.sty b/pmix.sty index ca792ba2..d7686acc 100644 --- a/pmix.sty +++ b/pmix.sty @@ -252,9 +252,9 @@ % New in this version \newcommand{\declareconstitemNEW}[1]{\item[\color{magenta}\code{#1}] \index[index_const]{#1|indexfmt} \label{const:#1} \hspace{1em}} % Deprecated -\newcommand{\declareconstitemDEP}[1]{\item[\color{green!80!black}\code{#1}] \index[index_const]{Y_#1@\emph{#1} (Deprecated)|indexdepfmt} \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} \hspace{1em}} % Removed -\newcommand{\declareconstitemRM}[1]{\item[\color{red!80!black}\code{#1}] \index[index_const]{Z_#1@\emph{#1} (Removed)|indexrmfmt} \label{const:#1} \hspace{1em}} +\newcommand{\declareconstitemRM}[1]{\item[\color{red!80!black}\code{#1}] \index[index_const]{Z_#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{const:#1} \hspace{1em}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -391,7 +391,17 @@ \newcommand{\declareEnvarDEP}[2]{% {\color{green!80!black}\code{#1}}% - \index[index_envars]{#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{envar:#1}% + \index[index_envars]{#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{envar:#1}% + \vspace{-1.3ex}% + \expandafter\begin{adjustwidth}{.95cm}{}% + \StdCopyEcho{#1}{#2}% + \end{adjustwidth}% + \vspace{-1.3ex}% +} + +\newcommand{\declareEnvarRM}[2]{% + {\color{green!80!black}\code{#1}}% + \index[index_envars]{#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{envar:#1}% \vspace{-1.3ex}% \expandafter\begin{adjustwidth}{.95cm}{}% \StdCopyEcho{#1}{#2}% @@ -434,7 +444,7 @@ \newcommand{\declareAttributeDEP}[4]{% {\color{green!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% - \index[index_attribute]{Y_#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{attr:#1}% + \index[index_attribute]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{attr:#1}% \StdCopy{str:#1}{\code{#2}}% \StdCopy{attr:#1}{\code{#3}}% \vspace{-1.3ex}% @@ -446,7 +456,7 @@ \newcommand{\declareAttributeRM}[4]{% {\color{red!80!black}\code{#1}} ~~\code{#2}~~(\code{#3})% - \index[index_attribute]{Z_#1@#1 \textbf{(Removed)}|indexdepfmt} \label{attr:#1}% + \index[index_attribute]{Z_#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{attr:#1}% \StdCopy{str:#1}{\code{#2}}% \StdCopy{attr:#1}{\code{#3}}% \vspace{-1.3ex}% From 34128de0703172a6f332e1886b1590a9653e55cc Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Thu, 10 Dec 2020 12:35:01 -0600 Subject: [PATCH 06/11] Fix constants removed but not deprecated Signed-off-by: Joshua Hursey (cherry picked from commit 121880ce0f609d095e0b9308d2cb6297e99c805a) --- Chap_Revisions.tex | 87 +++++++++++++++++++++++++++++++++++++- bin/check-multi-declare.py | 3 +- 2 files changed, 88 insertions(+), 2 deletions(-) diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index 9a4f09d2..e122849d 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -304,6 +304,91 @@ \section{Version 3.2: Oct. 2020} \end{compactitemize} +\subsection{Deprecated constants} + +The following constants were deprecated in v3.2: + +\begin{constantdesc} +% +\declareconstitemDEP{PMIX_ERR_DATA_VALUE_NOT_FOUND} +Data value not found +% +\declareconstitemDEP{PMIX_ERR_HANDSHAKE_FAILED} +Connection handshake failed +% +\declareconstitemDEP{PMIX_ERR_IN_ERRNO} +Error defined in \code{errno} +% +\declareconstitemDEP{PMIX_ERR_INVALID_ARG} +Invalid argument +% +\declareconstitemDEP{PMIX_ERR_INVALID_ARGS} +Invalid arguments +% +\declareconstitemDEP{PMIX_ERR_INVALID_KEY} +Invalid key +% +\declareconstitemDEP{PMIX_ERR_INVALID_KEY_LENGTH} +Invalid key length +% +\declareconstitemDEP{PMIX_ERR_INVALID_KEYVALP} +Invalid key/value pair +% +\declareconstitemDEP{PMIX_ERR_INVALID_LENGTH} +Invalid argument length +% +\declareconstitemDEP{PMIX_ERR_INVALID_NAMESPACE} +Invalid namespace +% +\declareconstitemDEP{PMIX_ERR_INVALID_NUM_ARGS} +Invalid number of arguments +% +\declareconstitemDEP{PMIX_ERR_INVALID_NUM_PARSED} +Invalid number parsed +% +\declareconstitemDEP{PMIX_ERR_INVALID_SIZE} +Invalid size +% +\declareconstitemDEP{PMIX_ERR_INVALID_VAL} +Invalid value +% +\declareconstitemDEP{PMIX_ERR_INVALID_VAL_LENGTH} +Invalid value length +% +\declareconstitemDEP{PMIX_ERR_NOT_IMPLEMENTED} +Not implemented +% +\declareconstitemDEP{PMIX_ERR_PACK_MISMATCH} +Pack mismatch +% +\declareconstitemDEP{PMIX_ERR_PROC_ENTRY_NOT_FOUND} +Process not found +% +\declareconstitemDEP{PMIX_ERR_PROC_REQUESTED_ABORT} +Process is already requested to abort +% +\declareconstitemDEP{PMIX_ERR_READY_FOR_HANDSHAKE} +Ready for handshake +% +\declareconstitemDEP{PMIX_ERR_SERVER_FAILED_REQUEST} +Failed to connect to the server +% +\declareconstitemDEP{PMIX_ERR_SERVER_NOT_AVAIL} +Server is not available +% +\declareconstitemDEP{PMIX_ERR_SILENT} +Silent error +% +\declareconstitemDEP{PMIX_GDS_ACTION_COMPLETE} +The \ac{GDS} action has completed +% +\declareconstitemDEP{PMIX_NOTIFY_ALLOC_COMPLETE} +Notify that a requested allocation operation is complete - the result of +the request will be included in the \refarg{info} array +% +\end{constantdesc} + + \subsection{Deprecated attributes} The following attributes were deprecated in v3.2: @@ -867,7 +952,7 @@ \subsection{Removed constants} as they are internal to a particular \ac{PMIx} implementation. \begin{constantdesc} -% +%!TEX encoding = UTF-8 Unicode \declareconstitemRM{PMIX_ERR_HANDSHAKE_FAILED} Connection handshake failed % diff --git a/bin/check-multi-declare.py b/bin/check-multi-declare.py index 9291dd74..584a3f97 100755 --- a/bin/check-multi-declare.py +++ b/bin/check-multi-declare.py @@ -39,7 +39,8 @@ print("-"*50) # subsection.A is Appendix A: Python Bindings - p = subprocess.Popen("grep \"newlabel{"+ref_str+"\" pmix-standard.aux | grep -v subsection.A", + # subsection.B is Appendix B: Revision History + p = subprocess.Popen("grep \"newlabel{"+ref_str+"\" pmix-standard.aux | grep -v \"subsection.A\|subsection.B\"", stdout=subprocess.PIPE, stderr=subprocess.STDOUT, shell=True, close_fds=True) sout = p.communicate()[0].decode("utf-8").splitlines() if p.returncode != 0: From 2964b7944e3d0c45144485e106200b58625ec366 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Fri, 11 Dec 2020 20:21:37 -0600 Subject: [PATCH 07/11] Replace deprecated refs to PMIx_tool_connect_to_server with new PMIx_tool_attach_to_server Signed-off-by: Joshua Hursey (cherry picked from commit 446c5fe74755eb8d8d84a5d57df24d96397694e9) --- Chap_API_Sync_Access.tex | 2 +- Chap_API_Tools.tex | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Chap_API_Sync_Access.tex b/Chap_API_Sync_Access.tex index 9cd61933..fd2c7d15 100644 --- a/Chap_API_Sync_Access.tex +++ b/Chap_API_Sync_Access.tex @@ -1022,7 +1022,7 @@ \section{Using Get vs Query} \section{Accessing attribute support information} \label{chap:api_job_mgmt:queryattrs} -Information as to which attributes are supported by either the \ac{PMIx} implementation or its host environment can be obtained via the \refapi{PMIx_Query_info} \acp{API}. The \refattr{PMIX_QUERY_ATTRIBUTE_SUPPORT} attribute must be listed as the first entry in the \refarg{keys} field of the \refstruct{pmix_query_t} structure, followed by the name of the function whose attribute support is being requested - support for multiple functions can be requested simultaneously by simply adding the function names to the array of \refarg{keys}. Function names \emph{must} be given as user-level \ac{API} names - e.g., ``PMIx_Get'', ``PMIx_server_setup_application'', or ``PMIx_tool_connect_to_server''. +Information as to which attributes are supported by either the \ac{PMIx} implementation or its host environment can be obtained via the \refapi{PMIx_Query_info} \acp{API}. The \refattr{PMIX_QUERY_ATTRIBUTE_SUPPORT} attribute must be listed as the first entry in the \refarg{keys} field of the \refstruct{pmix_query_t} structure, followed by the name of the function whose attribute support is being requested - support for multiple functions can be requested simultaneously by simply adding the function names to the array of \refarg{keys}. Function names \emph{must} be given as user-level \ac{API} names - e.g., ``PMIx_Get'', ``PMIx_server_setup_application'', or ``PMIx_tool_attach_to_server''. The desired levels of attribute support are provided as qualifiers. Multiple levels can be requested simultaneously by simply adding elements to the \refarg{qualifiers} array. Each qualifier should contain the desired level attribute with the boolean value set to indicate whether or not that level is to be included in the returned information. Failure to provide any levels is equivalent to a request for all levels. Supported levels include: diff --git a/Chap_API_Tools.tex b/Chap_API_Tools.tex index db3532c1..393f51d3 100644 --- a/Chap_API_Tools.tex +++ b/Chap_API_Tools.tex @@ -84,12 +84,12 @@ \section{Connection Mechanisms} \item \code{PMIX_SERVER_TMPDIR} as the directory specified by either the \refattr{PMIX_SERVER_TMPDIR} attribute or the \code{TMPDIR} environmental variable. \end{itemize} -The rendezvous methods are automatically employed for the initial tool connection during \refapi{PMIx_tool_init} unless the \refattr{PMIX_TOOL_DO_NOT_CONNECT} attribute is specified, and on all subsequent calls to \refapi{PMIx_tool_connect_to_server}. +The rendezvous methods are automatically employed for the initial tool connection during \refapi{PMIx_tool_init} unless the \refattr{PMIX_TOOL_DO_NOT_CONNECT} attribute is specified, and on all subsequent calls to \refapi{PMIx_tool_attach_to_server}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Rendezvousing with a local server} -Connection to a local \ac{PMIx} server is pursued according to the following precedence chain based on attributes contained in the call to the \refapi{PMIx_tool_init} or \refapi{PMIx_tool_connect_to_server} \acp{API}. Servers to which the tool already holds a connection will be ignored. Except where noted, the \ac{PMIx} library will return an error if the specified file cannot be found, the caller lacks permissions to read it, or the server specified within the file does not respond to or accept the connection — the library will not proceed to check for other connection options as the user specified a particular one to use. +Connection to a local \ac{PMIx} server is pursued according to the following precedence chain based on attributes contained in the call to the \refapi{PMIx_tool_init} or \refapi{PMIx_tool_attach_to_server} \acp{API}. Servers to which the tool already holds a connection will be ignored. Except where noted, the \ac{PMIx} library will return an error if the specified file cannot be found, the caller lacks permissions to read it, or the server specified within the file does not respond to or accept the connection — the library will not proceed to check for other connection options as the user specified a particular one to use. Note that the \ac{PMIx} implementation may choose to introduce a "delayed connection" protocol between steps in the precedence chain - i.e., the library may cycle several times, checking for creation of the rendezvous file each time after a delay of some period of time, thereby allowing the tool to wait for the server to create the rendezvous file before either returning an error or continuing to the next step in the chain. @@ -186,7 +186,7 @@ \subsection{Tool initialization environmental variables} \subsection{Tool connection attributes} \label{api:struct:attributes:connection} -These attributes are defined to assist PMIx-enabled tools to connect with a \ac{PMIx} server by passing them into either the \refapi{PMIx_tool_init} or the \refapi{PMIx_tool_connect_to_server} \acp{API} - thus, they are not typically accessed via the \refapi{PMIx_Get} \ac{API}. +These attributes are defined to assist PMIx-enabled tools to connect with a \ac{PMIx} server by passing them into either the \refapi{PMIx_tool_init} or the \refapi{PMIx_tool_attach_to_server} \acp{API} - thus, they are not typically accessed via the \refapi{PMIx_Get} \ac{API}. % \declareAttribute{PMIX_SERVER_PIDINFO}{"pmix.srvr.pidinfo"}{pid_t}{ @@ -1133,7 +1133,7 @@ \subsection{\code{PMIx_tool_init}} Initialize the \ac{PMIx} tool, returning the process identifier assigned to this tool in the provided \refstruct{pmix_proc_t} struct. The \refarg{info} array is used to pass user requests pertaining to the initialization and subsequent operations. Passing a \code{NULL} value for the array pointer is supported if no directives are desired. -If called with the \refattr{PMIX_TOOL_DO_NOT_CONNECT} attribute, the \ac{PMIx} tool library will fully initialize but not attempt to connect to a \ac{PMIx} server. The tool can connect to a server at a later point in time, if desired, by calling the \refapi{PMIx_tool_connect_to_server} function. If provided, the \refarg{proc} structure will be set to a zero-length namespace and a rank of \refconst{PMIX_RANK_UNDEF} unless the \refattr{PMIX_TOOL_NSPACE} and \refattr{PMIX_TOOL_RANK} attributes are included in the \refarg{info} array. +If called with the \refattr{PMIX_TOOL_DO_NOT_CONNECT} attribute, the \ac{PMIx} tool library will fully initialize but not attempt to connect to a \ac{PMIx} server. The tool can connect to a server at a later point in time, if desired, by calling the \refapi{PMIx_tool_attach_to_server} function. If provided, the \refarg{proc} structure will be set to a zero-length namespace and a rank of \refconst{PMIX_RANK_UNDEF} unless the \refattr{PMIX_TOOL_NSPACE} and \refattr{PMIX_TOOL_RANK} attributes are included in the \refarg{info} array. In all other cases, the \ac{PMIx} tool library will automatically attempt to connect to a \ac{PMIx} server according to the precedence chain described in Section \ref{chap:api_tools:cnct}. If successful, the function will return \refconst{PMIX_SUCCESS} and will fill the process structure (if provided) with the assigned namespace and rank of the tool. The server to which the tool connects will be designated its \emph{primary} server. Note that each connection attempt in the above precedence chain will retry (with delay between each retry) a number of times according to the values of the corresponding attributes. From 01a91a3f8b249e8465c3a4950c295131312afbf9 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Fri, 11 Dec 2020 20:44:08 -0600 Subject: [PATCH 08/11] Fix references to deprecated pmix_server_client_connected_fn_t Signed-off-by: Joshua Hursey (cherry picked from commit f81784ac57f604ad639d7dad47fc840e9c7e70b3) --- Chap_API_Security.tex | 2 +- Chap_API_Server.tex | 4 ++-- Chap_API_Struct.tex | 2 +- Chap_Revisions.tex | 2 +- pmix.sty | 10 ++++++---- 5 files changed, 11 insertions(+), 9 deletions(-) diff --git a/Chap_API_Security.tex b/Chap_API_Security.tex index 60c69e47..50af3fc0 100644 --- a/Chap_API_Security.tex +++ b/Chap_API_Security.tex @@ -8,7 +8,7 @@ \chapter{Security} When the client attempts to connect to the \ac{PMIx} server, the server shall use available standard \ac{OS} methods to determine the effective \ac{UID}/\ac{GID} of the process requesting the connection. \ac{PMIx} implementations shall not rely on any values reported by the client process itself. The effective \ac{UID}/\ac{GID} reported by the \ac{OS} is compared to the values provided by the host during registration - if the values fail to match, the \ac{PMIx} server is required to drop the connection request. This ensures that the \ac{PMIx} server does not allow connection from a client that doesn't at least meet some minimal security requirement. -Once the requesting client passes the initial test, the \ac{PMIx} server can, at the choice of the implementor, perform additional security checks. This may involve a variety of methods such as exchange of a system-provided key or credential. At the conclusion of that process, the \ac{PMIx} server reports the client connection request to the host via the \refapi{pmix_server_client_connected_fn_t} interface, if provided. The host may perform any additional checks and operations before responding with either \refconst{PMIX_SUCCESS} to indicate that the connection is approved, or a \ac{PMIx} error constant indicating that the connection request is refused. In this latter case, the \ac{PMIx} server is required to drop the connection. +Once the requesting client passes the initial test, the \ac{PMIx} server can, at the choice of the implementor, perform additional security checks. This may involve a variety of methods such as exchange of a system-provided key or credential. At the conclusion of that process, the \ac{PMIx} server reports the client connection request to the host via the \refapi{pmix_server_client_connected2_fn_t} interface, if provided. The host may perform any additional checks and operations before responding with either \refconst{PMIX_SUCCESS} to indicate that the connection is approved, or a \ac{PMIx} error constant indicating that the connection request is refused. In this latter case, the \ac{PMIx} server is required to drop the connection. Tools started by the host environment are classed as a subgroup of client processes and follow the client process procedure. However, tools that are not started by the host environment must be handled differently as registration information is not available prior to the connection request. In these cases, the \ac{PMIx} server library is required to use available standard \ac{OS} methods to get the effective \ac{UID}/\ac{GID} of the tool and report them upwards as part of invoking the \refapi{pmix_server_tool_connection_fn_t} interface, deferring initial security screening to the host. Host environments willing to accept tool connections must therefore both explicitly enable them via the \refattr{PMIX_SERVER_TOOL_SUPPORT} attribute, thereby confirming acceptance of the authentication and authorization burden, and provide the \refapi{pmix_server_tool_connection_fn_t} server module function pointer. diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 9db3ddbc..1e4b9dd4 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -1017,11 +1017,11 @@ \subsection{\code{PMIx_server_register_client}} The host server can also, if it desires, provide an object it wishes to be returned when a server function is called that relates to a specific process. For example, the host server may have an object that tracks the specific client. -Passing the object to the library allows the library to provide that object to the host server during subsequent calls related to that client, such as a \refapi{pmix_server_client_connected_fn_t} function. This allows the host server to access the object without performing a lookup based on the client's namespace and rank. +Passing the object to the library allows the library to provide that object to the host server during subsequent calls related to that client, such as a \refapi{pmix_server_client_connected2_fn_t} function. This allows the host server to access the object without performing a lookup based on the client's namespace and rank. \advicermstart Host environments are required to execute this operation prior to starting the client process. -The expected user ID and group ID of the child process allows the server library to properly authenticate clients as they connect by requiring the two values to match. Accordingly, the detected user and group ID's of the connecting process are not included in the \refapi{pmix_server_client_connected_fn_t} server module function. +The expected user ID and group ID of the child process allows the server library to properly authenticate clients as they connect by requiring the two values to match. Accordingly, the detected user and group ID's of the connecting process are not included in the \refapi{pmix_server_client_connected2_fn_t} server module function. \advicermend \adviceimplstart diff --git a/Chap_API_Struct.tex b/Chap_API_Struct.tex index d67fef67..01aa6b2c 100644 --- a/Chap_API_Struct.tex +++ b/Chap_API_Struct.tex @@ -2212,7 +2212,7 @@ \subsection{Op Callback Function} %%%% \descr -Used by a wide range of \ac{PMIx} API's including \refapi{PMIx_Fence_nb}, \refapi{pmix_server_client_connected_fn_t}, \refapi{PMIx_server_register_nspace}. +Used by a wide range of \ac{PMIx} API's including \refapi{PMIx_Fence_nb}, \refapi{pmix_server_client_connected2_fn_t}, \refapi{PMIx_server_register_nspace}. This callback function is used to return a status to an often nonblocking operation. diff --git a/Chap_Revisions.tex b/Chap_Revisions.tex index e122849d..b1b2b445 100644 --- a/Chap_Revisions.tex +++ b/Chap_Revisions.tex @@ -883,7 +883,7 @@ \subsection{Deprecated \acp{API}} \declareapiDEP{pmix_evhdlr_reg_cbfunc_t} Renamed to \refapi{pmix_hdlr_reg_cbfunc_t} -The \refapi{pmix_server_client_connected_fn_t} server module entry point has +The \refapiDEP{pmix_server_client_connected_fn_t} server module entry point has been \emph{deprecated} in favor of \refapi{pmix_server_client_connected2_fn_t} diff --git a/pmix.sty b/pmix.sty index d7686acc..6081acc5 100644 --- a/pmix.sty +++ b/pmix.sty @@ -391,7 +391,7 @@ \newcommand{\declareEnvarDEP}[2]{% {\color{green!80!black}\code{#1}}% - \index[index_envars]{#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{envar:#1}% + \index[index_envars]{Z_#1@\emph{#1}!\textbf{Deprecated}|indexdepfmt} \label{envar:#1}% \vspace{-1.3ex}% \expandafter\begin{adjustwidth}{.95cm}{}% \StdCopyEcho{#1}{#2}% @@ -401,7 +401,7 @@ \newcommand{\declareEnvarRM}[2]{% {\color{green!80!black}\code{#1}}% - \index[index_envars]{#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{envar:#1}% + \index[index_envars]{Z_#1@\emph{#1}!\textbf{Removed}|indexrmfmt} \label{envar:#1}% \vspace{-1.3ex}% \expandafter\begin{adjustwidth}{.95cm}{}% \StdCopyEcho{#1}{#2}% @@ -735,14 +735,16 @@ \newcommand{\refapi}[1]{\index[index_api]{#1}\hyperref[apifn:#1]{\code{#1}}} \newcommand{\argapi}[1] {\refapi{#1}} + \newcommand{\declareapiDEP}[1]{% {\color{green!80!black}\code{#1}}% - \index[index_api]{#1@#1 \textbf{(Deprecated)}|indexdepfmt} \label{apifn:#1}% + \index[index_api]{Z_#1@#1!\textbf{(Deprecated)}|indexdepfmt} \label{apifn:#1}% } \newcommand{\declareapiDEPNODISP}[1]{% - \index[index_api]{#1@#1|indexdepfmt} \label{apifn:#1}% + \index[index_api]{Z_#1@#1!\textbf{(Deprecated)}|indexdepfmt} \label{apifn:#1}% } +\newcommand{\refapiDEP}[1]{\index[index_api]{Z_#1@#1!\textbf{(Deprecated)}}\hyperref[apifn:#1]{\code{#1}}} % API references for language bindings (e.g., Python) % {Language specific function}{Primary C PMIx function}{Language Classification} From 9da1c09de80addeb54a3663432bda5892a65f183 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Fri, 11 Dec 2020 11:00:24 -0600 Subject: [PATCH 09/11] Fixup Python bindinds to match C bindings * Adds the following: - `PMIx_Parse_cpuset_string` - `PMIx_server_generate_locality_string` - `PMIx_server_generate_cpuset_string` * Fix cross-references of APIs to point to their blocking counterpart (instead of the nonblocking counterpart) for consistency. * Fix cross-references of callbacks to their C counterparts * Fix name of PMIx_Allocation_request Python binding from allocate to allocation_request * Fix arguments passed to Tool.set_server Signed-off-by: Joshua Hursey (cherry picked from commit de6fef7ef43f2120f10a26da2de48c383d2f82e9) --- App_Python.tex | 226 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 173 insertions(+), 53 deletions(-) diff --git a/App_Python.tex b/App_Python.tex index 46c8e940..cb0bb36a 100644 --- a/App_Python.tex +++ b/App_Python.tex @@ -51,49 +51,49 @@ \section{Datatype Definitions} \hline C-Definition & PMIx Name & Python Definition & Notes \\ \hline \endhead - \code{bool} & PMIX_BOOL & boolean & \\ \hline - \code{byte} & PMIX_BYTE & A single element byte array (i.e., a byte array of length one) & \\ \hline - \code{char*} & PMIX_STRING & string & \\ \hline - \code{size_t} & PMIX_SIZE & integer & \\ \hline - \code{pid_t} & PMIX_PID & integer & value shall be limited to the \code{uint32_t} range \\ \hline - \code{int, int8_t, int16_t, int32_t, int64_t} & PMIX_INT, PMIX_INT8, PMIX_INT16, PMIX_INT32, PMIX_INT64 & integer & value shall be limited to its corresponding range \\ \hline - \code{uint, uint8_t, uint16_t, uint32_t, uint64_t} & PMIX_UINT, PMIX_UINT8, PMIX_UINT16, PMIX_UINT32, PMIX_UINT64 & integer & value shall be limited to its corresponding range \\ \hline - \code{float, double} & PMIX_FLOAT, PMIX_DOUBLE & float & value shall be limited to its corresponding range \\ \hline - \code{struct timeval} & PMIX_TIMEVAL & \{'sec': sec, 'usec': microsec\} & each field is an integer value \\ \hline - \code{time_t} & PMIX_TIME & integer & limited to positive values \\ \hline - \refstruct{pmix_data_type_t} & PMIX_DATA_TYPE & integer & value shall be limited to the \code{uint16_t} range \\ \hline - \refstruct{pmix_status_t} & PMIX_STATUS & integer & \\ \hline + \code{bool} & \refconst{PMIX_BOOL} & boolean & \\ \hline + \code{byte} & \refconst{PMIX_BYTE} & A single element byte array (i.e., a byte array of length one) & \\ \hline + \code{char*} & \refconst{PMIX_STRING} & string & \\ \hline + \code{size_t} & \refconst{PMIX_SIZE} & integer & \\ \hline + \code{pid_t} & \refconst{PMIX_PID} & integer & value shall be limited to the \code{uint32_t} range \\ \hline + \code{int, int8_t, int16_t, int32_t, int64_t} & \refconst{PMIX_INT}, \refconst{PMIX_INT8}, \refconst{PMIX_INT16}, \refconst{PMIX_INT32}, \refconst{PMIX_INT64} & integer & value shall be limited to its corresponding range \\ \hline + \code{uint, uint8_t, uint16_t, uint32_t, uint64_t} & \refconst{PMIX_UINT}, \refconst{PMIX_UINT8}, \refconst{PMIX_UINT16}, \refconst{PMIX_UINT32}, \refconst{PMIX_UINT64} & integer & value shall be limited to its corresponding range \\ \hline + \code{float, double} & \refconst{PMIX_FLOAT}, \refconst{PMIX_DOUBLE} & float & value shall be limited to its corresponding range \\ \hline + \code{struct timeval} & \refconst{PMIX_TIMEVAL} & \{'sec': sec, 'usec': microsec\} & each field is an integer value \\ \hline + \code{time_t} & \refconst{PMIX_TIME} & integer & limited to positive values \\ \hline + \refstruct{pmix_data_type_t} & \refconst{PMIX_DATA_TYPE} & integer & value shall be limited to the \code{uint16_t} range \\ \hline + \refstruct{pmix_status_t} & \refconst{PMIX_STATUS} & integer & \\ \hline \refstruct{pmix_key_t} & N/A & \pylabel{key}string & The string's length shall be limited to one less than the size of the \refstruct{pmix_key_t} array (to reserve space for the terminating \code{NULL}) \\ \hline \refstruct{pmix_nspace_t} & N/A & \pylabel{nspace}string & The string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}) \\ \hline - \refstruct{pmix_rank_t} & PMIX_PROC_RANK & \pylabel{rank}integer & value shall be limited to the \code{uint32_t} range excepting the reserved values near \code{UINT32_MAX} \\ \hline - \refstruct{pmix_proc_t} & PMIX_PROC & \pylabel{proc}\{'nspace': nspace, 'rank': rank\} & \refarg{nspace} is a Python string and \refarg{rank} is an integer value. The \refarg{nspace} string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}), and the \refarg{rank} value shall conform to the constraints associated with \refstruct{pmix_rank_t} \\ \hline - \refstruct{pmix_byte_object_t} & PMIX_BYTE_OBJECT & \pylabel{byteobject}\{'bytes': bytes, 'size': size\} & \refarg{bytes} is a Python byte array and \refarg{size} is the integer number of bytes in that array. \\ \hline - \refstruct{pmix_persistence_t} & PMIX_PERSISTENCE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_scope_t} & PMIX_SCOPE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_data_range_t} & PMIX_RANGE & \pylabel{range}integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_proc_state_t} & PMIX_PROC_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_proc_info_t} & PMIX_PROC_INFO & \{'proc': \{'nspace': nspace, 'rank': rank\}, 'hostname': hostname, 'executable': executable, 'pid': pid, 'exitcode': exitcode, 'state': state\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{hostname} and \refarg{executable} are Python strings; and \refarg{pid}, \refarg{exitcode}, and \refarg{state} are Python integers \\ \hline - \refstruct{pmix_data_array_t} & PMIX_DATA_ARRAY & \pylabel{array}\{'type': type, 'array': array\} & \refarg{type} is the \ac{PMIx} type of object in the array and \refarg{array} is a Python \emph{list} containing the individual array elements. Note that \refarg{array} can consist of \emph{any} \ac{PMIx} types, including (for example) a Python \refpy{info} object that itself contains an \refpy{array} value \\ \hline - \refstruct{pmix_info_directives_t} & PMIX_INFO_DIRECTIVES & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline - \refstruct{pmix_alloc_directive_t} & PMIX_ALLOC_DIRECTIVE & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_iof_channel_t} & PMIX_IOF_CHANNEL & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline - \refstruct{pmix_envar_t} & PMIX_ENVAR & \{'envar': envar, 'value': value, 'separator': separator\} & \refarg{envar} and \refarg{value} are Python strings, and \refarg{separator} a single-character Python string \\ \hline - \refstruct{pmix_value_t} & PMIX_VALUE & \pylabel{value}\{'value': value, 'val_type': type\} & \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline - \refstruct{pmix_info_t} & PMIX_INFO & \pylabel{info}\{'key': key, 'flags': flags, value': value, 'val_type': type\} & \refarg{key} is a Python string \refpy{key}, \refarg{flags} is an \refpy{info directives} value, \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline - \refstruct{pmix_pdata_t} & PMIX_PDATA & \pylabel{pdata}\{'proc': \{'nspace': nspace, 'rank': rank\}, 'key': key, 'value': value, 'val_type': type\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{key} is a Python string \refpy{key}; \refarg{type} is the \ac{PMIx} datatype of \refarg{value}; and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline - \refstruct{pmix_app_t} & PMIX_APP & \pylabel{app}\{'cmd': cmd, 'argv': [argv], 'env': [env], 'maxprocs': maxprocs, 'info': [info]\} & \refarg{cmd} is a Python string; \refarg{argv} and \refarg{env} are Python \emph{lists} containing Python strings; \refarg{maxprocs} is an integer; and \refarg{info} is a Python \emph{list} of \refpy{info} values \\ \hline - \refstruct{pmix_query_t} & PMIX_QUERY & \pylabel{query}\{'keys': [keys], 'qualifiers': [info]\} & \refarg{keys} is a Python \emph{list} of Python strings, and \refarg{qualifiers} is a Python \emph{list} of \refpy{info} values \\ \hline - \refstruct{pmix_regattr_t} & PMIX_REGATTR & \pylabel{regattr}\{'name': name, 'key': key, 'type': type, 'info': [info], 'description': [desc]\} & \refarg{name} and \refarg{string} are Python strings; \refarg{type} is the \ac{PMIx} datatype for the attribute's value; \refarg{info} is a Python \emph{list} of \refpy{info} values; and \refarg{description} is a list of Python strings describing the attribute \\ \hline - \refstruct{pmix_job_state_t} & PMIX_JOB_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_link_state_t} & PMIX_LINK_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline - \refstruct{pmix_cpuset_t} & PMIX_PROC_CPUSET & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a list of string ranges identifying the \acp{PU} to which the process is bound (e.g., [1, 3-5, 7]) \\ \hline - \refstruct{pmix_locality_t} & PMIX_LOCTYPE & \pylabel{locality}list & list of integer values (defined in Section \ref{api:proc:locality}) describing the relative locality of the specified local process \\ \hline + \refstruct{pmix_rank_t} & \refconst{PMIX_PROC_RANK} & \pylabel{rank}integer & value shall be limited to the \code{uint32_t} range excepting the reserved values near \code{UINT32_MAX} \\ \hline + \refstruct{pmix_proc_t} & \refconst{PMIX_PROC} & \pylabel{proc}\{'nspace': nspace, 'rank': rank\} & \refarg{nspace} is a Python string and \refarg{rank} is an integer value. The \refarg{nspace} string's length shall be limited to one less than the size of the \refstruct{pmix_nspace_t} array (to reserve space for the terminating \code{NULL}), and the \refarg{rank} value shall conform to the constraints associated with \refstruct{pmix_rank_t} \\ \hline + \refstruct{pmix_byte_object_t} & \refconst{PMIX_BYTE_OBJECT} & \pylabel{byteobject}\{'bytes': bytes, 'size': size\} & \refarg{bytes} is a Python byte array and \refarg{size} is the integer number of bytes in that array. \\ \hline + \refstruct{pmix_persistence_t} & \refattr{PMIX_PERSISTENCE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_scope_t} & \refconst{PMIX_SCOPE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_data_range_t} & \refattr{PMIX_RANGE} & \pylabel{range}integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_proc_state_t} & \refconst{PMIX_PROC_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_proc_info_t} & \refconst{PMIX_PROC_INFO} & \{'proc': \{'nspace': nspace, 'rank': rank\}, 'hostname': hostname, 'executable': executable, 'pid': pid, 'exitcode': exitcode, 'state': state\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{hostname} and \refarg{executable} are Python strings; and \refarg{pid}, \refarg{exitcode}, and \refarg{state} are Python integers \\ \hline + \refstruct{pmix_data_array_t} & \refconst{PMIX_DATA_ARRAY} & \pylabel{array}\{'type': type, 'array': array\} & \refarg{type} is the \ac{PMIx} type of object in the array and \refarg{array} is a Python \emph{list} containing the individual array elements. Note that \refarg{array} can consist of \emph{any} \ac{PMIx} types, including (for example) a Python \refpy{info} object that itself contains an \refpy{array} value \\ \hline + \refstruct{pmix_info_directives_t} & \refconst{PMIX_INFO_DIRECTIVES} & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline + \refstruct{pmix_alloc_directive_t} & \refconst{PMIX_ALLOC_DIRECTIVE} & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_iof_channel_t} & \refconst{PMIX_IOF_CHANNEL} & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline + \refstruct{pmix_envar_t} & \refconst{PMIX_ENVAR} & \{'envar': envar, 'value': value, 'separator': separator\} & \refarg{envar} and \refarg{value} are Python strings, and \refarg{separator} a single-character Python string \\ \hline + \refstruct{pmix_value_t} & \refconst{PMIX_VALUE} & \pylabel{value}\{'value': value, 'val_type': type\} & \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline + \refstruct{pmix_info_t} & \refconst{PMIX_INFO} & \pylabel{info}\{'key': key, 'flags': flags, value': value, 'val_type': type\} & \refarg{key} is a Python string \refpy{key}, \refarg{flags} is an \refpy{info directives} value, \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline + \refstruct{pmix_pdata_t} & \refconst{PMIX_PDATA} & \pylabel{pdata}\{'proc': \{'nspace': nspace, 'rank': rank\}, 'key': key, 'value': value, 'val_type': type\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{key} is a Python string \refpy{key}; \refarg{type} is the \ac{PMIx} datatype of \refarg{value}; and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline + \refstruct{pmix_app_t} & \refconst{PMIX_APP} & \pylabel{app}\{'cmd': cmd, 'argv': [argv], 'env': [env], 'maxprocs': maxprocs, 'info': [info]\} & \refarg{cmd} is a Python string; \refarg{argv} and \refarg{env} are Python \emph{lists} containing Python strings; \refarg{maxprocs} is an integer; and \refarg{info} is a Python \emph{list} of \refpy{info} values \\ \hline + \refstruct{pmix_query_t} & \refconst{PMIX_QUERY} & \pylabel{query}\{'keys': [keys], 'qualifiers': [info]\} & \refarg{keys} is a Python \emph{list} of Python strings, and \refarg{qualifiers} is a Python \emph{list} of \refpy{info} values \\ \hline + \refstruct{pmix_regattr_t} & \refconst{PMIX_REGATTR} & \pylabel{regattr}\{'name': name, 'key': key, 'type': type, 'info': [info], 'description': [desc]\} & \refarg{name} and \refarg{string} are Python strings; \refarg{type} is the \ac{PMIx} datatype for the attribute's value; \refarg{info} is a Python \emph{list} of \refpy{info} values; and \refarg{description} is a list of Python strings describing the attribute \\ \hline + \refstruct{pmix_job_state_t} & \refconst{PMIX_JOB_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_link_state_t} & \refconst{PMIX_LINK_STATE} & integer & value shall be limited to the \code{uint8_t} range \\ \hline + \refstruct{pmix_cpuset_t} & \refconst{PMIX_PROC_CPUSET} & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a list of string ranges identifying the \acp{PU} to which the process is bound (e.g., [1, 3-5, 7]) \\ \hline + \refstruct{pmix_locality_t} & \refconst{PMIX_LOCTYPE} & \pylabel{locality}list & list of integer values (defined in Section \ref{api:proc:locality}) describing the relative locality of the specified local process \\ \hline \refstruct{pmix_fabric_t} & N/A & \pylabel{fabric}\{'name': name, 'index': idx, 'info': [info]\} & \refarg{name} is the string name assigned to the fabric; \refarg{index} is the integer ID assigned to the fabric; \refarg{info} is a list of \refpy{info} describing the fabric \\ \hline - \refstruct{pmix_endpoint_t} & PMIX_ENDPOINT & \pylabel{endpoint}\{'uuid': uuid, 'osname': osname, endpt': endpt\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; \refarg{endpt} is a \refpy{byteobject} containing the endpoint information \\ \hline - \refstruct{pmix_device_distance_t} & PMIX_DEVICE_DIST & \pylabel{devdist}\{'uuid': uuid, 'osname': osname, mindist': mindist, 'maxdist': maxdist\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{mindist} and \refarg{maxdist} are Python integers \\ \hline - \refstruct{pmix_coord_t} & PMIX_COORD & \pylabel{coord}\{'view': view, 'coord': [coords]\} & \refarg{view} is the \refstruct{pmix_coord_view_t} of the coordinate; and \refarg{coord} is a list of integer coordinates, one for each dimension of the fabric \\ \hline - \refstruct{pmix_geometry_t} & PMIX_GEOMETRY & \pylabel{geometry}\{'fabric': idx, 'uuid': uuid, 'osname': osname, coordinates': [coords]\} & \refarg{fabric} is the Python integer index of the fabric; \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{coordinates} is a list of \refpy{coord} containing the coordinates for the device across all views \\ \hline - \refstruct{pmix_device_type_t} & PMIX_DEVTYPE & \pylabel{devtype}list & list of integer values (defined in Section \ref{api:proc:devtype}) \\ \hline + \refstruct{pmix_endpoint_t} & \refconst{PMIX_ENDPOINT} & \pylabel{endpoint}\{'uuid': uuid, 'osname': osname, endpt': endpt\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; \refarg{endpt} is a \refpy{byteobject} containing the endpoint information \\ \hline + \refstruct{pmix_device_distance_t} & \refconst{PMIX_DEVICE_DIST} & \pylabel{devdist}\{'uuid': uuid, 'osname': osname, mindist': mindist, 'maxdist': maxdist\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{mindist} and \refarg{maxdist} are Python integers \\ \hline + \refstruct{pmix_coord_t} & \refconst{PMIX_COORD} & \pylabel{coord}\{'view': view, 'coord': [coords]\} & \refarg{view} is the \refstruct{pmix_coord_view_t} of the coordinate; and \refarg{coord} is a list of integer coordinates, one for each dimension of the fabric \\ \hline + \refstruct{pmix_geometry_t} & \refconst{PMIX_GEOMETRY} & \pylabel{geometry}\{'fabric': idx, 'uuid': uuid, 'osname': osname, coordinates': [coords]\} & \refarg{fabric} is the Python integer index of the fabric; \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{coordinates} is a list of \refpy{coord} containing the coordinates for the device across all views \\ \hline + \refstruct{pmix_device_type_t} & \refconst{PMIX_DEVTYPE} & \pylabel{devtype}list & list of integer values (defined in Section \ref{api:proc:devtype}) \\ \hline \refstruct{pmix_bind_envelope_t} & N/A & \pylabel{bindenv}integer & one of the values defined in Section \ref{api:proc:bindenv} \\ \hline \end{longtable} \end{small} @@ -148,6 +148,7 @@ \section{Callback Function Definitions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{IOF Delivery Function} \pylabel{iofcbfunc} +\declareapibinding{iofcbfunc}{pmix_iof_cbfunc_t}{Python} %%%% \summary @@ -181,6 +182,7 @@ \subsection{IOF Delivery Function} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Event Handler} \pylabel{evhandler} +\declareapibinding{evhandler}{pmix_notification_fn_t}{Python} %%%% \summary @@ -224,6 +226,7 @@ \subsection{Server Module Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Client Connected} +\declareapibinding{clientconnected2}{pmix_server_client_connected2_fn_t}{Python} %%%% \summary @@ -255,6 +258,7 @@ \subsubsection{Client Connected} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Client Finalized} +\declareapibinding{clientfinalized}{pmix_server_client_finalized_fn_t}{Python} %%%% \summary @@ -282,6 +286,7 @@ \subsubsection{Client Finalized} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Client Aborted} +\declareapibinding{clientaborted}{pmix_server_abort_fn_t}{Python} %%%% \summary @@ -318,6 +323,7 @@ \subsubsection{Client Aborted} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Fence} +\declareapibinding{fence}{pmix_server_fencenb_fn_t}{Python} %%%% \summary @@ -354,6 +360,7 @@ \subsubsection{Fence} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Direct Modex} +\declareapibinding{dmodex}{pmix_server_dmodex_req_fn_t}{Python} %%%% \summary @@ -389,6 +396,7 @@ \subsubsection{Direct Modex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Publish} +\declareapibinding{publish}{pmix_server_publish_fn_t}{Python} %%%% \summary @@ -423,6 +431,7 @@ \subsubsection{Publish} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Lookup} +\declareapibinding{lookup}{pmix_server_lookup_fn_t}{Python} %%%% \summary @@ -459,6 +468,7 @@ \subsubsection{Lookup} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Unpublish} +\declareapibinding{unpublish}{pmix_server_unpublish_fn_t}{Python} %%%% \summary @@ -494,6 +504,7 @@ \subsubsection{Unpublish} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Spawn} +\declareapibinding{spawn}{pmix_server_spawn_fn_t}{Python} %%%% \summary @@ -530,6 +541,7 @@ \subsubsection{Spawn} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Connect} +\declareapibinding{connect}{pmix_server_connect_fn_t}{Python} %%%% \summary @@ -564,6 +576,7 @@ \subsubsection{Connect} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Disconnect} +\declareapibinding{disconnect}{pmix_server_disconnect_fn_t}{Python} %%%% \summary @@ -598,6 +611,7 @@ \subsubsection{Disconnect} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Register Events} +\declareapibinding{register_events}{pmix_server_register_events_fn_t}{Python} %%%% \summary @@ -632,6 +646,7 @@ \subsubsection{Register Events} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Deregister Events} +\declareapibinding{deregister_events}{pmix_server_deregister_events_fn_t}{Python} %%%% \summary @@ -665,6 +680,7 @@ \subsubsection{Deregister Events} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Notify Event} +\declareapibinding{notify_event}{pmix_server_notify_event_fn_t}{Python} %%%% \summary @@ -701,6 +717,7 @@ \subsubsection{Notify Event} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Query} +\declareapibinding{query}{pmix_server_query_fn_t}{Python} %%%% \summary @@ -736,6 +753,7 @@ \subsubsection{Query} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Tool Connected} +\declareapibinding{tool_connected}{pmix_server_tool_connection_fn_t}{Python} %%%% \summary @@ -770,6 +788,7 @@ \subsubsection{Tool Connected} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Log} +\declareapibinding{log}{pmix_server_log_fn_t}{Python} %%%% \summary @@ -805,6 +824,7 @@ \subsubsection{Log} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Allocate Resources} +\declareapibinding{allocate}{pmix_server_alloc_fn_t}{Python} %%%% \summary @@ -841,6 +861,7 @@ \subsubsection{Allocate Resources} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Job Control} +\declareapibinding{job_control}{pmix_server_job_control_fn_t}{Python} %%%% \summary @@ -876,6 +897,7 @@ \subsubsection{Job Control} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Monitor} +\declareapibinding{monitor}{pmix_server_monitor_fn_t}{Python} %%%% \summary @@ -912,6 +934,7 @@ \subsubsection{Monitor} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Get Credential} +\declareapibinding{get_credential}{pmix_server_get_cred_fn_t}{Python} %%%% \summary @@ -948,6 +971,7 @@ \subsubsection{Get Credential} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Validate Credential} +\declareapibinding{validate_credential}{pmix_server_validate_cred_fn_t}{Python} %%%% \summary @@ -984,6 +1008,7 @@ \subsubsection{Validate Credential} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{IO Forward} +\declareapibinding{iof_pull}{pmix_server_iof_fn_t}{Python} %%%% \summary @@ -1019,6 +1044,7 @@ \subsubsection{IO Forward} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{IO Push} +\declareapibinding{iof_push}{pmix_server_stdin_fn_t}{Python} %%%% \summary @@ -1055,6 +1081,7 @@ \subsubsection{IO Push} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Group Operations} +\declareapibinding{group}{pmix_server_grp_fn_t}{Python} %%%% \summary @@ -1092,6 +1119,7 @@ \subsubsection{Group Operations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Fabric Operations} +\declareapibinding{fabric}{pmix_server_fabric_fn_t}{Python} %%%% \summary @@ -1710,7 +1738,7 @@ \subsection{Client.resolve_nodes} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.query} -\declareapibinding{PMIxClient.query}{PMIx_Query_info_nb}{Python} +\declareapibinding{PMIxClient.query}{PMIx_Query_info}{Python} %%%% \summary @@ -1738,7 +1766,7 @@ \subsection{Client.query} \item \refarg{info} - List of Python \refpy{info} containing results of the query (list) \end{itemize} -See \refapi{PMIx_Query_info_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Query_info} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1775,8 +1803,8 @@ \subsection{Client.log} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Client.allocate} -\declareapibinding{PMIxClient.allocate}{PMIx_Allocation_request_nb}{Python} +\subsection{Client.allocation_request} +\declareapibinding{PMIxClient.allocation_request}{PMIx_Allocation_request}{Python} %%%% \summary @@ -1789,7 +1817,7 @@ \subsection{Client.allocate} \versionMarker{4.0} \pyspecificstart \begin{codepar} -rc,info = myclient.allocate(request:integer, directives:list) +rc,info = myclient.allocation_request(request:integer, directives:list) \end{codepar} \pyspecificend @@ -1805,12 +1833,12 @@ \subsection{Client.allocate} \item \refarg{info} - List of Python \refpy{info} containing results of the request (list) \end{itemize} -See \refapi{PMIx_Allocation_request_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Allocation_request} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.job_ctrl} -\declareapibinding{PMIxClient.job_ctrl}{PMIx_Job_control_nb}{Python} +\declareapibinding{PMIxClient.job_ctrl}{PMIx_Job_control}{Python} %%%% \summary @@ -1839,12 +1867,12 @@ \subsection{Client.job_ctrl} \item \refarg{info} - List of Python \refpy{info} containing results of the request (list) \end{itemize} -See \refapi{PMIx_Job_control_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Job_control} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.monitor} -\declareapibinding{PMIxClient.monitor}{PMIx_Process_monitor_nb}{Python} +\declareapibinding{PMIxClient.monitor}{PMIx_Process_monitor}{Python} %%%% \summary @@ -1874,7 +1902,7 @@ \subsection{Client.monitor} \item \refarg{info} - List of Python \refpy{info} containing results of the request (list) \end{itemize} -See \refapi{PMIx_Process_monitor_nb} for description of all relevant attributes and behaviors. +See \refapi{PMIx_Process_monitor} for description of all relevant attributes and behaviors. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -2400,6 +2428,36 @@ \subsection{Client.get_cpuset} See \refapi{PMIx_Get_cpuset} for details. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Client.parse_cpuset_string} +\declareapibinding{PMIxClient.parse_cpuset_string}{PMIx_Parse_cpuset_string}{Python} + +\summary +Parse the \ac{PU} binding bitmap from its string representation. + +\format + +\versionMarker{4.0} +\pyspecificstart +\begin{codepar} +rc,cpuset = myclient.parse_cpuset_string(cpuset:string) +\end{codepar} +\pyspecificend + +\begin{arglist} +\argin{cpuset}{String returned by \refapibinding{PMIxServer.generate_cpuset_string} (string)} +\end{arglist} + + +Returns: + +\begin{itemize} + \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer) + \item \refarg{cpuset} - \refpy{cpuset} containing the source and bitmap of the cpuset (dict) +\end{itemize} + +See \refapi{PMIx_Parse_cpuset_string} for details. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Client.compute_distances} @@ -2917,7 +2975,7 @@ \subsection{Server.init} \begin{arglist} \argin{directives}{List of Python \refpy{info} dictionaries (list)} -\argin{map}{Python dictionary key-function pairs that map \refpy{server module} callback functions to provided implementations (dict)} +\argin{map}{Python dictionary key-function pairs that map \refpy{server module} callback functions to provided implementations (see \refapi{pmix_server_module_t}) (dict)} \end{arglist} Returns: @@ -3016,6 +3074,67 @@ \subsection{Server.generate_ppn} See \refapi{PMIx_generate_ppn} for details. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Server.generate_locality_string} +\declareapibinding{PMIxServer.generate_locality_string}{PMIx_server_generate_locality_string}{Python} + +\summary +Generate a PMIx locality string from a given cpuset. + +\format + +\versionMarker{4.0} +\pyspecificstart +\begin{codepar} +rc,locality = myserver.generate_locality_string(cpuset:dict) +\end{codepar} +\pyspecificend + + +\begin{arglist} +\argin{cset}{\refpy{cpuset} containing the bitmap of assigned PUs (dict)} +\end{arglist} + +Returns: + +\begin{itemize} + \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer) + \item \refarg{locality} - String representation of the PMIx locality corresponding to the input bitmap (string) +\end{itemize} + +See \refapi{PMIx_server_generate_locality_string} for details. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Server.generate_cpuset_string} +\declareapibinding{PMIxServer.generate_cpuset_string}{PMIx_server_generate_cpuset_string}{Python} + +\summary +Generate a PMIx string representation of the provided cpuset. + +\format + +\versionMarker{4.0} +\pyspecificstart +\begin{codepar} +rc,cpustr = myserver.generate_cpuset_string(cpuset:dict) +\end{codepar} +\pyspecificend + + +\begin{arglist} +\argin{cset}{\refpy{cpuset} containing the bitmap of assigned PUs (dict)} +\end{arglist} + +Returns: + +\begin{itemize} + \item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer) + \item \refarg{cpustr} - String representation of the input bitmap (string) +\end{itemize} + +See \refapi{PMIx_server_generate_cpuset_string} for details. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Server.register_nspace} \declareapibinding{PMIxServer.register_nspace}{PMIx_server_register_nspace}{Python} @@ -3733,12 +3852,13 @@ \subsection{Tool.set_server} \versionMarker{4.0} \pyspecificstart \begin{codepar} -rc = mytool.set_server(proc:dict) +rc = mytool.set_server(proc:dict, info:list) \end{codepar} \pyspecificend \begin{arglist} -\argin{proc}{Python \refpy{proc} containing the identifier of the servers\ to which the tool is to attach (list)} +\argin{proc}{Python \refpy{proc} containing the identifier of the servers to which the tool is to attach (list)} +\argin{info}{List of Python \refpy{info} dictionaries (list)} \end{arglist} Returns: From 4a24de52af101b3c64dde57cde15a8993db41922 Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Fri, 11 Dec 2020 13:52:55 -0600 Subject: [PATCH 10/11] Fix typo in parameter descriptions Signed-off-by: Joshua Hursey (cherry picked from commit 70fd1f4fc7de1c4e6647028f2417fb6166f5ba91) --- Chap_API_Server.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Chap_API_Server.tex b/Chap_API_Server.tex index 1e4b9dd4..9a6e4963 100644 --- a/Chap_API_Server.tex +++ b/Chap_API_Server.tex @@ -3692,7 +3692,7 @@ \subsection{\code{pmix_server_job_control_fn_t}} \argin{ntargets}{Number of elements in the \refarg{targets} array (integer)} \argin{directives}{Array of info structures (array of handles)} \argin{ndirs}{Number of elements in the \refarg{info} array (integer)} -\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)} +\argin{cbfunc}{Callback function \refapi{pmix_info_cbfunc_t} (function reference)} \argin{cbdata}{Data to be passed to the callback function (memory reference)} \end{arglist} @@ -3783,7 +3783,7 @@ \subsection{\code{pmix_server_monitor_fn_t}} \argin{error}{Status code to use in generating event if alarm triggers (integer)} \argin{directives}{Array of info structures (array of handles)} \argin{ndirs}{Number of elements in the \refarg{info} array (integer)} -\argin{cbfunc}{Callback function \refapi{pmix_op_cbfunc_t} (function reference)} +\argin{cbfunc}{Callback function \refapi{pmix_info_cbfunc_t} (function reference)} \argin{cbdata}{Data to be passed to the callback function (memory reference)} \end{arglist} From 4e5b29bd4ab162d09bc0122d150d941b12dfc1fa Mon Sep 17 00:00:00 2001 From: Joshua Hursey Date: Thu, 10 Dec 2020 16:04:25 -0600 Subject: [PATCH 11/11] Fix watermark generation on newer latex installs * Move from `xwatermark` to `draftwatermark` Signed-off-by: Joshua Hursey (cherry picked from commit f1b90f74ed622c4310648b5f7f11d3bc2839a376) --- pmix-standard.tex | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/pmix-standard.tex b/pmix-standard.tex index b9a515c9..abf0ff98 100644 --- a/pmix-standard.tex +++ b/pmix-standard.tex @@ -69,10 +69,13 @@ \input{pmix.sty} % Watermark for the Unofficial Drafts -% Note: "allpages","evenpages","oddpages" do not work. Likely because of the index. \ifthenelse{\boolean{is_unofficial_draft}} - {\usepackage[printwatermark]{xwatermark} - \newwatermark[firstpage,color=gray!30,angle=45,scale=3,xpos=-5,ypos=0]{Unofficial Draft} + {\usepackage{draftwatermark} + \SetWatermarkText{\textbf{Unofficial Draft}} + \SetWatermarkColor[gray]{0.85} + \SetWatermarkFontSize{90pt} + \SetWatermarkScale{1} + \SetWatermarkAngle{45} }{} %%%%%%%%%%%%%%%%%%% Indices