Class group

boost::mpi::group — A group is a representation of a subset of the processes within a communicator.

Synopsis

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


class group {
public:
  // construct/copy/destruct
  group();
  group(const MPI_Group &, bool);

  // public member functions
  optional< int > rank() const;
  int size() const;
  template<typename InputIterator, typename OutputIterator> 
    OutputIterator 
    translate_ranks(InputIterator, InputIterator, const group &, 
                    OutputIterator);
  operator bool() const;
  operator MPI_Group() const;
  template<typename InputIterator> group include(InputIterator, InputIterator);
  template<typename InputIterator> group exclude(InputIterator, InputIterator);
};

Description

The group class allows one to create arbitrary subsets of the processes within a communicator. One can compute the union, intersection, or difference of two groups, or create new groups by specifically including or excluding certain processes. Given a group, one can create a new communicator containing only the processes in that group.

`group` public construct/copy/destruct

```
group();
```
Constructs an empty group.

group(const MPI_Group & in_group, bool adopt);

Constructs a group from an MPI_Group.

This routine allows one to construct a Boost.MPI group from a C MPI_Group. The group object can (optionally) adopt the MPI_Group, after which point the group object becomes responsible for freeing the MPI_Group when the last copy of group disappears.

Parameters:

`adopt`	Whether the `group` should adopt the `MPI_Group`. When true, the `group` object (or one of its copies) will free the group (via `MPI_Comm_free`) when the last copy is destroyed. Otherwise, the user is responsible for calling `MPI_Group_free`.
`in_group`	The `MPI_Group` used to construct this `group`.

`group` public member functions

```
optional< int > rank() const;
```
Determine the rank of the calling process in the group.
This routine is equivalent to MPI_Group_rank.

Returns:

The rank of the calling process in the group, which will be a value in [0, size()). If the calling process is not in the group, returns an empty value.
```
int size() const;
```
Determine the number of processes in the group.
This routine is equivalent to MPI_Group_size.

Returns:

The number of processes in the group.

template<typename InputIterator, typename OutputIterator> 
  OutputIterator 
  translate_ranks(InputIterator first, InputIterator last, 
                  const group & to_group, OutputIterator out);

Translates the ranks from one group into the ranks of the same processes in another group.

This routine translates each of the integer rank values in the iterator range [first, last) from the current group into rank values of the corresponding processes in to_group. The corresponding rank values are written via the output iterator out. When there is no correspondence between a rank in the current group and a rank in to_group, the value MPI_UNDEFINED is written to the output iterator.

Parameters:

`first`	Beginning of the iterator range of ranks in the current group.
`last`	Past the end of the iterator range of ranks in the current group.
`out`	The output iterator to which the translated ranks will be written.
`to_group`	The group that we are translating ranks to.

Returns:

the output iterator, which points one step past the last rank written.

```
operator bool() const;
```
Determines whether the group is non-empty.

Returns:

True if the group is not empty, false if it is empty.
```
operator MPI_Group() const;
```
Retrieves the underlying MPI_Group associated with this group.

Returns:

The MPI_Group handle manipulated by this object. If this object represents the empty group, returns MPI_GROUP_EMPTY.
```
template<typename InputIterator> 
  group include(InputIterator first, InputIterator last);
```
Creates a new group including a subset of the processes in the current group.
This routine creates a new group which includes only those processes in the current group that are listed in the integer iterator range [first, last). Equivalent to MPI_Group_incl.

first The beginning of the iterator range of ranks to include.

last Past the end of the iterator range of ranks to include.

Returns:

A new group containing those processes with ranks [first, last) in the current group.
```
template<typename InputIterator> 
  group exclude(InputIterator first, InputIterator last);
```
Creates a new group from all of the processes in the current group, exluding a specific subset of the processes.
This routine creates a new group which includes all of the processes in the current group except those whose ranks are listed in the integer iterator range [first, last). Equivalent to MPI_Group_excl.

first The beginning of the iterator range of ranks to exclude.

last Past the end of the iterator range of ranks to exclude.

Returns:

A new group containing all of the processes in the current group except those processes with ranks [first, last) in the current group.

Class group

Synopsis

Description

group public construct/copy/destruct

group public member functions

`group` public construct/copy/destruct

`group` public member functions