shmem_swap(3)

NAME
     shmem_double_swap, shmem_float_swap, shmem_int_swap, shmem_long_swap,
     shmem_swap, shmem_int4_swap, shmem_int8_swap, shmem_real4_swap,
     shmem_real8_swap, shmem_longlong_swap - Performs an atomic swap to a
     remote data object

SYNOPSIS
     C or C++:

        #include <mpp/shmem.h>

        double shmem_double_swap(double *target, double value, int pe);

        float shmem_float_swap(float *target, float value, int pe);

        int shmem_int_swap(int *target, int value, int pe);

        long shmem_long_swap(long *target, long value, int pe);

        long long shmem_longlong_swap(long long *target, long long value,
        int pe);

        long shmem_swap(long *target, long value, int pe);

     Fortran:

        INTEGER pe

        INTEGER SHMEM_SWAP
        ires = SHMEM_SWAP(target, value, pe)

        INTEGER(KIND=4) SHMEM_INT4_SWAP
        ires = SHMEM_INT4_SWAP(target, value, pe)

        INTEGER(KIND=8) SHMEM_INT8_SWAP
        ires = SHMEM_INT8_SWAP(target, value, pe)

        REAL(KIND=4) SHMEM_REAL4_SWAP
        res = SHMEM_REAL4_SWAP(target, value, pe)

        REAL(KIND=8) SHMEM_REAL8_SWAP
        res = SHMEM_REAL8_SWAP(target, value, pe)

DESCRIPTION
     shmem_swap performs an atomic swap operation. It writes value value
     into target on processing element (PE) pe and returns the previous
     contents of target as an atomic operation.

     The arguments are as follows:

     target    The remotely accessible integer data object to be updated on
               the remote PE.  If you are using C/C++, the type of target
               should match that implied in the SYNOPSIS section.  If you
               are using Fortran, it must be of the following type:

                    Routine                  Data Type

                    SHMEM_SWAP               Integer of default kind

                    SHMEM_INT4_SWAP          4-byte integer

                    SHMEM_INT8_SWAP          8-byte integer

                    SHMEM_REAL4_SWAP         4-byte real

                    SHMEM_REAL8_SWAP         8-byte real

     value     Value to be atomically written to the remote PE.  value is
               the same type as target.

     pe        An integer that indicates the PE number on which target is
               to be updated.  If you are using Fortran, it must be a
               default integer value.

NOTES
     The term remotely accessible is defined in intro_shmem(3).

     shmem_swap writes directly into another PE's memory without notifying
     that PE, so the receiving PE should normally set automatic cache
     invalidation by use of shmem_set_cache_inv(3) or
     shmem_set_cache_line_inv(3).  If this is not done, the receiving PE's
     data cache might become incoherent.

     You can use shmem_swap without setting the remote write invalidate bit
     if you know, prior to the call, that the data at the target addresses
     are not cachable or are otherwise known not to reside in the remote
     processor's cache at the time of the call.  Alternatively, the
     receiving processor can flush its cache when it knows that it has
     received data from another processor.  In general, this requires
     synchronization.  The cache can be flushed using shmem_udcflush() or
     shmem_udcflush_line().

RETURN VALUES
     The contents that had been at the target address on the remote PE
     prior to the swap is returned.

SEE ALSO
     intro_shmem(3), shmem_clear_cache_inv(3), shmem_set_cache_inv(3),
     shmem_set_cache_line_inv(3)