NAME

       MPI_Comm_free  - Mark a communicator object for deallocation.

SYNTAX

C Syntax

       #include <mpi.h>
       int MPI_Comm_free(MPI_Comm *comm)

Fortran Syntax

       USE MPI
       ! or the older form: INCLUDE 'mpif.h'
       MPI_COMM_FREE(COMM, IERROR)
            INTEGER   COMM, IERROR

Fortran 2008 Syntax

       USE mpi_f08
       MPI_Comm_free(comm, ierror)
            TYPE(MPI_Comm), INTENT(INOUT) :: comm
            INTEGER, OPTIONAL, INTENT(OUT) :: ierror

C++ Syntax

       #include <mpi.h>
       void Comm::Free()

INPUT PARAMETER

       comm      Communicator to be destroyed (handle).

OUTPUT PARAMETER

       IERROR    Fortran only: Error status (integer).

DESCRIPTION

       This  operation  marks  the  communicator  object  for  deallocation. The handle is set to
       MPI_COMM_NULL. Any pending operations that use this communicator will  complete  normally;
       the  object  is  actually  deallocated only if there are no other active references to it.
       This call applies to intracommunicators and intercommunicators. Upon actual  deallocation,
       the  delete  callback  functions  for  all cached attributes (see Section 5.7 in the MPI-1
       Standard, "Caching") are called in arbitrary order.

NOTES

       Note that it is not defined by the MPI standard what happens  if  the  delete_fn  callback
       invokes other MPI functions.  In Open MPI, it is not valid for delete_fn callbacks (or any
       of their children) to add or delete attributes on the same object on which  the  delete_fn
       callback is being invoked.

ERRORS

       Almost all MPI routines return an error value; C routines as the value of the function and
       Fortran routines in the last argument. C++ functions do not return errors. If the  default
       error  handler  is  set  to  MPI::ERRORS_THROW_EXCEPTIONS, 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   MPI_Comm_set_errhandler;   the   predefined   error    handler
       MPI_ERRORS_RETURN 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

       MPI_Comm_delete_attr