Add support for put with signal operation

content/backmatter.tex

@@ -510,6 +510,9 @@ \section{Version 1.5}
 The following list describes the specific changes in \openshmem[1.5]:
 \begin{itemize}
 %
+\item Added support for blocking put-with-signal functions.
+\\ See Section \ref{subsec:shmem_put_signal}.
+%
 \item Specified the validity of communication contexts, added the constant
   \CONST{SHMEM\_CTX\_INVALID}, and clarified the behavior of
   \FUNC{shmem\_ctx\_*} routines on invalid contexts.

content/library_constants.tex

@@ -67,6 +67,20 @@
 See Section~\ref{subsec:shmem_ctx_create} for more detail about its use.
 \tabularnewline \hline
 %%
+\color{ForestGreen}
+\LibConstDecl{SHMEM\_SIGNAL\_SET} &
+\color{ForestGreen}
+An integer constant expression corresponding to the signal update set operation.
+See Section~\ref{subsec:shmem_put_signal} for more detail about its use.
+\tabularnewline \hline
+%%
+\color{ForestGreen}
+\LibConstDecl{SHMEM\_SIGNAL\_ADD} &
+\color{ForestGreen}
+An integer constant expression corresponding to the signal update add operation.
+See Section~\ref{subsec:shmem_put_signal} for more detail about its use.
+\tabularnewline \hline
+%%
 \LibConstDecl{SHMEM\_SYNC\_VALUE}
 \begin{DeprecateBlock}
   \LibConstDecl{\_SHMEM\_SYNC\_VALUE}

content/p2p_sync_intro.tex

@@ -3,8 +3,8 @@
 object.
 The point-to-point synchronization routines can be used to portably ensure
 that memory access operations observe remote updates in the order enforced by
-the initiator \ac{PE} using the \FUNC{shmem\_fence} and \FUNC{shmem\_quiet}
-routines.
+the initiator \ac{PE} using the put-with-signal, \FUNC{shmem\_fence} and
+\FUNC{shmem\_quiet} routines.
 
 Where appropriate compiler support is available, \openshmem provides
 type-generic point-to-point synchronization interfaces via \Cstd[11] generic

content/shmem_put_signal.tex

@@ -0,0 +1,105 @@
+\color{ForestGreen}
+\apisummary{
+    The put-with-signal routines provide a method for copying data from a
+    contiguous local data object to a data object on a specified \ac{PE}
+    and subsequently updating a remote flag to signal completion.
+}
+
+\begin{apidefinition}
+
+\begin{C11synopsis}
+void @\FuncDecl{shmem\_put\_signal}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+void @\FuncDecl{shmem\_put\_signal}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+\end{C11synopsis}
+where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}.
+
+\begin{Csynopsis}
+void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_put\_signal}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_put\_signal}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+\end{Csynopsis}
+where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}.
+
+\begin{CsynopsisCol}
+void @\FuncDecl{shmem\_put\FuncParam{SIZE}\_signal}@(void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+void @\FuncDecl{shmem\_ctx\_put\FuncParam{SIZE}\_signal}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+\end{CsynopsisCol}
+where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}.
+
+\begin{CsynopsisCol}
+void @\FuncDecl{shmem\_putmem\_signal}@(void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+void @\FuncDecl{shmem\_ctx\_putmem\_signal}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int sig_op, int pe);
+\end{CsynopsisCol}
+
+\begin{apiarguments}
+    \apiargument{IN}{ctx}{A context handle specifying the context on which to
+    perform the operation. When this argument is not provided, the operation is
+    performed on the default context.}
+    \apiargument{OUT}{dest}{Data object to be updated on the remote \ac{PE}.
+    This data object must be remotely accessible.}
+    \apiargument{IN}{source}{Data object containing the data to be copied.}
+    \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{}
+    arrays. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd.}
+    \apiargument{OUT}{sig\_addr}{Data object to be updated on the remote
+    \ac{PE} as the signal. This signal data object must be remotely accessible.}
+    \apiargument{IN}{signal}{Unsigned 64-bit value that is used for updating the
+    remote \VAR{sig\_addr} signal data object.}
+    \apiargument{IN}{sig\_op}{Signal operator that represents the type of update
+    to be performed on the remote \VAR{sig\_addr} signal data object.}
+    \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.}
+\end{apiarguments}
+
+\apidescription{
+    The put-with-signal routines provide a method for copying data from a
+    contiguous local data object to a data object on a specified \ac{PE}
+    and subsequently updating a remote flag to signal completion. The routines
+    return after the data has been copied out of the \source{} array on the
+    local \ac{PE}.
+
+    The \VAR{sig\_op} signal operator determines the type of update to be
+    performed on the remote \VAR{sig\_addr} signal data object. The completion
+    of signal update based on the \VAR{sig\_op} signal operator using the
+    \VAR{signal} flag on the remote \ac{PE} indicates the delivery of its
+    corresponding \dest{} data words into the data object on the remote \ac{PE}.
+
+    An update to the \VAR{sig\_addr} signal data object through a put-with-signal
+    routine completes as if performed atomically with respect to any other
+    put-with-signal routine that updates the \VAR{sig\_addr} signal data object
+    using the same \VAR{sig\_op} signal update operator and any point-to-point
+    synchronization routine that accesses the \VAR{sig\_addr} signal data object.
+}
+
+\apireturnvalues{
+    None.
+}
+
+\apinotes{
+    The \dest{} and \VAR{sig\_addr} data objects must both be remotely
+    accessible. The \VAR{sig\_addr} and \dest{} could be of different kinds,
+    for example, one could be a global/static \Cstd variable and the other could
+    be allocated on the symmetric heap.
+
+    \VAR{sig\_addr} and \dest{} may not be overlapping in memory.
+
+    The completion of signal update using the \VAR{signal} flag on the remote
+    \ac{PE} indicates only the delivery of its corresponding \dest{} data words
+    into the data object on the remote \ac{PE}. Without a memory-ordering
+    operation, there is no implied ordering between the signal update of a
+    put-with-signal routine and another data transfer. For example, the
+    completion of the signal update in a sequence consisting of a put routine
+    followed by a put-with-signal routine does not imply delivery of the put
+    routine's data.
+}
+
+\begin{apiexamples}
+
+\apicexample
+    {The following example demonstrates the usage of \FUNC{shmem\_put\_signal}.
+    It shows the implementation of a broadcast operation from \ac{PE} 0 to
+    itself and all other \acp{PE} in the job as a simple ring-based algorithm
+    using \FUNC{shmem\_put\_signal}:}
+    {./example_code/shmem_put_signal_example.c}
+    {}
+\end{apiexamples}
+
+\end{apidefinition}
+\color{black}

example_code/shmem_put_signal_example.c

@@ -0,0 +1,37 @@
+#include <shmem.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+int main(void)
+{
+    int i, err_count = 0;
+
+    shmem_init();
+
+    size_t          size     = 2048;
+    int             me       = shmem_my_pe();
+    int             n        = shmem_n_pes();
+    int             pe       = (me + 1) % n;
+    uint64_t *      message  = malloc(size * sizeof(uint64_t));
+    static uint64_t sig_addr = 0;
+
+    for (i = 0; i < size; i++) {
+        message[i] = me;
+    }
+
+    uint64_t *data = shmem_calloc(size, sizeof(uint64_t));
+
+    if (me == 0) {
+        shmem_put_signal(data, message, size, &sig_addr, 1, SHMEM_SIGNAL_SET, pe);
+    } else {
+        shmem_wait_until(&sig_addr, SHMEM_CMP_EQ, 1);
+        shmem_put_signal(data, data, size, &sig_addr, 1, SHMEM_SIGNAL_SET, pe);
+    }
+
+    free(message);
+    shmem_free(data);
+
+    shmem_finalize();
+    return 0;
+}

main_spec.tex

@@ -170,6 +170,9 @@ \subsubsection{\textbf{SHMEM\_P}}\label{subsec:shmem_p}
 \subsubsection{\textbf{SHMEM\_IPUT}}\label{subsec:shmem_iput}
 \input{content/shmem_iput.tex}
 
+\subsubsection{\textbf{SHMEM\_PUT\_SIGNAL}}\label{subsec:shmem_put_signal}
+\input{content/shmem_put_signal.tex}
+
 \subsubsection{\textbf{SHMEM\_GET}}\label{subsec:shmem_get}
 \input{content/shmem_get.tex}
 

utils/defs.tex

@@ -408,14 +408,16 @@
   \textbf{C11:}
   \lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt,
     escapechar=@,
-    morekeywords={size_t, ptrdiff_t, TYPE, _Noreturn, shmem_ctx_t},
+    morekeywords={size_t, ptrdiff_t, TYPE, _Noreturn, shmem_ctx_t,
+      uint64_t},
   aboveskip=0pt, belowskip=0pt}}{}
 
 \lstnewenvironment{CsynopsisCol}
 {
   \lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt,
     escapechar=@,
-    morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t},
+    morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t,
+      uint64_t},
   aboveskip=0pt, belowskip=0pt}}{}
 
 
@@ -424,7 +426,8 @@
   \textbf{C/C++:}
   \lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt,
     escapechar=@,
-    morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t},
+    morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t,
+      uint64_t},
   aboveskip=0pt, belowskip=0pt}}{}
 
 \lstnewenvironment{CsynopsisST}
@@ -516,7 +519,7 @@
     ##1
     \lstinputlisting[language={C}, tabsize=2,
       basicstyle=\ttfamily\footnotesize,
-      morekeywords={size_t, ptrdiff_t, shmem_ctx_t, _Thread_local}]{##2}
+      morekeywords={size_t, ptrdiff_t, shmem_ctx_t, _Thread_local, uint64_t}]{##2}
     ##3 }
 \newcommand{\apifexample}[3]{
     ##1