NAME

       MPI_Imrecv - Non-blocking receive for a matched message

SYNTAX

C Syntax

       #include <mpi.h>
       int MPI_Imrecv(void *buf, int count, MPI_Datatype type,
            MPI_Message *message, MPI_Request *request)

Fortran Syntax

       INCLUDE 'mpif.h'
       MPI_IMRECV(BUF, COUNT, DATATYPE, MESSAGE, REQUEST, IERROR)
            <type>    BUF(*)
            INTEGER   OUNT, DATATYPE, MESSAGE, REQUEST, IERROR

C++ Syntax

       There is no C++ binding for this function.

INPUT PARAMETERS

       count     Number of elements to receive (nonnegative integer).

       datatype  Datatype of each send buffer element (handle).

       message   Message (handle).

OUTPUT PARAMETERS

       buf       Initial address of receive buffer (choice).

       request   Request (handle).

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       The  functions MPI_Mrecv and MPI_Imrecv receive messages that have been previously matched
       by a matching probe.

       The request returned from MPI_Imrecv can be used with any of  the  MPI_Test  and  MPI_Wait
       variants, like any non-blocking receive request.

       If  MPI_Imrecv  is  called with MPI_MESSAGE_NULL as the message argument, a call to one of
       the MPI_Test or MPI_Wait variants will return immediately with the status  object  set  to
       source  =  MPI_PROC_NULL,  tag  =  MPI_ANY_TAG,  and  count  =  0,  as  if  a receive from
       MPI_PROC_NULL was issued.

       If reception of a matched message is started with  MPI_Imrecv,  then  it  is  possible  to
       cancel  the  returned request with MPI_Cancel. If MPI_Cancel succeeds, the matched message
       must be found by  a  subsequent  message  probe  (MPI_Probe,  MPI_Iprobe,  MPI_Mprobe,  or
       MPI_Improbe), received by a subsequent receive operation or canceled by the sender.

       Note,  however,  that  is  it  possible  for the cancellation of operations initiated with
       MPI_Imrecv to fail.  An example of a failing case is when canceling  the  matched  message
       receive  would  violate  MPI message ordering rules (e.g., if another message matching the
       same message signature has matched -- and possible received -- before this  MPI_Imrecv  is
       canceled).

NOTE

       This is an MPI-3 function and has no C++ binding.

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++ functions do not return errors.

       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_Mprobe
       MPI_Improbe
       MPI_Probe
       MPI_Iprobe
       MPI_Imrecv
       MPI_Cancel