Open MPI logo

MPI_Iprobe(3) man page (version 1.2.9)

  |   Home   |   Support   |   FAQ   |  

« 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