|
« Return to documentation listing
Table of Contents
MPI_Scan - Computes an inclusive scan (partial reduction)
#include <mpi.h>
int MPI_Scan(void *sendbuf, void *recvbuf, int count,
MPI_Datatype datatype, MPI_Op op, MPI_Comm comm)
INCLUDE ’mpif.h’
MPI_SCAN(SENDBUF, RECVBUF, COUNT, DATATYPE, OP, COMM, IERROR)
<type> SENDBUF(*), RECVBUF(*)
INTEGER COUNT, DATATYPE, OP, COMM, IERROR
#include <mpi.h>
void MPI::Intracomm::Scan(const void* sendbuf, void* recvbuf,
int count, const MPI::Datatype& datatype,
const MPI::Op& op) const
- 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).
- recvbuf
- Receive buffer (choice).
- IERROR
- Fortran only: Error status (integer).
MPI_Scan
is used to perform an inclusive 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 (inclusive). The
type of operations supported, their semantics, and the constraints on send
and receive buffers are as for MPI_Reduce.
This example uses a user-defined
operation to produce a segmented scan. A segmented scan takes, as input,
a set of values and a set of logicals, where the logicals delineate the
various segments of the scan. For example,
values v1 v2 v3 v4 v5 v6 v7 v8
logicals 0 0 1 1 1 0 0 1
result v1 v1+v2 v3 v3+v4 v3+v4+v5 v6 v6+v7 v8
The result for rank j is thus the sum v(i) + ... + v(j), where i is the lowest
rank such that for all ranks n, i <= n <= j, logical(n) = logical(j). The
operator that produces this effect is
[ u ] [ v ] [ w ]
[ ] o [ ] = [ ]
[ i ] [ j ] [ j ]
where
( u + v if i = j
w = (
( v if i != j
Note that this is a noncommutative operator. C code that implements it
is given below.
typedef struct {
double val;
int log;
} SegScanPair;
/*
* the user-defined function
*/
void segScan(SegScanPair *in, SegScanPair *inout, int *len,
MPI_Datatype *dptr)
{
int i;
SegScanPair c;
for (i = 0; i < *len; ++i) {
if (in->log == inout->log)
c.val = in->val + inout->val;
else
c.val = inout->val;
c.log = inout->log;
*inout = c;
in++;
inout++;
}
}
Note that the inout argument to the user-defined function corresponds to
the right-hand operand of the operator. When using this operator, we must
be careful to specify that it is noncommutative, as in the following:
int i, base;
SeqScanPair a, answer;
MPI_Op myOp;
MPI_Datatype type[2] = {MPI_DOUBLE, MPI_INT};
MPI_Aint disp[2];
int blocklen[2] = {1, 1};
MPI_Datatype sspair;
/*
* explain to MPI how type SegScanPair is defined
*/
MPI_Get_address(a, disp);
MPI_Get_address(a.log, disp + 1);
base = disp[0];
for (i = 0; i < 2; ++i)
disp[i] -= base;
MPI_Type_struct(2, blocklen, disp, type, &sspair);
MPI_Type_commit(&sspair);
/*
* create the segmented-scan user-op
* noncommutative - set commute (arg 2) to 0
*/
MPI_Op_create((MPI_User_function *)segScan, 0, &myOp);
...
MPI_Scan(a, answer, 1, sspair, myOp, comm);
When the communicator is an intracommunicator, you
can perform a scanning operation in place (the output buffer is used as
the input buffer). Use the variable MPI_IN_PLACE as the value of the sendbuf
argument. The input data is taken from the receive buffer and replaced
by the output data.
The reduction functions
of type MPI_Op do not return an error value. As a result, if the functions
detect an error, all they can do is either call MPI_Abort or silently skip
the problem. Thus, if the error handler is changed from MPI_ERRORS_ARE_FATAL
to something else (e.g., MPI_ERRORS_RETURN), 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.
Almost all MPI routines return
an error value; C routines as the value of the function and Fortran routines
in the last argument. C++ functions do not return errors. If the default
error handler is set to MPI::ERRORS_THROW_EXCEPTIONS, 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 MPI_Comm_set_errhandler; the
predefined error handler MPI_ERRORS_RETURN 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.
MPI_Exscan
MPI_Op_create
MPI_Reduce
« Return to documentation listing
|
