@@ -5,7 +5,7 @@ MPI_Finalize
55
66.. include_body
77
8- :ref: `MPI_Finalize ` |mdash | Terminates MPI execution environment .
8+ :ref: `MPI_Finalize ` |mdash | Terminates MPI world model .
99
1010SYNTAX
1111------
@@ -48,56 +48,82 @@ OUTPUT PARAMETER
4848DESCRIPTION
4949-----------
5050
51- This routine cleans up all MPI states. Once this routine is called, no
52- MPI routine (not even MPI_Init) may be called, except for
53- :ref: `MPI_Get_version `, :ref: `MPI_Initialized `, and :ref: `MPI_Finalized `. Unless there has
54- been a call to :ref: `MPI_Abort `, you must ensure that all pending
55- communications involving a process are complete before the process calls
56- :ref: `MPI_Finalize `. If the call returns, each process may either continue
57- local computations or exit without participating in further
58- communication with other processes. At the moment when the last process
59- calls :ref: `MPI_Finalize `, all pending sends must be matched by a receive, and
60- all pending receives must be matched by a send.
61-
62- :ref: `MPI_Finalize ` is collective over all connected processes. If no processes
63- were spawned, accepted, or connected, then this means it is collective
64- over MPI_COMM_WORLD. Otherwise, it is collective over the union of all
65- processes that have been and continue to be connected.
51+ This routine finalizes the MPI world model. If the MPI world model
52+ has been initialized in an MPI process, it *must * be finalized exactly
53+ once by invoking this routine during the lifetime of that MPI process.
54+ This is different than the MPI session model, which can be initialized
55+ and finalized multiple times in an MPI process. See
56+ :ref: `MPI_Session_init ` and :ref: `MPI_Session_finalize `.
57+
58+ Unless there has been a call to :ref: `MPI_Abort `, you must
59+ ensure that all pending communications in the MPI world model
60+ involving a process are complete before the process calls
61+ :ref: `MPI_Finalize `. If the call returns, each process may either
62+ continue local computations or exit without participating in further
63+ communication with other processes in the MPI world model. At the
64+ moment when the last process calls :ref: `MPI_Finalize `, all pending
65+ sends in the MPI world model must be matched by a receive, and all
66+ pending receives in the MPI world model must be matched by a send.
67+
68+ See `MPI-5.0:11.4.1 <https://www.mpi-forum.org/ >`_ for a list of MPI
69+ functionality that is available (e.g., even when the MPI
70+ world model has not yet initialized or has already been finalized).
71+
72+ :ref: `MPI_Finalize ` is collective over all connected processes. If no
73+ processes were spawned, accepted, or connected, then this means it is
74+ collective over ``MPI_COMM_WORLD ``. Otherwise, it is collective over
75+ the union of all processes that have been and continue to be
76+ connected.
6677
6778NOTES
6879-----
6980
70- All processes must call this routine before exiting. All processes will
71- still exist but may not make any further MPI calls. :ref: `MPI_Finalize `
72- guarantees that all local actions required by communications the user
73- has completed will, in fact, occur before it returns. However,
74- :ref: `MPI_Finalize ` guarantees nothing about pending communications that have
75- not been completed; completion is ensured only by :ref: `MPI_Wait `, :ref: `MPI_Test `, or
76- :ref: `MPI_Request_free ` combined with some other verification of completion.
77-
78- For example, a successful return from a blocking communication operation
79- or from :ref: `MPI_Wait ` or :ref: `MPI_Test ` means that the communication is completed
80- by the user and the buffer can be reused, but does not guarantee that
81- the local process has no more work to do. Similarly, a successful return
82- from :ref: `MPI_Request_free ` with a request handle generated by an :ref: `MPI_Isend `
83- nullifies the handle but does not guarantee that the operation has
84- completed. The :ref: `MPI_Isend ` is complete only when a matching receive has
85- completed.
86-
87- If you would like to cause actions to happen when a process finishes,
88- attach an attribute to MPI_COMM_SELF with a callback function. Then,
89- when :ref: `MPI_Finalize ` is called, it will first execute the equivalent of an
90- :ref: `MPI_Comm_free ` on MPI_COMM_SELF. This will cause the delete callback
91- function to be executed on all keys associated with MPI_COMM_SELF in an
92- arbitrary order. If no key has been attached to MPI_COMM_SELF, then no
93- callback is invoked. This freeing of MPI_COMM_SELF happens before any
94- other parts of MPI are affected. Calling :ref: `MPI_Finalized ` will thus return
95- "false" in any of these callback functions. Once you have done this with
96- MPI_COMM_SELF, the results of :ref: `MPI_Finalize ` are not specified.
81+ The MPI session model is different than the MPI world model, and has
82+ different scopes of availability for MPI functionality. See
83+ :ref: `MPI_Session_init ` and :ref: `MPI_Session_finalize `.
84+
85+ All processes that initialized the MPI world model must call this
86+ routine before exiting. All processes will still exist but may not
87+ make any further MPI calls in the MPI world model. :ref: `MPI_Finalize `
88+ guarantees that all local actions required by communications in the
89+ MPI world model that the user has completed will, in fact, occur
90+ before it returns. However, :ref: `MPI_Finalize ` guarantees nothing
91+ about pending communications in the MPI world model that have not been
92+ completed; completion is ensured only by the :ref: `MPI_Wait ` and
93+ :ref: `MPI_Test ` variants, or :ref: `MPI_Request_free ` combined with
94+ some other verification of completion.
95+
96+ For example, a successful return from a blocking communication
97+ operation or from one of the :ref: `MPI_Wait ` or :ref: `MPI_Test `
98+ varients means that the communication is completed by the user and the
99+ buffer can be reused, but does not guarantee that the local process
100+ has no more work to do. Similarly, a successful return from
101+ :ref: `MPI_Request_free ` with a request handle generated by an
102+ :ref: `MPI_Isend ` nullifies the handle but does not guarantee that the
103+ operation has completed. The :ref: `MPI_Isend ` is complete only when a
104+ matching receive has completed.
105+
106+ If you would like to cause actions to happen when a process finalizes the MPI
107+ world model, attach an attribute to ``MPI_COMM_SELF `` with a callback
108+ function. Then, when :ref: `MPI_Finalize ` is called, it will first
109+ execute the equivalent of an :ref: `MPI_Comm_free ` on
110+ ``MPI_COMM_SELF ``. This will cause the delete callback function to be
111+ executed on all keys associated with ``MPI_COMM_SELF `` in an arbitrary
112+ order. If no key has been attached to ``MPI_COMM_SELF ``, then no
113+ callback is invoked. This freeing of ``MPI_COMM_SELF `` happens before
114+ any other parts of the MPI world model are affected. Calling
115+ :ref: `MPI_Finalized ` will thus return ``false `` in any of these
116+ callback functions. Once you have done this with ``MPI_COMM_SELF ``,
117+ the results of :ref: `MPI_Finalize ` are not specified.
97118
98119ERRORS
99120------
100121
101122.. include :: ./ERRORS.rst
102123
103- .. seealso :: :ref:`MPI_Init`
124+ .. seealso ::
125+ * :ref: `MPI_Finalized `
126+ * :ref: `MPI_Init `
127+ * :ref: `MPI_Initialized `
128+ * :ref: `MPI_Session_init `
129+ * :ref: `MPI_Session_finalize `
0 commit comments