Update NBI put-with-signal atomicity description

Author: naveen-rn

content/shmem_put_signal_nbi.tex

@@ -1,62 +1,75 @@
+\color{ForestGreen}
 \apisummary{
     The nonblocking 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 setting a remote flag to signal completion.
+    and subsequently updating a remote flag to signal completion.
 }
 
 \begin{apidefinition}
 
 \begin{C11synopsis}
-void @\FuncDecl{shmem\_put\_signal\_nbi}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
-void @\FuncDecl{shmem\_put\_signal\_nbi}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
+void @\FuncDecl{shmem\_put\_signal\_nbi}@(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\_nbi}@(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\_nbi}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
-void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_put\_signal\_nbi}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
+void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_put\_signal\_nbi}@(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\_nbi}@(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\_nbi}@(void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
-void @\FuncDecl{shmem\_ctx\_put\FuncParam{SIZE}\_signal\_nbi}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
+void @\FuncDecl{shmem\_put\FuncParam{SIZE}\_signal\_nbi}@(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\_nbi}@(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\_nbi}@(void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
-void @\FuncDecl{shmem\_ctx\_putmem\_signal\_nbi}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe);
+void @\FuncDecl{shmem\_putmem\_signal\_nbi}@(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\_nbi}@(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{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 assigned to the
+    \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 nonblocking 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 setting a remote flag to signal completion. The routines
-    return after posting the operation. The operation is considered complete
-    after the subsequent call to \FUNC{shmem\_quiet}. At the completion of
-    \FUNC{shmem\_quiet}, the data has been copied out of the \source{}
-    array on the local \ac{PE} and delivered into the \dest{} array on the
-    destination \ac{PE}. The delivery of \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}.
+    and subsequently updating a remote flag to signal completion.
+
+    The routines return after posting the operation. The operation is considered
+    complete after a subsequent call to \FUNC{shmem\_quiet}. At the completion
+    of \FUNC{shmem\_quiet}, the data has been copied out of the \source{} array
+    on the local \ac{PE} and delivered into the \dest{} array on the destination
+    \ac{PE}. The delivery of \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}.
+
+    The \VAR{sig\_op} signal operator determines the type of update to be
+    performed on the remote \VAR{sig\_addr} signal data object.
+
+    An update to the \VAR{sig\_addr} signal data object through a non-blocking
+    put-with-signal routine completes as if performed atomically with respect to
+    any other non-blocking 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{
@@ -69,22 +82,8 @@
     for example, one could be a global/static \Cstd variable and the other could
     be allocated on the symmetric heap.
 
-    The \VAR{sig\_addr} and \dest{} may not be overlapping in memory.
-
-    The delivery of \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 delivery of the signal word of a nonblocking
-    put-with-signal routine and another data transfer. For example, the delivery
-    of the signal word in a sequence consisting of a put routine followed by a
-    nonblocking put-with-signal routine does not imply delivery of the put
-    routine's data.
-
-    The signal set by the nonblocking put-with-signal routines is compatible
-    with all point-to-point synchronization interfaces. The delivery of
-    \VAR{signal} flag on the remote \ac{PE} must not cause partial updates. This
-    requires the update on \VAR{signal} flag to be an atomic operation, with
-    atomicity guarantees described in Section~\ref{subsec:amo_guarantees}.
+    \VAR{sig\_addr} and \dest{} may not be overlapping in memory.
 }
 
 \end{apidefinition}
+\color{black}