Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Public Member Functions
Teuchos::CommRequest< OrdinalType > Class Template Reference

Encapsulation of a pending nonblocking communication operation. More...

#include <Teuchos_Comm.hpp>

Inheritance diagram for Teuchos::CommRequest< OrdinalType >:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual ~CommRequest ()
 Destructor; cancels the request if it is still pending.
virtual RCP< CommStatus
< OrdinalType > > 
wait ()=0
 Wait on this request (a blocking operation).

Detailed Description

template<class OrdinalType>
class Teuchos::CommRequest< OrdinalType >

Encapsulation of a pending nonblocking communication operation.

Template Parameters:
OrdinalTypeSame as the template parameter of Comm.

An instance of (a subclass of) this class represents a nonblocking communication operation, such as a nonblocking send, receive, or collective. To wait on the communication operation, you may give the CommRequest to functions like wait() or waitAll() (which may be found in Teuchos_CommHelpers.hpp). Here is an example of how to use wait().

 const int sourceRank = ...; // Rank of the sending process.
 RCP<const Comm<int> > comm = ...; // The communicator.
 ArrayRCP<double> buf (...); // Buffer for incoming data.
 RCP<CommRequest<int> > req = ireceive (comm, buf, sourceRank);

 // ... Do some other things ...

 // Wait on the request.  This blocks on the sending process.
 // When it finishes, it invalidates the req reference, and
 // returns a status (which wraps MPI_Status in an MPI
 // implementation).
 RCP<CommStatus<int> > status = wait (comm, ptr (&req));

This object's destructor cancels the request without communication. If you wish, you may rely on this behavior for speculative communication. For example:

 const int sourceRank = ...; // Rank of the sending process.
 RCP<const Comm<int> > comm = ...; // The communicator.
 ArrayRCP<double> buf (...); // Buffer for incoming data.
 RCP<CommRequest<int> > req = ireceive (comm, buf, sourceRank);

 // ... Do some other things ...
 // ... Find out we didn't need to receive data ...

 // This cancels the request.  We could also just let
 // the one reference to the request fall out of scope.
 req = null;
Note:
To implementers: The MPI implementation of this class (MpiCommRequest) wraps MPI_Request. The MPI version of waitAll() will need to unpack the array of wrapped requests, and then pack up the resulting MPI_Request after waiting on them. It would be preferable to have a class CommRequests that encapsulates a set of requests, so that you can avoid this unpacking and packing.

Definition at line 137 of file Teuchos_Comm.hpp.


Constructor & Destructor Documentation

template<class OrdinalType>
virtual Teuchos::CommRequest< OrdinalType >::~CommRequest ( ) [inline, virtual]

Destructor; cancels the request if it is still pending.

Canceling a communication request must always be a local operation. An MPI implementation may achieve this by first calling MPI_Cancel to cancel the request, then calling MPI_Wait (which behaves as a local operation for a canceled request) to complete the canceled request (as required by the MPI standard).

Definition at line 146 of file Teuchos_Comm.hpp.


Member Function Documentation

template<class OrdinalType>
virtual RCP<CommStatus<OrdinalType> > Teuchos::CommRequest< OrdinalType >::wait ( ) [pure virtual]

Wait on this request (a blocking operation).

Implemented in Teuchos::MpiCommRequestBase< OrdinalType >, and Teuchos::MpiCommRequestBase< int >.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines