| Home | Libraries | People | FAQ | More

## Class intercommunicator

boost::mpi::intercommunicator — Communication facilities among processes in different groups.

## Synopsis

    // In header: <boost/mpi/intercommunicator.hpp>

    class intercommunicator : public boost::mpi::communicator {
    public:
      // construct/copy/destruct
      intercommunicator(const MPI_Comm &, comm_create_kind);
      intercommunicator(const communicator &, int, const communicator &, int);

      // public member functions
      int local_size() const;
      boost::mpi::group local_group() const;
      int local_rank() const;
      int remote_size() const;
      boost::mpi::group remote_group() const;
      communicator merge(bool) const;
    };

## Description

The `intercommunicator` class provides communication facilities among processes from different groups. An intercommunicator is always associated with two process groups: one "local" process group, containing the process that initiates an MPI operation (e.g., the sender in a `send` operation), and one "remote" process group, containing the process that is the target of the MPI operation.

While intercommunicators have essentially the same point-to-point operations as intracommunicators (the latter communicate only within a single process group), all communication with intercommunicators occurs between the processes in the local group and the processes in the remote group; communication within a group must use a different (intra-)communicator.

### `intercommunicator` public construct/copy/destruct

1.     intercommunicator(const MPI_Comm & comm, comm_create_kind kind);

   Build a new Boost.MPI intercommunicator based on the MPI intercommunicator `comm`.

   `comm` may be any valid MPI intercommunicator. If `comm` is MPI_COMM_NULL, an empty communicator (that cannot be used for communication) is created and the `kind` parameter is ignored. Otherwise, the `kind` parameter determines how the Boost.MPI communicator will be related to `comm:`

   - If `kind` is `comm_duplicate`, duplicate `comm` to create a new communicator. This new communicator will be freed when the Boost.MPI communicator (and all copies of it) is destroyed. This option is only permitted if the underlying MPI implementation supports MPI 2.0; duplication of intercommunicators is not available in MPI 1.x.

   - If `kind` is `comm_take_ownership`, take ownership of `comm`. It will be freed automatically when all of the Boost.MPI communicators go out of scope.

   - If `kind` is `comm_attach`, this Boost.MPI communicator will reference the existing MPI communicator `comm` but will not free `comm` when the Boost.MPI communicator goes out of scope. This option should only be used when the communicator is managed by the user.

2.     intercommunicator(const communicator & local, int local_leader,
                         const communicator & peer, int remote_leader);

   Constructs a new intercommunicator whose local group is `local` and whose remote group is `peer`. The intercommunicator can then be used to communicate between processes in the two groups. This constructor is equivalent to a call to `MPI_Intercomm_create`.

   Parameters: |
   `local` | The intracommunicator containing all of the processes that will go into the local group.
   `local_leader` | The rank within the `local` intracommunicator that will serve as its leader.
   `peer` | The intracommunicator containing all of the processes that will go into the remote group.
   `remote_leader` | The rank within the `peer` group that will serve as its leader.

### `intercommunicator` public member functions

1.     int local_size() const;

   Returns the size of the local group, i.e., the number of local processes that are part of the group.

2.     boost::mpi::group local_group() const;

   Returns the local group, containing all of the local processes in this intercommunicator.

3.     int local_rank() const;

   Returns the rank of this process within the local group.

4.     int remote_size() const;

   Returns the size of the remote group, i.e., the number of processes that are part of the remote group.

5.     boost::mpi::group remote_group() const;

   Returns the remote group, containing all of the remote processes in this intercommunicator.

6.     communicator merge(bool high) const;

   Merge the local and remote groups in this intercommunicator into a new intracommunicator containing the union of the processes in both groups. This method is equivalent to `MPI_Intercomm_merge`.

   Parameters: |
   `high` | Whether the processes in this group should have the higher rank numbers than the processes in the other group. Each of the processes within a particular group shall have the same "high" value.
   Returns: | the new, merged intracommunicator