MPIIprobe(3OpenMPI) MPIIprobe(3OpenMPI)

NAME
       MMPPIIIIpprroobbee - Nonblocking test for a message.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPIIprobe(int source, int tag, MPIComm comm, int *flag,
            MPIStatus *status)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPIIPROBE(SOURCE, TAG, COMM, FLAG, STATUS, IERROR)
            LOGICAL   FLAG
            INTEGER   SOURCE, TAG, COMM, STATUS(MPISTATUSSIZE), IERROR


CC++++ SSyynnttaaxx
       #include 
       bool Comm::Iprobe(int source, int tag, Status& status) const

       bool Comm::Iprobe(int source, int tag) const


IINNPPUUTT PPAARRAAMMEETTEERRSS
       source    Source rank or MPIANYSOURCE (integer).

       tag       Tag value or MPIANYTAG (integer).

       comm      Communicator (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERRSS
       flag      Message-waiting flag (logical).

       status    Status object (status).

       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       The MPIProbe and MPIIprobe 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.

       MPIIprobe(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 MPIRecv(...,
       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
       MPIRecv(). Otherwise, the call returns flag = false, and leaves status
       undefined.

       If  MPIIprobe  returns  flag  =  true,  then the content of the status
       object can be subsequently accessed as described in  Section  3.2.5  of
       the  MPI-1  Standard,  "Return  Status,"  to  find the source, tag, and
       length of the probed message.

       A subsequent receive executed with the same context, and the source and
       tag  returned in status by MPIIprobe will receive the message that was
       matched by the probe if no other intervening receive occurs  after  the
       probe.  If  the  receiving  process  is multithreaded, it is the user's
       responsibility to ensure that the last condition holds.

       The source argument of MPIProbe can be  MPIANYSOURCE,  and  the  tag
       argument can be MPIANYTAG, 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 MPISTATUSIGNORE 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.


NNOOTTEE
       Users  of  libmpi-mt  should  remember  that  two  threads  may  do  an
       MPIIprobe that actually returns true for the  same  message  for  both
       threads.


EERRRROORRSS
       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::ERRORSTHROWEXCEPTIONS, 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
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       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
       MPIProbe
       MPICancel




Open MPI 1.2                    September 2006            MPIIprobe(3OpenMPI)