MPICancel(3OpenMPI) MPICancel(3OpenMPI)

NAME
       MMPPIICCaanncceell - Cancels a communication request.


SSYYNNTTAAXX
CC SSyynnttaaxx
       #include 
       int MPICancel(MPIRequest *request)


FFoorrttrraann SSyynnttaaxx
       INCLUDE 'mpif.h'
       MPICANCEL(REQUEST, IERROR)
            INTEGER   REQUEST, IERROR


CC++++ SSyynnttaaxx
       #include 
       void Request::Cancel() const


IINNPPUUTT PPAARRAAMMEETTEERR
       request   Communication request (handle).


OOUUTTPPUUTT PPAARRAAMMEETTEERR
       IERROR    Fortran only: Error status (integer).


DESCRIPTION
       The  MPICancel operation allows pending communications to be canceled.
       This is required for cleanup. Posting a send or a receive ties up  user
       resources (send or receive buffers), and a cancel may be needed to free
       these resources gracefully.

       A call to MPICancel marks for cancellation a pending, nonblocking com-
       munication  operation  (send  or receive). The cancel call is local. It
       returns immediately, possibly before the communication is actually can-
       celed.  It is still necessary to complete a communication that has been
       marked for cancellation, using a call to MPIRequestfree, MPIWait, or
       MPITest (or any of the derived operations).

       If  a  communication  is marked for cancellation, then an MPIWait call
       for that communication is guaranteed to  return,  irrespective  of  the
       activities  of other processes (i.e., MPIWait behaves as a local func-
       tion); similarly if MPITest is repeatedly called in a busy  wait  loop
       for a canceled communication, then MPITest will eventually be success-
       ful.

       MPICancel can be used to cancel a communication that uses a persistent
       request  (see Section 3.9 in the MPI-1 Standard, "Persistent Communica-
       tion 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 MPICancel and the subsequent call to
       MPIWait or MPITest, 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
       is received at the destination process, or that the  send  is  success-
       fully canceled, in which case no part of the message is 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 suc-
       cessfully  canceled,  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 canceled, then information to that effect
       will be returned in the status argument of the operation that completes
       the communication.


NNOOTTEESS
       The  primary  expected use of MPICancel is in multi-buffering schemes,
       where speculative MPIIrecvs are made.  When the computation completes,
       some  of these requests may remain; using MPICancel allows the user to
       cancel these unsatisfied requests.


EERRRROORRSS
       Almost all MPI routines return an error value; C routines as the  value
       of  the  function  and Fortran routines in the last argument. C++ func-
       tions do not return errors. If the default  error  handler  is  set  to
       MPI::ERRORSTHROWEXCEPTIONS, then on error the C++ exception mechanism
       will be used to throw an MPI:Exception object.

       Before the error value is returned, the current MPI  error  handler  is
       called.  By  default, this error handler aborts the MPI job, except for
       I/O  function  errors.  The  error  handler   may   be   changed   with
       MPICommseterrhandler; the predefined error handler MPIERRORSRETURN
       may be used to cause error values to be returned. Note  that  MPI  does
       not guarantee that an MPI program can continue past an error.


SEE ALSO
       MPIProbe
       MPIIprobe
       MPITestcancelled
       MPICartcoords




Open MPI 1.2                    September 2006            MPICancel(3OpenMPI)