Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | List of all members
Teuchos::CommRequest< OrdinalType > Class Template Referenceabstract

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

#include <Teuchos_Comm.hpp>

Inheritance diagram for Teuchos::CommRequest< OrdinalType >:
Teuchos::Describable Teuchos::LabeledObject

Public Member Functions

virtual ~CommRequest ()
 Destructor; cancels the request if it is still pending. More...
 
virtual RCP< CommStatus
< OrdinalType > > 
wait ()=0
 Wait on this request (a blocking operation). More...
 
- Public Member Functions inherited from Teuchos::Describable
virtual std::string description () const
 Return a simple one-line description of this object. More...
 
virtual void describe (FancyOStream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 Print the object with some verbosity level to a FancyOStream. More...
 
void describe (std::ostream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 Version of describe() that takes an std::ostream instead of a FancyOStream. More...
 
virtual ~Describable ()
 Destructor (marked virtual for memory safety of derived classes). More...
 
- Public Member Functions inherited from Teuchos::LabeledObject
 LabeledObject ()
 Construct with an empty label. More...
 
virtual ~LabeledObject ()
 
virtual void setObjectLabel (const std::string &objectLabel)
 Set the object label (see LabeledObject). More...
 
virtual std::string getObjectLabel () const
 Get the object label (see LabeledObject). More...
 

Additional Inherited Members

- Static Public Attributes inherited from Teuchos::Describable
static const EVerbosityLevel verbLevel_default = VERB_DEFAULT
 Default value for the verbLevel argument of describe(). More...
 

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 ( )
inlinevirtual

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).


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