shmem_put.tex

\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}.
}

\begin{apidefinition}

\begin{C11synopsis}
void shmem_put(TYPE *dest, const TYPE *source, size_t nelems, int pe);
\end{C11synopsis}
where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}.

\begin{Csynopsis}
void shmem_<TYPENAME>_put(TYPE *dest, const TYPE *source, size_t nelems, 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 shmem_put<SIZE>(void *dest, const void *source, size_t nelems, int pe);
\end{CsynopsisCol}
where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}.

\begin{CsynopsisCol}
void shmem_putmem(void *dest, const void *source, size_t nelems, int pe);
\end{CsynopsisCol}

\begin{Fsynopsis}
CALL SHMEM_CHARACTER_PUT(dest, source, nelems, pe)
CALL SHMEM_COMPLEX_PUT(dest, source, nelems, pe)
CALL SHMEM_DOUBLE_PUT(dest, source, nelems, pe)
CALL SHMEM_INTEGER_PUT(dest, source, nelems, pe)
CALL SHMEM_LOGICAL_PUT(dest, source, nelems, pe)
CALL SHMEM_PUT4(dest, source, nelems, pe)
CALL SHMEM_PUT8(dest, source, nelems, pe)
CALL SHMEM_PUT32(dest, source, nelems, pe)
CALL SHMEM_PUT64(dest, source, nelems, pe)
CALL SHMEM_PUT128(dest, source, nelems, pe)
CALL SHMEM_PUTMEM(dest, source, nelems, pe)
CALL SHMEM_REAL_PUT(dest, source, nelems, pe)
\end{Fsynopsis}

\begin{apiarguments}
    \apiargument{IN}{dest}{Data object to be updated on the remote \ac{PE}. This
    data object must be remotely accessible.}
    \apiargument{OUT}{source}{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
    \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
    of type integer. When using \Fortran, it must be a constant, variable,
    or array element of default integer type.}
\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.   
 }

\apidesctable{
    The \dest{} and \source{} data objects must conform to certain typing
    constraints, which are as follows:}
    {Routine}{Data type of \VAR{dest} and \VAR{source}}
    \apitablerow{shmem\_putmem}{\Fortran: Any noncharacter type. \Cstd: Any
        data  type.  nelems is scaled in bytes.}
    \apitablerow{shmem\_put4, shmem\_put32}{Any noncharacter type
        that has a storage size equal to \CONST{32} bits.}
    \apitablerow{shmem\_put8}{\Cstd: Any noncharacter type that
        has a storage size equal to \CONST{8} bits.}
    \apitablerow{}{\Fortran: Any noncharacter type that
        has a storage size equal to \CONST{64} bits.}
    \apitablerow{shmem\_put64}{Any noncharacter type that
        has a storage size equal to \CONST{64} bits.}
    \apitablerow{shmem\_put128}{Any noncharacter type that has a
        storage size equal to \CONST{128} bits.}
    \apitablerow{SHMEM\_CHARACTER\_PUT}{Elements of type character.  \VAR{nelems}
    is  the number  of	 characters to transfer. The actual character lengths of
    the \source{} and \dest{} variables are ignored. }
    \apitablerow{SHMEM\_COMPLEX\_PUT}{Elements of type complex of default size.}
    \apitablerow{SHMEM\_DOUBLE\_PUT}{Elements of type double precision. }
    \apitablerow{SHMEM\_INTEGER\_PUT}{Elements of type integer.}
    \apitablerow{SHMEM\_LOGICAL\_PUT}{Elements of type logical.}
    \apitablerow{SHMEM\_REAL\_PUT}{Elements of type real.}

\apireturnvalues{
    None.
}
\apinotes{
    When using \Fortran, data types must be of default size.  For example,
    a real variable must be declared as \CONST{REAL},  \CONST{REAL*4},  or
    \CONST{REAL(KIND=KIND(1.0))}. The Fortran API routine \FUNC{SHMEM\_PUT} has
    been deprecated, and either \FUNC{SHMEM\_PUT8} or \FUNC{SHMEM\_PUT64} should
    be used in its place.
}

\begin{apiexamples}

\apicexample
    { The following \FUNC{shmem\_put} example is for C11 programs:}
    {./example_code/shmem_put_example.c}
    {} 
\end{apiexamples}

\end{apidefinition}