diff --git a/content/atomics_intro.tex b/content/atomics_intro.tex index 67b0acdf..7664d635 100644 --- a/content/atomics_intro.tex +++ b/content/atomics_intro.tex @@ -29,6 +29,13 @@ The non-fetching routines include: \FUNC{shmem\_atomic\_\{set, inc, add, and, or, xor\}[\_nbi]}. +\begin{DeprecateBlock} + +Starting in \openshmem[1.4], all \ac{AMO} functions added "\_atomic\_" to the function +name and deprecated the equivalent functions without "\_atomic\_" in the name. + +\end{DeprecateBlock} + \end{itemize} \openshmem \ac{AMO} routines specified in this section have two variants. In @@ -56,7 +63,7 @@ integer types defined in \HEADER{stdint.h} by \Cstd[99]~\S7.18.1.1 and \Cstd[11]~\S7.20.1.1. When the \Cstd translation environment does not provide exact-width integer types with \HEADER{stdint.h}, an -\openshmem implemementation is not required to provide support for these types. +\openshmem implementation is not required to provide support for these types. \begin{table}[h] \begin{center} @@ -123,3 +130,10 @@ \label{bitamotypes} \end{center} \end{table} +] + + + + + + diff --git a/content/rma_intro.tex b/content/rma_intro.tex index 0cfd8cd0..b7bd5072 100644 --- a/content/rma_intro.tex +++ b/content/rma_intro.tex @@ -18,7 +18,7 @@ The destination \ac{PE} is specified as an integer representing the \ac{PE} number. This \ac{PE} number is relative to the team associated with the -communication context being using for the operation. If no context argument is passed to the routine, +communication context being used for the operation. If no context argument is passed to the routine, then the routine operates on the default context, which implies that the \ac{PE} number is relative to the world team. If the \ac{PE} number passed to the routine is invalid, being negative @@ -44,7 +44,7 @@ \footnote{Formally, the \Cstd[99] specification is ISO/IEC~9899:1999(E).}% ~\S7.18.1.1 and \Cstd[11]~\S7.20.1.1. When the \Cstd translation environment does not provide exact-width integer types with \HEADER{stdint.h}, an -\openshmem implemementation is not required to provide support for these types. +\openshmem implementation is not required to provide support for these types. \begin{table}[h] \begin{center} diff --git a/content/shmem_atomic_add.tex b/content/shmem_atomic_add.tex index 12737496..8a3b4f3d 100644 --- a/content/shmem_atomic_add.tex +++ b/content/shmem_atomic_add.tex @@ -39,8 +39,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic add operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number upon which - \dest{} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_and.tex b/content/shmem_atomic_and.tex index f82ee4bf..5803812b 100644 --- a/content/shmem_atomic_and.tex +++ b/content/shmem_atomic_and.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise AND operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_compare_swap.tex b/content/shmem_atomic_compare_swap.tex index 85b371fa..3763909d 100644 --- a/content/shmem_atomic_compare_swap.tex +++ b/content/shmem_atomic_compare_swap.tex @@ -45,8 +45,8 @@ type as \VAR{dest}.} \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number upon which - \VAR{dest} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_compare_swap_nbi.tex b/content/shmem_atomic_compare_swap_nbi.tex index 84a90a12..a3dabaa5 100644 --- a/content/shmem_atomic_compare_swap_nbi.tex +++ b/content/shmem_atomic_compare_swap_nbi.tex @@ -35,8 +35,8 @@ \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number upon which - \VAR{dest} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch.tex b/content/shmem_atomic_fetch.tex index 3c11f2a1..3e7fab8a 100644 --- a/content/shmem_atomic_fetch.tex +++ b/content/shmem_atomic_fetch.tex @@ -40,9 +40,9 @@ the default context.} \apiargument{IN}{source}{Symmetric address of the source data object. The type of \source{} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number from which - \VAR{source} is to be fetched.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} on which \VAR{source} resides + relative to the team associated with the given \VAR{ctx} when provided, or the + default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_add.tex b/content/shmem_atomic_fetch_add.tex index a07977ec..a0e73984 100644 --- a/content/shmem_atomic_fetch_add.tex +++ b/content/shmem_atomic_fetch_add.tex @@ -41,9 +41,8 @@ SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic fetch-and-add operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \VAR{dest} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_add_nbi.tex b/content/shmem_atomic_fetch_add_nbi.tex index 3b9e4021..7f1007a2 100644 --- a/content/shmem_atomic_fetch_add_nbi.tex +++ b/content/shmem_atomic_fetch_add_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic fetch-and-add operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \VAR{dest} is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_and.tex b/content/shmem_atomic_fetch_and.tex index 0a4d7843..675449f2 100644 --- a/content/shmem_atomic_fetch_and.tex +++ b/content/shmem_atomic_fetch_and.tex @@ -27,9 +27,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise AND operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_and_nbi.tex b/content/shmem_atomic_fetch_and_nbi.tex index 9959a1cc..97b8b0c5 100644 --- a/content/shmem_atomic_fetch_and_nbi.tex +++ b/content/shmem_atomic_fetch_and_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise AND operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_inc.tex b/content/shmem_atomic_fetch_inc.tex index 44710246..96437ac7 100644 --- a/content/shmem_atomic_fetch_inc.tex +++ b/content/shmem_atomic_fetch_inc.tex @@ -38,9 +38,8 @@ the default context.} \apiargument{OUT}{dest}{Symmetric address of the destination data object. The type of \dest{} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_atomic_fetch_inc_nbi.tex b/content/shmem_atomic_fetch_inc_nbi.tex index 6cfbfb3a..a7c17c3b 100644 --- a/content/shmem_atomic_fetch_inc_nbi.tex +++ b/content/shmem_atomic_fetch_inc_nbi.tex @@ -28,9 +28,8 @@ The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} \apiargument{OUT}{dest}{Symmetric address of the destination data object. The type of \dest{} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_atomic_fetch_nbi.tex b/content/shmem_atomic_fetch_nbi.tex index 4891dc97..43fdd53b 100644 --- a/content/shmem_atomic_fetch_nbi.tex +++ b/content/shmem_atomic_fetch_nbi.tex @@ -28,9 +28,8 @@ The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} \apiargument{OUT}{source}{Symmetric address of the source data object. The type of \source{} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number from which - \VAR{source} is to be fetched.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_or.tex b/content/shmem_atomic_fetch_or.tex index 81046d8a..0eb922bd 100644 --- a/content/shmem_atomic_fetch_or.tex +++ b/content/shmem_atomic_fetch_or.tex @@ -27,9 +27,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise OR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_or_nbi.tex b/content/shmem_atomic_fetch_or_nbi.tex index 7a6c8668..d62fcd3a 100644 --- a/content/shmem_atomic_fetch_or_nbi.tex +++ b/content/shmem_atomic_fetch_or_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise OR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_xor.tex b/content/shmem_atomic_fetch_xor.tex index a390500e..fd563cb1 100644 --- a/content/shmem_atomic_fetch_xor.tex +++ b/content/shmem_atomic_fetch_xor.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise XOR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_xor_nbi.tex b/content/shmem_atomic_fetch_xor_nbi.tex index 2b2cd085..f69739c3 100644 --- a/content/shmem_atomic_fetch_xor_nbi.tex +++ b/content/shmem_atomic_fetch_xor_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise XOR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_inc.tex b/content/shmem_atomic_inc.tex index fde7e9dc..c7cc359f 100644 --- a/content/shmem_atomic_inc.tex +++ b/content/shmem_atomic_inc.tex @@ -38,9 +38,8 @@ the default context.} \apiargument{OUT}{dest}{Symmetric address of the destination data object. The type of \dest{} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_or.tex b/content/shmem_atomic_or.tex index 033de757..5f00c530 100644 --- a/content/shmem_atomic_or.tex +++ b/content/shmem_atomic_or.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise OR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_set.tex b/content/shmem_atomic_set.tex index fcea7dbc..070e760f 100644 --- a/content/shmem_atomic_set.tex +++ b/content/shmem_atomic_set.tex @@ -42,9 +42,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic set operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \VAR{dest} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_swap.tex b/content/shmem_atomic_swap.tex index adab7bdb..3a0a6577 100644 --- a/content/shmem_atomic_swap.tex +++ b/content/shmem_atomic_swap.tex @@ -39,8 +39,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{ An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_swap_nbi.tex b/content/shmem_atomic_swap_nbi.tex index bfac883c..fb619f20 100644 --- a/content/shmem_atomic_swap_nbi.tex +++ b/content/shmem_atomic_swap_nbi.tex @@ -30,8 +30,8 @@ \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_xor.tex b/content/shmem_atomic_xor.tex index d4f863ad..65a7b6dc 100644 --- a/content/shmem_atomic_xor.tex +++ b/content/shmem_atomic_xor.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise XOR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_g.tex b/content/shmem_g.tex index ff5384f8..8f1b91fc 100644 --- a/content/shmem_g.tex +++ b/content/shmem_g.tex @@ -23,6 +23,9 @@ \apiargument{IN}{source}{Symmetric address of the source data object. The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{pe}{The number of the remote \ac{PE} on which \VAR{source} resides.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} on which \VAR{source} resides + relative to the team associated with the given \VAR{ctx} when provided, or the + default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_get.tex b/content/shmem_get.tex index 890f83f2..b34f84cf 100644 --- a/content/shmem_get.tex +++ b/content/shmem_get.tex @@ -37,12 +37,13 @@ The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays. For \FUNC{shmem\_getmem} and \FUNC{shmem\_ctx\_getmem}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ The get routines provide a method for copying a contiguous symmetric data - object from a different \ac{PE} to a contiguous data object on the local + object from a remote \ac{PE} to a contiguous data object on the local \ac{PE}. The routines return after the data has been delivered to the \dest{} array on the local \ac{PE}. } diff --git a/content/shmem_get_nbi.tex b/content/shmem_get_nbi.tex index 57adb768..61bbb698 100644 --- a/content/shmem_get_nbi.tex +++ b/content/shmem_get_nbi.tex @@ -39,12 +39,13 @@ \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays. For \FUNC{shmem\_getmem\_nbi} and \FUNC{shmem\_ctx\_getmem\_nbi}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ The get routines provide a method for copying a contiguous symmetric data - object from a different \ac{PE} to a contiguous data object on the local + object from a remote \ac{PE} to a contiguous data object on the local \ac{PE}. The routines return after initiating the operation. The operation is considered complete after a subsequent call to \FUNC{shmem\_quiet}. At the completion of \FUNC{shmem\_quiet}, the diff --git a/content/shmem_ibget.tex b/content/shmem_ibget.tex index 4deacf0f..811f1e2d 100644 --- a/content/shmem_ibget.tex +++ b/content/shmem_ibget.tex @@ -42,7 +42,8 @@ arrays.} \apiargument{IN}{nblocks}{Number of blocks to be copied from the \source{} array to the \dest{} array.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_ibput.tex b/content/shmem_ibput.tex index 2c949854..55b2987d 100644 --- a/content/shmem_ibput.tex +++ b/content/shmem_ibput.tex @@ -42,13 +42,14 @@ arrays.} \apiargument{IN}{nblocks}{Number of blocks to be copied from the \source{} array to the \dest{} array.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ The \FUNC{shmem\_ibput} routines provide a method for copying strided data - blocks (specified by \VAR{sst}) of an array from a \source{} array on the + blocks (of size \VAR{bsize}) with stride (specified by \VAR{sst}) of an array from a \source{} array on the local \ac{PE} to locations specified by stride \VAR{dst} on a \dest{} array on specified remote \ac{PE}. The routines return when the data has been copied out of the \VAR{source} array on the local \ac{PE} but not diff --git a/content/shmem_iget.tex b/content/shmem_iget.tex index 85871571..369d057a 100644 --- a/content/shmem_iget.tex +++ b/content/shmem_iget.tex @@ -40,7 +40,8 @@ indicates contiguous data.} \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_iput.tex b/content/shmem_iput.tex index 16006b00..a937d54e 100644 --- a/content/shmem_iput.tex +++ b/content/shmem_iput.tex @@ -39,7 +39,8 @@ scaled by the element size of the \source{} array. A value of \CONST{1} indicates contiguous data.} \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_p.tex b/content/shmem_p.tex index 0887b507..6aebc504 100644 --- a/content/shmem_p.tex +++ b/content/shmem_p.tex @@ -24,7 +24,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The value to be transferred to \VAR{dest}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{The number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put.tex b/content/shmem_put.tex index f71355a8..ce5c3c22 100644 --- a/content/shmem_put.tex +++ b/content/shmem_put.tex @@ -38,7 +38,8 @@ The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} arrays. For \FUNC{shmem\_putmem} and \FUNC{shmem\_ctx\_putmem}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put_nbi.tex b/content/shmem_put_nbi.tex index 0c42d7c8..0f7c385d 100644 --- a/content/shmem_put_nbi.tex +++ b/content/shmem_put_nbi.tex @@ -39,7 +39,8 @@ \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} arrays. For \FUNC{shmem\_putmem\_nbi} and \FUNC{shmem\_ctx\_putmem\_nbi}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put_signal.tex b/content/shmem_put_signal.tex index 7fd33a8e..79912934 100644 --- a/content/shmem_put_signal.tex +++ b/content/shmem_put_signal.tex @@ -48,7 +48,8 @@ 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}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put_signal_nbi.tex b/content/shmem_put_signal_nbi.tex index 3cbf3625..611d301e 100644 --- a/content/shmem_put_signal_nbi.tex +++ b/content/shmem_put_signal_nbi.tex @@ -48,7 +48,8 @@ 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}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_signal_add.tex b/content/shmem_signal_add.tex index 272b03a6..a7bb2aa3 100644 --- a/content/shmem_signal_add.tex +++ b/content/shmem_signal_add.tex @@ -5,12 +5,12 @@ \begin{apidefinition} \begin{C11synopsis} -void @\FuncDecl{shmem\_signal\_add}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_signal\_add}@(shmem_ctx_t ctx, 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); +void @\FuncDecl{shmem\_signal\_add}@(uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_signal\_add}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); \end{Csynopsis} \begin{apiarguments} @@ -27,9 +27,8 @@ 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}. - } + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_signal_set.tex b/content/shmem_signal_set.tex index 00c70345..b463917a 100644 --- a/content/shmem_signal_set.tex +++ b/content/shmem_signal_set.tex @@ -5,12 +5,12 @@ \begin{apidefinition} \begin{C11synopsis} -void @\FuncDecl{shmem\_signal\_set}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_signal\_set}@(shmem_ctx_t ctx, 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); +void @\FuncDecl{shmem\_signal\_set}@(uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_signal\_set}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); \end{Csynopsis} \begin{apiarguments} @@ -27,9 +27,8 @@ 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}. - } + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_signal_wait_until.tex b/content/shmem_signal_wait_until.tex index 5d93ec7f..564c5a77 100644 --- a/content/shmem_signal_wait_until.tex +++ b/content/shmem_signal_wait_until.tex @@ -11,7 +11,7 @@ \begin{apiarguments} -\apiargument{IN}{sig\_addr}{Local address of the source signal variable.} +\apiargument{IN}{sig\_addr}{Local address of the remotely accessible source signal variable.} \apiargument{IN}{cmp}{The comparison operator that compares \VAR{sig\_addr} with \VAR{cmp\_value}.} \apiargument{IN}{cmp\_value}{The value against which the object pointed to diff --git a/content/signaling.tex b/content/signaling.tex new file mode 100644 index 00000000..bd04940b --- /dev/null +++ b/content/signaling.tex @@ -0,0 +1,57 @@ +This section specifies the OpenSHMEM support for \OPR{put-with-signal}, +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-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 +valid context, the behavior is undefined. In the other variant, the context +handle is not explicitly passed and thus, the operations are performed on the +default context. + +\subsubsection{Atomicity Guarantees for Signaling Operations} +\label{subsec:signal_atomicity} +All signaling operations put-with-signal, nonblocking put-with-signal, and +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 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 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. +\end{itemize} + +\subsubsection{Available Signal Operators} +\label{subsec:signal_operator} + +With the atomicity guarantees as described in +Section~\ref{subsec:signal_atomicity}, the following options can be used as a +signal operator. + + \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_SET}}{An update to signal data + object is an atomic set operation. It writes an unsigned 64-bit value as a + signal into the signal data object on a remote \VAR{PE} as an atomic + operation.} + + \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_ADD}}{An update to signal data + object is an atomic add operation. It adds an unsigned 64-bit value as a + signal into the signal data object on a remote \VAR{PE} as an atomic + operation.} diff --git a/main_spec.tex b/main_spec.tex index 6c3935d6..6698ad6b 100644 --- a/main_spec.tex +++ b/main_spec.tex @@ -305,64 +305,7 @@ \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-\{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-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 -valid context, the behavior is undefined. In the other variant, the context -handle is not explicitly passed and thus, the operations are performed on the -default context. - -\subsubsection{Atomicity Guarantees for Signaling Operations} -\label{subsec:signal_atomicity} -All signaling operations put-with-signal, nonblocking put-with-signal, and -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 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 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. -\end{itemize} - -\subsubsection{Available Signal Operators} -\label{subsec:signal_operator} - -With the atomicity guarantees as described in -Section~\ref{subsec:signal_atomicity}, the following options can be used as a -signal operator. - - \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_SET}}{An update to signal data - object is an atomic set operation. It writes an unsigned 64-bit value as a - signal into the signal data object on a remote \VAR{PE} as an atomic - operation.} - - \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_ADD}}{An update to signal data - object is an atomic add operation. It adds an unsigned 64-bit value as a - signal into the signal data object on a remote \VAR{PE} as an atomic - operation.} - +\input{content/signaling.tex} \subsubsection{\textbf{SHMEM\_PUT\_SIGNAL}}\label{subsec:shmem_put_signal} \input{content/shmem_put_signal.tex}