MPI_CANCEL(3)					     Open MPI					     MPI_CANCEL(3)

MPI_Cancel — Cancels a communication request.

SYNTAX
   C Syntax
	  #include <mpi.h>

	  int MPI_Cancel(MPI_Request *request)

   Fortran Syntax
	  USE MPI
	  ! or the older form: INCLUDE 'mpif.h'

	  MPI_CANCEL(REQUEST, IERROR)
	      INTEGER REQUEST, IERROR

   Fortran 2008 Syntax
	  USE mpi_f08

	  MPI_Cancel(request, ierror)
	      TYPE(MPI_Request), INTENT(IN) :: request
	      INTEGER, OPTIONAL, INTENT(OUT) :: ierror

INPUT PARAMETER
       • request : Communication request (handle).

OUTPUT PARAMETER
       • ierror : Fortran only: Error status (integer).

DESCRIPTION
       The  MPI_Cancel	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 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
       canceled. It is still necessary to complete a communication that has been marked for cancellation, using	 a
       call  to MPI_Request_free <#mpi-request-free>, MPI_Wait <#mpi-wait>, or MPI_Test <#mpi-test> (or any of the
       derived operations).

       If a communication is marked for cancellation, then an MPI_Wait <#mpi-wait> call for that communication	is
       guaranteed to return, irrespective of the activities of other processes (i.e., MPI_Wait <#mpi-wait> behaves
       as  a  local  function);	 similarly  if MPI_Test <#mpi-test> is repeatedly called in a busy wait loop for a
       canceled communication, then MPI_Test <#mpi-test> will eventually be successful.

       MPI_Cancel can be used to cancel a communication that uses a persistent request (see Section 3.9 in the MPI
       Standard <https://www.mpi-forum.org/docs/>, “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  <#mpi-wait>  or  MPI_Test	<#
       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  is	 received  at the destination process, or that the send is successfully 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 successfully 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.

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

ERRORS
       Almost  all MPI routines return an error value; C routines as the return result of the function and Fortran
       routines in the last argument.

       Before the error value is returned, the current MPI error handler associated with the communication  object
       (e.g.,  communicator, window, file) is called.  If no communication object is associated with the MPI call,
       then the call is considered attached to MPI_COMM_SELF and will call the associated MPI error handler.  When
       MPI_COMM_SELF  is  not  initialized  (i.e., before MPI_Init <#mpi-init>/MPI_Init_thread <#mpi-init-thread>,
       after MPI_Finalize <#mpi-finalize>, or when using the Sessions Model  exclusively)  the	error  raises  the
       initial	error  handler.	 The  initial  error  handler can be changed by calling MPI_Comm_set_errhandler <#
       mpi-comm-set-errhandler> on MPI_COMM_SELF when using the World model,  or  the  mpi_initial_errhandler  CLI
       argument	  to   mpiexec	 or   info  key	 to  MPI_Comm_spawn  <#mpi-comm-spawn>/MPI_Comm_spawn_multiple	<#
       mpi-comm-spawn-multiple>.  If no other appropriate error handler has been set, then  the	 MPI_ERRORS_RETURN
       error  handler  is  called  for	MPI I/O functions and the MPI_ERRORS_ABORT error handler is called for all
       other MPI functions.

       Open MPI includes three predefined error handlers that can be used:

       • MPI_ERRORS_ARE_FATAL Causes the program to abort all connected MPI processes.

       • MPI_ERRORS_ABORT An error handler that can be invoked on a communicator, window, file, or  session.  When
	 called on a communicator, it acts as if MPI_Abort <#mpi-abort> was called on that communicator. If called
	 on  a window or file, acts as if MPI_Abort <#mpi-abort> was called on a communicator containing the group
	 of processes in the corresponding window or file. If called on a session, aborts only the local process.

       • MPI_ERRORS_RETURN Returns an error code to the application.

       MPI applications can also implement their own error handlers by calling:

       • MPI_Comm_create_errhandler	<#mpi-comm-create-errhandler>	  then	   MPI_Comm_set_errhandler	<#
	 mpi-comm-set-errhandler>

       • MPI_File_create_errhandler	 <#mpi-file-create-errhandler>	   then	    MPI_File_set_errhandler	<#
	 mpi-file-set-errhandler>

       • MPI_Session_create_errhandler	 <#mpi-session-create-errhandler>   then   MPI_Session_set_errhandler	<#
	 mpi-session-set-errhandler> or at MPI_Session_init <#mpi-session-init>

       • MPI_Win_create_errhandler	<#mpi-win-create-errhandler>	  then	    MPI_Win_set_errhandler	<#
	 mpi-win-set-errhandler>

       Note that MPI does not guarantee that an MPI program can continue past an error.

       See the MPI man page <#open-mpi> for a full list of MPI error codes <#open-mpi-errors>.

       See the Error Handling section of the MPI-3.1 standard for more information.

       See also:

	  • MPI_Probe <#mpi-probe>

Copyright
       2003-2026, The Open MPI Community

						   Mar 05, 2026					     MPI_CANCEL(3)
