sessions: improve writing, fix example, SAME_AMO

content/sessions_intro.tex

@@ -10,6 +10,10 @@
 which patterns of \openshmem RMA and AMO routines will occur within a session.
 These options serve only as \textit{hints} to the library; it is up to the
 implementation whether or not to apply any optimizations within a session.
+A session may be provided a configuration argument that specifies attributes
+assosiated with the session. This configuration argument is of type
+\CTYPE{shmem\_session\_config\_t}, which is detailed further in
+Section~\ref{subsec:shmem_team_config_t}.
 
 Usage of the \openshmem session APIs on a particular context must comply with
 the requirements of all options set on that context.
@@ -22,5 +26,5 @@
 routines not performed on a communication context (like collective routines)
 are ineligible for session hints.
 
-The \FUNC{shmem\_config\_t} object requires the \CONST{SIZE\_MAX} macro
+The \FUNC{shmem\_session\_config\_t} object requires the \CONST{SIZE\_MAX} macro
 defined in \HEADER{stdint.h} by \Cstd[99]~\S7.18.3 and \Cstd[11]~\S7.20.3.

content/shmem_session_config_t.tex

@@ -34,9 +34,9 @@
   completions, or memory ordering operations are unaffected by the value of
   \FUNC{total\_ops}.
 
-  When using the configuration structure to start a communication session, a
-  mask parameter controls which fields are accessed by the \openshmem
-  library.
+  When passing a configuration structure to \FUNC{shmem\_session\_start}, the
+  mask parameter specifies which fields the application requests to associate
+  with the session.
   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 must set only the fields for which it does not want
@@ -56,17 +56,16 @@
   The default values for configuration parameters are:
 
   \apitablerow{\VAR{total\_ops} = \CONST{SIZE\_MAX}}{
-    By default, the number of expected maximum number of calls to \openshmem
-    RMA routines is set to the upper bound of a \VAR{size\_t} variable,
-    \VAR{SIZE\_MAX}. This is a representative constant that indicates the
-    \openshmem library is free to select any value appropriate for the
-    implementation.
+    By default, the expected maximum number of calls to \openshmem RMA routines
+    in the session is set to the maximum value of a \VAR{size\_t} variable,
+    \VAR{SIZE\_MAX}. This default setting indicates that the \openshmem
+    application chooses not to specify a value for \VAR{total\_ops}.
   }
 }
 
 \apinotes{
     Users are discouraged from calling \FUNC{shmem\_fence},
-    \FUNC{shmem\_cxt\_fence}, \FUNC{shmem\_quiet}, or \FUNC{shmem\_ctx\_quiet}
+    \FUNC{shmem\_ctx\_fence}, \FUNC{shmem\_quiet}, or \FUNC{shmem\_ctx\_quiet}
     routines within a session whenever possible, because the library must
     impose strict completions to comply with ordering semantics.
     However, hints provided by \FUNC{shmem\_session\_config\_t} do not imply

content/shmem_session_start.tex

@@ -91,25 +91,36 @@
     memory ordering routines might require the library to enforce
     completions, reducing the potential benefit of batching.
 
-    The \VAR{total\_ops} field of \VAR{config} with mask value
-    \LibConstRef{SHMEM\_SESSION\_TOTAL\_OPS} indicates the expected maximum
+    The \VAR{total\_ops} field of \VAR{config} indicates the expected maximum
     number of calls to \openshmem RMA routines within the session.
     See Section~\ref{subsec:shmem_session_config_t} for details
     about \VAR{shmem\_session\_config\_t} parameters.
     } \hline
 
 \sessiontablerow{\LibConstRef{SHMEM\_SESSION\_SAME\_AMO}}{
-    The session will contain a batch (as defined by the
-    \VAR{SHMEM\_SESSION\_BATCH} option) of only AMOs that will not occur
-    concurrently across any different signal operators
-    (i.e.~\ref{subsec:signal_operator}), operations (\ref{sec:amo}), or types
-    (Tables \ref{stdamotypes} and \ref{extamotypes}).
-
-    The same members of the \VAR{config} structure that apply to the
-    \LibConstRef{SHMEM\_SESSION\_BATCH} option also apply to the
-    \LibConstRef{SHMEM\_SESSION\_SAME\_AMO} option. See
-    Section~\ref{subsec:shmem_session_config_t} for details about these
-    parameters.
+    The \VAR{SHMEM\_SESSION\_SAME\_AMO} hint indicates the session will contain
+    a series of calls to AMO and/or signaling routines that do not differ in
+    their signal operators (see Section \ref{subsec:signal_operator}), atomic
+    operations (see Section \ref{sec:amo}), or datatypes (see
+    Tables~\ref{stdamotypes} and \ref{extamotypes}).
+    For example, this hint would apply to a session that includes \textit{only}
+    calls to \FUNC{shmem\_int\_atomic\_inc}.
+    However, this hint would not apply to a session that includes both calls to
+    \FUNC{shmem\_int\_atomic\_inc} and \FUNC{shmem\_int\_atomic\_fetch},
+    because the operation \textit{fetch} differs from \textit{increment}.
+    (Similarly, this hint would not apply to a session that includes both calls to
+    \FUNC{shmem\_int\_atomic\_inc} and \FUNC{shmem\_long\_atomic\_inc},
+    because the datatype \textit{long} differs from \textit{int}.)
+    The \VAR{SHMEM\_SESSION\_SAME\_AMO} hint is applicable to sessions that
+    exclusively use \textit{either} the \VAR{SHMEM\_SIGNAL\_SET} or the
+    \VAR{SHMEM\_SIGNAL\_ADD} operators in signaling operations, but not both.
+    This hint does not restrict the application from calling other (non-atomic)
+    RMA routines within the session.
+
+    The \VAR{total\_ops} field of \VAR{config} indicates the expected maximum
+    number of calls to \openshmem RMA routines within the session.
+    See Section~\ref{subsec:shmem_session_config_t} for details about
+    \VAR{shmem\_session\_config\_t} parameters.
     } \hline
 
 \sessiontableend

content/shmem_session_stop.tex

@@ -33,7 +33,7 @@
 \begin{apiexamples}
 
 \apicexample
-    {The following \Cstd[11] program demonstrates the usage of
+    {The following \CorCpp{} program demonstrates the usage of
     \FUNC{shmem\_session\_start} and \FUNC{shmem\_session\_stop} with a loop of
     random atomic non-fetching XOR updates to a distributed table, similar to
     the HPC Challenge RandomAccess GUPS (Giga-updates per second) benchmark

content/shmem_team_config_t.tex

@@ -32,8 +32,8 @@
   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 may be accessed by the \openshmem library.
+  When passing a configuration structure to a team creation routine, the mask parameter
+  specifies which fields the application requests to associate with the new team.
   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 must set only the fields for which it does not want the default value.

example_code/shmem_session_example.c

@@ -1,6 +1,7 @@
 #include <shmem.h>
 #include <stdint.h>
 #include <stdlib.h>
+#include <stdio.h>
 
 #define N_UPDATES (1lu << 18)
 #define N_INDICES (1lu << 10)
@@ -23,18 +24,19 @@ int main(void) {
       shmem_global_exit(1);
   }
 
-  shmem_config_t config;
+  shmem_session_config_t config;
   long config_mask;
   config.total_ops = N_UPDATES;
   config_mask = SHMEM_SESSION_TOTAL_OPS;
+  long options = SHMEM_SESSION_BATCH | SHMEM_SESSION_SAME_AMO;
 
-  shmem_session_start(ctx, SHMEM_SESSION_SAME_AMO, config, config_mask);
+  shmem_session_start(ctx, options, &config, config_mask);
 
   for (size_t i = 0; i < N_UPDATES; i++) {
       int random_pe = rand() % npes;
       size_t random_idx = rand() % N_INDICES;
       uint64_t random_val = rand() % N_VALUES;
-      shmem_uint64_atomic_xor(ctx, &table[random_idx], random_val, random_pe);
+      shmem_ctx_uint64_atomic_xor(ctx, &table[random_idx], random_val, random_pe);
   }
 
   shmem_session_stop(ctx);

utils/defs.tex

@@ -373,7 +373,7 @@
 }
 
 \newcommand{\sessiontablebegin} {
-\begin{table}[h]
+\begin{table}[h!]
 \hspace{-0.5cm}
 \begin{tabular}{|p{4.8cm}|p{12cm}|}
     \hline