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/2] 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 1c254cea3d29ac3fec357eb2b9fbddd896152994 Mon Sep 17 00:00:00 2001 From: Danielle Sikich Date: Thu, 1 Jun 2023 16:48:09 +0000 Subject: [PATCH 2/2] 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}%