Add declaration of destroy_communicator(); implementation will come tomorrow.

git-svn-id: https://svn.dealii.org/trunk@19385 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/base/include/base/utilities.h b/deal.II/base/include/base/utilities.h
index ff50b19364ba78794b7c61103ca80aaaded0fd59..580ec0d0539b6bac09780662a044ef0e7bc29766 100644 (file)
--- a/deal.II/base/include/base/utilities.h
+++ b/deal.II/base/include/base/utilities.h
@@ -457,6 +457,45 @@ namespace Utilities
     Epetra_Comm *
     duplicate_communicator (const Epetra_Comm &communicator);
 
+                                    /**
+                                     * Given an Epetra communicator that was
+                                     * created by the
+                                     * duplicate_communicator() function,
+                                     * destroy the underlying MPI
+                                     * communicator object and reset the
+                                     * Epetra_Comm object to a the result of
+                                     * comm_self().
+                                     *
+                                     * It is necessary to call this function
+                                     * at the time when the result of
+                                     * duplicate_communicator() is no longer
+                                     * needed. The reason is that in that
+                                     * function, we first create a new
+                                     * MPI_Comm object and then create an
+                                     * Epetra_Comm around it. While we can
+                                     * take care of destroying the latter, it
+                                     * doesn't destroy the communicator since
+                                     * it can only assume that it may also be
+                                     * still used by other objects in the
+                                     * program. Consequently, we have to take
+                                     * care of destroying it ourselves,
+                                     * explicitly.
+                                     *
+                                     * This function does exactly
+                                     * that. Because this has to happen while
+                                     * the Epetra_Comm object is still
+                                     * around, it first resets the latter and
+                                     * then destroys the communicator object.
+                                     *
+                                     * @note If you call this function on an
+                                     * Epetra_Comm object that is not created
+                                     * by duplicate_communicator(), you are
+                                     * likely doing something quite
+                                     * wrong. Don't do this.
+                                     */
+    void
+    destroy_communicator (Epetra_Comm &communicator);
+    
                                     /**
                                      * Return the number of MPI processes
                                      * there exist in the given communicator