| Home | Libraries | People | FAQ | More

## 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

1.     group();

   Constructs an empty group.

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

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

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

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

4.     operator bool() const;

   Determines whether the group is non-empty.

   Returns: | True if the group is not empty, false if it is empty.

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

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

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