Another pass at adding PMIX_DATA_TO_PUBLISH directive

Author: dsolt

Chap_API_Publish.tex

@@ -76,23 +76,31 @@ \section{\code{PMIx_Publish}}
 ranges. Custom ranges are consider different if they have different members.
 Duplicate keys being published on the same data range shall return the
 \refconst{PMIX_ERR_DUPLICATE_KEY} error.
+publishing to a \declareconstitem{PMIX_RANGE_CUSTOM}
+range which does not include the publisher will prevent
+any processes from using \refapi{PMIX_Lookup} to access the published data.
 
 In some cases, implementations may be incapable of distinguishing which
 info keys in the \refarg{info} array are for publishing and which info keys are
 directives.  To make it clear, it is recommended that the keys to be published
 are designated by passing them as a \refstruct{pmix_data_array_t} using the
 \refattr{PMIX_DATA_TO_PUBLISH} directive.
-
-For the purpose of distinguishing between info array elements that specify keys and attributes, implementations should attempt to
-recognize all standardized attributes to the publish call,
-even attributes the implementation does not support.  Non-supported attributes
+If the \refarg{info} array contains a \refattr{PMIX_DATA_TO_PUBLISH} info,
+all other elements of the info array will be treated as directives.
+If the info array does not include a \refattr{PMIX_DATA_TO_PUBLISH} info,
+the implementation should
+distinguishing between info array elements that specify keys and directives as follows:
+All standardized directives to the publish call,
+including optional attributes the implementation does not support,
+should be treated as
+directives.  Non-supported directives
 may be ignored as outlined in Section \ref{intro:portability:attributes},
 but should not be treated as data to
-publish.  Only if a member of the \refarg{info} array is not recognized
-as an attribute, should it be assumed to be data to be published.
-Since implementations may support custom directives, it is always preferable that
-clients use the \refattr{PMIX_DATA_TO_PUBLISH} directive to clearly designate the
-keys to be published.
+publish.  The implementation may treat any custom (non-standardized) directives it
+supports as directives.  All other \refarg{info} array elements
+should it be assumed to be data to be published.
+Since additional directives may be added to the standard and implementations may add support for additional custom directives, the use of \refattr{PMIX_DATA_TO_PUBLISH} is the only reliable way to ensure that
+future implementations will not mis-classify elements of an \refarg{info} array.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -368,8 +376,10 @@ \section{\code{PMIx_Lookup}}
 \descr
 
 Lookup information published by a process or host environment using \refapi{PMIx_Publish} or \refapi{PMIx_Publish_nb}.
-By default, the search will be constrained to publishers that fall within the \refconst{PMIX_RANGE_SESSION} range in case duplicate keys exist on different ranges.
-Changes to the range (e.g., expanding the search to all potential publishers via the \refconst{PMIX_RANGE_GLOBAL} constant), and any additional directives, can be provided in the \refstruct{pmix_info_t} array. Data is returned per the retrieval rules of Section \ref{chap:pub:retrules}.
+A lookup operation is always performed on a range which can be specified using the directive \refconst{PMIX_RANGE} or otherwise defaults to \refconst{PMIX_RANGE_SESSION}.
+The lookup operation will be constrained to publishers that fall within 
+the range and that published data to the range.
+Data is returned per the retrieval rules of Section \ref{chap:pub:retrules}.
 
 The \argref{data} parameter consists of an array of \refstruct{pmix_pdata_t} structures with the keys specifying the requested information.
 Data will be returned for each \code{key} field in the associated \code{value} field of this structure as per the above description of return values. The \code{proc} field in each \refstruct{pmix_pdata_t} structure will contain the namespace/rank of the process that published the data.
@@ -569,44 +579,27 @@ \subsubsection{Lookup data structure support macros}
 \section{Retrieval rules for published data}
 \label{chap:pub:retrules}
 
-\begingroup
-\begin{figure*}[ht!]
-\begin{center}
-\includegraphics[clip,width=0.9\textwidth]{figs/publish_lookup.pdf}
-\end{center}
-\caption{Example Publish, Lookup retrieval rules}
-\label{fig:publish_lookup}
-\end{figure*}
-\endgroup
-
 The retrieval rules for published data primarily revolve around enforcing data access permissions and range constraints.
 All publish and lookup operations operate on a range. If not specified, the range defaults to \refconst{PMIX_RANGE_SESSION}.
 The key being looked up will match with a published key only if all of the following conditions are met:
 
 \begin{enumerate}
     \item The lookup key matches the published key.
-    \item The publisher of the published key falls within the lookup range specified by the requester.
-    \item The requester falls within the range specified by the publisher.
+    \item The type of range specified by the publisher is the same as the type of range specified by the requester.
+    \item If a custom range is specified by the publisher and the requester, the members described in both cases must be identical.
+    \item The publisher must be a member of the requestors range.
+    \item The requestor must be a member of the publishers range.
+
+%%option2:
+%%
+%%    \item The publisher's range must describe the same set of processes as the requestor's range.
+%%    \item The requestor must be a member of the range specified.
+%%
+%% The difference here is in how custom ranges are handled in which the publisher is not a member of the custom range it describes.   The later case allows the publisher to publish to a custom range that includes a set of processes not including itself.
+
     \item If the publisher specified access permissions, the effective \ac{UID} and \ac{GID} of the requester must meet those requirements.
 \end{enumerate}
 
-Fig.~\ref{fig:publish_lookup} shows process P0 executing on Host X in Namespace 1 in Session A publishing the key "tree" on three ranges.  Publishing to different ranges is allowed.
-However, as the figure demonstrates, doing so must be done carefully to ensure predictable outcomes across different implementations.  The figure shows processes P1 and P2 performing various lookup operation on the key "tree" using different ranges.
-Process P1 does not successfully lookup a value for "tree" on the range \refconst{PMIX_RANGE_LOCAL}
-because the only publisher is not within P1's specified range which covers only its
-local host.  Similarly, P1 will not successfully lookup a value for "tree" on the range
-\refconst{PMIX_RANGE_NAMESPACE} since the only publisher is not within P1's namespace.
-A lookup of "tree" by P1 on the range \refconst{PMIX_RANGE_GLOBAL} does permit possible matches of keys published by P0.  P0 has published "tree" three times,
-but P1 is outside of the P0's node and namespace ranges.  Therefore, only the value of "tree"
-published to the session level is retrievable by P1.  Notice that the lookup range
-does not need to match the publishing range for a match to occur.  The requirement
-is that the requester is in the range specified by the publisher and the publisher is in the range specified by the requester.
-
-The figure shows a similar scenario for P2.  However, unlike P1, P2 is in the same namespace as P0 which results in two possible published values of
-"tree" that could be returned by a call to \refapi{PMIx_Lookup} by P2 on the range \refconst{PMIX_RANGE_SESSION} or \refconst{PMIX_RANGE_NAMESPACE}.
-An implementation is required to return one of the possible matches in such cases where
-there are multiple possible matches.
-
 The status returned by the datastore shall be set to:
 
 \begin{itemize}
@@ -622,13 +615,6 @@ \section{Retrieval rules for published data}
 \item a non-zero \ac{PMIx} error constant indicating a reason for the request's failure.
 \end{itemize}
 
-\adviceuserstart
-Note that duplicate keys are allowed to exist on different ranges, and that ranges do overlap each other. Thus, if duplicate keys are published on overlapping ranges, it is possible for the datastore to successfully find multiple responses for a given key should publisher and requester specify sufficiently broad ranges. In this situation, the choice of resolving the duplication is left to the datastore implementation - e.g., it may return the first value found in its search, or the value corresponding to the most limited range of the found values, or it may choose to simply return an error.
-
-Users are advised to avoid this ambiguity by careful selection of key values and ranges - e.g., by creating range-specific keys where necessary.
-\adviceuserend
-
-
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{\code{PMIx_Unpublish}}