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 */ intercommunicator(const shared_ptr<MPI_Comm> & cp)62 explicit intercommunicator(const shared_ptr<MPI_Comm>& cp) 63 { 64 this->comm_ptr = cp; 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 */ intercommunicator(const MPI_Comm & comm,comm_create_kind kind)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 */ local_size() const123 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 */ local_rank() const134 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 166