These procedures are useful for accessing the information associated with a request, without freeing the request (in case the user is expected to access it later). It allows one to layer libraries more conveniently, since multiple layers of software may access the same completed request and extract from it the status information.
| MPI_REQUEST_GET_STATUS(request, flag, status) | |
| IN request | request (handle) |
| OUT flag | boolean flag, same as from MPI_TEST (logical) |
| OUT status | status object if flag is true (status) |
Sets flag = true if the operation is complete, and, if so, returns in status the request status. However, unlike test or wait, it does not deallocate or inactivate the request; a subsequent call to test, wait or free should be executed with that request. It sets flag = false if the operation is not complete.
One is allowed to call MPI_REQUEST_GET_STATUS with a null or inactive request argument. In such a case the procedure returns with flag = true and empty status.
The progress rule for MPI_TEST, as described in Section Semantics of Nonblocking Communication Operations, also applies to MPI_REQUEST_GET_STATUS.
| MPI_REQUEST_GET_STATUS_ANY(count, array_of_requests, index, flag, status) | |
| IN count | list length (non-negative integer) |
| IN array_of_requests | array of requests (array of handles) |
| OUT index | index of operation that completed or MPI_UNDEFINED if none completed (integer) |
| OUT flag | true if one of the operations is complete (logical) |
| OUT status | status object if flag is true (status) |
Tests for completion of either one or none of the operations associated with active handles. In the former case, it returns flag = true, returns in index the index of this request in the array, and returns in status the status of that operation. (The array is indexed from zero in C, and from one in Fortran.) In the latter case (no operation completed), it returns flag = false, returns a value of MPI_UNDEFINED in index and status is undefined.
The array may contain null or inactive handles. If the array contains no active handles then the call returns immediately with flag = true, index = MPI_UNDEFINED, and an empty status.
If the array of requests contains active handles then the execution of MPI_REQUEST_GET_STATUS_ANY has the same effect as the execution of MPI_REQUEST_GET_STATUS with each of the active array elements in some arbitrary order, until one call returns flag = true, or all return flag = false. In the former case, index is set to indicate which array element returned flag = true and in the latter case, it is set to MPI_UNDEFINED. MPI_REQUEST_GET_STATUS_ANY with an array containing one request is equivalent to MPI_REQUEST_GET_STATUS.
| MPI_REQUEST_GET_STATUS_ALL(count, array_of_requests, flag, array_of_statuses) | |
| IN count | list length (non-negative integer) |
| IN array_of_requests | array of requests (array of handles) |
| OUT flag | true if all of the operations are complete (logical) |
| OUT array_of_statuses | array of status objects (array of status) |
MPI_REQUEST_GET_STATUS_ALL returns flag = true if all communication operations associated with active handles in the array have completed (this includes the case where all handles in the list are inactive or MPI_REQUEST_NULL). In this case, each status entry that corresponds to an active request is set to the status of the corresponding operation. Unlike test or wait, it does not deallocate or inactivate the requests; a subsequent call to test, wait or free should be executed with each of those requests.
Each status entry that corresponds to a null or inactive handle is set to empty.
Otherwise, flag = false is returned and the values of the status entries are undefined.
The progress rule for MPI_TEST, as described in Section Semantics of Nonblocking Communication Operations, also applies to MPI_REQUEST_GET_STATUS_ALL.
| MPI_REQUEST_GET_STATUS_SOME(incount, array_of_requests, outcount, array_of_indices, array_of_statuses) | |
| IN incount | length of array_of_requests (non-negative integer) |
| IN array_of_requests | array of requests (array of handles) |
| OUT outcount | number of completed requests (integer) |
| OUT array_of_indices | array of indices of operations that completed (array of integers) |
| OUT array_of_statuses | array of status objects for operations that completed (array of status) |
MPI_REQUEST_GET_STATUS_SOME returns in outcount the number of requests from the list array_of_requests that have completed. Returns in the first outcount locations of the array array_of_indices the indices of these operations within the array array_of_requests; the array is indexed from zero in C and from one in Fortran. Returns in the first outcount locations of the array array_of_statuses the status for these completed operations. However, unlike test or wait, it does not deallocate or inactivate any requests in array_of_requests; a subsequent call to test, wait or free should be executed with each completed request. If no operation in array_of_requests is complete, it returns outcount = 0. If all operations in array_of_requests are either MPI_REQUEST_NULL or inactive, outcount will be set to MPI_UNDEFINED. The progress rule for MPI_TEST, as described in Section Semantics of Nonblocking Communication Operations, also applies to MPI_REQUEST_GET_STATUS_SOME.
Like MPI_WAITSOME and MPI_TESTSOME,
MPI_REQUEST_GET_STATUS_SOME fulfills a
fairness requirement: If a request for a receive repeatedly
appears in a list of requests passed to MPI_REQUEST_GET_STATUS_SOME,
MPI_WAITSOME, or
MPI_TESTSOME and
a matching send has been started, then the receive
will eventually succeed, unless the send is satisfied by another receive; and
similarly for send requests.
Errors that occur during the execution of MPI_REQUEST_GET_STATUS_SOME are handled as for MPI_WAITSOME.
Advice
to implementors.
MPI_REQUEST_GET_STATUS_SOME should complete as many pending communication operations as
possible.
( End of advice to implementors.)
Advice to users.
MPI_REQUEST_GET_STATUS_ANY, MPI_REQUEST_GET_STATUS_SOME, and MPI_REQUEST_GET_STATUS_ALL
offer tradeoffs between precision and speed, as do the corrsponding TEST and WAIT functions. The ANY variants are fast, but imprecise and unfair.
The ALL variants will provide all-or-nothing information and/or completion, which can limit their applicability. The SOME variants, because
of their precision and fairness guarantee, will typically be the slowest on a per-call basis.
( End of advice to users.)