MPIScatter(3OpenMPI) MPIScatter(3OpenMPI)

NAME
       MMPPIISSccaatttteerr - Sends data from one task to all tasks in a group.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIScatter(void *sendbuf, int sendcount, MPIDatatype sendtype,
            void *recvbuf, int recvcount, MPIDatatype recvtype, int root,
            MPIComm comm)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPISCATTER(SENDBUF, SENDCOUNT, SENDTYPE, RECVBUF, RECVCOUNT,
                 RECVTYPE, ROOT, COMM, IERROR)
                SENDBUF(*), RECVBUF(*)
            INTEGER   SENDCOUNT, SENDTYPE, RECVCOUNT, RECVTYPE, ROOT
            INTEGER   COMM, IERROR


CC++++ SSyynnttaaxx
       #include 
       void MPI::Comm::Scatter(const void* sendbuf, int sendcount,
            const MPI::Datatype& sendtype, void* recvbuf,
            int recvcount, const MPI::Datatype& recvtype,
            int root) const


IINNPPUUTT PPAARRAAMMEETTEERRSS
       sendbuf   Address of send buffer (choice, significant only at root).

       sendcount Number of elements sent to each process (integer, significant
                 only at root).

       sendtype  Datatype of send buffer elements (handle, significant only at
                 root).

       recvcount Number of elements in receive buffer (integer).

       recvtype  Datatype of receive buffer elements (handle).

       root      Rank of sending process (integer).

       comm      Communicator (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       recvbuf   Address of receive buffer (choice).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       MPIScatter is the inverse operation to MPIGather.

       The outcome is as if the root executed n send operations,

           MPISend(sendbuf + i * sendcount * extent(sendtype), sendcount,
                    sendtype, i, ...)

       and each process executed a receive,

           MPIRecv(recvbuf, recvcount, recvtype, i, ...).

       An  alternative  description  is  that  the  root  sends a message with
       MPISend(sendbuf, sendcount * n, sendtype, ...). This message is  split
       into  n  equal  segments, the ith segment is sent to the ith process in
       the group, and each process receives this message as above.

       The send buffer is ignored for all nonroot processes.

       The type signature associated with sendcount, sendtype at the root must
       be  equal  to the type signature associated with recvcount, recvtype at
       all processes (however, the type maps may be different).  This  implies
       that  the  amount  of  data  sent  must  be equal to the amount of data
       received, pairwise between each process and  the  root.  Distinct  type
       maps between sender and receiver are still allowed.

       All arguments to the function are significant on process root, while on
       other processes, only arguments  recvbuf,  recvcount,  recvtype,  root,
       comm  are  significant. The arguments root and comm must have identical
       values on all processes.

       The specification of counts and types should not cause any location  on
       the root to be read more than once.

       RRaattiioonnaallee::  Though not needed, the last restriction is imposed so as to
       achieve symmetry with MPIGather, where the  corresponding  restriction
       (a multiple-write restriction) is necessary.

       EExxaammppllee::  The  reverse  of Example 1 in the MPIGather manpage. Scatter
       sets of 100 ints from the root to each process in the group.

               MPIComm comm;
               int gsize,*sendbuf;
               int root, rbuf[100];
               ...
               MPICommsize(comm, &gsize);
               sendbuf = (int *)malloc(gsize*100*sizeof(int));
               ...
               MPIScatter(sendbuf, 100, MPIINT, rbuf, 100,
                           MPIINT, root, comm);


UUSSEE OOFF IINN-PPLLAACCEE OOPPTTIIOONN
       When the communicator is an intracommunicator, you can perform a gather
       operation  in-place  (the  output  buffer is used as the input buffer).
       Use the variable MPIINPLACE as the value of the root process recvbuf.
       In  this case, recvcount and recvtype are ignored, and the root process
       sends no data to itself.

       Note that MPIINPLACE is a special kind of  value;  it  has  the  same
       restrictions on its use as MPIBOTTOM.

       Because  the  in-place  option converts the receive buffer into a send-
       and-receive buffer, a Fortran binding that includes  INTENT  must  mark
       these as INOUT, not OUT.


WWHHEENN CCOOMMMMUUNNIICCAATTOORR IISS AANN IINNTTEERR-CCOOMMMMUUNNIICCAATTOORR
       When the communicator is an inter-communicator, the root process in the
       first group sends data to all processes in the second group.  The first
       group  defines  the  root  process.   That process uses MPIROOT as the
       value of its root argument.  The remaining processes use  MPIPROCNULL
       as the value of their root argument.  All processes in the second group
       use the rank of that root process in the first group as  the  value  of
       their  root argument.   The receive buffer argument of the root process
       in the first group must be consistent with the receive buffer  argument
       of the processes in the second group.


EERRRROORRSS
       Almost  all MPI routines return an error value; C routines as the value
       of the function and Fortran routines in the last  argument.  C++  func-
       tions  do  not  return  errors.  If the default error handler is set to
       MPI::ERRORSTHROWEXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before  the  error  value is returned, the current MPI error handler is
       called. By default, this error handler aborts the MPI job,  except  for
       I/O   function   errors.   The   error  handler  may  be  changed  with
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       may  be  used  to cause error values to be returned. Note that MPI does
       not guarantee that an MPI program can continue past an error.


SEE ALSO
       MPIScatterv
       MPIGather
       MPIGatherv




Open MPI 1.2                    September 2006           MPIScatter(3OpenMPI)