SAMRAI::tbox::AsyncCommGroup Class Reference

Supports many-to-one and one-to-many asynchronous communication operations within a given group of processes by sending messages along the branches of a conceptual tree. More...

#include <source/toolbox/parallel/AsyncCommGroup.h>

List of all members.

Public Member Functions
	AsyncCommGroup (const int nchild)
	Construct communication group.
virtual	~AsyncCommGroup (void)
	Destructor.
void	setGroupAndRootIndex (const Array< int > &group, const int root_index)
	Setup the tree for the given group of processes. The root process is specified by its index in the group array.
void	setGroupAndRootRank (const Array< int > &group, const int root_rank)
	Setup the group for the given group. The root process is specified by its rank.
void	setMPITag (const int mpi_tag)
	Set the MPI tag used for communication within the group.
void	setMPICommunicator (MPI::comm &mpi_communicator)
	Set the MPI communicator used for communication within the group.
void	setUseBlockingSendToParent (const bool flag)
	Set whether sends to parents should be blocking.
void	setUseBlockingSendToChildren (const bool flag)
	Set whether sends to children should be blocking.
bool	beginBcast (int *buffer, int size)
	Begin a broadcast communication.
bool	checkBcast ()
	Check the current broadcast communication and complete the broadcast if all MPI requests are fulfilled.
bool	beginGather (int *buffer, int size)
	Begin a gather communication.
bool	checkGather ()
	Check the current gather communication and complete the gather if all MPI requests are fulfilled.
bool	beginSumReduce (int *buffer, int size)
	Begin a sum reduce communication.
bool	checkSumReduce ()
	Check the current sum reduce communication and complete the sum reduce if all MPI requests are fulfilled.
bool	checkOperation ()
	Check the current communication and complete it if all MPI requests are fulfilled.
void	waitOperation ()
	Wait for the current operation to complete.
bool	isDone () const
	Whether the last communication operation has finished.
int	getNumberOfChildren () const
void	logCurrentState (ostream &co) const

---

Detailed Description

Supports many-to-one and one-to-many asynchronous communication operations within a given group of processes by sending messages along the branches of a conceptual tree.

This class was created to perform certain group communications without using MPI global communications, which require creating new MPI communicators (can be expensive) and does not support asynchronous operations.

The supported communications are asynchronous in that you can start one and wait for it or check back on it occassionally until it completes. Asynchronous operations in conjunction with other groups can be done by using a AsyncCommStage to allocate the groups and to check for completed communications.

Supported operations are currently broadcast, gather and sum reduce. Only integer data is supported.

A tree is an acyclic graph in which a node at position pos has nchild children, and the following positions for its

• parent: (pos-1)/nchild
• first (oldest) child: pos*nchild+1
• last (youngest) child: (pos+1)*nchild

For example, nchild=2 corresponds to a binary tree.

Communication is done by sending messages toward the root (for all-to-one operations) or leaves (for one-to-all operations). For the former, we receive data from the children and send to the parent. For the latter, we receive from the parent and send to the children. Thus every communication involves a receive and a send (except at the root and leaf nodes of the tree).

Using a tree generally gives better performance than having all processes in the the tree communicate directly with the root process. Using MPI communicators corresponding to the groups may faster than using this class, but the cost of creating MPI communicators MAY be expensive.

This class supports communication and uses MPI for message passing. If MPI is disabled, the job of this class disappears and the class is effectively empty. The public interfaces still remain so the class can compile, but the implementations are trivial.

---

Constructor & Destructor Documentation

SAMRAI::tbox::AsyncCommGroup::AsyncCommGroup (  const int  nchild  )

Construct communication group. The number of children per node is flexible. Parameters: nchild  Number of children per node in the group, i.e., nchild=2 is a binary tree.

SAMRAI::tbox::AsyncCommGroup::~AsyncCommGroup (  void   )  [virtual]

Destructor.

---

Member Function Documentation

void SAMRAI::tbox::AsyncCommGroup::setGroupAndRootIndex (  const Array< int > &  group, const int  root_index )

Setup the tree for the given group of processes. The root process is specified by its index in the group array. The root is specified by dereferencing group array with root_index.

void SAMRAI::tbox::AsyncCommGroup::setGroupAndRootRank (  const Array< int > &  group, const int  root_rank )

Setup the group for the given group. The root process is specified by its rank. The rank of the root is root_rank, which must be one of the ranks given in the group.

void SAMRAI::tbox::AsyncCommGroup::setMPITag (  const int  mpi_tag  )  [inline]

Set the MPI tag used for communication within the group. Attention: This class is NOT (and cannot be) responsible for ensuring that the MPI communicator and tag are sufficient to select the correct messages. Please specify appropriate values for the MPI communicator and tag. Very elusive bugs can occur if incorrect messages are received.

void SAMRAI::tbox::AsyncCommGroup::setMPICommunicator (  MPI::comm &  mpi_communicator  )  [inline]

Set the MPI communicator used for communication within the group. Attention: This class is NOT (and cannot be) responsible for ensuring that the MPI communicator and tag are sufficient to select the correct messages. Please specify appropriate values for the MPI communicator and tag. Very elusive bugs can occur if incorrect messages are received. To be safe, it is best to create a new communicator to avoid interference with other communications within SAMRAI.

void SAMRAI::tbox::AsyncCommGroup::setUseBlockingSendToParent (  const bool  flag  )  [inline]

Set whether sends to parents should be blocking. The default is to use blocking send to parent. Because there is just one parent, short messages can be buffered by MPI to improve the performance of blocking sends. Blocking sends need not be checked for completion.

void SAMRAI::tbox::AsyncCommGroup::setUseBlockingSendToChildren (  const bool  flag  )  [inline]

Set whether sends to children should be blocking. The default is to use nonblocking send to children. Nonblocking sends to children are generally appropriate as there are multiple children.

bool SAMRAI::tbox::AsyncCommGroup::beginBcast (  int *  buffer, int  size )

Begin a broadcast communication. Root process of broadcast may send less data (smaller size) than receivers of broadcast, in which case the missing data is considered irrelevant by the root. If this method returns false, checkBcast() must be called until it returns true before any change in object state is allowed. Returns: Whether operation is completed.

bool SAMRAI::tbox::AsyncCommGroup::checkBcast (   )

Check the current broadcast communication and complete the broadcast if all MPI requests are fulfilled. If no communication is in progress, this call does nothing. Returns: Whether operation is completed.

bool SAMRAI::tbox::AsyncCommGroup::beginGather (  int *  buffer, int  size )

Begin a gather communication. Sending processes of gather may send less data (smaller size) than receivers of broadcast, in which case the missing data is considered irrelevant by the sender. If this method returns false, checkGather() must be called until it returns true before any change in object state is allowed. On non-root processes, buffer should contain the data to be gathered. On the root process, it should have enough space for all the data from all the processes in the group. Parameters: buffer  Data to gather. size  Size of data contributed by each process. Returns: Whether operation is completed.

bool SAMRAI::tbox::AsyncCommGroup::checkGather (   )

Check the current gather communication and complete the gather if all MPI requests are fulfilled. Returns: Whether operation is completed.

bool SAMRAI::tbox::AsyncCommGroup::beginSumReduce (  int *  buffer, int  size )

Begin a sum reduce communication. Assume all messages are the same size. If this method returns false, checkSumReduce() must be called until it returns true before any change in object state is allowed. Buffer should contain the data to be gathered. Returns: Whether operation is completed.

bool SAMRAI::tbox::AsyncCommGroup::checkSumReduce (   )

Check the current sum reduce communication and complete the sum reduce if all MPI requests are fulfilled. Returns: Whether operation is completed.

bool SAMRAI::tbox::AsyncCommGroup::checkOperation (   )

Check the current communication and complete it if all MPI requests are fulfilled.

void SAMRAI::tbox::AsyncCommGroup::waitOperation (   )

Wait for the current operation to complete.

bool SAMRAI::tbox::AsyncCommGroup::isDone (   )  const [inline]

Whether the last communication operation has finished.

int SAMRAI::tbox::AsyncCommGroup::getNumberOfChildren (   )  const [inline]

void SAMRAI::tbox::AsyncCommGroup::logCurrentState (  ostream &  co  )  const

---

The documentation for this class was generated from the following files:

• source/toolbox/parallel/AsyncCommGroup.h
• source/toolbox/parallel/AsyncCommGroup.C
• source/toolbox/parallel/AsyncCommGroup.I

---