ordering of blocking gets and other edits to make text uniform across…

… the *p*/*g* APIs
openshmem-org · Jul 25, 2018 · 4fbc3ae · 4fbc3ae
1 parent d4f9e0e
commit 4fbc3ae
Show file tree

Hide file tree

Showing 8 changed files with 107 additions and 84 deletions.
diff --git a/content/shmem_g.tex b/content/shmem_g.tex
@@ -1,5 +1,5 @@
 \apisummary{
-    Copies one data item from a remote \ac{PE}
+    Copies one element from a symmetric data object from a specified \ac{PE}.
 }
 
 \begin{apidefinition}
@@ -20,13 +20,19 @@
   \apiargument{IN}{ctx}{The context on which to perform the operation.
     When this argument is not provided, the operation is performed on
     \CONST{SHMEM\_CTX\_DEFAULT}.}
-  \apiargument{IN}{source}{The remotely accessible array element or scalar data object.}
+  \apiargument{IN}{source}{The remotely accessible data object
+    on the remote \ac{PE} which will provide the value to be returned.}
   \apiargument{IN}{pe}{The number of the remote \ac{PE} on which \VAR{source} resides.}
 \end{apiarguments}
 
 \apidescription{
-  These routines provide a very low latency get capability for single elements
-  of most basic types. 
+    These routines provide a very low latency get capability for single elements
+    of most basic types. 
+
+    The delivery of the data word into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{shmem\_g} 
+    routine may deliver data out of order unless a call to \FUNC{shmem\_fence} or
+    a read of the return value is introduced between the two calls.
 }
 
 \apireturnvalues{

diff --git a/content/shmem_get.tex b/content/shmem_get.tex
@@ -1,5 +1,5 @@
 \apisummary{
-    Copies data from a specified \ac{PE}.
+    Copies contiguous data from a symmetric data object from a specified \ac{PE} such that the destination object can be consumed on return.
 }
 
 \begin{apidefinition}
@@ -48,11 +48,10 @@
         When this argument is not provided, the operation is performed on
         \CONST{SHMEM\_CTX\_DEFAULT}.}
     \apiargument{OUT}{dest}{Local data object to be updated.}
-    \apiargument{IN}{source}{Data object on the \ac{PE} identified by \VAR{pe}
-        that contains the data to be copied.  This data object must be remotely
-        accessible.}
+    \apiargument{IN}{source}{The remotely accessible data object
+      on the remote \ac{PE} which provides 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. When
+        objects. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When
         using \Fortran, it must be a constant, variable, or array element of default
         integer type.}
     \apiargument{IN}{pe}{\ac{PE}  number of the remote \ac{PE}.  \VAR{pe} must
@@ -61,10 +60,14 @@
 \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
-   \ac{PE}.  The routines return after the data has been delivered to the
-   \dest{} array on the local \ac{PE}. 
+    The \FUNC{get} routines provide a method for copying contiguous data from a
+    symmetric data object on any \ac{PE} to a data object on the local \ac{PE}. 
+    On return, the calling thread on reading the \VAR{dest} object is guaranteed 
+    to observe the copied data. 
+    The delivery of the data words into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{get}
+    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} or
+    a read of the \VAR{dest} object is introduced between the two calls.
 }
 
 \apidesctable{

diff --git a/content/shmem_get_nbi.tex b/content/shmem_get_nbi.tex
@@ -1,6 +1,5 @@
 \apisummary{
-    The nonblocking get routines provide a method for copying data from a
-    contiguous remote data object on the specified \ac{PE} to the local data object. 
+    Copies contiguous data from a symmetric data object on a specified \ac{PE} such that the destination object cannot be consumed on return.
 }
 
 \begin{apidefinition}
@@ -49,11 +48,10 @@
         When this argument is not provided, the operation is performed on
         \CONST{SHMEM\_CTX\_DEFAULT}.}
     \apiargument{OUT}{dest}{Local data object to be updated.}
-    \apiargument{IN}{source}{Data object on the \ac{PE} identified by \VAR{pe}
-        that contains the data to be copied.  This data object must be remotely
-        accessible.}
+    \apiargument{IN}{source}{The remotely accessible data object
+      on the remote \ac{PE} which provides 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. When
+        objects. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When
         using \Fortran, it must be a constant, variable, or array element of default
         integer type.}
     \apiargument{IN}{pe}{\ac{PE}  number of the remote \ac{PE}.  \VAR{pe} must
@@ -62,12 +60,17 @@
 \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
-   \ac{PE}.   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 delivered to the \dest{} array on the local \ac{PE}. 
+    The \FUNC{get_nbi} routines provide a method for copying contiguous data from a
+    symmetric data object on any \ac{PE} to a data object on the local \ac{PE} that 
+    return after posting the operation.
+    On return, the calling thread on reading the \VAR{dest} object is not
+    guaranteed to observe the copied data. A subsequent call to \FUNC{shmem\_quiet} 
+    is required to complete the operation by copying the data into the \dest{} 
+    object on the destination \ac{PE}. 
+    The delivery of data words into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{get_nbi} 
+    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is 
+    introduced between the two calls.
 }
 
 \apidesctable{

diff --git a/content/shmem_iget.tex b/content/shmem_iget.tex
@@ -1,5 +1,5 @@
 \apisummary{
-    Copies strided data from a specified \ac{PE}.
+    Copies strided data from a symmetric data object from a specified \ac{PE} such that the destination object can be consumed on return.
 }
 
 \begin{apidefinition}
@@ -40,20 +40,21 @@
     \apiargument{IN}{ctx}{The context on which to perform the operation.
         When this argument is not provided, the operation is performed on
         \CONST{SHMEM\_CTX\_DEFAULT}.}
-    \apiargument{OUT}{dest}{Array to be updated on the local \ac{PE}. }
-    \apiargument{IN}{source}{Array containing the data to be copied on the remote \ac{PE}.}
+    \apiargument{OUT}{dest}{Local data object to be updated. }
+    \apiargument{IN}{source}{The remotely accessible data object
+      on the remote \ac{PE} which provides the data to be copied.}
     \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{}
-        array.  The stride is scaled by the element size of the \dest{} array.
+        object. The stride is scaled by the element size of the \dest{} object.
         A  value of \CONST{1} indicates contiguous data. \VAR{dst} must be of
         type \CTYPE{ptrdiff\_t}.  When using  \Fortran,  it  must
         be a default integer value.}
     \apiargument{IN}{sst}{The stride between consecutive elements of the
-        \source{} array.  The stride is scaled by the element size of the \source{}
-        array.  A  value of \CONST{1} indicates contiguous data.  \VAR{sst} must be
+        \source{} object.  The stride is scaled by the element size of the \source{}
+        object.  A  value of \CONST{1} indicates contiguous data.  \VAR{sst} must be
         of type \CTYPE{ptrdiff\_t}.  When using  \Fortran,  it  must
         be a default integer value.}
     \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{}
-        arrays.  \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When
+        objects.  \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When
         using \Fortran, it must be  a constant, variable, or array element of
         default integer type.}
     \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.  \VAR{pe} must be
@@ -62,10 +63,16 @@
 \end{apiarguments}
 
 \apidescription{
-    The \FUNC{iget} routines provide a method for copying strided data elements from
-    a symmetric array from a specified remote \ac{PE} to strided locations on a
-    local array.  The routines return when the data has been copied into the local
-    \VAR{dest} array.
+    The \FUNC{iget} routines provide a method for copying strided data from a 
+    symmetric data object (specified by stride \VAR{sst}) from any \ac{PE} to 
+    a strided data object (specified by stride \VAR{dst}) on the local \ac{PE}. 
+    Both strides, \VAR{dst} and \VAR{sst}, must be greater than or equal to \CONST{1}. 
+    On return, the calling thread on reading the \VAR{dest} object is guaranteed
+    to observe the copied data.
+    The delivery of data words into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{iget} 
+    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} or
+    a read of the \VAR{dest} object is introduced between the two calls.
 }
 
 \apidesctable{

diff --git a/content/shmem_iput.tex b/content/shmem_iput.tex
@@ -1,5 +1,5 @@
 \apisummary{
-    Copies strided data to a specified \ac{PE}.
+    Copies strided data to a symmetric data object on a specified \ac{PE} such that the source object can be reused on return.
 }
 
 \begin{apidefinition}
@@ -40,20 +40,20 @@
     \apiargument{IN}{ctx}{The context on which to perform the operation.
         When this argument is not provided, the operation is performed on
         \CONST{SHMEM\_CTX\_DEFAULT}.}
-    \apiargument{OUT}{dest}{Array to be updated on the remote \ac{PE}. This data
-        object  must be remotely accessible.}
-    \apiargument{IN}{source}{Array containing the data to be copied.}
+    \apiargument{OUT}{dest}{The remotely accessible data object
+      on the remote \ac{PE} which will receive the data to be copied.}
+    \apiargument{IN}{source}{Local data object containing the data to be copied.}
     \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{}
-        array.  The stride is scaled by the element size of the \dest{} array.  A
+        object.  The stride is scaled by the element size of the \dest{} object.  A
         value of \CONST{1} indicates contiguous data.  \VAR{dst} must be of type
         \CTYPE{ptrdiff\_t}.  When using \Fortran, it must be a default integer value.}
     \apiargument{IN}{sst}{The  stride between consecutive elements of the
-        \source{} array.  The stride is scaled by the element size of the \source{}
-        array.  A  value of \CONST{1} indicates contiguous data.  \VAR{sst} must be
+        \source{} object.  The stride is scaled by the element size of the \source{}
+        object.  A  value of \CONST{1} indicates contiguous data.  \VAR{sst} must be
         of type \CTYPE{ptrdiff\_t}.  When using \Fortran, it must be a
         default integer value.}
     \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{}
-        arrays.  \VAR{nelems} must be of type \VAR{size\_t} for \Cstd.  When
+        objects.  \VAR{nelems} must be of type \VAR{size\_t} for \Cstd.  When
         using \Fortran, it must be  a constant, variable, or array element of
         default integer type.}
     \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.  \VAR{pe} must be
@@ -63,13 +63,15 @@
 
 
 \apidescription{
-    The \FUNC{iput} routines provide a method  for  copying strided data
-    elements (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}. Both strides, \VAR{dst} and \VAR{sst}, must be
-    greater than or equal to \CONST{1}. The routines return when the data has
-    been copied out of the \VAR{source} array on the local \ac{PE} but not
-    necessarily before the data has been delivered to the remote data object.
+    The \FUNC{iput} routines provide a method for copying strided data from a
+    data object (specified by stride \VAR{sst}) on the local \ac{PE} to a strided 
+    symmetric data object (specified by stride \VAR{dst} on any \ac{PE}. Both 
+    strides, \VAR{dst} and \VAR{sst}, must be greater than or equal to \CONST{1}. 
+    On return, the calling thread can modify the \VAR{source} object.
+    The delivery of data words into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{iput} 
+    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is 
+    introduced between the two calls.
 }
 
 \apidesctable{

diff --git a/content/shmem_p.tex b/content/shmem_p.tex
@@ -1,5 +1,5 @@
 \apisummary{
-    Copies one data item to a remote \ac{PE}.
+    Copies one data element to a symmetric data object on a specified \ac{PE}.
 }
 
 \begin{apidefinition}
@@ -20,9 +20,9 @@
   \apiargument{IN}{ctx}{The context on which to perform the operation.
     When this argument is not provided, the operation is performed on
     \CONST{SHMEM\_CTX\_DEFAULT}.}
-  \apiargument{OUT}{dest}{The remotely accessible array element or scalar data object
-    which will receive the data on the remote \ac{PE}.}
-  \apiargument{IN}{value}{The value to be transferred to \VAR{dest} on the
+  \apiargument{OUT}{dest}{The remotely accessible data object
+    on the remote \ac{PE} which will receive the value to be copied.}
+  \apiargument{IN}{value}{The value to be copied to \VAR{dest} on the
     remote \ac{PE}.}
   \apiargument{IN}{pe}{The number of the remote \ac{PE}.}
 \end{apiarguments}
@@ -31,9 +31,10 @@
     These routines provide a very low latency put capability for single elements of
     most basic types.
 
-    As with \FUNC{shmem\_put}, these routines start the remote transfer and may
-    return before the data is delivered to the remote \ac{PE}.  Use
-    \FUNC{shmem\_quiet} to force completion of all remote \PUT{} transfers.
+    The delivery of the data word into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{shmem\_p} 
+    routine may deliver data out of order unless a call to \FUNC{shmem\_fence} is 
+    introduced between the two calls.
 }
 
 \apireturnvalues{

diff --git a/content/shmem_put.tex b/content/shmem_put.tex
@@ -1,6 +1,5 @@
 \apisummary{
-    The  put routines  provide  a method for copying data from a contiguous local
-    data object to a data object on a specified \ac{PE}.
+    Copies contiguous data to a symmetric data object on a specified \ac{PE} such that the source object can be reused on return.
 }
 
 \begin{apidefinition}
@@ -47,11 +46,11 @@
     \apiargument{IN}{ctx}{The context on which to perform the operation.
       When this argument is not provided, the operation is performed on
       \CONST{SHMEM\_CTX\_DEFAULT}.}
-    \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{OUT}{dest}{The remotely accessible data object
+      on the remote \ac{PE} which will receive the data to be copied.}
+    \apiargument{IN}{source}{Local data object containing the data to be copied.}
     \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source}
-    arrays. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When using
+    objects. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When using
     \Fortran, it must be a constant, variable, or array element of default
     integer type.}
     \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}. \VAR{pe} must be
@@ -60,11 +59,13 @@
 \end{apiarguments}
 
 \apidescription{
-    The routines return after the data has been copied out of the \source{} array
-    on the local \ac{PE}.  The delivery of data words into the data object on the
-    destination \ac{PE} may occur in any order.  Furthermore, two successive put
-    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is
-    introduced between the two calls.   
+    The \FUNC{put} routines provide a method for copying contiguous data from a
+    data object on the local \ac{PE} to a symmetric data object on any \ac{PE}. 
+    On return, the calling thread can modify the \VAR{source} object. 
+    The delivery of data words into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{put} 
+    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is 
+    introduced between the two calls.
  }
 
 \apidesctable{

diff --git a/content/shmem_put_nbi.tex b/content/shmem_put_nbi.tex
@@ -1,6 +1,5 @@
 \apisummary{
-    The nonblocking put routines provide a method for copying data
-    from a contiguous local data object to a data object on a specified \ac{PE}. 
+    Copies contiguous data to a symmetric data object on a specified \ac{PE} such that the source object cannot be reused on return.
 }
 
 \begin{apidefinition}
@@ -47,11 +46,11 @@
   \apiargument{IN}{ctx}{The context on which to perform the operation.
     When this argument is not provided, the operation is performed on
     \CONST{SHMEM\_CTX\_DEFAULT}.}
-  \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{OUT}{dest}{The remotely accessible data object
+    on the remote \ac{PE} which will receive the data to be copied.}
+  \apiargument{IN}{source}{Local data object containing the data to be copied.}
   \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source}
-    arrays. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When using
+    objects. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd. When using
     \Fortran, it must be a constant, variable, or array element of default
     integer type.}
   \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}. \VAR{pe} must be
@@ -60,15 +59,16 @@
 \end{apiarguments}
 
 \apidescription{
-    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 into the \dest{} array
-    on the destination \ac{PE}.
-    The delivery of data words into the data object on the
-    destination \ac{PE} may occur in any order.
-    Furthermore, two successive put
-    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is
-    introduced between the two calls.   
+    The \FUNC{put_nbi} routines provide a method for copying contiguous data from a
+    data object on the local \ac{PE} to a symmetric data object on any \ac{PE} that 
+    return after posting the operation. 
+    On return, the calling thread cannot modify the \VAR{source} object. A 
+    subsequent call to \FUNC{shmem\_quiet} is required to complete the operation 
+    by copying the data into the \dest{} object on the destination \ac{PE}.
+    The delivery of data words into the data object on the destination \ac{PE} 
+    may occur in any order. Furthermore, two successive calls to \FUNC{put_nbi} 
+    routines may deliver data out of order unless a call to \FUNC{shmem\_fence} is 
+    introduced between the two calls.
  }
 
 \apidesctable{