|IN request||communication request (handle)|
int MPI_Cancel(MPI_Request *request)
TYPE(MPI_Request), INTENT(IN) :: request
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
INTEGER REQUEST, IERROR
A call to MPI_CANCEL marks for cancellation a pending, nonblocking communication operation (send or receive). The cancel call is local. It returns immediately, possibly before the communication is actually cancelled. It is still necessary to call MPI_REQUEST_FREE, MPI_WAIT or MPI_TEST (or any of the derived operations) with the cancelled request as argument after the call to MPI_CANCEL. If a communication is marked for cancellation, then a MPI_WAIT call for that communication is guaranteed to return, irrespective of the activities of other processes (i.e., MPI_WAIT behaves as a local function); similarly if MPI_TEST is repeatedly called in a busy wait loop for a cancelled communication, then MPI_TEST will eventually be successful.
MPI_CANCEL can be used to cancel a communication that uses a persistent request (see Section Persistent Communication Requests ), in the same way it is used for nonpersistent requests. A successful cancellation cancels the active communication, but not the request itself. After the call to MPI_CANCEL and the subsequent call to MPI_WAIT or MPI_TEST, the request becomes inactive and can be activated for a new communication.
The successful cancellation of a buffered send frees the buffer space occupied by the pending message.
Either the cancellation succeeds, or the communication succeeds, but not both. If a send is marked for cancellation, then it must be the case that either the send completes normally, in which case the message sent was received at the destination process, or that the send is successfully cancelled, in which case no part of the message was received at the destination. Then, any matching receive has to be satisfied by another send. If a receive is marked for cancellation, then it must be the case that either the receive completes normally, or that the receive is successfully cancelled, in which case no part of the receive buffer is altered. Then, any matching send has to be satisfied by another receive.
If the operation has been cancelled, then information to that effect will be returned in the status argument of the operation that completes the communication.
Although the IN request handle parameter should not need to be passed
by reference, the C binding has listed the argument type as MPI_Request* since
MPI-1.0. This function signature therefore cannot be changed without breaking
existing MPI applications.
( End of rationale.)
|IN status||status object (Status)|
int MPI_Test_cancelled(const MPI_Status *status, int *flag)
MPI_Test_cancelled(status, flag, ierror)
TYPE(MPI_Status), INTENT(IN) :: status
LOGICAL, INTENT(OUT) :: flag
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
MPI_TEST_CANCELLED(STATUS, FLAG, IERROR)
INTEGER STATUS(MPI_STATUS_SIZE), IERROR
Returns flag = true if the communication associated with the status object was cancelled successfully. In such a case, all other fields of status (such as count or tag) are undefined. Returns flag = false, otherwise. If a receive operation might be cancelled then one should call MPI_TEST_CANCELLED first, to check whether the operation was cancelled, before checking on the other fields of the return status.
Advice to users.
Cancel can be an expensive operation that should be used only exceptionally.
( End of advice to users.)
Advice to implementors.
If a send operation uses an ``eager'' protocol (data is transferred to
before a matching receive is posted), then the cancellation of this send
may require communication with the intended receiver in order to free
buffers. On some systems this may require an interrupt to the
Note that, while communication may be needed to implement
this is still a local operation, since its completion does not
depend on the code executed by other processes. If processing is required on
another process, this should be transparent to the application (hence the need
for an interrupt and an interrupt handler).
( End of advice to implementors.)