The source or tag of a received message may not be known if wildcard values were used in the receive operation. Also, if multiple requests are completed by a single MPI function (see Section Multiple Completions ), a distinct error code may need to be returned for each request. The information is returned by the status argument of MPI_RECV. The type of status is MPI-defined. Status variables need to be explicitly allocated by the user, that is, they are not system objects.
In C, status is a structure that contains three fields named MPI_SOURCE, MPI_TAG, and MPI_ERROR; the structure may contain additional fields. Thus, status.MPI_SOURCE, status.MPI_TAG and status.MPI_ERROR contain the source, tag, and error code, respectively, of the received message.
In Fortran, status is an array of INTEGERs of size MPI_STATUS_SIZE. The constants MPI_SOURCE, MPI_TAG and MPI_ERROR are the indices of the entries that store the source, tag and error fields. Thus, status(MPI_SOURCE), status(MPI_TAG) and status(MPI_ERROR) contain, respectively, the source, tag and error code of the received message.
In C++, the status object is handled through the following methods:
{ int MPI::Status::Get_source() const (binding deprecated, see Section Deprecated since MPI-2.2
) }
The error field in status is not needed for calls that return only one
status, such as MPI_WAIT, since that would only duplicate the
information returned by the function itself. The current design
avoids the additional overhead of setting it, in such cases. The field
is needed for calls that return multiple statuses, since each request
may have had a different failure.
( End of rationale.)
The status argument also returns information on the length of the message
received. However, this information is not directly available as a field
of the status variable and a call to MPI_GET_COUNT is required
to ``decode'' this information.
int MPI_Get_count(MPI_Status *status, MPI_Datatype datatype, int *count)
MPI_GET_COUNT(STATUS, DATATYPE, COUNT, IERROR)
Some message-passing libraries use INOUT count,
tag and source arguments, thus using them both to specify
the selection criteria for incoming messages and return the actual envelope
values of the received message.
The use of a separate status argument prevents errors that are often attached
with INOUT argument (e.g., using the
MPI_ANY_TAG constant as
the tag in a receive).
Some libraries use calls that refer implicitly to the ``last message
received.'' This is not thread safe.
The datatype argument is passed to MPI_GET_COUNT so as to
improve performance. A message might be received without counting the number
of elements it contains, and the count value is often not needed.
Also, this allows the same function to be used after a call to
MPI_PROBE or MPI_IPROBE. With a status from MPI_PROBE or MPI_IPROBE,
the same datatypes are allowed as in a call to MPI_RECV to receive this message.
( End of rationale.)
Zero-length datatypes may be created in a number of cases.
An important case is
MPI_TYPE_CREATE_DARRAY, where the
definition of the particular
darray
results in an empty block on some
MPI process. Programs written in an SPMD style will not check for
this special case and may want to use MPI_GET_COUNT to check
the status.
( End of rationale.)
The buffer size required for the receive can be affected by data conversions and
by the stride of the receive datatype.
In most cases, the safest approach is to use the same datatype with MPI_GET_COUNT and the receive.
( End of advice to users.)
{ void MPI::Status::Set_source(int source) (binding deprecated, see Section Deprecated since MPI-2.2
) }
{ int MPI::Status::Get_tag() const (binding deprecated, see Section Deprecated since MPI-2.2
) }
{ void MPI::Status::Set_tag(int tag) (binding deprecated, see Section Deprecated since MPI-2.2
) }
{ int MPI::Status::Get_error() const (binding deprecated, see Section Deprecated since MPI-2.2
) }
{ void MPI::Status::Set_error(int error) (binding deprecated, see Section Deprecated since MPI-2.2
) }
In general, message-passing calls do not modify the value of the error
code field of status variables. This field may be updated only by
the functions in Section Multiple Completions
which return multiple
statuses. The field is updated if and only if such function returns with
an error code of MPI_ERR_IN_STATUS.
Rationale.
MPI_GET_COUNT(status, datatype, count) IN status return status of receive operation (Status) IN datatype datatype of each receive buffer entry (handle) OUT count number of received entries (integer)
INTEGER STATUS(MPI_STATUS_SIZE), DATATYPE, COUNT, IERROR
{ int MPI::Status::Get_count(const MPI::Datatype& datatype) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
Returns the number of entries received. (Again, we count entries, each of
type datatype, not bytes.)
The datatype argument should match
the argument provided by the receive call that set the status variable.
(We shall later see, in Section Use of General Datatypes in Communication
, that
MPI_GET_COUNT may return, in certain situations, the value
MPI_UNDEFINED.)
Rationale.
The value returned as the count argument of
MPI_GET_COUNT for a datatype of length zero where zero bytes
have been transferred is zero. If the number of bytes transfered is
greater than zero, MPI_UNDEFINED is returned.
Rationale.
Advice to users.
All send and receive operations use the buf, count,
datatype, source, dest, tag,
comm and status arguments in the same way as the blocking
MPI_SEND and
MPI_RECV operations described in this section.
Up: Blocking Send and Receive Operations
Next: Passing MPI_STATUS_IGNORE for Status
Previous: Blocking Receive
Return to MPI-2.2 Standard Index
Return to MPI Forum Home Page
(Unofficial) MPI-2.2 of September 4, 2009
HTML Generated on September 10, 2009