Return status

Up: Blocking Send and Receive Operations Next: Data type matching and data conversion Previous: Blocking receive

The source or tag of a received message may not be known if wildcard values were used in the receive operation. 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 two fields named MPI_SOURCE and MPI_TAG, and the structure may contain additional fields. Thus, status.MPI_SOURCE and status.MPI_TAG contain the source and tag, respectively, of the received message.

In Fortran, status is an array of INTEGERs of size MPI_STATUS_SIZE. The two constants MPI_SOURCE and MPI_TAG are the indices of the entries that store the source and tag fields. Thus status(MPI_SOURCE) and status(MPI_TAG) contain, respectively, the source and the tag of the received message.

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.

MPI_GET_COUNT(status, datatype, count)
[ IN status] return status of receive operation (Status)
[ IN datatype] datatype of each receive buffer element (handle)
[ OUT count] number of received elements (integer)

int MPI_Get_count(MPI_Status status, MPI_Datatype datatype, int *count)


Returns the number of elements received. (Again, we count elements, 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.

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 send). 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. ( End of rationale.)
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: Data type matching and data conversion Previous: Blocking receive

Return to MPI Standard Index
Return to MPI home page