From 327abef38e64f2fcf4e72b0bfc57bd00b332cb71 Mon Sep 17 00:00:00 2001
From: Douglas Gregor <doug.gregor@gmail.com>
Date: Thu, 31 May 2007 16:02:07 +0000
Subject: [PATCH] Support building communicators from groups and comparing
 communicators

[SVN r37832]
---
 doc/mpi.qbk                        | 10 +++++--
 include/boost/mpi/communicator.hpp | 45 ++++++++++++++++++++++++++++++
 src/communicator.cpp               | 19 ++++++++++++-
 3 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/doc/mpi.qbk b/doc/mpi.qbk
index 04e60c2..e92b7d3 100644
--- a/doc/mpi.qbk
+++ b/doc/mpi.qbk
@@ -921,6 +921,11 @@ rank 0 in the `local` (collector) communicator. It receives a message
 from a generator via the `world` communicator, then broadcasts the
 message to each of the collectors via the `local` communicator.
 
+For more control in the creation of communicators for subgroups of
+processes, the Boost.MPI [classref boost::mpi::group `group`] provides
+facilities to compute the union (`|`), intersection (`&`), and
+difference (`-`) of two groups, generate arbitrary subgroups, etc.
+
 [endsect]
 
 [section:skeleton_and_content Separating structure from content]
@@ -1425,12 +1430,13 @@ boost::mpi::communicator `communicator`] class.
   `MPI_Comm_rank`]] [[memberref boost::mpi::communicator::rank
   `communicator::rank`]]]
   [[[@http://www.mpi-forum.org/docs/mpi-11-html/node101.html#Node101
-  `MPI_Comm_compare`]] [unsupported]]
+  `MPI_Comm_compare`]] [operators `==` and `!=`]]
   [[[@http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102
   `MPI_Comm_dup`]] [[classref boost::mpi::communicator `communicator`]
   class constructor using `comm_duplicate`]]
   [[[@http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102
-  `MPI_Comm_create`]] [unsupported]]
+  `MPI_Comm_create`]] [[classref boost::mpi::communicator
+  `communicator`] constructor]]
   [[[@http://www.mpi-forum.org/docs/mpi-11-html/node102.html#Node102
   `MPI_Comm_split`]] [[memberref boost::mpi::communicator::split
   `communicator::split`]]]
diff --git a/include/boost/mpi/communicator.hpp b/include/boost/mpi/communicator.hpp
index dc9d538..5b3df23 100644
--- a/include/boost/mpi/communicator.hpp
+++ b/include/boost/mpi/communicator.hpp
@@ -86,6 +86,14 @@ const int any_tag = MPI_ANY_TAG;
  */
 enum comm_create_kind { comm_duplicate, comm_take_ownership, comm_attach };
 
+/**
+ * INTERNAL ONLY
+ * 
+ * Forward-declaration of @c group needed for the @c group
+ * constructor.
+ */
+class group;
+
 /**
  * @brief A communicator that permits communication and
  * synchronization among a set of processes.
@@ -135,6 +143,21 @@ class communicator
    */
   communicator(const MPI_Comm& comm, comm_create_kind kind);
 
+  /**
+   * Build a new Boost.MPI communicator based on a subgroup of another
+   * MPI communicator.
+   *
+   * This routine will construct a new communicator containing all of
+   * the processes from communicator @c comm that are listed within
+   * the group @c subgroup. Equivalent to @c MPI_Comm_create.
+   *
+   * @param comm An MPI communicator.
+   *
+   * @param subgroup A subgroup of the MPI communicator, @p comm, for
+   * which we will construct a new communicator.
+   */
+  communicator(const communicator& comm, const group& subgroup);
+
   /**
    * @brief Determine the rank of the executing process in a
    * communicator.
@@ -945,6 +968,28 @@ class communicator
   shared_ptr<MPI_Comm> comm_ptr;
 };
 
+/**
+ * @brief Determines whether two communicators are identical.
+ *
+ * Equivalent to calling @c MPI_Comm_compare and checking whether the
+ * result is @c MPI_IDENT.
+ *
+ * @returns True when the two communicators refer to the same
+ * underlying MPI communicator.
+ */
+bool operator==(const communicator& comm1, const communicator& comm2);
+
+/**
+ * @brief Determines whether two communicators are different.
+ *
+ * @returns @c !(comm1 == comm2)
+ */
+inline bool operator!=(const communicator& comm1, const communicator& comm2)
+{
+  return !(comm1 == comm2);
+}
+
+
 /************************************************************************
  * Implementation details                                               *
  ************************************************************************/
diff --git a/src/communicator.cpp b/src/communicator.cpp
index b9b5570..c9f6855 100644
--- a/src/communicator.cpp
+++ b/src/communicator.cpp
@@ -4,6 +4,7 @@
 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 #include <boost/mpi/communicator.hpp>
+#include <boost/mpi/group.hpp>
 #include <boost/mpi/skeleton_and_content.hpp>
 #include <boost/mpi/detail/point_to_point.hpp>
 
@@ -52,7 +53,15 @@ communicator::communicator(const MPI_Comm& comm, comm_create_kind kind)
     comm_ptr.reset(new MPI_Comm(comm));
     break;
   }
- }
+}
+
+communicator::communicator(const communicator& comm, const group& subgroup)
+{
+  MPI_Comm newcomm;
+  BOOST_MPI_CHECK_RESULT(MPI_Comm_create, 
+                         ((MPI_Comm)comm, (MPI_Group)subgroup, &newcomm));
+  comm_ptr.reset(new MPI_Comm(newcomm), comm_free());
+}
 
 int communicator::size() const
 {
@@ -264,4 +273,12 @@ request communicator::irecv(int source, int tag) const
   return req;
 }
 
+bool operator==(const communicator& comm1, const communicator& comm2)
+{
+  int result;
+  BOOST_MPI_CHECK_RESULT(MPI_Comm_compare,
+                         ((MPI_Comm)comm1, (MPI_Comm)comm2, &result));
+  return result == MPI_IDENT;
+}
+
 } } // end namespace boost::mpi