OpenSHMEM Sessions (ctx hints) API

content/backmatter.tex

@@ -674,6 +674,10 @@ \section{Version 1.6}
     operations for team-based reductions.
 \ChangelogRef{teamreducetypes}%
 %
+\item Added the session routines, \FUNC{shmem\_session\_start} and
+    \FUNC{shmem\_session\_stop}, which allow users to pass hints to the
+    \openshmem library to apply runtime optimizations.
+\ChangelogRef{subsec:session}%
 \item Added fine grained completion routine: \FUNC{shmem\_pe\_quiet}.
 \ChangelogRef{subsec:shmem_pe_quiet}%
 %

content/sessions_intro.tex

@@ -0,0 +1,23 @@
+\openshmem \emph{sessions} provide a mechanism for applications to inform the
+\openshmem library of an upcoming sequence of communication routines that
+exhibit suitable patterns for runtime optimizations.
+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
+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.
+
+Usage of the \openshmem session APIs on a particular context must comply with
+the requirements of all options set on that context.
+Starting and stoping \openshmem sessions should not affect the completion or
+ordering semantics of any \openshmem routines in the program.
+For these reasons, multi-threaded \openshmem programs may require additional
+thread synchronization to ensure sessions hints are correctly applied to
+shareable contexts.
+Because sessions are associated with an \openshmem communication context,
+routines not performed on a communication context (like collective routines)
+are ineligible for session hints.

content/shmem_session_start.tex

@@ -0,0 +1,96 @@
+\apisummary{
+    Start a communication session.
+}
+
+\begin{apidefinition}
+
+\begin{Csynopsis}
+void @\FuncDecl{shmem\_session\_start}@(long options, shmem_ctx_t ctx);
+\end{Csynopsis}
+
+\begin{apiarguments}
+    \apiargument{IN}{options}{The set of requested options from
+    Table~\ref{session_opts} for this session.  Multiple options may be
+    requested by combining them with a bitwise OR operation; otherwise,
+    \CONST{0} can be given if no options are requested.}
+    \apiargument{IN}{ctx}{A context handle specifying the context associated
+    with this session.}
+\end{apiarguments}
+
+\apidescription{
+    \FUNC{shmem\_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.
+    If a session is already started on a given context, another call to
+    \FUNC{shmem\_session\_start} on that same context combines new options via a
+    bitwise OR operation.
+    Passing false or ambiguous \VAR{options} to a session should never result in
+    undefined behavior, but may result in poor library performance.
+}
+
+\apireturnvalues{
+    None.
+}
+
+\begin{longtable}{|p{0.45\textwidth}|p{0.5\textwidth}|}
+    \hline
+    \hline
+    \textbf{Option} & \textbf{Usage hint}
+    \tabularnewline \hline
+    \endhead
+    %%
+    \LibConstDecl{SHMEM\_SESSION\_OP\_PUT} &
+    \newline 
+    The session will contain non-blocking \textit{put} and/or scalar put operations.
+    \tabularnewline \hline
+
+    \LibConstDecl{SHMEM\_SESSION\_OP\_GET} &
+    \newline
+    The session will contain non-blocking \textit{get} operations.
+    \tabularnewline \hline
+
+    \LibConstDecl{SHMEM\_SESSION\_OP\_PUT\_SIGNAL} &
+    \newline
+    The session will contain non-blocking \textit{put-with-signal} operations.
+    \tabularnewline \hline
+
+    \LibConstDecl{SHMEM\_SESSION\_OP\_AMO} &
+    \newline
+    The session will contain non-fetching AMOs.
+    \tabularnewline \hline
+
+    \LibConstDecl{SHMEM\_SESSION\_OP\_AMO\_FETCH} &
+    \newline
+    The session will contain non-blocking fetching AMOs.
+    \tabularnewline \hline
+
+    \LibConstDecl{SHMEM\_SESSION\_CHAIN} &
+    \newline
+    The session will contain a chain (a trivial repeating pattern) of similar RMA operations.
+    \tabularnewline \hline 
+
+    \LibConstDecl{SHMEM\_SESSION\_UNIFORM\_AMO} &
+    \newline
+    The session will contain a chain of 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}).
+    \tabularnewline \hline
+    \TableCaptionRef{Session options}
+    \label{session_opts}
+\end{longtable}
+
+\apinotes{
+    The \FUNC{shmem\_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
+    synchronization.
+    Implementations are encouraged to supply users with information about the
+    session options being applied or ignored; for instance, when
+    \LibConstRef{SHMEM\_DEBUG} is set.
+}
+
+\end{apidefinition}

content/shmem_session_stop.tex

@@ -0,0 +1,46 @@
+\apisummary{
+    Stop a communication session.
+}
+
+\begin{apidefinition}
+
+\begin{Csynopsis}
+void @\FuncDecl{shmem\_session\_stop}@(shmem_ctx_t ctx);
+\end{Csynopsis}
+
+\begin{apiarguments}
+    \apiargument{IN}{ctx}{A context handle specifying the context associated
+    with this session.}
+\end{apiarguments}
+
+\apidescription{
+    The \FUNC{shmem\_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.
+}
+
+\apireturnvalues{
+    None.
+}
+
+\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}.
+}
+
+
+\begin{apiexamples}
+
+\apicexample
+    {The following example 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 Giga-updates per second (GUPS) microbenchmark
+    \footnote{http://icl.cs.utk.edu/projectsfiles/hpcc/RandomAccess/}.}
+    {./example_code/shmem_session_example.c}
+    {}
+\end{apiexamples}
+
+\end{apidefinition}
+

example_code/shmem_session_example.c

@@ -0,0 +1,33 @@
+#include <shmem.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+#define N_UPDATES (1lu << 18)
+#define N_INDICES (1lu << 10)
+#define N_VALUES  (1lu << 31)
+
+int main(void) {
+
+  shmem_init();
+
+  uint64_t *table = shmem_calloc(N_INDICES, sizeof(uint64_t));
+
+  int mype = shmem_my_pe();
+  int npes = shmem_n_pes();
+  srand(mype);
+
+  shmem_session_start(SHMEM_SESSION_UNIFORM_AMO, SHMEM_CTX_DEFAULT);
+
+  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(&table[random_idx], random_val, random_pe);
+  }
+
+  shmem_session_stop(SHMEM_CTX_DEFAULT);
+
+  shmem_free(table);
+  shmem_finalize();
+  return 0;
+}

main_spec.tex

@@ -166,7 +166,6 @@ \subsubsection{\textbf{SHMEM\_CTX\_GET\_TEAM}}
 \label{subsec:shmem_ctx_get_team}
 \input{content/shmem_ctx_get_team.tex}
 
-
 \subsection{Remote Memory Access Routines}\label{sec:rma}
 \input{content/rma_intro.tex}
 
@@ -358,6 +357,15 @@ \subsubsection{\textbf{SHMEM\_SIGNAL\_FETCH}}\label{subsec:shmem_signal_fetch}
 \input{content/shmem_signal_fetch.tex}
 
 
+\subsection{Session Routines}\label{subsec:sessions}
+\input{content/sessions_intro.tex}
+
+\subsubsection{\textbf{SHMEM\_SESSION\_START}}\label{subsec:shmem_session_start}
+\input{content/shmem_session_start.tex}
+
+\subsubsection{\textbf{SHMEM\_SESSION\_STOP}}\label{subsec:shmem_session_stop}
+\input{content/shmem_session_stop.tex}
+
 
 \subsection{Collective Routines}\label{subsec:coll}
 \input{content/collective_intro.tex}