Teams/Contexts Section Edits

content/context_intro.tex

@@ -9,7 +9,7 @@
 thread interference.
 
 A specific communication context is referenced through a context handle, which is
-passed as an argument in the \Cstd \CTYPE{shmem\_ctx\_*} and type-generic \ac{API}
+passed as an argument in the \CTYPE{shmem\_ctx\_*} and type-generic \ac{API}
 routines.  \ac{API} routines that do not accept a context handle argument operate on the
 default context.  The default context can be used explicitly through the
 \LibHandleRef{SHMEM\_CTX\_DEFAULT} handle.
@@ -42,4 +42,31 @@
 All point-to-point routines that operate on this context will do so with
 respect to the team-relative \ac{PE} numbering of the associated team.
 If the PE number passed to such a routine is invalid, being negative or greater
-than or equal to the size of the \openshmem team, then the behavior is undefined.
+than or equal to the size of the \openshmem team, then the behavior is undefined.
+
+By default, contexts are {\em shareable} and, when it is allowed by the
+threading model provided by the \openshmem library, they can be used concurrently by
+multiple threads within the PE where they were created.
+%
+The following options can be supplied during context creation to restrict
+this usage model and enable performance optimizations.  When using a given
+context, the application must comply with the requirements of all options
+set on that context; otherwise, the behavior is undefined.
+No options are enabled on the default context.
+
+\apitablerow{\LibConstRef{SHMEM\_CTX\_SERIALIZED}}{
+    The given context is shareable; however, it will not be used by multiple threads
+    concurrently.  When the \CONST{SHMEM\_CTX\_SERIALIZED} option is
+    set, the user must ensure that operations involving the given
+    context are serialized by the application.}
+
+\apitablerow{\LibConstRef{SHMEM\_CTX\_PRIVATE}}{
+    The given context will be used only by the thread that created it.}
+
+\apitablerow{\LibConstRef{SHMEM\_CTX\_NOSTORE}}{
+    Quiet and fence operations performed on the given context are not
+    required to enforce completion and ordering of memory store
+    operations.
+    When ordering of store operations is needed, the application must
+    perform a synchronization operation on a context without the
+    \CONST{SHMEM\_CTX\_NOSTORE} option enabled.}

content/shmem_ctx_create.tex

@@ -18,7 +18,10 @@
 
 \apidescription{
     The \FUNC{shmem\_ctx\_create} routine creates a new communication context
-    and returns its handle through the \VAR{ctx} argument.  If the context was
+    and returns its handle through the \VAR{ctx} argument.
+    This context is created from the world team;
+    however, the context creation operation is not collective.
+    If the context was
     created successfully, a value of zero is returned
     and the context handle pointed to by \VAR{ctx} specifies a valid context;
     otherwise, a nonzero value is returned and \VAR{ctx} is set to
@@ -28,40 +31,10 @@
     in a correct state.  The creation call can be reattempted with different
     options or after additional resources become available.
 
-    A newly created communication context has a fixed association with the
-    world team.
     All \openshmem routines that operate on this context will do so with
     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.
-
-    By default, contexts are {\em shareable} and, when it is allowed by the
-    threading model provided by the \openshmem library, they can be used concurrently by
-    multiple threads within the PE where they were created.
-    %
-    The following options can be supplied during context creation to restrict
-    this usage model and enable performance optimizations.  When using a given
-    context, the application must comply with the requirements of all options
-    set on that context; otherwise, the behavior is undefined.
-    No options are enabled on the default context.
-
-        \apitablerow{\LibConstRef{SHMEM\_CTX\_SERIALIZED}}{
-            The given context is shareable; however, it will not be used by multiple threads
-            concurrently.  When the \CONST{SHMEM\_CTX\_SERIALIZED} option is
-            set, the user must ensure that operations involving the given
-            context are serialized by the application.}
-
-        \apitablerow{\LibConstRef{SHMEM\_CTX\_PRIVATE}}{
-            The given context will be used only by the thread that created it.}
-
-        \apitablerow{\LibConstRef{SHMEM\_CTX\_NOSTORE}}{
-            Quiet and fence operations performed on the given context are not
-            required to enforce completion and ordering of memory store
-            operations.
-            When ordering of store operations is needed, the application must
-            perform a synchronization operation on a context without the
-            \CONST{SHMEM\_CTX\_NOSTORE} option enabled.}
-
 }
 
 \apireturnvalues{

content/shmem_ctx_get_team.tex

@@ -23,15 +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 \VAR{team} is assigned the handle value
+  \FUNC{shmem\_ctx\_create}, \VAR{team} is assigned the handle value
   \LibHandleRef{SHMEM\_TEAM\_WORLD}.
 
   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.
 }
 
 \apireturnvalues{

content/shmem_team_config_t.tex

@@ -16,7 +16,7 @@
 
 
 \apidescription{
-  A team configuration argument acts as an input
+  A team configuration object is provided as an argument to
   \FUNC{shmem\_team\_split\_*} routines.
   It specifies the requested capabilities of the team to be
   created.
@@ -26,42 +26,35 @@
   These contexts may be created in any number of threads. Successful
   creation of a team configured with \VAR{num\_contexts} of $N$ means
   that the implementation will make a best effort to reserve enough
-  resources to allow the team to have $N$ contexts created from the team
+  resources to support $N$ contexts created from the team
   in existance at any given time. It is not a guaruntee that $N$
   calls to \FUNC{shmem\_team\_create\_ctx} will succeed.
   See Section~\ref{sec:ctx} for more on communication contexts and
   Section~\ref{subsec:shmem_team_create_ctx} for team-based context creation.
 
   When using the configuration structure to create teams, a mask parameter
-  controls which fields to use.
+  controls which fields may be accessed by the \openshmem library.
   Any configuration parameter value that is not indicated in the mask will be
   ignored, and the default value will be used instead.
-  Therefore, a program does not have to set all fields in the config struct;
-  only those for which it does not want the default values.
-
-  A configuration mask value is created by combining individual field
-  masks with through a bitwise OR operation of the following library constants:
-
-  {
-    \apitablerow{\LibConstRef{SHMEM\_TEAM\_NUM\_CONTEXTS}}{
-      The team should be created using the value of the
-      \VAR{num\_contexts} member of the configuration parameter
-      \VAR{config} as a requirement.
-    }
-  }
+  Therefore, a program must only set the fields for which it does not want the default value.
 
+  A configuration mask is created through a bitwise OR operation of the
+  following library constants.
   A configuration mask value of \CONST{0} indicates that the team
   should be created with the default values for all configuration
   parameters.
 
+  \apitablerow{\LibConstRef{SHMEM\_TEAM\_NUM\_CONTEXTS}}{
+    The team should be created using the value of the
+    \VAR{num\_contexts} member of the configuration parameter
+    \VAR{config} as a requirement.
+  }
+
   The default values for configuration parameters are:
 
-  {
-    \apitablerow{num\_contexts = \CONST{0}}{
-      By default, no contexts can be created on a new team
-    }
+  \apitablerow{\VAR{num\_contexts} = \CONST{0}}{
+    By default, no contexts can be created on a new team
   }
-
 }
 
 \end{apidefinition}

content/shmem_team_split_2d.tex

@@ -1,8 +1,8 @@
 \apisummary{
 Create two new teams by splitting an existing parent team into two subsets based on a
-2D Cartesian space defined by the \VAR{xrange} argument and a \VAR{y} dimension derived from \VAR{xrange}
-and the parent team size. These ranges describe the Cartesian space in \emph{x}-
-and \emph{y}-dimensions.}
+2D Cartesian space defined by the \VAR{xrange} argument and a \VAR{y} dimension that is derived from \VAR{xrange}
+and the parent team size.
+}
 
 \begin{apidefinition}
 
@@ -16,7 +16,7 @@
 \apiargument{IN}{parent\_team}{A valid \openshmem team. Any predefined teams, such as
 \LibHandleRef{SHMEM\_TEAM\_WORLD}, may be used, or any team created by the user.}
 
-\apiargument{IN}{xrange}{A nonnegative integer representing the number of
+\apiargument{IN}{xrange}{A positive integer representing the number of
 elements in the first dimension.}
 
 \apiargument{IN}{xaxis\_config}{
@@ -27,7 +27,7 @@
   from \VAR{xaxis\_config}.}
 
 \apiargument{OUT}{xaxis\_team}{A new \ac{PE} team handle representing a \ac{PE}
-subset consisting of all the \acp{PE} that have the same coordinate along the \VAR{x}-axis
+subset consisting of all the \acp{PE} that have the same coordinate along the \VAR{y}-axis
 as the calling \ac{PE}.}
 
 \apiargument{IN}{yaxis\_config}{
@@ -38,22 +38,24 @@
   from \VAR{yaxis\_config}.}
 
 \apiargument{OUT}{yaxis\_team}{A new \ac{PE} team handle representing a \ac{PE}
-subset consisting of all the \acp{PE} that have the same coordinate along the \VAR{y}-axis
+subset consisting of all the \acp{PE} that have the same coordinate along the \VAR{x}-axis
 as the calling \ac{PE}.}
 \end{apiarguments}
 
 \apidescription{
-The \FUNC{shmem\_team\_split\_2d} routine is a collective routine. It creates two
-new teams by splitting an existing parent team into up to two subsets based on a
+The \FUNC{shmem\_team\_split\_2d} routine is a collective operation. It returns two
+new teams to the calling \ac{PE} by splitting an existing parent team into subsets based on a
 2D Cartesian space. The user provides the size of the \VAR{x} dimension, which is then
 used to derive the size of the \VAR{y} dimension based on the size of the parent team.
 The size of the \VAR{y} dimension will be equal to $\lceil N \div xrange \rceil$, where
 \VAR{N} is the size of the parent team. In other words,
 $xrange \times yrange \geq N$, so that every \ac{PE} in the parent team has a
-unique \VAR{(x,y)} location the 2D Cartesian space.
+unique \VAR{(x,y)} location in the 2D Cartesian space. The resulting \VAR{xaxis\_team}
+and \VAR{yaxis\_team} correspond to the calling \ac{PE}'s row and column, respectively, in the
+2D Cartesian space.
 
 The mapping of \ac{PE} number to coordinates is $(x, y) = ( pe \mod xrange, \lfloor pe \div xrange \rfloor )$,
-where $pe$ is the \ac{PE} number in the parent team. So, if $xrange = 3$,
+where $pe$ is the \ac{PE} number in the parent team. For example, if $xrange = 3$,
 then the first 3 \acp{PE} in the parent team will form the first
 \VAR{xteam}, the second three \acp{PE} in the parent team form the second \VAR{xteam},
 and so on.
@@ -64,14 +66,14 @@
 \VAR{x}-axis as the calling \ac{PE}.
 
 The \acp{PE} are numbered in the new teams based on the coordinate of the
-\ac{PE} along the given axis. So, another way to think of the result of the split
-operation is that the value returned by \FUNC{shmem\_team\_my\_pe(\VAR{xteam})} is the
-x-coordinate and the value returned by \FUNC{shmem\_team\_my\_pe(\VAR{yteam})}
-is the y-coordinate of the calling \ac{PE}.
+\ac{PE} along the given axis. As a result,
+the value returned by \FUNC{shmem\_team\_my\_pe(\VAR{xteam})} is the
+\VAR{x}-coordinate and the value returned by \FUNC{shmem\_team\_my\_pe(\VAR{yteam})}
+is the \VAR{y}-coordinate of the calling \ac{PE}.
 
 Any valid \openshmem team can be used as the parent team. This routine must be
 called by all \acp{PE} in the parent team. The value of \VAR{xrange} must be
-nonnegative and all \acp{PE} in the parent team must pass the same value for
+a positive integer and all \acp{PE} in the parent team must pass the same value for
 \VAR{xrange}.
 
 The \VAR{xaxis\_config} and \VAR{yaxis\_config} arguments specify team
@@ -137,8 +139,8 @@
 for \VAR{yaxis\_config} than all of the other \acp{PE}, as long as the configuration parameters match
 for all \acp{PE} in each of the new teams.
 
-See the description of team handles and predefined teams at the top of section
-\ref{subsec:team} for more information about team handle semantics and usage.
+See the description of team handles and predefined teams in Section~\ref{subsec:team}
+for more information about team handle semantics and usage.
 }
 
 \begin{apiexamples}

content/shmem_team_split_strided.tex

@@ -30,40 +30,40 @@
   The bitwise mask representing the set of configuration parameters to use
   from \VAR{config}.}
 
-\apiargument{OUT}{new\_team}{A new \openshmem team handle, representing a \ac{PE}
-subset of all the \acp{PE} in the parent team that is created from
-the \ac{PE} triplet provided.}
+\apiargument{OUT}{new\_team}{An \openshmem team handle. Upon successful creation, it
+references an \openshmem team that contains the subset of all \acp{PE} in the
+parent team specified by the \ac{PE} triplet provided.}
 
 \end{apiarguments}
 
 \apidescription{
 The \FUNC{shmem\_team\_split\_strided} routine is a collective routine.
-It creates a new \openshmem team from a subset of the existing parent team,
-where the \ac{PE} subset is defined by the triplet of arguments
+It creates a new \openshmem team from an existing parent team,
+where the \ac{PE} subset of the resulting team is defined by the triplet of arguments
 (\VAR{start}, \VAR{stride}, \VAR{size}).
 A valid triplet is one such that:
 \begin{equation*}
-  start + stride \cdot i \in \mathbb{Z}_N
-  \hspace{0.35em}
+  start + stride \cdot i \in \mathbb{Z}_{N-1}
+  \;
   \forall
-  \hspace{0.35em}
-  i \in \mathbb{Z}_{size}
+  \;
+  i \in \mathbb{Z}_{size-1}
 \end{equation*}
-where $N$ is the number of \acp{PE} in the parent team and $size$ is greater than zero.
+where $\mathbb{Z}$ is the set of natural numbers ($0, 1, \dots$), $N$ is the
+number of \acp{PE} in the parent team and $size$ is a positive number indicating
+the number of \acp{PE} in the new team. The index $i$ specifies the number of
+the given PE in the new team. Thus, \acp{PE} in the new team remain in the same
+relative order as in the parent team.
 
 This routine must be called by all \acp{PE} in the parent team.
 All \acp{PE} must provide the same values for the \ac{PE} triplet.
-This routine will return a \VAR{new\_team} containing the \ac{PE}
-subset specified by the triplet and ordered by the existing global
-\ac{PE} number.
-
 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}.
+  subset of \acp{PE} in the parent team that are members of the new team.
+\item Those \acp{PE} in the parent team that are not members of the new team
+  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}
@@ -94,15 +94,14 @@
 }
 
 \apinotes{
-  It is important to note the use of the less restrictive
-  \VAR{stride} argument instead of \VAR{logPE\_stride}. This method of
-  creating a team with an arbitrary set of \acp{PE} is inherently restricted
-  by its parameters, but allows for many additional use-cases over using a
-  \VAR{logPE\_stride} parameter, and may provide an easier transition for
-  existing \openshmem programs to create and use \openshmem teams.
-
-  See the description of team handles and predefined teams at the top of
-  Section~\ref{subsec:team} for more information about semantics and usage.
+  The \FUNC{shmem\_team\_split\_strided} operation uses an arbitrary
+  \VAR{stride} argument, whereas the \VAR{logPE\_stride} argument to the
+  active set collective operations only permits strides that are a power of two.
+  Arbitrary strides allow a greater number of PE subsets to be expressed
+  and can support a broader range of usage models.
+
+  See the description of team handles and predefined teams in
+  Section~\ref{subsec:team} for more information about team handle semantics and usage.
 }
 
 \begin{apiexamples}

content/shmem_team_translate_pe.tex

@@ -20,7 +20,7 @@
 The \FUNC{shmem\_team\_translate\_pe} routine will translate a given \ac{PE} number
 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
+\ac{PE}'s number in \VAR{dest\_team}. If \VAR{src\_pe} is not a member of both
 \VAR{src\_team} and \VAR{dest\_team}, a value of \CONST{-1} is returned.
 
 If at least one of \VAR{src\_team} and \VAR{dest\_team} compares equal