MPI_IPROBE, MPI_Iprobe

Purpose

Checks to see if a message matching source, tag, and comm has arrived.

C synopsis

#include <mpi.h>
int MPI_Iprobe(int source,int tag,MPI_Comm comm,int *flag,
               MPI_Status *status);

C++ synopsis

#include mpi.h
bool MPI::Comm::Iprobe(int source, int tag) const;

#include mpi.h
bool MPI::Comm::Iprobe(int source, int tag, MPI::Status& status) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_IPROBE(INTEGER SOURCE,INTEGER TAG,INTEGER COMM,INTEGER FLAG,
           INTEGER STATUS(MPI_STATUS_SIZE),INTEGER IERROR)

Description

This subroutine lets you check for incoming messages without actually
receiving them.

MPI_IPROBE(source, tag, comm, flag, status) returns flag = true when there
is a message that can be received 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 values that would have been returned by MPI_RECV(). Otherwise, the
call returns flag = false and leaves status undefined.

When MPI_IPROBE returns flag = true, the content of the status object can
be accessed to find the source, tag and length of the probed message.

A subsequent receive operation executed with the same comm, and the source
and tag returned in status by MPI_IPROBE receives the message that was
matched by the probe, if no other intervening receive occurs after the
initial probe.

source can be MPI_ANY_SOURCE and tag can be MPI_ANY_TAG. This allows you to
probe messages from any source and with any tag or both, but you must
provide a specific communicator with comm.

When a message is not received immediately after it is probed, the same
message can be probed for several times before it is received.

Passing MPI_STATUS_IGNORE for the status argument causes PE MPI to skip
filling in the status fields. By passing this value for status, you can
avoid having to allocate a status object in programs that do not need to
examine the status fields.

Parameters

source
     is a source rank or MPI_ANY_SOURCE (integer) (IN)
tag
     is a tag value or MPI_ANY_TAG (positive integer) (IN)
comm
     is a communicator (handle) (IN)
flag
     (logical) (OUT)
status
     is a status object (Status) (INOUT). Note that in FORTRAN a single
     status object is an array of integers.
IERROR
     is the FORTRAN return code. It is always the last argument.

Notes

In a threads environment, MPI_PROBE or MPI_IPROBE followed by MPI_RECV,
based on the information from the probe, may not be a thread-safe
operation. You must ensure that no other thread received the detected
message.

An MPI_IPROBE cannot prevent a message from being cancelled successfully by
the sender, making it unavailable for the MPI_RECV. Structure your program
so this will not occur.

Errors

Invalid communicator

Invalid source
     source < 0 or source > = groupsize

Invalid status ignore value

Invalid tag
     tag < 0

MPI already finalized

MPI not initialized

Related information

     MPI_PROBE
     MPI_RECV