sessions: rename entire API to shmem_ctx_session_*

content/sessions_intro.tex

@@ -4,15 +4,15 @@
 A session is associated with a specific \openshmem communication context
 (Section~\ref{sec:ctx}), and it indicates the beginning and ending of
 communication phases on that context.
-The \FUNC{shmem\_session\_start} routine indicates the beginning of a session,
-and the \FUNC{shmem\_session\_stop} routine indicates the end of a session.
-The \LibConstRef{SHMEM\_SESSION\_*} options (Table~\ref{session_opts}) indicate
+The \FUNC{shmem\_ctx\_session\_start} routine indicates the beginning of a session,
+and the \FUNC{shmem\_ctx\_session\_stop} routine indicates the end of a session.
+The \LibConstRef{SHMEM\_CTX\_SESSION\_*} options (Table~\ref{session_opts}) indicate
 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
+associated with the session. This configuration argument is of type
+\CTYPE{shmem\_ctx\_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
@@ -26,5 +26,6 @@
 routines not performed on a communication context (like collective routines)
 are ineligible for session hints.
 
-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.
+The \FUNC{shmem\_ctx\_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 → content/shmem_ctx_session_config_t.tex

@@ -7,7 +7,7 @@
 \begin{Csynopsis}
 typedef struct {
   size_t total_ops;
-} shmem_session_config_t;
+} shmem_ctx_session_config_t;
 \end{Csynopsis}
 
 \begin{apiarguments}
@@ -17,26 +17,26 @@
 
 \apidescription{
   A communication session configuration object is provided as an argument to
-  the \FUNC{shmem\_session\_start} routine.
-  The \VAR{shmem\_session\_config\_t} object contains optional parameters
+  the \FUNC{shmem\_ctx\_session\_start} routine.
+  The \VAR{shmem\_ctx\_session\_config\_t} object contains optional parameters
   that are associated with the options of a communication session.
   These parameters serve only as \textit{hints} to the library; it is up to
   the implementation whether or not to use the parameter values within
   a session.
 
   The \VAR{total\_ops} member indicates the expected maximum number of all
   calls to \openshmem RMA routines within the session (i.e., after a call to
-  \FUNC{shmem\_session\_start} and before a corresponding call to
-  \FUNC{shmem\_session\_stop}).
+  \FUNC{shmem\_ctx\_session\_start} and before a corresponding call to
+  \FUNC{shmem\_ctx\_session\_stop}).
   If \VAR{total\_ops} differs from the \textit{actual} number of calls to
   \openshmem RMA routines within the session, then application performance
   might be suboptimal; however, the result of any data transfers,
   completions, or memory ordering operations are unaffected by the value of
   \FUNC{total\_ops}.
 
-  When passing a configuration structure to \FUNC{shmem\_session\_start}, the
-  mask parameter specifies which fields the application requests to associate
-  with the session.
+  When passing a configuration structure to \FUNC{shmem\_ctx\_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
@@ -48,14 +48,14 @@
   should be started with the default values for all configuration
   parameters.
 
-  \apitablerow{\LibConstRef{SHMEM\_SESSION\_TOTAL\_OPS}}{
+  \widetablerow{\LibConstRef{SHMEM\_CTX\_SESSION\_TOTAL\_OPS}}{
     The value of the \VAR{total\_ops} member of the \VAR{config} structure is
     unmasked within the session and applied as a hint.
   }
 
   The default values for configuration parameters are:
 
-  \apitablerow{\VAR{total\_ops} = \CONST{SIZE\_MAX}}{
+  \widetablerow{\VAR{total\_ops} = \CONST{SIZE\_MAX}}{
     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
@@ -68,12 +68,12 @@
     \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
+    However, hints provided by \FUNC{shmem\_ctx\_session\_config\_t} do not imply
     the occurence of any completion or memory ordering operations.
     The requirements on buffers provided to \openshmem routines that are
     \textit{in-use} (as described in Section
     \ref{subsec:invoking_openshmem_operations}) apply regardless of any
-    \FUNC{shmem\_session\_config\_t} hints.
+    \FUNC{shmem\_ctx\_session\_config\_t} hints.
 }
 
 \end{apidefinition}

content/shmem_session_start.tex → content/shmem_ctx_session_start.tex

@@ -5,7 +5,7 @@
 \begin{apidefinition}
 
 \begin{Csynopsis}
-void @\FuncDecl{shmem\_session\_start}@(shmem_ctx_t ctx, long options, const shmem_session_config_t *config, long config_mask);
+void @\FuncDecl{shmem\_ctx\_session\_start}@(shmem_ctx_t ctx, long options, const shmem_ctx_session_config_t *config, long config_mask);
 \end{Csynopsis}
 
 \begin{apiarguments}
@@ -23,34 +23,34 @@
 \end{apiarguments}
 
 \apidescription{
-    \FUNC{shmem\_session\_start} is a non-collective routine that begins a
+    \FUNC{shmem\_ctx\_session\_start} is a non-collective routine that begins a
     session on communication context \VAR{ctx} with hints requested via
     \VAR{options}.
     Sessions on a communication context must be stopped with a call to
-    \FUNC{shmem\_session\_stop} on the same context.
+    \FUNC{shmem\_ctx\_session\_stop} on the same context.
     If a session is already started on a given context, another call to
-    \FUNC{shmem\_session\_start} on that same context combines new options
+    \FUNC{shmem\_ctx\_session\_start} on that same context combines new options
     via a bitwise OR operation. In such a case, unmasked member values in the
     \VAR{config} argument replace any existing configuration values that are
     already applied to the session.
 
     If \VAR{ctx} compares equal to \LibConstRef{SHMEM\_CTX\_INVALID} then
-    \FUNC{shmem\_session\_start} performs no action and returns immediately.
+    \FUNC{shmem\_ctx\_session\_start} performs no action and returns immediately.
 
-    No combination of \VAR{options} passed to \FUNC{shmem\_session\_start}
+    No combination of \VAR{options} passed to \FUNC{shmem\_ctx\_session\_start}
     results in undefined behavior, but some combinations may be detrimental for
     performance; for example, when selecting an option that is not applicable
     to the session. It is the user's responsibility to determine which
     combination of \VAR{options} benefits the performance of the session.
 
     The \VAR{config} argument specifies session configuration parameters,
-    which are described in Section~\ref{subsec:shmem_session_config_t}.
+    which are described in Section~\ref{subsec:shmem_ctx_session_config_t}.
 
     The \VAR{config\_mask} argument is a bitwise mask representing the set of
     configuration parameters to use from \VAR{config}.
     A \VAR{config\_mask} value of \CONST{0} indicates that the session should
     be started with the default values for all configuration parameters.
-    See Section~\ref{subsec:shmem_session_config_t} for field mask names and
+    See Section~\ref{subsec:shmem_ctx_session_config_t} for field mask names and
     default configuration parameters.
 }
 
@@ -60,11 +60,11 @@
 
 \sessiontablebegin
 
-\sessiontablerow{\LibConstRef{SHMEM\_SESSION\_BATCH}}{
+\sessiontablerow{\LibConstRef{SHMEM\_CTX\_SESSION\_BATCH}}{
     A \textit{batch} is a series of calls to \openshmem routines that occur
     within a session on a communication context (i.e., after a call to
-    \FUNC{shmem\_session\_start} and before a corresponding call to
-    \FUNC{shmem\_session\_stop}), that might tolerate an increase in
+    \FUNC{shmem\_ctx\_session\_start} and before a corresponding call to
+    \FUNC{shmem\_ctx\_session\_stop}), that might tolerate an increase in
     individual call latencies. Designating a batch may provide an opportunity
     to decrease the overall overhead typically involved with the \openshmem
     library implementing the series as individual RMA operations.  In other
@@ -75,7 +75,7 @@
     routines.  The specific mechanisms for improving performance using
     batching optimizations depend on the \openshmem library implementation.
 
-    The \VAR{SHMEM\_SESSION\_BATCH} hint indicates that a communication
+    The \VAR{SHMEM\_CTX\_SESSION\_BATCH} hint indicates that a communication
     context will be used to issue a batch.  An example of a batch is an
     iterative loop of non-blocking RMA and/or AMO routines. A batch may
     include a memory ordering or collective operation, but such routines
@@ -93,12 +93,12 @@
 
     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.
+    See Section~\ref{subsec:shmem_ctx_session_config_t} for details
+    about \VAR{shmem\_ctx\_session\_config\_t} parameters.
     } \hline
 
-\sessiontablerow{\LibConstRef{SHMEM\_SESSION\_SAME\_AMO}}{
-    The \VAR{SHMEM\_SESSION\_SAME\_AMO} hint indicates the session will contain
+\sessiontablerow{\LibConstRef{SHMEM\_CTX\_SESSION\_SAME\_AMO}}{
+    The \VAR{SHMEM\_CTX\_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
@@ -111,25 +111,25 @@
     (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
+    The \VAR{SHMEM\_CTX\_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.
+    See Section~\ref{subsec:shmem_ctx_session_config_t} for details about
+    \VAR{shmem\_ctx\_session\_config\_t} parameters.
     } \hline
 
 \sessiontableend
 
 \apinotes{
-    The \FUNC{shmem\_session\_start} routine provides hints for improving
+    The \FUNC{shmem\_ctx\_session\_start} routine provides hints for improving
     performance, and \openshmem implementations are not required to apply any
     optimization.
-    \FUNC{shmem\_session\_start} is non-collective, so there is no implied
+    \FUNC{shmem\_ctx\_session\_start} is non-collective, so there is no implied
     synchronization.
     Blocking puts must be sufficiently small to benefit from batching, and the
     exact threshold for this benefit depends on the \openshmem implemenation

content/shmem_session_stop.tex → content/shmem_ctx_session_stop.tex

@@ -5,7 +5,7 @@
 \begin{apidefinition}
 
 \begin{Csynopsis}
-void @\FuncDecl{shmem\_session\_stop}@(shmem_ctx_t ctx);
+void @\FuncDecl{shmem\_ctx\_session\_stop}@(shmem_ctx_t ctx);
 \end{Csynopsis}
 
 \begin{apiarguments}
@@ -14,9 +14,9 @@
 \end{apiarguments}
 
 \apidescription{
-    The \FUNC{shmem\_session\_stop} routine ends a session on context \VAR{ctx}.
+    The \FUNC{shmem\_ctx\_session\_stop} routine ends a session on context \VAR{ctx}.
     If a session is already stopped on a given communication context, another
-    call to \FUNC{shmem\_session\_stop} on that context has no effect.
+    call to \FUNC{shmem\_ctx\_session\_stop} on that context has no effect.
 }
 
 \apireturnvalues{
@@ -26,19 +26,19 @@
 \apinotes{
     Users are discouraged from including non-\openshmem code, such as a long
     computation loop, within a session without first calling
-    \FUNC{shmem\_session\_stop}.
+    \FUNC{shmem\_ctx\_session\_stop}.
 }
 
 
 \begin{apiexamples}
 
 \apicexample
     {The following \CorCpp{} program demonstrates the usage of
-    \FUNC{shmem\_session\_start} and \FUNC{shmem\_session\_stop} with a loop of
+    \FUNC{shmem\_ctx\_session\_start} and \FUNC{shmem\_ctx\_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
     \footnote{http://icl.cs.utk.edu/projectsfiles/hpcc/RandomAccess/}.}
-    {./example_code/shmem_session_example.c}
+    {./example_code/shmem_ctx_session_example.c}
     {}
 \end{apiexamples}
 

example_code/shmem_session_example.c → example_code/shmem_ctx_session_example.c

@@ -24,13 +24,13 @@ int main(void) {
       shmem_global_exit(1);
   }
 
-  shmem_session_config_t config;
+  shmem_ctx_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;
+  config_mask = SHMEM_CTX_SESSION_TOTAL_OPS;
+  long options = SHMEM_CTX_SESSION_BATCH | SHMEM_CTX_SESSION_SAME_AMO;
 
-  shmem_session_start(ctx, options, &config, config_mask);
+  shmem_ctx_session_start(ctx, options, &config, config_mask);
 
   for (size_t i = 0; i < N_UPDATES; i++) {
       int random_pe = rand() % npes;
@@ -39,9 +39,9 @@ int main(void) {
       shmem_ctx_uint64_atomic_xor(ctx, &table[random_idx], random_val, random_pe);
   }
 
-  shmem_session_stop(ctx);
-  shmem_ctx_quiet(ctx);    /* shmem_session_stop() does not quiet the context. */
-  shmem_sync_all();        /* shmem_session_stop() does not synchronize.       */
+  shmem_ctx_session_stop(ctx);
+  shmem_ctx_quiet(ctx);      /* shmem_ctx_session_stop() does not quiet the context. */
+  shmem_sync_all();          /* shmem_ctx_session_stop() does not synchronize.       */
 
   /* At this point, it is safe to check and/or validate the table result... */
 

main_spec.tex

@@ -360,14 +360,14 @@ \subsubsection{\textbf{SHMEM\_SIGNAL\_FETCH}}\label{subsec:shmem_signal_fetch}
 \subsection{Session Routines}\label{subsec:sessions}
 \input{content/sessions_intro.tex}
 
-\subsubsection{\textbf{SHMEM\_SESSION\_CONFIG\_T}}\label{subsec:shmem_session_config_t}
-\input{content/shmem_session_config_t.tex}
+\subsubsection{\textbf{SHMEM\_CTX\_SESSION\_CONFIG\_T}}\label{subsec:shmem_ctx_session_config_t}
+\input{content/shmem_ctx_session_config_t.tex}
 
-\subsubsection{\textbf{SHMEM\_SESSION\_START}}\label{subsec:shmem_session_start}
-\input{content/shmem_session_start.tex}
+\subsubsection{\textbf{SHMEM\_CTX\_SESSION\_START}}\label{subsec:shmem_ctx_session_start}
+\input{content/shmem_ctx_session_start.tex}
 
-\subsubsection{\textbf{SHMEM\_SESSION\_STOP}}\label{subsec:shmem_session_stop}
-\input{content/shmem_session_stop.tex}
+\subsubsection{\textbf{SHMEM\_CTX\_SESSION\_STOP}}\label{subsec:shmem_ctx_session_stop}
+\input{content/shmem_ctx_session_stop.tex}
 
 
 \subsection{Collective Routines}\label{subsec:coll}

utils/defs.tex

@@ -372,10 +372,16 @@
   \end{tabular}\\
 }
 
+\newcommand{\widetablerow}[2]{
+ \begin{tabular}{p{6cm} p{8cm}}
+ #1 & #2 \tabularnewline
+  \end{tabular}\\
+}
+
 \newcommand{\sessiontablebegin} {
 \begin{table}[h!]
-\hspace{-0.5cm}
-\begin{tabular}{|p{4.8cm}|p{12cm}|}
+\hspace{-1.0cm}
+\begin{tabular}{|p{5.6cm}|p{12cm}|}
     \hline
     \textbf{Option} & \textbf{Usage hint}
     \tabularnewline \hline