MPI supports several different types of requests besides those for point-to-point operations. These range from MPI calls for I/O to generalized requests. It is desirable to allow these calls to use the same request mechanism, which allows one to wait or test on different types of requests. However, MPI_{TEST|WAIT}{ANY|SOME|ALL} returns a status with information about the request. With the generalization of requests, one needs to define what information will be returned in the status object.
Each MPI call fills in the appropriate fields in the status object. Any unused fields will have undefined values. A call to MPI_{TEST|WAIT}{ANY|SOME|ALL} can modify any of the fields in the status object. Specifically, it can modify fields that are undefined. The fields with meaningful values for a given request are defined in the sections with the new request.
Generalized requests raise additional considerations. Here, the user provides the functions to deal with the request. Unlike other MPI calls, the user needs to provide the information to be returned in the status. The status argument is provided directly to the callback function where the status needs to be set. Users can directly set the values in 3 of the 5 status values. The count and cancel fields are opaque. To overcome this, these calls are provided:
| MPI_STATUS_SET_ELEMENTS(status, datatype, count) | |
| INOUT status | status with which to associate count (status) |
| IN datatype | datatype associated with count (handle) |
| IN count | number of elements to associate with status (integer) |
This procedure modifies the opaque part of status so calls to MPI_GET_ELEMENTS will return count. Calls to MPI_GET_COUNT will return a compatible value.
Rationale.
The number of elements is set instead of the count because the former
can deal with
a
non-integer number of datatypes.
( End of rationale.)
A subsequent call to MPI_GET_COUNT or MPI_GET_ELEMENTS must use a
datatype argument that has the same type signature as the
datatype argument that was used in the call to
MPI_STATUS_SET_ELEMENTS.
Rationale.
The requirement of matching type signatures for these calls is similar to the restriction that holds
when
count is set by a
receive operation: in that case, calls to
MPI_GET_COUNT and MPI_GET_ELEMENTS must use a
datatype with the same signature as the datatype used in the
receive call.
( End of rationale.)
| MPI_STATUS_SET_CANCELLED(status, flag) | |
| INOUT status | status with which to associate cancel flag (status) |
| IN flag | if true, indicates request was cancelled (logical) |
If flag is set to true then a subsequent call to MPI_TEST_CANCELLED will also return flag = true, otherwise it will return false.
Advice to users.
Users are advised not to reuse the status fields for values other than
those for which they were intended. Doing so may lead to unexpected
results when using the status object. For example, calling
MPI_GET_ELEMENTS may cause an error if the value is
out of range or it may be impossible to detect such an error. The
extra_state argument provided with a generalized request can
be used to return information that does not logically belong in
status.
Furthermore, modifying the values in a status set internally by MPI,
e.g., MPI_RECV, may lead to unpredictable results and is
strongly discouraged.
( End of advice to users.)
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
modify them via the procedure calls described below.
Procedures for querying these fields from a
status object are defined in Section Return Status.
| MPI_STATUS_SET_SOURCE(status, source) | |
| INOUT status | status with which to associate source rank (status) |
| IN source | rank to set in the MPI_SOURCE field (integer) |
Set the MPI_SOURCE field in the status object to the provided source argument.
| MPI_STATUS_SET_TAG(status, tag) | |
| INOUT status | status with which to associate tag (status) |
| IN tag | tag to set in the MPI_TAG field (integer) |
Set the MPI_TAG field in the status object to the provided tag argument.
| MPI_STATUS_SET_ERROR(status, err) | |
| INOUT status | status with which to associate error (status) |
| IN err | error to set in the MPI_ERROR field (integer) |
Set the MPI_ERROR field in the status object to the provided err error code.
Rationale.
These functions exist for convenience when using MPI from languages
other than C and Fortran, where having a function in the MPI library
with a known API reduces the need for utility code written in C.
( End of rationale.)