SAMRAI::tbox::AsyncCommGroup

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 setMPITag (const int mpi_tag)
 Set the MPI tag used for communication within the group.
void setMPICommunicator (SAMRAI_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.
int getNumberOfChildren () const
void logCurrentState (std::ostream &co) const
Define the communication group
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.
Communication methods
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.

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

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 ( SAMRAI_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 ( std::ostream &  co  )  const

The documentation for this class was generated from the following files:
Generated on Thu Jun 18 11:29:06 2009 for SAMRAI by  doxygen 1.5.1