MPI_CANCEL, MPI_Cancel

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

request
     is a communication request (handle) (IN)

IERROR
     is the FORTRAN return code. It is always the last argument.

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

Invalid request

CCL request

Cancel inactive persistent request

MPI Grequest cancel function returned an error

MPI not initialized

MPI already finalized

Related information

     MPI_TEST_CANCELLED
     MPI_WAIT