4.8.4. Cancel

A call to MPI_CANCEL marks for cancellation a pending, nonblockingcommunication operation (send or receive). Cancelling a send request by calling MPI_CANCEL is deprecated. 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 procedures) 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 MPI processes (i.e., MPI_WAIT behaves as a local function); similarly if MPI_TEST is repeatedly called for a cancelled communication, then MPI_TEST will eventually return flag = true.

MPI_CANCEL can be used to cancel a communication that uses a persistent communication request (see Section Persistent Communication Requests), in the same way as it is described above for nonblocking operations. Cancelling a persistent send request by calling MPI_CANCEL is deprecated. 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 mode send frees the buffer space occupied by the pending message. Cancelling a buffered mode send request by calling MPI_CANCEL is deprecated.

Either the cancellation succeeds, or the communication succeeds, but not both. If a send is marked for cancellation, which is deprecated, then it must be the case that either the send completes normally, in which case the message sent was received at the destination, 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.

Rationale.

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

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 the receiver before a matching receive is started), then the cancellation of this send may require communication with the intended receiver in order to free allocated buffers. On some systems this may require an interrupt to the intended receiver. Note that, while communication may be needed to implement MPI_CANCEL, this is still a local procedure, since its completion does not depend on the code executed by other MPI processes. If processing is required on another MPI process, this should be transparent to the application (hence the need for an interrupt and an interrupt handler). See also Section Progress on progress. ( End of advice to implementors.)