Document Kokkos::push_finalize_hook

docs/source/API/core/Initialize-and-Finalize.rst

@@ -57,3 +57,4 @@ In the above example, ``my_view`` will not go out of scope until the end of the
    ./initialize_finalize/ScopeGuard
    ./initialize_finalize/InitializationSettings
    ./initialize_finalize/InitArguments
+   ./initialize_finalize/push_finalize_hook

docs/source/API/core/initialize_finalize/finalize.rst

@@ -53,4 +53,10 @@ Example
             Kokkos::View<double*> my_view("my_view", 10);
         }  // scope of my_view ends here
         Kokkos::finalize();
-    }
+    }
+
+
+See also
+--------
+* `Kokkos::initialize <initialize.html>`_: initializes the Kokkos execution environment
+* `Kokkos::push_finalize_hook <push_finalize_hook.html>`_: registers a function to be called on ``Kokkos::finalize()`` invocation

docs/source/API/core/initialize_finalize/push_finalize_hook.rst

@@ -0,0 +1,68 @@
+``push_finalize_hook``
+======================
+
+.. role::cpp(code)
+    :language: cpp
+
+Defined in header ``<Kokkos_Core.hpp>``
+
+Usage
+-----
+
+.. code-block:: cpp
+
+    Kokkos::push_finalize_hook(func);
+
+Registers the callable object ``func`` to be called when Kokkos execution
+environment is terminated.
+
+The functions registered via ``Kokkos::push_finalize_hook()`` will be called in
+reverse order when entering ``Kokkos::finalize()``, before releasing acquired
+resources and finalizing all backends.
+
+If a function exits via a thrown exception, ``std::terminate`` is called.
+
+Interface
+---------
+
+.. cppkokkos:Function:: void push_finalize_hook(std::function<void()> func);
+
+   Register the function object ``func`` to be called when entering
+   ``Kokkos::finalize()``
+
+
+
+
+Example
+-------
+
+.. code-block:: cpp
+
+    #include <Kokkos_Core.hpp>
+    #include <iostream>
+
+    void my_hook() {
+      std::cout << "Cruel world!\n";
+    }
+
+    int main(int argc, char* argv[]) {
+        Kokkos::initialize(argc, argv);
+        Kokkos::push_finalize_hook(my_hook);
+        Kokkos::push_finalize_hook([]{ std::cout << "Goodbye\n"; });
+        std::cout << "Calling Kokkos::finalize() ...\n";
+        Kokkos::finalize();
+    }
+
+
+Output:
+
+.. code-block::
+
+    Calling Kokkos::finalize() ...
+    Goodbye
+    Cruel world!
+
+
+See also
+--------
+* `Kokkos::finalize <finalize.html>`_: terminates the Kokkos execution environment