Define PMIX_ERR_EXISTS_OUTSIDE_SCOPE constant

Signed-off-by: Ralph Castain <rhc@pmix.org>

Chap_API_NonReserved_Keys.tex

@@ -9,8 +9,8 @@ \chapter{Process-Related Non-Reserved Keys}
 application when information needs to be exchanged between processes (e.g.,
 where connection information is required and the host environment does not
 support the \refterm{instant on} option) or where the host environment does not
-provide a required piece of data. Other than the prefix, there are no
-restrictions on the use or content of non-reserved keys.
+provide a required piece of data. Beyond the restriction on name prefix,
+non-reserved keys are required to be unique across conflicting \emph{scopes} as defined in Section \ref{api:nres:scope} - e,g., a non-reserved key cannot be posted by the same process in both the \refconst{PMIX_LOCAL} and \refconst{PMIX_REMOTE} scopes (note that posting the key in the \refconst{PMIX_GLOBAL} scope would have met the desired objective).
 
 \ac{PMIx} provides support for two methods of exchanging non-reserved keys:
 
@@ -93,6 +93,7 @@ \subsection{\code{PMIx_Put}}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsubsection{Scope of Put Data}
 \declarestruct{pmix_scope_t}
+\label{api:nres:scope}
 
 \versionMarker{1.0}
 The \refstruct{pmix_scope_t} structure is a \code{uint8_t} type that defines the availability of data passed to \refapi{PMIx_Put}.
@@ -212,9 +213,15 @@ \section{Retrieval rules for non-reserved keys}
     \item Check the local \ac{PMIx} client cache for the requested key - if not found and either the \refattr{PMIX_OPTIONAL} or \refattr{PMIX_GET_REFRESH_CACHE} attribute was given, the search will stop at this point and return the \refconst{PMIX_ERR_NOT_FOUND} status.
 
     \item Request the information from the local \ac{PMIx} server. The server
-    will check its cache for the specified key. If the
-    value still isn't found and the \refattr{PMIX_IMMEDIATE} attribute was
-    given, then the library shall return the \refconst{PMIX_ERR_NOT_FOUND}
+    will check its cache for the specified key within the appropriate scope as
+    defined by the process that originally posted the key. If the value exists
+    in a scope that contains the requesting process, then the value shall be
+    returned. If the value exists, but in a scope that excludes the requesting
+    process, then the server shall immediately return the
+    \refconst{PMIX_ERR_EXISTS_OUTSIDE_SCOPE}.
+
+    If the value still isn't found and the \refattr{PMIX_IMMEDIATE} attribute
+    was given, then the library shall return the \refconst{PMIX_ERR_NOT_FOUND}
     error constant to the requester. Otherwise, the \ac{PMIx} server library
     will take one of the following actions:
     \begin{compactitemize}

Chap_API_Struct.tex

@@ -124,6 +124,9 @@ \subsection{PMIx Return Status Constants}
 Requested operation would overwrite an existing value - typically returned
 when an operation would overwrite an existing file or directory.
 %
+\declareconstitemNEW{PMIX_ERR_EXISTS_OUTSIDE_SCOPE}
+The requested key exists, but was posted in a \emph{scope} (see Section \ref{api:nres:scope}) that does not include the requester
+%
 \declareconstitem{PMIX_ERR_INVALID_CRED}
 Invalid security credentials.
 %

Chap_API_Sync_Access.tex

@@ -210,6 +210,7 @@ \section{\code{PMIx_Get}}
 \begin{itemize}
 \item \refconst{PMIX_SUCCESS} The requested data has been returned in the manner requested (i.e., in a provided static memory location )
 \item \refconst{PMIX_ERR_BAD_PARAM} A bad parameter was passed to the function call - e.g., the request included the \refattr{PMIX_GET_STATIC_VALUES} directive, but the provided storage location was \code{NULL}
+\item \refconst{PMIX_ERR_EXISTS_OUTSIDE_SCOPE} The requested key exists, but was posted in a \emph{scope} (see Section \ref{api:nres:scope}) that does not include the requester.
 \item \refconst{PMIX_ERR_NOT_FOUND} The requested data was not available.
 \item a non-zero \ac{PMIx} error constant indicating a reason for the request's failure.
 \end{itemize}
@@ -286,14 +287,14 @@ \subsection{\code{PMIx_Get_nb}}
 
 \begin{itemize}
     \item \refconst{PMIX_SUCCESS}, indicating that the request is being processed by the host environment - result will be returned in the provided \refarg{cbfunc}. Note that the library must not invoke the callback function prior to returning from the \ac{API}.
-    \item \refconst{PMIX_OPERATION_SUCCEEDED}, indicating that the request was immediately processed and returned \textit{success} - the \refarg{cbfunc} will \textit{not} be called.
     \item a \ac{PMIx} error constant indicating either an error in the input or that the request was immediately processed and failed - the \refarg{cbfunc} will \textit{not} be called.
 \end{itemize}
 
 If executed, the status returned in the provided callback function will be one of the following constants:
 
 \begin{itemize}
 \item \refconst{PMIX_SUCCESS} The requested data has been returned.
+\item \refconst{PMIX_ERR_EXISTS_OUTSIDE_SCOPE} The requested key exists, but was posted in a \emph{scope} (see Section \ref{api:nres:scope}) that does not include the requester.
 \item \refconst{PMIX_ERR_NOT_FOUND} The requested data was not available.
 \item a non-zero \ac{PMIx} error constant indicating a reason for the request's failure.
 \end{itemize}

Chap_Revisions.tex

@@ -413,32 +413,37 @@ \section{Version 4.0: Sept 2020}
 
 \subsection{Added Constants}
 
+%
+\littleheader{General error constants}
+\refconst{PMIX_ERR_EXISTS_OUTSIDE_SCOPE} \\
+
+%
 \littleheader{Data type constants}
-\refconst{PMIX_COORD}
-\refconst{PMIX_REGATTR}
-\refconst{PMIX_REGEX}
-\refconst{PMIX_JOB_STATE}
-\refconst{PMIX_LINK_STATE}
-\refconst{PMIX_PROC_CPUSET}
-\refconst{PMIX_GEOMETRY}
-\refconst{PMIX_DEVICE_DIST}
-\refconst{PMIX_ENDPOINT}
-\refconst{PMIX_TOPO}
-\refconst{PMIX_DEVTYPE}
-\refconst{PMIX_LOCTYPE}
-\refconst{PMIX_DATA_TYPE_MAX}
+\refconst{PMIX_COORD} \\
+\refconst{PMIX_REGATTR} \\
+\refconst{PMIX_REGEX} \\
+\refconst{PMIX_JOB_STATE} \\
+\refconst{PMIX_LINK_STATE} \\
+\refconst{PMIX_PROC_CPUSET} \\
+\refconst{PMIX_GEOMETRY} \\
+\refconst{PMIX_DEVICE_DIST} \\
+\refconst{PMIX_ENDPOINT} \\
+\refconst{PMIX_TOPO} \\
+\refconst{PMIX_DEVTYPE} \\
+\refconst{PMIX_LOCTYPE} \\
+\refconst{PMIX_DATA_TYPE_MAX} \\
 
 %
 \littleheader{Server constants}
-\refconst{PMIX_ERR_REPEAT_ATTR_REGISTRATION}
+\refconst{PMIX_ERR_REPEAT_ATTR_REGISTRATION} \\
 %
 %
 \littleheader{Job-Mgmt constants}
-\refconst{PMIX_ERR_CONFLICTING_CLEANUP_DIRECTIVES}
+\refconst{PMIX_ERR_CONFLICTING_CLEANUP_DIRECTIVES} \\
 %
 %
 \littleheader{Publish constants}
-\refconst{PMIX_ERR_DUPLICATE_KEY}
+\refconst{PMIX_ERR_DUPLICATE_KEY} \\
 %
 %
 \littleheader{Tool constants}