Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
PrevUpHomeNext

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.

Copyright © 2005-2007 Douglas Gregor, Matthias Troyer, Trustees of Indiana University

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt"> http://www.boost.org/LICENSE_1_0.txt </ulink>)

PrevUpHomeNext