.\" -*- nroff -*-
.\" Copyright 2012 Cisco Systems, Inc.  All rights reserved.
.\" Copyright 2006-2008 Sun Microsystems, Inc.
.\" Copyright (c) 1996 Thinking Machines Corporation
.\" $COPYRIGHT$
.TH MPI_Imrecv 3 "Oct 29, 2018" "3.1.3" "Open MPI"
.SH NAME
\fBMPI_Imrecv\fP \- Non-blocking receive for a matched message

.SH SYNTAX
.ft R
.SH C Syntax
.nf
#include <mpi.h>
int MPI_Imrecv(void \fI*buf\fP, int\fI count\fP, MPI_Datatype\fI type\fP,
	MPI_Message\fI *message\fP, MPI_Request\fI *request\fP)

.fi
.SH Fortran Syntax
.nf
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_IMRECV(\fIBUF, COUNT, DATATYPE, MESSAGE, REQUEST, IERROR\fP)
	<type>	\fIBUF(*)\fP
	INTEGER	\fICOUNT, DATATYPE, MESSAGE, REQUEST, IERROR\fP

.fi
.SH Fortran 2008 Syntax
.nf
USE mpi_f08
MPI_Imrecv(\fIbuf\fP, \fIcount\fP, \fIdatatype\fP, \fImessage\fP, \fIrequest\fP, \fIierror\fP)
	TYPE(*), DIMENSION(..), ASYNCHRONOUS :: \fIbuf\fP
	INTEGER, INTENT(IN) :: \fIcount\fP
	TYPE(MPI_Datatype), INTENT(IN) :: \fIdatatype\fP
	TYPE(MPI_Message), INTENT(INOUT) :: \fImessage\fP
	TYPE(MPI_Request), INTENT(OUT) :: \fIrequest\fP
	INTEGER, OPTIONAL, INTENT(OUT) :: \fIierror\fP

.fi
.SH C++ Syntax
.nf
There is no C++ binding for this function.

.fi
.SH INPUT PARAMETERS
.ft R
.TP 1i
count
Number of elements to receive (nonnegative integer).
.TP 1i
datatype
Datatype of each send buffer element (handle).
.TP 1i
message
Message (handle).

.SH OUTPUT PARAMETERS
.ft R
.TP 1i
buf
Initial address of receive buffer (choice).
.TP 1i
request
Request (handle).
.TP 1i
IERROR
Fortran only: Error status (integer).

.SH DESCRIPTION
.ft R
The functions MPI_Mrecv and MPI_Imrecv receive messages that have been
previously matched by a matching probe.
.sp
The \fIrequest\fP returned from MPI_Imrecv can be used with any of the
MPI_Test and MPI_Wait variants, like any non-blocking receive request.
.sp
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 \fIstatus\fP object set to \fIsource\fP =
MPI_PROC_NULL, \fItag\fP = MPI_ANY_TAG, and \fIcount\fP = 0, as if a
receive from MPI_PROC_NULL was issued.
.sp
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.
.sp
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).

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

.SH 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.
.sp
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.

.SH SEE ALSO
.ft R
.nf
MPI_Mprobe
MPI_Improbe
MPI_Probe
MPI_Iprobe
MPI_Imrecv
MPI_Cancel