The syntax of the blocking receive operation is given below.
| MPI_RECV (buf, count, datatype, source, tag, comm, status) | |
| OUT buf | initial address of receive buffer (choice) |
| IN count | number of elements in receive buffer (non-negative integer) |
| IN datatype | datatype of each receive buffer element (handle) |
| IN source | rank of source (integer) |
| IN tag | message tag (integer) |
| IN comm | communicator (handle) |
| OUT status | status object (Status) |
int MPI_Recv(void* buf, int count, MPI_Datatype datatype, int source, int tag, MPI_Comm comm, MPI_Status *status)
MPI_RECV(BUF, COUNT, DATATYPE, SOURCE, TAG, COMM, STATUS, IERROR)
<type> BUF(*)
INTEGER COUNT, DATATYPE, SOURCE, TAG, COMM, STATUS(MPI_STATUS_SIZE), IERROR
void MPI::Comm::Recv(void* buf, int count, const MPI::Datatype& datatype, int source, int tag, MPI::Status& status) const
void MPI::Comm::Recv(void* buf, int count, const MPI::Datatype& datatype, int source, int tag) const
The blocking semantics of this call are described in Section Communication Modes
.
The receive buffer consists of the storage containing count consecutive elements of the type specified by datatype, starting at address buf. The length of the received message must be less than or equal to the length of the receive buffer. An overflow error occurs if all incoming data does not fit, without truncation, into the receive buffer.
If a message that is shorter than the receive buffer arrives, then only those locations corresponding to the (shorter) message are modified.
Advice to users.
The MPI_PROBE function described in
Section Probe and Cancel
can be used to receive messages of
unknown length.
( End of advice to users.)
Advice
to implementors.
Even though no specific behavior is mandated by MPI for erroneous programs, the recommended handling of overflow situations is to return in status information about the source and tag of the incoming message. The receive operation will return an error code. A quality implementation will also ensure that no memory that is outside the receive buffer will ever be overwritten.
In the case of a message shorter than the receive buffer, MPI is
quite strict in that it allows no modification of the other locations.
A more lenient statement would allow for some
optimizations but this is not allowed. The implementation must be ready to
end a copy into the receiver memory exactly at the end of the receive
buffer, even if it is an odd address.
( End of advice to implementors.)
The selection of a message by a receive operation is governed by
the value of the message envelope.
A message can be received by a receive operation
if its envelope matches the source, tag and
comm values specified by the
receive operation. The receiver may specify a wildcard
MPI_ANY_SOURCE
value for source, and/or
a wildcard MPI_ANY_TAG value for tag,
indicating that any source and/or tag are acceptable. It cannot specify a
wildcard value for comm.
Thus, a message can be received by a receive
operation only if it is addressed
to the receiving process, has a matching communicator, has
matching source unless
source= MPI_ANY_SOURCE
in the pattern, and has a matching tag unless
tag= MPI_ANY_TAG
in the pattern.
The message tag is specified by the tag argument of the
receive operation.
The argument source, if different from MPI_ANY_SOURCE,
is specified as a rank within the process group associated
with that same communicator (remote process group, for intercommunicators).
Thus, the range of valid values for the
source argument is
{0,...,n-1}
{MPI_ANY_SOURCE}, where
n is the number of processes in this group.
Note the asymmetry between send and receive operations: A receive operation may accept messages from an arbitrary sender, on the other hand, a send operation must specify a unique receiver. This matches a ``push'' communication mechanism, where data transfer is effected by the sender (rather than a ``pull'' mechanism, where data transfer is effected by the receiver).
Source = destination is allowed, that is, a process can send a message to itself. (However, it is unsafe to do so with the blocking send and receive operations described above, since this may lead to deadlock. See Section Semantics of Point-to-Point Communication .)
Advice
to implementors.
Message context and other communicator information
can be implemented as an additional tag field. It differs
from the regular message tag in that wild card matching is not allowed on this
field, and that value setting for this field is controlled by communicator
manipulation functions.
( End of advice to implementors.)