Skip to content

Commit 2d024ce

Browse files
edgargabrieledgargabriel
authored
Merge pull request #11825 from edgargabriel/topic/docs-deprecated-funcs
docs: update list of deprecated/removed functions
2 parents a8fbb4d + 30ec7e1 commit 2d024ce

File tree

4 files changed

+325
-35
lines changed

4 files changed

+325
-35
lines changed

‎docs/building-apps/abi-compatibility.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.. _label-binary-compatibility:
2+
3+
ABI compatibility to previous versions of Open MPI
4+
==================================================
5+
6+
The Open MPI |ompi_series| series maintains Application Binary Interface (ABI)
7+
compatibility for the C MPI bindings to the last major Open MPI release. Specifically, an
8+
application compiled with Open MPI v4.x can be executed with Open MPI
9+
|ompi_series| without having to recompile the application.
10+
11+
.. important:: ABI is maintained for *most* of the Fortran MPI bindings, too -- see below for additional information.
12+
13+
There are however a few scenarios where an application compiled with
14+
Open MPI v4.x might not execute correctly with Open MPI 5.0.
15+
16+
- Fortran compilers provide varying degrees of ABI guarantees between
17+
their releases. As such, Open MPI can only provide ABI guarantees
18+
with MPI applications that use the Fortran MPI bindings when all
19+
three entities |mdash| Open MPI v4.x, Open MPI |ompi_series|, and
20+
the MPI application |mdash| were built with exactly the same Fortran
21+
compiler and environment.
22+
23+
If these conditions are met, Open MPI's ABI guarantees between the
24+
Open MPI v4.x and |ompi_series| series are in effect, with the
25+
exception of the following cases:
26+
27+
* When using the Fortran ``mpi`` module bindings with GCC compiler
28+
versions prior to v4.8, non-compliant Fortran interfaces for
29+
``MPI_Comm_spawn_multiple``, ``MPI_Testall``, ``MPI_Testsome``,
30+
``MPI_Waitall``, and ``MPI_Waitsome`` were removed starting with
31+
Open MPI v5.0.0.
32+
33+
* When using the Fortran ``mpi`` module with modern Fortran
34+
compilers (e.g., GNU Fortran >= v4.9), Open MPI v5.0.0 removed the
35+
names from the MPI interfaces when there is only a single
36+
subroutine in the interface, and that subroutine name exactly
37+
matches the iterface name. This change is likely to make Open MPI
38+
|ompi_series|'s ``mpi`` module bindings *less* restrictive than
39+
Open MPI v4.x, but it *may* also have ABI implications, depending
40+
on your Fortran compiler.
41+
42+
`See this git commit message
43+
<https://github.com/open-mpi/ompi/commit/f34782fe0c493963ec44bcf7dde9d94b88a7ea91>`_
44+
for more details.
45+
46+
.. important:: This is likely a compiler-specific issue, and may
47+
need to be tested in your environment.
48+
49+
* When using the Fortran ``mpi_f08`` module bindings in an
50+
environment where a Fortran ``INTEGER`` is 8 bytes but a C ``int``
51+
is 4 bytes, the size of a ``Type(MPI_Status)`` was increased
52+
starting with Open MPI v5.0.0.
53+
54+
- Open MPI v5.0.0 removed support for the MPI C++ bindings. If an application
55+
was using the deprecated and now removed C++ bindings, it will not
56+
be able to compile or execute with Open MPI v5.0.0. For details on deprecated and
57+
removed functions see :ref:`Removed MPI constructs
58+
<label-removed-mpi-constructs>` and :ref:`Deprecation warnings
59+
<label-deprecated-functions>`

‎docs/building-apps/deprecation-warnings.rst‎

Lines changed: 238 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1+
.. _label-deprecated-functions:
2+
13
Deprecation warnings while compiling MPI applications
24
=====================================================
35

46
If you see deprecation warnings when compiling MPI applications, it is
57
because your application is symbols / functions that are deprecated in
6-
MPI. For example:
8+
MPI. For example:
79

810
.. code-block:: sh
911
@@ -25,16 +27,240 @@ advises you to use ``MPI_Comm_delete_attr()`` instead of
2527
Also, note that even if Open MPI was configured with
2628
``--enable-mpi1-compatibility`` to re-enable removed MPI-1 symbols,
2729
you will still get compiler warnings when you use the removed symbols.
28-
For example:
2930

30-
.. code-block:: sh
31+
The following is a list of functions that have been deprecated in MPI,
32+
and the function that is replacing them. Some functions have been
33+
deprecated and removed from the MPI specification, these functions are
34+
listed :ref:`here <label-removed-mpi-constructs>`.
35+
36+
.. list-table::
37+
:header-rows: 1
38+
39+
* - Deprecated symbol
40+
41+
(click for more details, below)
42+
- Replaced with
43+
44+
(click to go to the corresponding man page)
45+
- MPI version deprecating the symbol
46+
47+
* - :ref:`MPI_KEYVAL_CREATE <label-mpi-keyval-create>`
48+
- :ref:`MPI_COMM_CREATE_KEYVAL <mpi_comm_create_keyval>`
49+
- MPI-2.0 (1996)
50+
51+
* - :ref:`MPI_KEYVAL_FREE <label-mpi-keyval-free>`
52+
- :ref:`MPI_COMM_FREE_KEYVAL <mpi_comm_free_keyval>`
53+
- MPI-2.0 (1996)
54+
55+
* - :ref:`MPI_COPY_FUNCTION <label-mpi-copy-delete-function>`
56+
- :ref:`MPI_COMM_COPY_ATTR_FUNCTION <mpi_comm_create_keyval>`
57+
- MPI-2.0 (1996)
58+
59+
* - :ref:`MPI_DELETE_FUNCTION <label-mpi-copy-delete-function>`
60+
- :ref:`MPI_COMM_DELETE_ATTR_FUNCTION <mpi_comm_create_keyval>`
61+
- MPI-2.0 (1996)
62+
63+
* - :ref:`MPI_ATTR_PUT <label-mpi-attr-put>`
64+
- :ref:`MPI_COMM_SET_ATTR <mpi_comm_set_attr>`
65+
- MPI-2.0 (1996)
66+
67+
* - :ref:`MPI_ATTR_GET <label-mpi-attr-get>`
68+
- :ref:`MPI_COMM_GET_ATTR <mpi_comm_get_attr>`
69+
- MPI-2.0 (1996)
70+
71+
* - :ref:`MPI_ATTR_DELETE <label-mpi-attr-delete>`
72+
- :ref:`MPI_COMM_DELETE_ATTR <mpi_comm_delete_attr>`
73+
- MPI-2.0 (1996)
74+
75+
* - :ref:`MPI_Comm_errhandler_fn <label-errhandler-fn>`
76+
- :ref:`MPI_Comm_errhandler_function <mpi_comm_create_errhandler>`
77+
- MPI-2.2 (2009)
78+
79+
* - :ref:`MPI_File_errhandler_fn <label-errhandler-fn>`
80+
- :ref:`MPI_File_errhandler_function <mpi_file_create_errhandler>`
81+
- MPI-2.2 (2009)
82+
83+
* - :ref:`MPI_Win_errhandler_fn <label-errhandler-fn>`
84+
- :ref:`MPI_Win_errhandler_function <mpi_win_create_errhandler>`
85+
- MPI-2.2 (2009)
86+
87+
* - :ref:`MPI_INFO_GET <label-mpi-info-get>`
88+
- :ref:`MPI_INFO_GET_STRING <mpi_info_get_string>`
89+
- MPI-4.0 (2021)
90+
91+
* - :ref:`MPI_INFO_GET_VALUELEN <label-mpi-info-get-valuelen>`
92+
- :ref:`MPI_INFO_GET_STRING <mpi_info_get_string>`
93+
- MPI-4.0 (2021)
94+
95+
* - :ref:`MPI_SIZEOF <label-mpi-sizeof>`
96+
- Fortran intrinsics``c_sizeof`` or ``storage_size``
97+
- MPI-4.0 (2021)
98+
99+
.. _label-mpi-keyval-create:
100+
101+
MPI_Keyval_create
102+
-----------------
103+
104+
``MPI_Keyval_create`` has been deprecated and replaced by
105+
``MPI_Comm_create_keyval``. The C binding of the new function is
106+
identical to the deprecated version. Hence, applications can simply
107+
replace the function that is being invoked.
108+
109+
The Fortran binding differs in that the ``extra_state`` argument is an
110+
address-sized integer in the new interfaces (vs. a regular integer in
111+
the old interfaces). Also, the copy and delete callback functions have
112+
Fortran bindings that are consistent with address-sized attributes.
113+
114+
.. code-block:: Fortran
115+
116+
USE mpi
117+
EXTERNAL my_copy_attr_function
118+
EXTERNAL my_copy_delete_function
119+
INTEGER ierror
120+
INTEGER comm_keyval
121+
INTEGER old_extra_state
122+
INTEGER(KIND=MPI_ADDRESS_KIND) new_extra_state
123+
124+
! Old way
125+
CALL MPI_KEYVAL_CREATE(my_copy_attr_function, my_copy_delete_function,
126+
comm_keyval, old_extra_state, ierror)
127+
128+
! New way
129+
CALL MPI_COMM_CREATE_KEYVAL(my_copy_attr_function, my_delete_attr_function,
130+
comm_keyval, new_extra_state, ierror)
131+
132+
133+
.. _label-mpi-keyval-free:
134+
135+
MPI_Keyval_free
136+
----------------
137+
138+
The binding of ``MPI_Keyval_free`` and ``MPI_Comm_free_keyval`` are identical
139+
for both C and Fortran. Users can directly replace the deprecated function with its
140+
new version.
141+
142+
.. _label-mpi-copy-delete-function:
143+
144+
MPI_Copy_function and MPI_Delete_function
145+
------------------------------------------
146+
147+
The ``MPI_Copy_function`` and ``MPI_Delete_function`` are only used in the
148+
deprecated function ``MPI_Keyval_create()``, as described in the
149+
:ref:`MPI_COMM_CREATE_KEYVAL <label-mpi-keyval-create>`.
150+
151+
For C codes, developers can simply use the new, exactly-equivalent
152+
type name (i.e., the return type, number, and type of parameters
153+
didn't change) ``MPI_Comm_copy_attr_function``, and
154+
``MPI_Comm_delete_attr_function`` respectively.
155+
156+
For Fortran applications, the only difference lies in required integer type for the
157+
``extra_state`` argument, which now has to be an address-sized integer.
158+
159+
.. _label-mpi-attr-put:
160+
161+
MPI_Attr_put
162+
------------
163+
164+
The C binding for the deprecated ``MPI_Attr_put`` is identical to its
165+
replacement, ``MPI_Comm_set_attr``. The Fortran binding differ in the
166+
usage of an addressed size integer for the attribute value in the new
167+
``MPI_Comm_set_attr`` vs. a regular integer in ``MPI_Attr_put``.
168+
169+
.. code-block:: Fortran
170+
171+
USE mpi
172+
INTEGER ierror
173+
INTEGER comm_keyval
174+
INTEGER old_attr_val
175+
INTEGER(KIND=MPI_ADDRESS_KIND) new_attr_val
176+
177+
! Old way
178+
CALL MPI_ATTR_PUT(MPI_COMM_WORLD, comm_keyval,
179+
old_attr_val, ierror)
180+
181+
! New way
182+
CALL MPI_COMM_SET_ATTR(MPI_COMM_WORLD, comm_keyval,
183+
new_attr_val, ierror)
184+
185+
.. _label-mpi-attr-get:
186+
187+
MPI_Attr_get
188+
------------
189+
190+
The C bindings of the old and the new interfaces are identical.
191+
Fortran binding differ in the usage of an addressed size integer for
192+
the attribute value in the new ``MPI_Comm_get_attr`` vs. a regular
193+
integer in ``MPI_Attr_get``.
194+
195+
.. _label-mpi-attr-delete:
196+
197+
MPI_Attr_delete
198+
---------------
199+
200+
C and Fortran bindings are identical for ``MPI_Attr_delete`` and
201+
``MPI_Comm_delete_attr``, hence developers should be able to just
202+
directly substitute one function call by the other.
203+
204+
205+
.. _label-mpi-info-get:
206+
207+
MPI_Info_get
208+
------------
209+
210+
Applications should replace the use of ``MPI_Info_get`` with ``MPI_Info_get_string``,
211+
but the usage differs slightly. See the example below.
212+
213+
.. code-block:: c++
214+
215+
MPI_Info info;
216+
217+
// Create an info object using MPI_Info_create()
218+
...
219+
220+
// Retrieve the the value of a provided key later in the code
221+
char key[] = "my_key";
222+
char value[64];
223+
int valuelen=64;
224+
int flag;
225+
226+
// Old way
227+
MPI_Info_get(info, key, valuelen, &value, &flag);
228+
229+
// New way
230+
// Note that we pass the address of valuelen with
231+
// the new interfaces, since the variable will
232+
// contain the length of the value string after
233+
// the function call.
234+
MPI_Info_get_string(info, key, &valuelen, &value, &flag);
235+
}
236+
237+
.. _label-mpi-info-get-valuelen:
238+
239+
MPI_Info_get_valuelen
240+
---------------------
241+
242+
``MPI_Info_get_valuelen`` has been deprecated since the new function
243+
``MPI_Info_get_string`` also returns the length of the value string.
244+
Please refer to the example shown in :ref:`MPI_INFO_GET <label-mpi-info-get>`.
245+
246+
.. _label-mpi-sizeof:
247+
248+
MPI_Sizeof
249+
----------
250+
251+
The ``MPI_SIZEOF`` construct in Fortran has been deprected since there
252+
are standard Fortran language constructs such as ``c_sizeof`` and
253+
``storage_size`` that can be used instead.
254+
255+
.. _label-errhandler-fn:
256+
257+
MPI_Comm_errhandler_fn, MPI_File_errhandler_fn, MPI_Win_errhandler_fn
258+
---------------------------------------------------------------------
259+
260+
The following function typedefs have been deprecated and are superseded by new
261+
names. Other than the typedef names, the function signatures are exactly the same; the
262+
names were updated to match conventions of other function typedef names.
31263

32-
shell$ mpicc deleted-example.c -c
33-
deleted-example.c: In function 'foo':
34-
deleted-example.c:8:5: warning: 'MPI_Address' is deprecated: MPI_Address was removed in MPI-3.0; use MPI_Get_address instead. [-Wdeleted-declarations]
35-
MPI_Address(buffer, &address);
36-
^~~~~~~~~~~
37-
In file included from deleted-example.c:2:
38-
/usr/local/openmpi/include/mpi.h:2689:20: note: declared here
39-
OMPI_DECLSPEC int MPI_Address(void *location, MPI_Aint *address)
40-
^~~~~~~~~~~
264+
* ``MPI_Comm_errhandler_fn`` |rarrow| ``MPI_Comm_errhandler_function``
265+
* ``MPI_File_errhandler_fn`` |rarrow| ``MPI_File_errhandler_function``
266+
* ``MPI_Win_errhandler_fn`` |rarrow| ``MPI_Win_errhandler_function``

‎docs/building-apps/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Open MPI "wrapper" compilers.
1010
quickstart
1111
customizing-wrappers
1212
extracting-wrapper-flags
13+
abi-compatibility
1314
removed-mpi-constructs
1415
deprecation-warnings
1516
building-static-apps

0 commit comments

Comments
 (0)