Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages
SAMRAI::tbox::AsyncCommStage

SAMRAI::tbox::AsyncCommStage Class Reference

Stage multiple asynchronous group communications so that the collective can advance asynchronously (as individual underlying MPI requests are completed). More...

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

List of all members.

Public Member Functions

 AsyncCommStage ()
 Construct a stage that may begin allocating and managing groups.
virtual ~AsyncCommStage (void)
 Deallocate groups remaining in the stage and all internal data used to manage groups.
AsyncCommGroup * allocateCommGroup (int nchild, RelaunchableJob *handle=NULL)
 Allocate a group in this stage.
RelaunchableJob * advanceAny ()
 Advance to completion one group (any group) that is currently waiting for communication to complete.
int advanceSome (Array< RelaunchableJob * > &completed)
 Advance to completion one or more groups (any groups) that are currently waiting for communication to complete.
bool isDone () const
 Return whether the stage is done with all requested communications.
bool numberOfOutstandingGroups () const
 Return the number of allocated groups that have pending communication.
bool numberOfOutstandingRequests () const
 Return the number of pending MPI::request objects.

Friends

class StagedGroup

Detailed Description

Stage multiple asynchronous group communications so that the collective can advance asynchronously (as individual underlying MPI requests are completed).

Use this class when you

This class allocates a set of AsyncCommGroup objects and manages the space for their MPI::request's. The requests are staged such that a single MPI_Waitany or MPI_Waitsome call applies to all communication groups allocated by the stage. Thus the communications performed by the AsyncCommGroup objects can complete in the order allowed by the MPI messages. The exact order is NOT deterministic!

To advance the communication operation of any of the allocated AsyncCommGroup objects, use advanceAny() or advanceSome(). In general, advanceSome() has better performance than advanceAny() because it gets around the "starvation" problem. See the MPI documentation for a discussion of starvation.

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, except for allocating and deallocating AsyncCommGroup objects. The public interfaces still remain so the class can compile, but the implementations are trivial.

Constructor & Destructor Documentation

SAMRAI::tbox::AsyncCommStage::AsyncCommStage (   ) 
 

Construct a stage that may begin allocating and managing groups.

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

Deallocate groups remaining in the stage and all internal data used to manage groups.

Member Function Documentation

AsyncCommGroup * SAMRAI::tbox::AsyncCommStage::allocateCommGroup (  int  nchild,
RelaunchableJob *  handle = NULL
) 
 

Allocate a group in this stage.

You may specify a handle associated with the allocated group and pointing back to an object. These pointers are returned when their group communications are completed by the stage methods advanceAny() or advanceSome(). They help identify the user object waiting for the communication to complete.

To use the handle, create a user class inheritting from RelaunchableJob so that any handle can be dynamically casted back to the user class.

Usage outline:

  1. Derive class UserClass from RelaunchableJob. Implement the pure virtual interfaces therein.
  2. Associate a UserClass object with a AsyncCommGroup object by using the address of the UserClass object to allocate the group. See AsyncCommStage::allocateCommGroup().
  3. Use the allocated group to initiate a group communication.
  4. Repeat the above for any number of user objects.
  5. Determine the specific user object associated with the communication completed by AsyncCommStage::advanceAny() and AsyncCommStage::advanceSome() by dynamically casting the output RelaunchableJob pointer to pointers to UserClass objects.

Usage example: 

    * class UserClass : RelaunchableJob { ... };
    * UserClass user_object[10];
    * AsyncCommStage stage;
    * for ( i=0; i<10; ++i ) {
    *    AsyncCommGroup *group =
    *      stage.allocateCommGroup( 2, &user_object[i] );
    *    useGroupToInitiateCommunication(group);
    * }
    * RelaunchableJob *handle = stage.advanceAny();
    * UserClass *completed_user_object = dynamic_cast<UserClass*>(handle);
    *

Allocating a group with a NULL handle works, but you lose the ability to map a specific communication back to a user object. See advanceAny() and advanceSome().

An allocated group should be deallocated using the delete operator when no longer needed. All allocated groups will be deleted when the stage goes out of scope. Since it is an error to delete a group that has pending message requests, it is also an error to delete a stage that has groups with pending message requests.

Parameters:
nchild Number of child branches per tree node (see AsyncCommGroup).
handle Optional pointer back to a user object associated with the group. See class documentation.

RelaunchableJob * SAMRAI::tbox::AsyncCommStage::advanceAny (   ) 
 

Advance to completion one group (any group) that is currently waiting for communication to complete.

This method uses MPI_Waitany, which may be prone to starvation. It is better to use advanceSome(), which uses MPI_Waitsome, which avoids starvation.

Returns:
the RelaunchableJob pointer used to construct the group that is completed. NULL if no group in the stage had incomplete communication.

int SAMRAI::tbox::AsyncCommStage::advanceSome (  Array< RelaunchableJob * > &  completed  ) 
 

Advance to completion one or more groups (any groups) that are currently waiting for communication to complete.

Parameters:
completed Array space to put handleegies associated with the completed communications.
Returns:
number of groups completed or 0 if none have outstanding communication. The strategy pointers corresponding to the completed groups are set in the completed array.

bool SAMRAI::tbox::AsyncCommStage::isDone (   )  const
 

Return whether the stage is done with all requested communications.

bool SAMRAI::tbox::AsyncCommStage::numberOfOutstandingGroups (   )  const
 

Return the number of allocated groups that have pending communication.

bool SAMRAI::tbox::AsyncCommStage::numberOfOutstandingRequests (   )  const
 

Return the number of pending MPI::request objects.

Friends And Related Function Documentation

friend class StagedGroup [friend]
 

The documentation for this class was generated from the following files:
Generated on Fri Dec 2 11:33:32 2005 for SAMRAI by  doxygen 1.4.2