4.2.5. Return Status

PreviousUpNext
Up: Blocking Send and Receive Operations Next: Passing MPI_STATUS_IGNORE for Status Previous: Blocking Receive

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 with USE mpi or (deprecated) INCLUDE 'mpif.h', 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.

With Fortran USE mpi_f08, status is defined as the Fortran BIND(C) derived type TYPE(MPI_Status) containing three public INTEGER fields named MPI_SOURCE, MPI_TAG, and MPI_ERROR. TYPE(MPI_Status) may contain additional, implementation-specific fields. Thus, status%MPI_SOURCE, status%MPI_TAG, and status%MPI_ERROR contain the source, tag, and error code of a received message respectively. Additionally, within both the mpi and the mpi_f08 modules, the constants MPI_STATUS_SIZE, MPI_SOURCE, MPI_TAG, MPI_ERROR, and TYPE(MPI_Status) are defined to allow conversion between both status representations. Conversion routines are provided in Section Status.


Rationale.

The Fortran TYPE(MPI_Status) is defined as a BIND(C) derived type so that it can be used at any location where the status integer array representation can be used, e.g., in user defined common blocks. ( End of rationale.)

Rationale.

It is allowed to have the same name (e.g., MPI_SOURCE) defined as a constant (e.g., Fortran parameter) and as a field of a derived type. ( End of rationale.)
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 that return multiple statuses. The field is updated if and only if such function returns with an error code of MPI_ERR_IN_STATUS.


Rationale.

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.

MPI_GET_COUNT(status, datatype, count)
IN statusreturn status of receive operation (status)
IN datatypedatatype of each receive buffer entry (handle)
OUT countnumber of received entries (integer)
C binding
int MPI_Get_count(const MPI_Status *status, MPI_Datatype datatype, int *count)
int MPI_Get_count_c(const MPI_Status *status, MPI_Datatype datatype, MPI_Count *count)
Fortran 2008 binding
MPI_Get_count(status, datatype, count, ierror)

TYPE(MPI_Status), INTENT(IN) :: status
TYPE(MPI_Datatype), INTENT(IN) :: datatype
INTEGER, INTENT(OUT) :: count
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
MPI_Get_count(status, datatype, count, ierror) !(_c)

TYPE(MPI_Status), INTENT(IN) :: status
TYPE(MPI_Datatype), INTENT(IN) :: datatype
INTEGER(KIND=MPI_COUNT_KIND), INTENT(OUT) :: count
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_GET_COUNT(STATUS, DATATYPE, COUNT, IERROR)

INTEGER STATUS(MPI_STATUS_SIZE), DATATYPE, COUNT, IERROR

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. If the number of entries received exceeds the limits of the count parameter, then MPI_GET_COUNT sets the value of count to MPI_UNDEFINED. There are other situations where the value of count can be set to MPI_UNDEFINED; see Section Use of General Datatypes in Communication.


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 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.)
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 transferred is greater than zero, MPI_UNDEFINED is returned.


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.)

Advice to users.

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.)
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 procedures described in this section.

While the MPI_SOURCE, MPI_TAG, and MPI_ERROR status values are directly accessible by the user, for convenience in some contexts, users can also access them via procedure calls, as described below.

MPI_STATUS_GET_SOURCE(status, source)
IN statusstatus from which to retrieve source rank (status)
OUT sourcerank set in the MPI_SOURCE field (integer)
C binding
int MPI_Status_get_source(MPI_Status *status, int *source)
Fortran 2008 binding
MPI_Status_get_source(status, source, ierror)

TYPE(MPI_Status), INTENT(IN) :: status
INTEGER, INTENT(OUT) :: source
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_STATUS_GET_SOURCE(STATUS, SOURCE, IERROR)

INTEGER STATUS(MPI_STATUS_SIZE), SOURCE, IERROR

Returns in source the value of the MPI_SOURCE field in the status object.

MPI_STATUS_GET_TAG(status, tag)
IN statusstatus from which to retrieve tag (status)
OUT tagtag set in the MPI_TAG field (integer)
C binding
int MPI_Status_get_tag(MPI_Status *status, int *tag)
Fortran 2008 binding
MPI_Status_get_tag(status, tag, ierror)

TYPE(MPI_Status), INTENT(IN) :: status
INTEGER, INTENT(OUT) :: tag
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_STATUS_GET_TAG(STATUS, TAG, IERROR)

INTEGER STATUS(MPI_STATUS_SIZE), TAG, IERROR

Returns in tag the value in the MPI_TAG field of the status object.

MPI_STATUS_GET_ERROR(status, err)
IN statusstatus from which to retrieve error (status)
OUT errerror set in the MPI_ERROR field (integer)
C binding
int MPI_Status_get_error(MPI_Status *status, int *err)
Fortran 2008 binding
MPI_Status_get_error(status, err, ierror)

TYPE(MPI_Status), INTENT(IN) :: status
INTEGER, INTENT(OUT) :: err
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_STATUS_GET_ERROR(STATUS, ERR, IERROR)

INTEGER STATUS(MPI_STATUS_SIZE), ERR, IERROR

Returns in err the value in the MPI_ERROR field of the status object.

Procedures for setting these fields in a status object are defined in Section Associating Information with Status.


PreviousUpNext
Up: Blocking Send and Receive Operations Next: Passing MPI_STATUS_IGNORE for Status Previous: Blocking Receive


Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023