.. _mpi_finalize:

MPI_Finalize
============

.. include_body

:ref:`MPI_Finalize` |mdash| Terminates MPI execution environment.

SYNTAX
------

C Syntax
^^^^^^^^

.. code-block:: c

   #include <mpi.h>

   int MPI_Finalize()

Fortran Syntax
^^^^^^^^^^^^^^

.. code-block:: fortran

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

   MPI_FINALIZE(IERROR)
       INTEGER IERROR

Fortran 2008 Syntax
^^^^^^^^^^^^^^^^^^^

.. code-block:: fortran

   USE mpi_f08

   MPI_Finalize(ierror)
       INTEGER, OPTIONAL, INTENT(OUT) :: ierror

OUTPUT PARAMETER
----------------

* ``ierror`` : Fortran only: Error status (integer).

DESCRIPTION
-----------

This routine cleans up all MPI states. Once this routine is called, no
MPI routine (not even MPI_Init) may be called, except for
:ref:`MPI_Get_version`, :ref:`MPI_Initialized`, and :ref:`MPI_Finalized`. Unless there has
been a call to :ref:`MPI_Abort`, you must ensure that all pending
communications involving a process are complete before the process calls
:ref:`MPI_Finalize`. If the call returns, each process may either continue
local computations or exit without participating in further
communication with other processes. At the moment when the last process
calls :ref:`MPI_Finalize`, all pending sends must be matched by a receive, and
all pending receives must be matched by a send.

:ref:`MPI_Finalize` is collective over all connected processes. If no processes
were spawned, accepted, or connected, then this means it is collective
over MPI_COMM_WORLD. Otherwise, it is collective over the union of all
processes that have been and continue to be connected.

NOTES
-----

All processes must call this routine before exiting. All processes will
still exist but may not make any further MPI calls. :ref:`MPI_Finalize`
guarantees that all local actions required by communications the user
has completed will, in fact, occur before it returns. However,
:ref:`MPI_Finalize` guarantees nothing about pending communications that have
not been completed; completion is ensured only by :ref:`MPI_Wait`, :ref:`MPI_Test`, or
:ref:`MPI_Request_free` combined with some other verification of completion.

For example, a successful return from a blocking communication operation
or from :ref:`MPI_Wait` or :ref:`MPI_Test` means that the communication is completed
by the user and the buffer can be reused, but does not guarantee that
the local process has no more work to do. Similarly, a successful return
from :ref:`MPI_Request_free` with a request handle generated by an :ref:`MPI_Isend`
nullifies the handle but does not guarantee that the operation has
completed. The :ref:`MPI_Isend` is complete only when a matching receive has
completed.

If you would like to cause actions to happen when a process finishes,
attach an attribute to MPI_COMM_SELF with a callback function. Then,
when :ref:`MPI_Finalize` is called, it will first execute the equivalent of an
:ref:`MPI_Comm_free` on MPI_COMM_SELF. This will cause the delete callback
function to be executed on all keys associated with MPI_COMM_SELF in an
arbitrary order. If no key has been attached to MPI_COMM_SELF, then no
callback is invoked. This freeing of MPI_COMM_SELF happens before any
other parts of MPI are affected. Calling :ref:`MPI_Finalized` will thus return
"false" in any of these callback functions. Once you have done this with
MPI_COMM_SELF, the results of :ref:`MPI_Finalize` are not specified.

ERRORS
------

.. include:: ./ERRORS.rst

.. seealso:: :ref:`MPI_Init`