docs: update list of deprecated/removed functions.

This commit address issue open-mpi#10099 Update documentation with the list of depreacted functions in MPI 2.2 and MPI-4.0. Add some examples and explanation on how to convert code from the deprecated interfaces to the new ones. Add a new section on ABI compatibility to Open MPI 4.1 Signed-off-by: Edgar Gabriel <[email protected]>
edgargabriel · Jul 14, 2023 · ee20cf8 · ee20cf8
1 parent 7b87ae4
commit ee20cf8
Show file tree

Hide file tree

Showing 9 changed files with 295 additions and 41 deletions.
diff --git a/3rd-party/openpmix b/3rd-party/openpmix
diff --git a/3rd-party/prrte b/3rd-party/prrte
diff --git a/config/oac b/config/oac
diff --git a/docs/building-apps/abi-compatibility.rst b/docs/building-apps/abi-compatibility.rst
@@ -0,0 +1,19 @@
+.. -label-binary-compatibility:
+
+ABI compatibility to previous versions of Open MPI
+==================================================
+
+Open MPI v5.0 intends to maintain Application Binary Interface (ABI)
+compatibility to the last major Open MPI release. Technically, an
+application compiled with Open MPI 4.1 can be executed with Open MPI
+5.0 without having to recompile the application.
+
+There are however a few scenarios where an application compiled with
+Open MPI 4.1 might not execute correctly with Open MPI 5.0.
+
+- There were some minor changes in the Fortran Interfaces (Jeff, need
+  your help what to say here).
+
+- Open MPI 5.0 removed support for the C++ bindings. If an application
+  was using the deprecated and now removed C++ bindings, it will not
+  be able to execute with Open MPI 5.0, for details on deprecated and removed functions see :ref:`Removed MPI constructs <label-removed-mpi-constructs>` and :ref: `Deprecation warnings <label-deprecated-functions>`
diff --git a/docs/building-apps/deprecation-warnings.rst b/docs/building-apps/deprecation-warnings.rst
@@ -1,9 +1,11 @@
+.. _label-deprecated-functions:
+
 Deprecation warnings while compiling MPI applications
 =====================================================
 
 If you see deprecation warnings when compiling MPI applications, it is
 because your application is symbols / functions that are deprecated in
-MPI.  For example:
+MPI. For example:
 
 .. code-block:: sh
 
@@ -25,16 +27,236 @@ advises you to use ``MPI_Comm_delete_attr()`` instead of
 Also, note that even if Open MPI was configured with
 ``--enable-mpi1-compatibility`` to re-enable removed MPI-1 symbols,
 you will still get compiler warnings when you use the removed symbols.
-For example:
 
-.. code-block:: sh
+The following is a list of functions that have been deprecated in MPI,
+and the function that is replacing them. Some functions have been
+deprecated and removed from the MPI specification, these functions are
+listed :ref:`here <label-removed-mpi-constructs>`.
+
+.. list-table::
+    :header-rows: 1
+
+    * - Deprecated symbol
+
+        (click for more details, below)
+      - Replaced with
+
+        (click to go to the corresponding man page)
+      - MPI version deprecating the symbol
+
+    * - :ref:`MPI_KEYVAL_CREATE <label-mpi-keyval-create>`
+      - :ref:`MPI_COMM_CREATE_KEYVAL <mpi_comm_create_keyval>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_KEYVAL_FREE <label-mpi-keyval-free>`
+      - :ref:`MPI_COMM_FREE_KEYVAL <mpi_comm_free_keyval>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_COPY_FUNCTION <label-mpi-copy-delete-function>`
+      - :ref:`MPI_COMM_COPY_ATTR_FUNCTION <mpi_comm_create_keyval>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_DELETE_FUNCTION <label-mpi-copy-delete-function>`
+      - :ref:`MPI_COMM_DELETE_ATTR_FUNCTION <mpi_comm_create_keyval>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_ATTR_PUT <label-mpi-attr-put>`
+      - :ref:`MPI_COMM_SET_ATTR <mpi_comm_set_attr>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_ATTR_GET <label-mpi-attr-get>`
+      - :ref:`MPI_COMM_GET_ATTR <mpi_comm_get_attr>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_ATTR_DELETE <label-mpi-attr-delete>`
+      - :ref:`MPI_COMM_DELETE_ATTR <mpi_comm_delete_attr>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_Comm_errhandler_fn <label-errhandler-fn>`
+      - :ref:`MPI_Comm_errhandler_function <mpi_comm_create_errhandler>`
+      - MPI-2.2 (2009)
+
+    * - :ref:`MPI_File_errhandler_fn <label-errhandler-fn>`
+      - :ref:`MPI_File_errhandler_function <mpi_file_create_errhandler>`
+      - MPI-2.2 (2009)
+
+    * - :ref:`MPI_Win_errhandler_fn <label-errhandler-fn>`
+      - :ref:`MPI_Win_errhandler_function <mpi_win_create_errhandler>`
+      - MPI-2.2 (2009)
+
+    * - :ref:`MPI_INFO_GET <label-mpi-info-get>`
+      - :ref:`MPI_INFO_GET_STRING <mpi_info_get_string>`
+      - MPI-4.0 (2021)
+
+    * - :ref:`MPI_INFO_GET_VALUELEN <label-mpi-info-get-valuelen>`
+      - :ref:`MPI_INFO_GET_STRING <mpi_info_get_string>`
+      - MPI-4.0 (2021)
+
+    * - :ref:`MPI_SIZEOF <label-mpi-sizeof>`
+      - `c_sizeof` or `storage_size`
+      - MPI-4.0 (2021)
+
+.. _label-mpi-keyval-create:
+
+MPI_Keyval_create
+-----------------
+
+`MPI_Keyval_create` has been deprecated and replaced by
+`MPI_Comm_create_keyval`. The C binding of the new function is
+identical to the deprecated version. Hence, applications can simply
+replace the function that is being invoked.
+
+The Fortran binding differs in that the `extra_state` argument is an
+address-sized integer in the new interfaces (vs. a regular integer in
+the old interfaces). Also, the copy and delete callback functions have
+Fortran bindings that are consistent with address-sized attributes.
+
+.. code-block:: Fortran
+
+    USE mpi
+    EXTERNAL my_copy_attr_function
+    EXTERNAL my_copy_delete_function
+    INTEGER ierror
+    INTEGER comm_keyval
+    INTEGER old_extra_state
+    INTEGER(KIND=MPI_ADDRESS_KIND) new_extra_state
+
+    ! Old way
+    CALL MPI_KEYVAL_CREATE(my_copy_attr_function, my_copy_delete_function,
+                           comm_keyval, old_extra_state, ierror)
+
+    ! New way
+    CALL MPI_COMM_CREATE_KEYVAL(my_copy_attr_function, my_delete_attr_function,
+                                comm_keyval, new_extra_state, ierror)
+
+
+.. _label-mpi-keyval-free:
+
+MPI_Keyval_free
+----------------
+
+The binding of ``MPI_Keyval_free`` and ``MPI_Comm_free_keyval`` are identical
+for both C and Fortran. Users can directly replace the depracted function with its
+new version.
+
+.. _label-mpi-copy-delete-function:
+
+MPI_Copy_function and MPI_Delete_function
+------------------------------------------
+
+The ``MPI_Copy_function`` and ``MPI_Delete_function`` are only used in the
+deprecated function ``MPI_Keyval_create()``, as described in the
+:ref:`MPI_COMM_CREATE_KEYVAL <label-mpi-keyval-create>`.
+
+For C codes, developers can simply use the new, exactly-equivalent
+type name (i.e., the return type, number, and type of parameters
+didn't change) ``MPI_Comm_copy_attr_function``, and
+``MPI_Comm_delete_attr_function`` respectively.
+
+For Fortran applications, the only difference lies in required integer type for the
+``extra_state`` argument, which now has to be an address-sized integer.
+
+.. _label-mpi-attr-put:
+
+MPI_Attr_put
+------------
+
+C bindings are identical. Fortran binding differ in the usage of an
+addressed size integer for the attribute value in the new
+``MPI_Comm_set_attr`` vs. a regular integer in ``MPI_Attr_put``.
+
+.. code-block:: Fortran
+
+    USE mpi
+    INTEGER ierror
+    INTEGER comm_keyval
+    INTEGER old_attr_val
+    INTEGER(KIND=MPI_ADDRESS_KIND) new_attr_val
+
+    ! Old way
+    CALL MPI_ATTR_PUT(MPI_COMM_WORLD, comm_keyval,
+                       old_attr_val, ierror)
+
+    ! New way
+    CALL MPI_COMM_SET_ATTR(MPI_COMM_WORLD, comm_keyval,
+	                   new_attr_val, ierror)
+
+.. _label-mpi-attr-get:
+
+MPI_Attr_get
+------------
+
+The C bindings of the old and the new interfaces are identical.
+Fortran binding differ in the usage of an addressed size integer for
+the attribute value in the new ``MPI_Comm_get_attr`` vs. a regular
+integer in ``MPI_Attr_get``.
+
+.. _label-mpi-attr-delete:
+
+MPI_Attr_delete
+---------------
+
+C and Fortran bindings are identical for ``MPI_Attr_delete`` and
+``MPI_Comm_delete_attr``, hence developers should be able to just
+directly substitute one function call by the other.
+
+
+.. _label-mpi-info-get:
+
+MPI_Info_get
+------------
+
+.. code-block:: c++
+
+        MPI_Info info;
+
+	// Create an info object using MPI_Info_create()
+	...
+
+	// Retrieve the the value of a provided key later in the code
+	char key[] = "my_key";
+	char value[64];
+        int valuelen=64;
+	int flag;
+
+	// Old way
+        MPI_Info_get(info, key, valuelen, &value, &flag);
+
+        // New way
+	// Note that we pass the address of valuelen with
+	// the new interfaces, since the variable will
+	// contain the length of the value string after
+	// the function call.
+        MPI_Info_get_string(info, key, &valuelen, &value, &flag);
+    }
+
+.. _label-mpi-info-get-valuelen:
+
+MPI_Info_get_valuelen
+---------------------
+
+`MPI_Info_get_valuelen` has been deprecated since the new function
+`MPI_Info_get_string` also returns the length of the value string.
+Please refer to the example shown in :ref:`MPI_INFO_GET <label-mpi-info-get>`.
+
+.. _label-mpi-sizeof:
+
+MPI_Sizeof
+----------
+
+The `MPI_SIZEOF` construct in Fortran has been deprected since there
+are standard Fortran language constructs such as `c_sizeof` and
+`storage_size` that can be used instead.
+
+.. _label-errhandler-fn:
+
+MPI_Comm_errhandler_fn, MPI_File_errhandler_fn, MPI_Win_errhandler_fn
+---------------------------------------------------------------------
+
+The following function typedefs have been deprecated and are superseded by new
+names. Other than the typedef names, the function signatures are exactly the same; the
+names were updated to match conventions of other function typedef names.
 
-    shell$ mpicc deleted-example.c -c
-    deleted-example.c: In function 'foo':
-    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]
-         MPI_Address(buffer, &address);
-         ^~~~~~~~~~~
-    In file included from deleted-example.c:2:
-    /usr/local/openmpi/include/mpi.h:2689:20: note: declared here
-     OMPI_DECLSPEC  int MPI_Address(void *location, MPI_Aint *address)
-                        ^~~~~~~~~~~
+* ``MPI_Comm_errhandler_fn`` |rarrow| ``MPI_Comm_errhandler_function``
+* ``MPI_File_errhandler_fn`` |rarrow| ``MPI_File_errhandler_function``
+* ``MPI_Win_errhandler_fn`` |rarrow| ``MPI_Win_errhandler_function``
diff --git a/docs/building-apps/index.rst b/docs/building-apps/index.rst
@@ -10,6 +10,7 @@ Open MPI "wrapper" compilers.
    quickstart
    customizing-wrappers
    extracting-wrapper-flags
+   abi-compatibility
    removed-mpi-constructs
    deprecation-warnings
    building-static-apps

diff --git a/docs/building-apps/removed-mpi-constructs.rst b/docs/building-apps/removed-mpi-constructs.rst
@@ -3,9 +3,6 @@
 Removed MPI constructs
 ======================
 
-.. error:: **TODO This section needs to be renamed/updated for the
-           5.0.0 behavior.**
-
 Starting with v4.0.0, Open MPI |mdash| by default |mdash| removes the
 prototypes from ``mpi.h`` for MPI symbols that were deprecated in 1996
 in the MPI-2.0 standard, and finally removed from the MPI-3.0 standard
@@ -110,18 +107,23 @@ default:
       - MPI-3.0 (2012)
 
 Although these symbols are no longer prototyped in ``mpi.h``, *they are
-still present in the MPI library in Open MPI v4.0.x*. This enables
+still present in the MPI library in Open MPI |ompi_ver|. This enables
 legacy MPI applications to *link and run* successfully with Open MPI
-v4.0.x, even though they will fail to *compile*.
+|ompi_ver|, even though they will fail to *compile*.
+
+Furthermore, the C++ interfaces of MPI have been deprecated in version
+2.2 of the specification and have bee removed in MPI-3.0.  Starting
+from v5.0 Open MPI will not have support for the C++ interfaces
+anymore. Users that would like to continue using the C++ interfaces of
+MPI will have to revert to an older release of Open MPI.
 
 .. warning:: The Open MPI team **strongly** encourages all
    MPI application developers to stop using these constructs that were
    first deprecated over 20 years ago, and finally removed from the MPI
    specification in MPI-3.0 (in 2012).
 
-The FAQ items in this category
-show how to update your application to stop using these removed
-symbols.
+The FAQ items in this category show how to update your application to
+stop using these removed symbols.
 
 All that being said, if you are unable to immediately update your
 application to stop using these removed MPI-1 symbols, you can
@@ -131,22 +133,24 @@ re-enable them in ``mpi.h`` by configuring Open MPI with the
 .. note:: Future releases of Open MPI may remove these symbols
    altogether.
 
-Why on earth are you breaking the compilation of MPI applications?
+Why is Open MPI breaking the compilation of MPI applications?
 ------------------------------------------------------------------
 
-.. error:: **TODO This section needs to be renamed/updated (or
-           deleted?) for the 5.0.0 behavior.**
-
 The Open MPI developer community decided to take a first step of
-removing the prototypes for these symbols from ``mpi.h`` starting with
-the Open MPI v4.0.x series for the following reasons:
-
-#. These symbols have been deprecated since *1996.* It's time to start
-   raising awareness for developers who are inadvertently still using
-   these removed symbols.
-#. The MPI Forum removed these symbols from the MPI-3.0 specification
-   in 2012.  This is a sign that the Forum itself recognizes that
-   these removed symbols are no longer needed.
+removing prototypes of deprecated functions from ``mpi.h`` starting
+with the Open MPI v4.0.x series for the following reasons:
+
+#. The first set of symbols have been deprecated since *1996.* It's
+   time to start raising awareness for developers who are
+   inadvertently still using these removed symbols.
+#. The MPI Forum removed a substantial set of symbols from the MPI-3.0
+   specification in 2012. This is a sign that the Forum itself
+   recognizes that these removed symbols are no longer needed.
+#. More functions have been deprecated in MPI 2.2 and MPI 4.0, and
+   additional functions are expected to be deprecated and removed in
+   future MPI versions. It is in the interest of both, developers and
+   end-users, to minimize confusion as much as possible, and stick
+   closely to the MPI specification.
 #. Note that Open MPI *did not fully remove* these removed symbols: we
    just made it slightly more painful to get to them.  This is an
    attempt to raise awareness so that MPI application developers can
@@ -189,7 +193,7 @@ to change:
     MPI_Get_address(buffer, &address);
 
 In Fortran, the type of the parameter changed from ``INTEGER``
-$right_arrow ``INTEGER(KIND=MPI_ADDRESS_KIND)`` so that it can hold
+|rarrow| ``INTEGER(KIND=MPI_ADDRESS_KIND)`` so that it can hold
 larger values (e.g., 64 bit pointers):
 
 .. code-block:: Fortran
@@ -251,7 +255,7 @@ In Fortran, only the subroutine name changed:
     ! Old way
     CALL MPI_ERRHANDLER_CREATE(my_errhandler_function, my_handler, ierror)
 
-    ! Old way
+    ! New way
     CALL MPI_COMM_CREATE_ERRHANDLER(my_errhandler_function, my_handler, ierror)
 
 .. _label-mpi-errhandler-get: