Purpose
Marks a nonblocking request for cancellation.
C synopsis
#include <mpi.h> int MPI_Cancel(MPI_Request *request);
C++ synopsis
#include mpi.h void MPI::Request::Cancel(void) const;
FORTRAN synopsis
include 'mpif.h' or use mpi MPI_CANCEL(INTEGER REQUEST,INTEGER IERROR)
Parameters
Description
This subroutine marks a nonblocking request for cancellation. The cancel call is local. It returns immediately; it can return even before the communication is actually cancelled. It is necessary to complete an operation marked for cancellation by using a call to MPI_WAIT or MPI_TEST (or any other wait or test call).
You can use MPI_CANCEL to cancel a persistent request 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. It is erroneous to cancel an inactive persistent request.
The successful cancellation of a buffered send frees the buffer space occupied by the pending message.
Either the cancellation succeeds or the operation succeeds, but not both. If a send is marked for cancellation, either the send completes normally, in which case the message sent was received at the destination task, or 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 the receive completes normally or 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 successfully, information to that effect is returned in the status argument of the operation that completes the communication, and may be retrieved by a call to MPI_TEST_CANCELLED.
Notes
Nonblocking collective communication requests cannot be cancelled. MPI_CANCEL may be called on non-blocking file operation requests. The eventual call to MPI_TEST_CANCELLED will show that the cancellation did not succeed.
Errors
Related information