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

```
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.

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

```
int local_size() const;
```
Returns the size of the local group, i.e., the number of local processes that are part of the group.
```
boost::mpi::group local_group() const;
```
Returns the local group, containing all of the local processes in this intercommunicator.
```
int local_rank() const;
```
Returns the rank of this process within the local group.
```
int remote_size() const;
```
Returns the size of the remote group, i.e., the number of processes that are part of the remote group.
```
boost::mpi::group remote_group() const;
```
Returns the remote group, containing all of the remote processes in this intercommunicator.

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