128 строки
4.0 KiB
Groff
128 строки
4.0 KiB
Groff
.\"Copyright 2006, Sun Microsystems, Inc.
|
|
.\" Copyright (c) 1996 Thinking Machines Corporation
|
|
.TH MPI_Exscan 3OpenMPI "September 2006" "Open MPI 1.2" " "
|
|
|
|
.SH NAME
|
|
\fBMPI_Exscan\fP \- Computes an exclusive scan (partial reduction)
|
|
|
|
.SH SYNTAX
|
|
.ft R
|
|
|
|
.SH C Syntax
|
|
.nf
|
|
#include <mpi.h>
|
|
int MPI_Exscan(void *\fIsendbuf\fP, void *\fIrecvbuf\fP, int \fIcount\fP,
|
|
MPI_Datatype \fIdatatype\fP, MPI_Op \fIop\fP, MPI_Comm \fIcomm\fP)
|
|
|
|
.SH Fortran Syntax
|
|
.nf
|
|
INCLUDE 'mpif.h'
|
|
MPI_SCAN(\fISENDBUF, RECVBUF, COUNT, DATATYPE, OP, COMM, IERROR\fP)
|
|
<type> \fISENDBUF(*), RECVBUF(*)\fP
|
|
INTEGER \fICOUNT, DATATYPE, OP, COMM, IERROR\fP
|
|
|
|
.SH C++ Syntax
|
|
.nf
|
|
#include <mpi.h>
|
|
void MPI::Intracomm::Exscan(const void* \fIsendbuf\fP, void* \fIrecvbuf\fP,
|
|
int \fIcount\fP, const MPI::Datatype& \fIdatatype\fP,
|
|
const MPI::Op& \fIop\fP) const
|
|
|
|
.SH INPUT PARAMETERS
|
|
.ft R
|
|
.TP 1i
|
|
sendbuf
|
|
Send buffer (choice).
|
|
.TP 1i
|
|
count
|
|
Number of elements in input buffer (integer).
|
|
.TP 1i
|
|
datatype
|
|
Data type of elements of input buffer (handle).
|
|
.TP 1i
|
|
op
|
|
Operation (handle).
|
|
.TP 1i
|
|
comm
|
|
Communicator (handle).
|
|
|
|
.SH OUTPUT PARAMETERS
|
|
.ft R
|
|
.TP 1i
|
|
recvbuf
|
|
Receive buffer (choice).
|
|
.ft R
|
|
.TP 1i
|
|
IERROR
|
|
Fortran only: Error status (integer).
|
|
|
|
.SH DESCRIPTION
|
|
.ft R
|
|
MPI_Exscan is used to perform an exclusive prefix reduction on data
|
|
distributed across the calling processes. The operation returns, in
|
|
the \fIrecvbuf\fP of the process with rank i, the reduction
|
|
(calculated according to the function \fIop\fP) of the values in the
|
|
\fIsendbuf\fPs of processes with ranks 0, ..., i-1. Compare this with
|
|
the functionality of MPI_Scan, 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 MPI_Reduce.
|
|
.sp
|
|
The value in \fIrecvbuf\fP on process 0 is undefined and unreliable
|
|
as \fIrecvbuf\fP is not significant for process 0. The value of
|
|
\fIrecvbuf\fP on process 1 is always the value in \fIsendbuf\fP on
|
|
process 0.
|
|
.sp
|
|
No MPI_IN_PLACE operation is supported.
|
|
|
|
.SH NOTES
|
|
.ft R
|
|
MPI does not specify which process computes which operation. In
|
|
particular, both processes 0 and 1 may participate in the computation
|
|
even though the results for both processes' \fIrecvbuf\fP are
|
|
degenerate. Therefore, all processes, including 0 and 1, must provide
|
|
the same \fIop\fP.
|
|
.sp
|
|
It can be argued, from a mathematical perspective, that the definition
|
|
of MPI_Exscan 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
|
|
\fIop\fP functions as there is no way for MPI to "know" the unit value
|
|
for these custom operations.
|
|
|
|
.SH NOTES ON COLLECTIVE OPERATIONS
|
|
.ft R
|
|
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.
|
|
.sp
|
|
The reason for this is the performance problems in ensuring that
|
|
all collective routines return the same error value.
|
|
|
|
.SH ERRORS
|
|
.ft R
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
See the MPI man page for a full list of MPI error codes.
|
|
|
|
.SH SEE ALSO
|
|
.ft R
|
|
.nf
|
|
MPI_Op_create
|
|
MPI_Reduce
|
|
MPI_Scan
|
|
|