Chris@16: // Copyright (C) 2007 The Trustees of Indiana University. Chris@16: Chris@16: // Authors: Douglas Gregor Chris@16: // Andrew Lumsdaine Chris@16: Chris@16: // Use, modification and distribution is subject to the Boost Software Chris@16: // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at Chris@16: // http://www.boost.org/LICENSE_1_0.txt) Chris@16: Chris@16: /** @file intercommunicator.hpp Chris@16: * Chris@16: * This header defines the @c intercommunicator class, which permits Chris@16: * communication between different process groups. Chris@16: */ Chris@16: #ifndef BOOST_MPI_INTERCOMMUNICATOR_HPP Chris@16: #define BOOST_MPI_INTERCOMMUNICATOR_HPP Chris@16: Chris@16: #include Chris@16: Chris@16: namespace boost { namespace mpi { Chris@16: Chris@16: /** Chris@16: * INTERNAL ONLY Chris@16: * Chris@16: * Forward declaration of the MPI "group" representation, for use in Chris@16: * the description of the @c intercommunicator class. Chris@16: */ Chris@16: class group; Chris@16: Chris@16: /** Chris@16: * @brief Communication facilities among processes in different Chris@16: * groups. Chris@16: * Chris@16: * The @c intercommunicator class provides communication facilities Chris@16: * among processes from different groups. An intercommunicator is Chris@16: * always associated with two process groups: one "local" process Chris@16: * group, containing the process that initiates an MPI operation Chris@16: * (e.g., the sender in a @c send operation), and one "remote" process Chris@16: * group, containing the process that is the target of the MPI Chris@16: * operation. Chris@16: * Chris@16: * While intercommunicators have essentially the same point-to-point Chris@16: * operations as intracommunicators (the latter communicate only Chris@16: * within a single process group), all communication with Chris@16: * intercommunicators occurs between the processes in the local group Chris@16: * and the processes in the remote group; communication within a group Chris@16: * must use a different (intra-)communicator. Chris@16: * Chris@16: */ Chris@16: class BOOST_MPI_DECL intercommunicator : public communicator Chris@16: { Chris@16: private: Chris@16: friend class communicator; Chris@16: Chris@16: /** Chris@16: * INTERNAL ONLY Chris@16: * Chris@16: * Construct an intercommunicator given a shared pointer to the Chris@16: * underlying MPI_Comm. This operation is used for "casting" from a Chris@16: * communicator to an intercommunicator. Chris@16: */ Chris@16: explicit intercommunicator(const shared_ptr& cp) Chris@16: { Chris@16: this->comm_ptr = cp; Chris@16: } Chris@16: Chris@16: public: Chris@16: /** Chris@16: * Build a new Boost.MPI intercommunicator based on the MPI Chris@16: * intercommunicator @p comm. Chris@16: * Chris@16: * @p comm may be any valid MPI intercommunicator. If @p comm is Chris@16: * MPI_COMM_NULL, an empty communicator (that cannot be used for Chris@16: * communication) is created and the @p kind parameter is Chris@16: * ignored. Otherwise, the @p kind parameter determines how the Chris@16: * Boost.MPI communicator will be related to @p comm: Chris@16: * Chris@16: * - If @p kind is @c comm_duplicate, duplicate @c comm to create Chris@16: * a new communicator. This new communicator will be freed when Chris@16: * the Boost.MPI communicator (and all copies of it) is Chris@16: * destroyed. This option is only permitted if the underlying MPI Chris@16: * implementation supports MPI 2.0; duplication of Chris@16: * intercommunicators is not available in MPI 1.x. Chris@16: * Chris@16: * - If @p kind is @c comm_take_ownership, take ownership of @c Chris@16: * comm. It will be freed automatically when all of the Boost.MPI Chris@16: * communicators go out of scope. Chris@16: * Chris@16: * - If @p kind is @c comm_attach, this Boost.MPI communicator Chris@16: * will reference the existing MPI communicator @p comm but will Chris@16: * not free @p comm when the Boost.MPI communicator goes out of Chris@16: * scope. This option should only be used when the communicator is Chris@16: * managed by the user. Chris@16: */ Chris@16: intercommunicator(const MPI_Comm& comm, comm_create_kind kind) Chris@16: : communicator(comm, kind) { } Chris@16: Chris@16: /** Chris@16: * Constructs a new intercommunicator whose local group is @p local Chris@16: * and whose remote group is @p peer. The intercommunicator can then Chris@16: * be used to communicate between processes in the two groups. This Chris@16: * constructor is equivalent to a call to @c MPI_Intercomm_create. Chris@16: * Chris@16: * @param local The intracommunicator containing all of the Chris@16: * processes that will go into the local group. Chris@16: * Chris@16: * @param local_leader The rank within the @p local Chris@16: * intracommunicator that will serve as its leader. Chris@16: * Chris@16: * @param peer The intracommunicator containing all of the processes Chris@16: * that will go into the remote group. Chris@16: * Chris@16: * @param remote_leader The rank within the @p peer group that will Chris@16: * serve as its leader. Chris@16: */ Chris@16: intercommunicator(const communicator& local, int local_leader, Chris@16: const communicator& peer, int remote_leader); Chris@16: Chris@16: /** Chris@16: * Returns the size of the local group, i.e., the number of local Chris@16: * processes that are part of the group. Chris@16: */ Chris@16: int local_size() const { return this->size(); } Chris@16: Chris@16: /** Chris@16: * Returns the local group, containing all of the local processes in Chris@16: * this intercommunicator. Chris@16: */ Chris@16: boost::mpi::group local_group() const; Chris@16: Chris@16: /** Chris@16: * Returns the rank of this process within the local group. Chris@16: */ Chris@16: int local_rank() const { return this->rank(); } Chris@16: Chris@16: /** Chris@16: * Returns the size of the remote group, i.e., the number of Chris@16: * processes that are part of the remote group. Chris@16: */ Chris@16: int remote_size() const; Chris@16: Chris@16: /** Chris@16: * Returns the remote group, containing all of the remote processes Chris@16: * in this intercommunicator. Chris@16: */ Chris@16: boost::mpi::group remote_group() const; Chris@16: Chris@16: /** Chris@16: * Merge the local and remote groups in this intercommunicator into Chris@16: * a new intracommunicator containing the union of the processes in Chris@16: * both groups. This method is equivalent to @c MPI_Intercomm_merge. Chris@16: * Chris@16: * @param high Whether the processes in this group should have the Chris@16: * higher rank numbers than the processes in the other group. Each Chris@16: * of the processes within a particular group shall have the same Chris@16: * "high" value. Chris@16: * Chris@16: * @returns the new, merged intracommunicator Chris@16: */ Chris@16: communicator merge(bool high) const; Chris@16: }; Chris@16: Chris@16: } } // end namespace boost::mpi Chris@16: Chris@16: #endif // BOOST_MPI_INTERCOMMUNICATOR_HPP