Revise error handling w.r.t. invalid teams

content/collective_intro.tex

@@ -123,6 +123,11 @@ \subsubsection*{Team-implicit collectives}
 call to \FUNC{shmem\_team\_sync} on the default team.
 
 \subsubsection*{Error codes returned from collectives}
-\CorCpp routines that return an integer error code follow the convention that \CONST{0} indicates successful local completion of the operation. This is considered a best effort of the implementation to indicate that all required local operations have been performed correctly inside the routine and the internal \openshmem state on the calling \ac{PE} is consistent with the description of the routine and its arguments upon completion. Implementations may use an integer return value from a routine to define integer error codes specific to the implementation as long as those codes are not already explicitly defined for that routine by the \openshmem specification.
 
-Collective operations involving many \acp{PE} may return values indicating success while other \acp{PE} are still executing the collective operation. Return values indicating success of a collective routine on one \ac{PE} do not indicate that all \acp{PE} involved in the collective operation will return from the routine successfully. In the case where successful local completion of a collective implies the success of some global operation, such as team creation resulting in a valid team on all involved \acp{PE}, the implementation should not return \CONST{0} from the routine if the implied or stated global guarantees of the routine are not met.
+Collective operations involving multiple \acp{PE} may return values
+indicating success while other \acp{PE} are still executing the
+collective operation. Return values indicating success or failure of a
+collective routine on one \ac{PE} may not indicate that all \acp{PE}
+involved in the collective operation will return the same value. Some
+operations, such as team creation, must return identical return codes
+across multiple \acp{PE}.

content/shmem_ctx_get_team.tex

@@ -23,12 +23,13 @@
   The team handle is returned through the pointer argument \VAR{team}.
 
   If \VAR{ctx} is the default context or one created by a call to
-  \FUNC{shmem\_ctx\_create}, the returned team is the default team.
+  \FUNC{shmem\_ctx\_create}, the \VAR{team} is assigned the handle value
+  \LibHandleRef{SHMEM\_TEAM\_WORLD}.
 
-  When \VAR{ctx} is an invalid context, if \VAR{ctx} compares equal to
-  \LibConstRef{SHMEM\_CTX\_INVALID}, then \VAR{team} is assigned the
-  value \LibConstRef{SHMEM\_TEAM\_INVALID} and a nonzero value is
-  returned; otherwise, the behavior is undefined.
+  If \VAR{ctx} compares equal to \LibConstRef{SHMEM\_CTX\_INVALID},
+  then \VAR{team} is assigned the value
+  \LibConstRef{SHMEM\_TEAM\_INVALID} and a nonzero value is returned.
+  If \VAR{ctx} is otherwise invalid, the behavior is undefined.
 
   If \VAR{team} is a null pointer, the behavior is undefined.
 }

content/shmem_team_create_ctx.tex

@@ -47,6 +47,11 @@
   respect to the associated \ac{PE} team.
   That is, all point-to-point routines operating on this context will use
   team-relative \ac{PE} numbering.
+
+  If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID},
+  then a nonzero value is returned and \VAR{ctx} is set to
+  \LibConstRef{SHMEM\_CTX\_INVALID}.
+  If \VAR{team} is otherwise invalid, the behavior is undefined.
 }
 
 \apireturnvalues{

content/shmem_team_destroy.tex

@@ -24,11 +24,11 @@
 enabled prior to calling this routine; otherwise, the behavior is
 undefined.
 
-It is an error to free the default team or any other predefined team.
+It is an error to destroy the default team or any other predefined team.
 
-When \VAR{team} specifies an invalid team, if \VAR{team} compares
-equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, then no operation is
-performed; otherwise, the behavior is undefined.
+If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID},
+then no operation is performed.
+If \VAR{team} is otherwise invalid, the behavior is undefined.
 }
 
 \apireturnvalues{

content/shmem_team_get_config.tex

@@ -19,16 +19,16 @@
 the configuration parameters of the given team, which were assigned according
 to input configuration parameters when the team was created.
 
-When \VAR{team} specifies an invalid team, if \VAR{team} compares
-equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, then no operation is
-performed; otherwise, the behavior is undefined.
+If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID},
+then no operation is performed.
+If \VAR{team} is otherwise invalid, the behavior is undefined.
 }
 
 \apireturnvalues{
   If \VAR{team} does not compare equal to
   \LibConstRef{SHMEM\_TEAM\_INVALID}, then
-  \FUNC{shmem\_team\_get\_config} returns \CONST{0}; otherwise,
-  returns nonzero.
+  \FUNC{shmem\_team\_get\_config} returns \CONST{0};
+  otherwise, it returns nonzero.
 }
 
 \apinotes{

content/shmem_team_my_pe.tex

@@ -16,12 +16,12 @@
   When \VAR{team} specifies a valid team, the
   \FUNC{shmem\_team\_my\_pe} routine returns the number of the calling
   \ac{PE} within the specified team.
-  The number is an integer between $0$ and $N-1$ for a team of size $N$.
+  The number is an integer between $0$ and $N-1$ for a team containing $N$ \acp{PE}.
   Each member of the team has a unique number.
 
-  When \VAR{team} specifies an invalid team, if \VAR{team} compares
-  equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, then the value
-  \CONST{-1} is returned; otherwise, the behavior is undefined.
+  If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID},
+  then the value \CONST{-1} is returned.
+  If \VAR{team} is otherwise invalid, the behavior is undefined.
 }
 
 \apireturnvalues{

content/shmem_team_n_pes.tex

@@ -19,9 +19,9 @@
   This will always be a value between $1$ and $N$, where $N$ is the
   total number of \acp{PE} running in the \openshmem program.
 
-  When \VAR{team} specifies an invalid team, if \VAR{team} compares
-  equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, then the value
-  \CONST{-1} is returned; otherwise, the behavior is undefined.
+  If \VAR{team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID},
+  then the value \CONST{-1} is returned.
+  If \VAR{team} is otherwise invalid, the behavior is undefined.
 }
 
 \apireturnvalues{

content/shmem_team_split_2d.tex

@@ -90,19 +90,23 @@
 See Section~\ref{subsec:shmem_team_config_t} for field mask names and
 default configuration parameters.
 
-If \VAR{parent\_team} is an invalid team handle, the behavior is undefined.
+If \VAR{parent\_team} compares equal to
+\LibConstRef{SHMEM\_TEAM\_INVALID}, then no new teams will be created
+and both \VAR{xaxis\_team} and \VAR{yaxis\_team} will be assigned the
+value \LibConstRef{SHMEM\_TEAM\_INVALID}.
+If \VAR{parent\_team} is otherwise invalid, the behavior is undefined.
+
+If any \VAR{xaxis\_team} or \VAR{yaxis\_team} on any \ac{PE} in
+\VAR{parent\_team} cannot be created, then both team handles on all
+\acp{PE} in \VAR{parent\_team} will be assigned the value
+\LibConstRef{SHMEM\_TEAM\_INVALID} and \FUNC{shmem\_team\_split\_2d}
+will return a nonzero value.
 
-If \VAR{parent\_team} compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, no new
-teams will be created, and both \VAR{xaxis\_team} and \VAR{yaxis\_team}
-will be assigned the value \LibConstRef{SHMEM\_TEAM\_INVALID}.
-
-If either team cannot be created, that team will be assigned the value
-\LibConstRef{SHMEM\_TEAM\_INVALID}.
 }
 
 \apireturnvalues{
-  Zero on successful creation of both \VAR{xaxis\_team} and \VAR{yaxis\_team},
-  nonzero otherwise.
+  Zero on successful creation of all \VAR{xaxis\_team}s and \VAR{yaxis\_team}s;
+  otherwise, nonzero.
 }
 
 \apinotes{

content/shmem_team_split_strided.tex

@@ -57,12 +57,21 @@
 subset specified by the triplet and ordered by the existing global
 \ac{PE} number.
 
-On successful creation of the new team, the \VAR{new\_team} handle
-will reference a valid team for the subset of \acp{PE} in the parent
-team specified by the triplet.
-Those \acp{PE} in the parent team that are not in the subset specified
-by the triplet will have \VAR{new\_team} assigned to
-\LibConstRef{SHMEM\_TEAM\_INVALID}.
+On successful creation of the new team:
+\begin{itemize}
+\item The \VAR{new\_team} handle will reference a valid team for the
+  subset of \acp{PE} in the parent team specified by the triplet.
+\item Those \acp{PE} in the parent team that are not in the subset
+  specified by the triplet will have \VAR{new\_team} assigned to
+  \LibConstRef{SHMEM\_TEAM\_INVALID}.
+\item \FUNC{shmem\_team\_split\_strided} will return zero to all
+  \acp{PE} in the parent team.
+\end{itemize}
+
+If the new team cannot be created, then \VAR{new\_team} will be
+assigned the value \LibConstRef{SHMEM\_TEAM\_INVALID} and
+\FUNC{shmem\_team\_split\_strided} will return a nonzero value on all
+\acp{PE} in the parent team.
 
 The \VAR{config} argument specifies team configuration parameters, which are
 described in Section~\ref{subsec:shmem_team_config_t}.
@@ -74,20 +83,17 @@
 See Section~\ref{subsec:shmem_team_config_t} for field mask names and
 default configuration parameters.
 
-When \VAR{parent\_team} specifies an invalid team, if \VAR{parent\_team}
+If \VAR{parent\_team}
 compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}, then no new team
 will be created and \VAR{new\_team} will be assigned the value
-\LibConstRef{SHMEM\_TEAM\_INVALID}; otherwise, the behavior is undefined.
+\LibConstRef{SHMEM\_TEAM\_INVALID}.  If \VAR{parent\_team} is otherwise invalid, the behavior is undefined.
 
 If an invalid \ac{PE} triplet is provided, then the \VAR{new\_team}
 will not be created.
-
-If \VAR{new\_team} cannot be created, then it will be assigned the value
-\LibConstRef{SHMEM\_TEAM\_INVALID}.
 }
 
 \apireturnvalues{
-  Zero on successful creation of \VAR{new\_team}, nonzero otherwise.
+  Zero on successful creation of \VAR{new\_team}; otherwise, nonzero.
 }
 
 \apinotes{

content/shmem_team_translate_pe.tex

@@ -11,20 +11,22 @@
 \end{Csynopsis}
 
 \begin{apiarguments}
-\apiargument{IN}{src\_team}{A valid SHMEM team handle.}
+\apiargument{IN}{src\_team}{An \openshmem team handle.}
 \apiargument{IN}{src\_pe}{A \ac{PE} number in \VAR{src\_team}.}
-\apiargument{IN}{dest\_team}{A valid SHMEM team handle.}
+\apiargument{IN}{dest\_team}{An \openshmem team handle.}
 \end{apiarguments}
 
 \apidescription{
 The \FUNC{shmem\_team\_translate\_pe} routine will translate a given \ac{PE} number
-to the corresponding \ac{PE} number in another team.
+in one team into the corresponding \ac{PE} number in another team.
 Specifically, given the \VAR{src\_pe} in \VAR{src\_team}, this routine returns that
 \ac{PE}'s number in \VAR{dest\_team}. If \VAR{src\_pe} is not a member of both the
 \VAR{src\_team} and \VAR{dest\_team}, a value of \CONST{-1} is returned.
 
-
-If either of the \VAR{src\_team} or \VAR{dest\_team} handle is invalid, the behavior is undefined.
+If at least one of \VAR{src\_team} and \VAR{dest\_team} compares equal
+to \LibConstRef{SHMEM\_TEAM\_INVALID}, then \CONST{-1} is returned.
+If either of the \VAR{src\_team} or \VAR{dest\_team} handles are
+otherwise invalid, the behavior is undefined.
 }
 
 \apireturnvalues{