docs: update list of deprecated functions.

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. Signed-off-by: Edgar Gabriel <[email protected]>
edgargabriel · Jul 11, 2023 · 4f66032 · 4f66032
1 parent 7b87ae4
commit 4f66032
Show file tree

Hide file tree

Showing 4 changed files with 270 additions and 35 deletions.
diff --git a/docs/building-apps/deprecation-warnings.rst b/docs/building-apps/deprecation-warnings.rst
@@ -3,7 +3,7 @@ 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 +25,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_copy_attr_function>`
+      - MPI-2.0 (1996)
+
+    * - :ref:`MPI_DELETE_FUNCTION <label-mpi-copy-delete-function>`
+      - :ref:`MPI_COMM_DELETE_ATTR_FUNCTION <mpi_comm_delete_attr_function>`
+      - 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_Comm_errhandler_fn <label-errhandler-fn>`
+      - :ref:`MPI_Comm_errhandler_function <mpi_comm_errhandler_function>`
+      - MPI-2.2 (2009)
+
+    * - :ref:`MPI_File_errhandler_fn <label-errhandler-fn>`
+      - :ref:`MPI_File_errhandler_function <mpi_file_errhandler_function>`
+      - MPI-2.2 (2009)
+
+    * - :ref:`MPI_Win_errhandler_fn <label-errhandler-fn>`
+      - :ref:`MPI_Win_errhandler_function <mpi_win_errhandler_function>`
+      - MPI-2.2 (2009)
+
+    * - :ref:`MPI_ATTR_DELETE <label-mpi-attr-delete>`
+      - :ref:`MPI_COMM_DELETE_ATTR <mpi_comm_delete_attr`
+      - MPI-2.0 (1996)
+
+    * - :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>`
+      - :ref:`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/removed 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 pointer to valuelen here,
+	// since it is an INOUT argument, i.e. it 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-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/removed-mpi-constructs.rst b/docs/building-apps/removed-mpi-constructs.rst
@@ -110,18 +110,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 +136,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 +196,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 +258,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:

diff --git a/docs/man-openmpi/man3/MPI_Info_get.3.rst b/docs/man-openmpi/man3/MPI_Info_get.3.rst
@@ -6,8 +6,8 @@ MPI_Info_get
 
 .. include_body
 
-:ref:`MPI_Info_get` - Retrieves the value associated with a key in an info
-object.
+:ref:`MPI_Info_get` - Retrieves the value associated with a key in an
+info object -- |deprecated_favor| :ref:`MPI_Info_get_string`.
 
 
 SYNTAX
@@ -67,6 +67,9 @@ OUTPUT PARAMETER
 DESCRIPTION
 -----------
 
+Note that use of this routine is *deprecated as of MPI-4.0. Please use
+:ref:`MPI_Info_get_string`.
+
 :ref:`MPI_Info_get` retrieves the value associated with *key* in a previous
 call to :ref:`MPI_Info_set`. If such a key exists, it sets *flag* to true and
 returns the value in *value*; otherwise it sets *flag* to false and

diff --git a/docs/man-openmpi/man3/MPI_Info_get_valuelen.3.rst b/docs/man-openmpi/man3/MPI_Info_get_valuelen.3.rst
@@ -7,7 +7,8 @@ MPI_Info_get_valuelen
 .. include_body
 
 :ref:`MPI_Info_get_valuelen` - Retrieves the length of the key value
-associated with an info object.
+associated with an info object -- |deprecated_favor|
+:ref:`MPI_Info_get_string`.
 
 
 SYNTAX
@@ -66,6 +67,10 @@ OUTPUT PARAMETERS
 DESCRIPTION
 -----------
 
+Note that use of this routine is *deprecated as of MPI-4.0. Please use
+:ref:`MPI_Info_get_string`.
+
+
 :ref:`MPI_Info_get_valuelen` retrieves the length of the *value* associated
 with *key*. If *key* is defined, *valuelen* is set to the length of its
 associated value and *flag* is set to true. If *key* is not defined,