From be9b62aa30e9c3f8bb987c26158a945ade36a0ba Mon Sep 17 00:00:00 2001 From: "Nicholas S. Park" Date: Wed, 23 Mar 2022 15:39:41 -0400 Subject: [PATCH 1/5] Add shmem_signal_{add,set}; update signal intro text --- content/shmem_signal_add.tex | 47 ++++++++++++++++++++++++++++++++++++ content/shmem_signal_set.tex | 47 ++++++++++++++++++++++++++++++++++++ main_spec.tex | 30 +++++++++++++++++------ 3 files changed, 116 insertions(+), 8 deletions(-) create mode 100644 content/shmem_signal_add.tex create mode 100644 content/shmem_signal_set.tex diff --git a/content/shmem_signal_add.tex b/content/shmem_signal_add.tex new file mode 100644 index 00000000..272b03a6 --- /dev/null +++ b/content/shmem_signal_add.tex @@ -0,0 +1,47 @@ +\apisummary{ + Adds to a signal value of a remote data object. +} + +\begin{apidefinition} + +\begin{C11synopsis} +void @\FuncDecl{shmem\_signal\_add}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +\end{C11synopsis} + +\begin{Csynopsis} +void @\FuncDecl{shmem\_signal\_add}@(const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_signal\_add}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +\end{Csynopsis} + +\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}{sig\_addr}{ + Symmetric address of the signal data object to be updated on the + remote \ac{PE}. + } + \apiargument{IN}{signal}{ + Unsigned 64-bit value that is used for updating the remote + \VAR{sig\_addr} signal data object. + } + \apiargument{IN}{pe}{ + \ac{PE} number of the remote \ac{PE}. + } +\end{apiarguments} + +\apidescription{ + \FUNC{shmem\_signal\_add} adds \VAR{value} to the signal data + object pointed to by \VAR{sig\_addr} on \ac{PE}~\VAR{pe}. + The update to the \VAR{sig\_addr} signal object at the calling + \ac{PE} is expected to satisfy the atomicity guarantees as described + in Section~\ref{subsec:signal_atomicity}. +} + +\apireturnvalues{ + None. +} + +\end{apidefinition} diff --git a/content/shmem_signal_set.tex b/content/shmem_signal_set.tex new file mode 100644 index 00000000..00c70345 --- /dev/null +++ b/content/shmem_signal_set.tex @@ -0,0 +1,47 @@ +\apisummary{ + Sets the signal value of a remote data object. +} + +\begin{apidefinition} + +\begin{C11synopsis} +void @\FuncDecl{shmem\_signal\_set}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +\end{C11synopsis} + +\begin{Csynopsis} +void @\FuncDecl{shmem\_signal\_set}@(const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_signal\_set}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +\end{Csynopsis} + +\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}{sig\_addr}{ + Symmetric address of the signal data object to be updated on the + remote \ac{PE}. + } + \apiargument{IN}{signal}{ + Unsigned 64-bit value that is used for updating the remote + \VAR{sig\_addr} signal data object. + } + \apiargument{IN}{pe}{ + \ac{PE} number of the remote \ac{PE}. + } +\end{apiarguments} + +\apidescription{ + \FUNC{shmem\_signal\_set} writes \VAR{value} into the signal data + object pointed to by \VAR{sig\_addr} on \ac{PE}~\VAR{pe}. + The update to the \VAR{sig\_addr} signal object at the calling + \ac{PE} is expected to satisfy the atomicity guarantees as described + in Section~\ref{subsec:signal_atomicity}. +} + +\apireturnvalues{ + None. +} + +\end{apidefinition} diff --git a/main_spec.tex b/main_spec.tex index 13e1917f..105970a7 100644 --- a/main_spec.tex +++ b/main_spec.tex @@ -298,13 +298,17 @@ \subsubsubsection{\textbf{SHMEM\_ATOMIC\_FETCH\_XOR\_NBI}} \subsection{Signaling Operations}\label{sec:shmem_signal} This section specifies the OpenSHMEM support for \OPR{put-with-signal}, -nonblocking \OPR{put-with-signal}, and \OPR{signal-fetch} routines. The +nonblocking \OPR{put-with-signal}, and \OPR{signal-\{add, fetch, set\}} routines. 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 signal-fetch routine provides -support for fetching a signal update operation. - -\openshmem \OPR{put-with-signal} routines specified in this section have two +updating a remote flag to signal completion. +The signal-add and signal-set routines provide methods for updating +the signal object without the associated data transfer of a +put-with-signal operation. +The signal-fetch routine provides support for reading a local signal value. + +\openshmem \OPR{put-with-signal} and \OPR{signal-\{add, set\}} +routines specified in this section have two variants. In one of the variants, the context handle, \VAR{ctx}, is explicitly passed as an argument. In this variant, the operation is performed on the specified context. If the context handle \VAR{ctx} does not correspond to a @@ -315,16 +319,20 @@ \subsection{Signaling Operations}\label{sec:shmem_signal} \subsubsection{Atomicity Guarantees for Signaling Operations} \label{subsec:signal_atomicity} All signaling operations put-with-signal, nonblocking put-with-signal, and -signal-fetch are performed on a signal data object, a remotely accessible +signal-\{add, fetch, set\} are performed on a signal data object, a remotely accessible symmetric object of type \VAR{uint64\_t}. A signal operator in the -put-with-signal routine is a \openshmem library constant that determines the +put-with-signal routine is an \openshmem library constant that determines the type of update to be performed as a signal on the signal data object. -All signaling operations on the signal data object completes as if performed +All signaling operations on the signal data object complete as if performed atomically with respect to the following: \begin{itemize} \item other blocking or nonblocking variant of the put-with-signal routine that updates the signal data object using the same signal update operator; + \item signal-add routine when the put-with-signal routine uses the + \LibConstRef{SHMEM\_SIGNAL\_ADD} signal operator; + \item signal-set routine when the put-with-signal routine uses the + \LibConstRef{SHMEM\_SIGNAL\_SET} signal operator; \item signal-fetch routine that fetches the signal data object; and \item any point-to-point synchronization routine that accesses the signal data object. @@ -354,9 +362,15 @@ \subsubsection{\textbf{SHMEM\_PUT\_SIGNAL}}\label{subsec:shmem_put_signal} \subsubsection{\textbf{SHMEM\_PUT\_SIGNAL\_NBI}}\label{subsec:shmem_put_signal_nbi} \input{content/shmem_put_signal_nbi.tex} +\subsubsection{\textbf{SHMEM\_SIGNAL\_ADD}}\label{subsec:shmem_signal_add} +\input{content/shmem_signal_add.tex} + \subsubsection{\textbf{SHMEM\_SIGNAL\_FETCH}}\label{subsec:shmem_signal_fetch} \input{content/shmem_signal_fetch.tex} +\subsubsection{\textbf{SHMEM\_SIGNAL\_SET}}\label{subsec:shmem_signal_set} +\input{content/shmem_signal_set.tex} + \subsection{Collective Routines}\label{subsec:coll} From a2d5268d96d34af185808afbfd44da37f87a3a1e Mon Sep 17 00:00:00 2001 From: James Dinan Date: Thu, 24 Mar 2022 16:10:42 -0400 Subject: [PATCH 2/5] In reductions, src and dest must be same at all PEs Signed-off-by: James Dinan --- content/shmem_reductions.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/shmem_reductions.tex b/content/shmem_reductions.tex index c01dd899..ff7e7c5b 100644 --- a/content/shmem_reductions.tex +++ b/content/shmem_reductions.tex @@ -283,6 +283,8 @@ \subsubsubsection{PROD} provides one element for each reduction. The results of the reductions are placed in the \dest{} array on all \acp{PE} participating in the reduction. + The same \source{} and \dest{} arrays must be passed by all PEs that + participate in the collective. The \source{} and \dest{} arguments must either be the same symmetric address, or two different symmetric addresses corresponding to buffers that do not overlap in memory. That is, they must be completely overlapping or From 5ec302d338adab3f2f20d6aa918c7204276ebc35 Mon Sep 17 00:00:00 2001 From: James Dinan Date: Fri, 25 Mar 2022 14:16:46 -0400 Subject: [PATCH 3/5] Update content/shmem_reductions.tex Add "in place" parenthetical --- content/shmem_reductions.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/shmem_reductions.tex b/content/shmem_reductions.tex index ff7e7c5b..ff933b35 100644 --- a/content/shmem_reductions.tex +++ b/content/shmem_reductions.tex @@ -287,7 +287,7 @@ \subsubsubsection{PROD} participate in the collective. The \source{} and \dest{} arguments must either be the same symmetric address, or two different symmetric addresses corresponding to buffers that - do not overlap in memory. That is, they must be completely overlapping or + do not overlap in memory. That is, they must be completely overlapping (sometimes referred to as an ``in place'' reduction) or completely disjoint. Team-based reduction routines operate over all \acp{PE} in the provided team argument. All From 86eeb0b7cd6d2a0f5bf2e7b8a9d663076a97883a Mon Sep 17 00:00:00 2001 From: James Dinan Date: Fri, 20 Jan 2023 10:41:17 -0500 Subject: [PATCH 4/5] Clarify fence orders only within same context Signed-off-by: James Dinan --- content/backmatter.tex | 4 ++++ content/shmem_fence.tex | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/content/backmatter.tex b/content/backmatter.tex index 9f5f77cd..fbb2cde6 100644 --- a/content/backmatter.tex +++ b/content/backmatter.tex @@ -660,6 +660,10 @@ \section{Version 1.6} The following list describes the specific changes in \openshmem[1.6]: \begin{itemize} % +\item Clarified that \OPR{Fence} operations only guarantee ordering for + operations that are performed on the same context. +\ChangelogRef{subsec:shmem_fence}% +% \item Added a team-based pointer query routine: \FUNC{shmem\_team\_ptr}. \ChangelogRef{subsec:shmem_team_ptr}% diff --git a/content/shmem_fence.tex b/content/shmem_fence.tex index e7b116ea..a470a477 100644 --- a/content/shmem_fence.tex +++ b/content/shmem_fence.tex @@ -24,7 +24,7 @@ \ac{PE} on the given context prior to the call to \FUNC{shmem\_fence} are guaranteed to be delivered before any subsequent operations on symmetric data - objects to the same \ac{PE}. \FUNC{shmem\_fence} guarantees order of delivery, + objects to the same \ac{PE} on the same context. \FUNC{shmem\_fence} guarantees order of delivery, not completion. It does not guarantee order of delivery of nonblocking \GET{} or values fetched by nonblocking \ac{AMO} routines. If \VAR{ctx} has the value \CONST{SHMEM\_CTX\_INVALID}, no operation is From 1c254cea3d29ac3fec357eb2b9fbddd896152994 Mon Sep 17 00:00:00 2001 From: Danielle Sikich Date: Thu, 1 Jun 2023 16:48:09 +0000 Subject: [PATCH 5/5] Add changelog entry for shmem_signal_add/set --- content/backmatter.tex | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/backmatter.tex b/content/backmatter.tex index c10b1baf..e38b1dbe 100644 --- a/content/backmatter.tex +++ b/content/backmatter.tex @@ -660,6 +660,10 @@ \section{Version 1.6} The following list describes the specific changes in \openshmem[1.6]: \begin{itemize} % +\item Added \FUNC{shmem\_signal\_add} and \FUNC{shmem\_signal\_set} to + update a remote flag without associated data transfer of a put-with-signal operation. +\ChangelogRef{subsec:shmem_signal_add, subsec:shmem_signal_set}% +% \item Added a team-based pointer query routine: \FUNC{shmem\_team\_ptr}. \ChangelogRef{subsec:shmem_team_ptr}%