boost/mpi/intercommunicator.hpp

   1 // Copyright (C) 2007 The Trustees of Indiana University.
   2
   3 // Authors: Douglas Gregor
   4 //          Andrew Lumsdaine
   5
   6 // Use, modification and distribution is subject to the Boost Software
   7 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   8 // http://www.boost.org/LICENSE_1_0.txt)
   9
  10 /** @file intercommunicator.hpp
  11  *
  12  *  This header defines the @c intercommunicator class, which permits
  13  *  communication between different process groups.
  14  */
  15 #ifndef BOOST_MPI_INTERCOMMUNICATOR_HPP
  16 #define BOOST_MPI_INTERCOMMUNICATOR_HPP
  17
  18 #include <boost/mpi/communicator.hpp>
  19
  20 namespace boost { namespace mpi {
  21
  22 /**
  23  * INTERNAL ONLY
  24  *
  25  * Forward declaration of the MPI "group" representation, for use in
  26  * the description of the @c intercommunicator class.
  27  */
  28 class group;
  29
  30 /**
  31  * @brief Communication facilities among processes in different
  32  * groups.
  33  *
  34  * The @c intercommunicator class provides communication facilities
  35  * among processes from different groups. An intercommunicator is
  36  * always associated with two process groups: one "local" process
  37  * group, containing the process that initiates an MPI operation
  38  * (e.g., the sender in a @c send operation), and one "remote" process
  39  * group, containing the process that is the target of the MPI
  40  * operation.
  41  *
  42  * While intercommunicators have essentially the same point-to-point
  43  * operations as intracommunicators (the latter communicate only
  44  * within a single process group), all communication with
  45  * intercommunicators occurs between the processes in the local group
  46  * and the processes in the remote group; communication within a group
  47  * must use a different (intra-)communicator.
  48  *
  49  */
  50 class BOOST_MPI_DECL intercommunicator : public communicator
  51 {
  52 private:
  53   friend class communicator;
  54
  55   /**
  56    * INTERNAL ONLY
  57    *
  58    * Construct an intercommunicator given a shared pointer to the
  59    * underlying MPI_Comm. This operation is used for "casting" from a
  60    * communicator to an intercommunicator.
  61    */
  62   explicit intercommunicator(const shared_ptr<MPI_Comm>& comm_ptr)
  63   {
  64     this->comm_ptr = comm_ptr;
  65   }
  66
  67 public:
  68   /**
  69    * Build a new Boost.MPI intercommunicator based on the MPI
  70    * intercommunicator @p comm.
  71    *
  72    * @p comm may be any valid MPI intercommunicator. If @p comm is
  73    * MPI_COMM_NULL, an empty communicator (that cannot be used for
  74    * communication) is created and the @p kind parameter is
  75    * ignored. Otherwise, the @p kind parameter determines how the
  76    * Boost.MPI communicator will be related to @p comm:
  77    *
  78    *   - If @p kind is @c comm_duplicate, duplicate @c comm to create
  79    *   a new communicator. This new communicator will be freed when
  80    *   the Boost.MPI communicator (and all copies of it) is
  81    *   destroyed. This option is only permitted if the underlying MPI
  82    *   implementation supports MPI 2.0; duplication of
  83    *   intercommunicators is not available in MPI 1.x.
  84    *
  85    *   - If @p kind is @c comm_take_ownership, take ownership of @c
  86    *   comm. It will be freed automatically when all of the Boost.MPI
  87    *   communicators go out of scope.
  88    *
  89    *   - If @p kind is @c comm_attach, this Boost.MPI communicator
  90    *   will reference the existing MPI communicator @p comm but will
  91    *   not free @p comm when the Boost.MPI communicator goes out of
  92    *   scope. This option should only be used when the communicator is
  93    *   managed by the user.
  94    */
  95   intercommunicator(const MPI_Comm& comm, comm_create_kind kind)
  96     : communicator(comm, kind) { }
  97
  98   /**
  99    * Constructs a new intercommunicator whose local group is @p local
 100    * and whose remote group is @p peer. The intercommunicator can then
 101    * be used to communicate between processes in the two groups. This
 102    * constructor is equivalent to a call to @c MPI_Intercomm_create.
 103    *
 104    * @param local The intracommunicator containing all of the
 105    * processes that will go into the local group.
 106    *
 107    * @param local_leader The rank within the @p local
 108    * intracommunicator that will serve as its leader.
 109    *
 110    * @param peer The intracommunicator containing all of the processes
 111    * that will go into the remote group.
 112    *
 113    * @param remote_leader The rank within the @p peer group that will
 114    * serve as its leader.
 115    */
 116   intercommunicator(const communicator& local, int local_leader,
 117                     const communicator& peer, int remote_leader);
 118
 119   /**
 120    * Returns the size of the local group, i.e., the number of local
 121    * processes that are part of the group.
 122    */
 123   int local_size() const { return this->size(); }
 124
 125   /**
 126    * Returns the local group, containing all of the local processes in
 127    * this intercommunicator.
 128    */
 129   boost::mpi::group local_group() const;
 130
 131   /**
 132    * Returns the rank of this process within the local group.
 133    */
 134   int local_rank() const { return this->rank(); }
 135
 136   /**
 137    * Returns the size of the remote group, i.e., the number of
 138    * processes that are part of the remote group.
 139    */
 140   int remote_size() const;
 141
 142   /**
 143    * Returns the remote group, containing all of the remote processes
 144    * in this intercommunicator.
 145    */
 146   boost::mpi::group remote_group() const;
 147
 148   /**
 149    * Merge the local and remote groups in this intercommunicator into
 150    * a new intracommunicator containing the union of the processes in
 151    * both groups. This method is equivalent to @c MPI_Intercomm_merge.
 152    *
 153    * @param high Whether the processes in this group should have the
 154    * higher rank numbers than the processes in the other group. Each
 155    * of the processes within a particular group shall have the same
 156    * "high" value.
 157    *
 158    * @returns the new, merged intracommunicator
 159    */
 160   communicator merge(bool high) const;
 161 };
 162
 163 } } // end namespace boost::mpi
 164
 165 #endif // BOOST_MPI_INTERCOMMUNICATOR_HPP