MPIExscan(3OpenMPI) MPIExscan(3OpenMPI)

NAME
       MMPPIIEExxssccaann - Computes an exclusive scan (partial reduction)


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIExscan(void *sendbuf, void *recvbuf, int count,
            MPIDatatype datatype, MPIOp op, MPIComm comm)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPISCAN(SENDBUF, RECVBUF, COUNT, DATATYPE, OP, COMM, IERROR)
                SENDBUF(*), RECVBUF(*)
            INTEGER   COUNT, DATATYPE, OP, COMM, IERROR


CC++++ SSyynnttaaxx
       #include 
       void MPI::Intracomm::Exscan(const void* sendbuf, void* recvbuf,
            int count, const MPI::Datatype& datatype,
            const MPI::Op& op) const


IINNPPUUTT PPAARRAAMMEETTEERRSS
       sendbuf   Send buffer (choice).

       count     Number of elements in input buffer (integer).

       datatype  Data type of elements of input buffer (handle).

       op        Operation (handle).

       comm      Communicator (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       recvbuf   Receive buffer (choice).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       MPIExscan  is  used  to  perform an exclusive prefix reduction on data
       distributed across the calling processes. The operation returns, in the
       recvbuf of the process with rank i, the reduction (calculated according
       to the function op) of the values in the  sendbufs  of  processes  with
       ranks  0,  ...,  i-1.  Compare this with the functionality of MPIScan,
       which calculates over the range 0, ...,  i  (inclusive).  The  type  of
       operations  supported, their semantics, and the constraints on send and
       receive buffers are as for MPIReduce.

       The value in recvbuf on  process  0  is  undefined  and  unreliable  as
       recvbuf  is  not  significant  for  process  0. The value of recvbuf on
       process 1 is always the value in sendbuf on process 0.

       No MPIINPLACE operation is supported.


NNOOTTEESS
       MPI does not specify which process computes which operation. In partic-
       ular,  both  processes  0 and 1 may participate in the computation even
       though the results for both processes' recvbuf are  degenerate.  There-
       fore, all processes, including 0 and 1, must provide the same op.

       It  can be argued, from a mathematical perspective, that the definition
       of MPIExscan is unsatisfactory because the  output  at  process  0  is
       undefined.   The "mathematically correct" output for process 0 would be
       the unit element of the reduction operation. However, such a definition
       of  an  exclusive scan would not work with user-defined op functions as
       there is no way for MPI to "know" the unit value for these custom oper-
       ations.


NNOOTTEESS OONN CCOOLLLLEECCTTIIVVEE OOPPEERRAATTIIOONNSS
       The  reduction  functions  of type MPIOp do not return an error value.
       As a result, if the functions detect an  error,  all  they  can  do  is
       either  call MPIAbort or silently skip the problem. Thus, if the error
       handler is changed from MPIERRORSAREFATAL to something  else  (e.g.,
       MPIERRORSRETURN), then no error may be indicated.

       The  reason  for  this is the performance problems in ensuring that all
       collective routines return the same error value.


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 the MPI man page for a full list of MPI error codes.


SEE ALSO
       MPIOpcreate
       MPIReduce
       MPIScan




Open MPI 1.2                    September 2006            MPIExscan(3OpenMPI)