|
« Return to documentation listing
NAME
MPI_Iprobe - Nonblocking test for a message.
SYNTAX
C Syntax
#include <mpi.h>
int MPI_Iprobe(int source, int tag, MPI_Comm comm, int *flag,
MPI_Status *status)
Fortran Syntax
INCLUDE 'mpif.h'
MPI_IPROBE(SOURCE, TAG, COMM, FLAG, STATUS, IERROR)
LOGICAL FLAG
INTEGER SOURCE, TAG, COMM, STATUS(MPI_STATUS_SIZE), IERROR
C++ Syntax
#include <mpi.h>
bool Comm::Iprobe(int source, int tag, Status& status) const
bool Comm::Iprobe(int source, int tag) const
INPUT PARAMETERS
source Source rank or MPI_ANY_SOURCE (integer).
tag Tag value or MPI_ANY_TAG (integer).
comm Communicator (handle).
OUTPUT PARAMETERS
flag Message-waiting flag (logical).
status Status object (status).
IERROR Fortran only: Error status (integer).
DESCRIPTION
The MPI_Probe and MPI_Iprobe operations allow checking of incoming mes-
sages without actual receipt of them. The user can then decide how to
receive them, based on the information returned by the probe (basi-
cally, the information returned by status). In particular, the user may
allocate memory for the receive buffer, according to the length of the
probed message.
MPI_Iprobe(source, tag, comm, flag, status) returns flag = true if
there is a message that can be received and that matches the pattern
specified by the arguments source, tag, and comm. The call matches the
same message that would have been received by a call to MPI_Recv(...,
source, tag, comm, status) executed at the same point in the program,
and returns in status the same value that would have been returned by
MPI_Recv(). Otherwise, the call returns flag = false, and leaves status
undefined.
probe. If the receiving process is multithreaded, it is the user's
responsibility to ensure that the last condition holds.
The source argument of MPI_Probe can be MPI_ANY_SOURCE, and the tag
argument can be MPI_ANY_TAG, so that one can probe for messages from an
arbitrary source and/or with an arbitrary tag. However, a specific com-
munication context must be provided with the comm argument.
If your application does not need to examine the status field, you can
save resources by using the predefined constant MPI_STATUS_IGNORE as a
special value for the status argument.
It is not necessary to receive a message immediately after it has been
probed for, and the same message may be probed for several times before
it is received.
NOTE
Users of libmpi-mt should remember that two threads may do an
MPI_Iprobe that actually returns true for the same message for both
threads.
ERRORS
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::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 ALSO
MPI_Probe
MPI_Cancel
Open MPI 1.2 September 2006 MPI_Iprobe(3OpenMPI)
« Return to documentation listing
|
