NAME

       shmem_broadcast4(3),  shmem_broadcast8(3),  shmem_broadcast32(3),  shmem_broadcast64(3)  -
       Copy a data object from a designated PE to a target location  on  all  other  PEs  of  the
       active set.

SYNOPSIS

       C or C++:
       #include <mpp/shmem.h>

       void shmem_broadcast32(void *target, const void *source,
         size_t nelems, int PE_root, int PE_start, int logPE_stride,
         int PE_size, long *pSync);

       void shmem_broadcast64(void *target, const void *source,
         size_t nelems, int PE_root, int PE_start, int logPE_stride,
         int PE_size, long *pSync);

       Fortran:
       INCLUDE "mpp/shmem.fh"

       INTEGER nelems, PE_root, PE_start, logPE_stride, PE_size
       INTEGER pSync(SHMEM_BCAST_SYNC_SIZE)

       CALL SHMEM_BROADCAST4(target, source, nelems, PE_root,
       & PE_start, logPE_stride, PE_size, fIpSync)

       CALL SHMEM_BROADCAST8(target, source, nelems, PE_root,
       & PE_start, logPE_stride, PE_size, pSync)

       CALL SHMEM_BROADCAST32(target, source, nelems,
       & PE_root, PE_start, logPE_stride, PE_size, pSync)

       CALL SHMEM_BROADCAST64(target, source, nelems,
       & PE_root, PE_start, logPE_stride, PE_size, pSync)

DESCRIPTION

       The  broadcast routines write the data at address source of the PE specified by PE_root to
       address target on all other PEs in the active set. The active set of PEs is defined by the
       triplet  PE_start, logPE_stride and PE_size.  The data is not copied to the target address
       on the PE specified by PE_root.  Before returning, the broadcast routines ensure that  the
       elements of the pSync array are restored to their initial values.

       As with all SHMEM collective routines, each of these routines assumes that only PEs in the
       active set call the routine. If a PE not in  the  active  set  calls  a  SHMEM  collective
       routine, undefined behavior results.

       The arguments are as follows:

       target A symmetric data object with one of the following data types:

              shmem_broadcast8, shmem_broadcast64: Any noncharacter type that
                     has an element size of 64 bits. No Fortran derived types or C/C++ structures
                     are allowed.

              shmem_broadcast32: Any noncharacter type that has an element size
                     of 32 bits. No Fortran derived types or C/C++ structures are allowed.

              shmem_broadcast4: Any noncharacter type that has an element size
                     of 32 bits.

       source A symmetric data object that can be of any data type that is  permissible  for  the
              target argument.

       nelems The  number of elements in source. For shmem_broadcast32 and shmem_broadcast4, this
              is the number of 32-bit halfwords. nelems must be of  type  integer.   If  you  are
              using Fortran, it must be a default integer value.

       PE_root
              Zero-based  ordinal  of the PE, with respect to the active set, from which the data
              is copied. Must be greater than or equal to 0 and less than PE_size.  PE_root  must
              be of type integer. If you are using Fortran, it must be a default integer value.

       PE_start
              The  lowest  virtual  PE  number of the active set of PEs. PE_start must be of type
              integer. If you are using Fortran, it must be a default integer value.

       logPE_stride
              The log (base 2) of the stride between consecutive virtual PE numbers in the active
              set.  log_PE_stride must be of type integer. If you are using Fortran, it must be a
              default integer value.

       PE_size
              The number of PEs in the active set. PE_size must be of type integer.  If  you  are
              using Fortran, it must be a default integer value.

       pSync  A   symmetric  work  array.  In  C/C++,  pSync  must  be  of  type  long  and  size
              _SHMEM_BCAST_SYNC_SIZE.  In Fortran,  pSync  must  be  of  type  integer  and  size
              SHMEM_BCAST_SYNC_SIZE.  Every  element  of  this array must be initialized with the
              value _SHMEM_SYNC_VALUE (in C/C++) or SHMEM_SYNC_VALUE (in Fortran) before  any  of
              the PEs in the active set enter shmem_barrier().

       The  values of arguments PE_root, PE_start, logPE_stride, and PE_size must be equal on all
       PEs in the active set. The same target and source data objects and  the  same  pSync  work
       array must be passed to all PEs in the active set.

       Before  any  PE  calls  a broadcast routine, you must ensure that the following conditions
       exist (synchronization via a barrier or some other method is often needed to ensure this):
       The  pSync  array  on all PEs in the active set is not still in use from a prior call to a
       broadcast routine. The target array on all PEs in the active set is ready  to  accept  the
       broadcast data.

       Upon  return  from  a  broadcast  routine, the following are true for the local PE: If the
       current PE is not the root PE, the target data object is updated. The values in the  pSync
       array are restored to the original values.

NOTES

       The terms collective and symmetric are defined in intro_shmem(3).

       All  SHMEM  broadcast  routines  restore pSync to its original contents. Multiple calls to
       SHMEM routines that use the same pSync array do not require that  pSync  be  reinitialized
       after the first call.

       You  must ensure the that the pSync array is not being updated by any PE in the active set
       while any of the PEs participates in processing of a SHMEM broadcast routine.  Be  careful
       to  avoid  these  situations:  If the pSync array is initialized at run time, some type of
       synchronization is needed to ensure that all PEs in the working set have initialized pSync
       before  any  of  them enter a SHMEM routine called with the pSync synchronization array. A
       pSync array may be reused on a subsequent SHMEM broadcast routine only if none of the  PEs
       in  the active set are still processing a prior SHMEM broadcast routine call that used the
       same  pSync  array.  In  general,  this  can  be  ensured  only  by  doing  some  type  of
       synchronization.   However,  in  the  special case of SHMEM routines being called with the
       same active set, you  can  allocate  two  pSync  arrays  and  alternate  between  them  on
       successive calls.

EXAMPLES

       In  the  following examples, the call to shmem_broadcast64 copies source on PE 4 to target
       on PEs 5, 6, and 7.

       C/C++ example:
       for (i=0; i < _SHMEM_BCAST_SYNC_SIZE; i++) {
         pSync[i] = _SHMEM_SYNC_VALUE;
       }
       shmem_barrier_all(); /* Wait for all PEs to initialize pSync */
       shmem_broadcast64(target, source, nelems, 0, 4, 0, 4, pSync);

       Fortran example:
       INTEGER PSYNC(SHMEM_BCAST_SYNC_SIZE)
       INTEGER TARGET, SOURCE, NELEMS, PE_ROOT, PE_START,
       & LOGPE_STRIDE, PE_SIZE, PSYNC
       COMMON /COM/ TARGET, SOURCE
       DATA PSYNC /SHMEM_BCAST_SYNC_SIZE*SHMEM_SYNC_VALUE/

       CALL SHMEM_BROADCAST64(TARGET, SOURCE, NELEMS, 0, 4, 0, 4,
       & PSYNC)

SEE ALSO

       intro_shmem(3)