Teuchos - Trilinos Tools Package Version of the Day
Public Member Functions | Related Functions
Teuchos::MpiComm< Ordinal > Class Template Reference

Implementation of Comm that uses MPI for communication. More...

#include <Teuchos_DefaultMpiComm.hpp>

Inheritance diagram for Teuchos::MpiComm< Ordinal >:
Teuchos::Comm< Ordinal > Teuchos::Describable Teuchos::LabeledObject

List of all members.

Public Member Functions

int getTag () const
 The current tag.
Constructors
 MpiComm (MPI_Comm rawMpiComm)
 Construct an MpiComm with an MPI_Comm.
 MpiComm (const RCP< const OpaqueWrapper< MPI_Comm > > &rawMpiComm)
 Construct an MpiComm with the given wrapped MPI_Comm.
 MpiComm (const MpiComm< Ordinal > &other)
 Construct a communicator with a new context with the same properties as the original.
RCP< const OpaqueWrapper
< MPI_Comm > > 
getRawMpiComm () const
 Return the embedded wrapped opaque MPI_Comm object.
void setErrorHandler (const RCP< const OpaqueWrapper< MPI_Errhandler > > &errHandler)
 Set the MPI error handler for this communicator.
Implementation of Comm interface
virtual int getRank () const
 
virtual int getSize () const
 
virtual void barrier () const
 
virtual void broadcast (const int rootRank, const Ordinal bytes, char buffer[]) const
 
virtual void gather (const Ordinal sendBytes, const char sendBuffer[], const Ordinal recvBytes, char recvBuffer[], const int root) const
 Gather values from all processes to the root process.
virtual void gatherAll (const Ordinal sendBytes, const char sendBuffer[], const Ordinal recvBytes, char recvBuffer[]) const
 
virtual void reduceAll (const ValueTypeReductionOp< Ordinal, char > &reductOp, const Ordinal bytes, const char sendBuffer[], char globalReducts[]) const
 
virtual void reduceAllAndScatter (const ValueTypeReductionOp< Ordinal, char > &reductOp, const Ordinal sendBytes, const char sendBuffer[], const Ordinal recvCounts[], char myGlobalReducts[]) const
 
virtual void scan (const ValueTypeReductionOp< Ordinal, char > &reductOp, const Ordinal bytes, const char sendBuffer[], char scanReducts[]) const
 
virtual void send (const Ordinal bytes, const char sendBuffer[], const int destRank) const
 
virtual void send (const Ordinal bytes, const char sendBuffer[], const int destRank, const int tag) const
 
virtual void ssend (const Ordinal bytes, const char sendBuffer[], const int destRank) const
 
virtual void ssend (const Ordinal bytes, const char sendBuffer[], const int destRank, const int tag) const
 Variant of ssend() that takes a message tag.
virtual int receive (const int sourceRank, const Ordinal bytes, char recvBuffer[]) const
 
virtual void readySend (const ArrayView< const char > &sendBuffer, const int destRank) const
 
virtual void readySend (const Ordinal bytes, const char sendBuffer[], const int destRank, const int tag) const
 Variant of readySend() that accepts a message tag.
virtual RCP< CommRequest
< Ordinal > > 
isend (const ArrayView< const char > &sendBuffer, const int destRank) const
 
virtual RCP< CommRequest
< Ordinal > > 
isend (const ArrayView< const char > &sendBuffer, const int destRank, const int tag) const
 Variant of isend() that takes a tag.
virtual RCP< CommRequest
< Ordinal > > 
ireceive (const ArrayView< char > &Buffer, const int sourceRank) const
 
virtual RCP< CommRequest
< Ordinal > > 
ireceive (const ArrayView< char > &Buffer, const int sourceRank, const int tag) const
 
virtual void waitAll (const ArrayView< RCP< CommRequest< Ordinal > > > &requests) const
 
virtual void waitAll (const ArrayView< RCP< CommRequest< Ordinal > > > &requests, const ArrayView< RCP< CommStatus< Ordinal > > > &statuses) const
 
virtual RCP< CommStatus
< Ordinal > > 
wait (const Ptr< RCP< CommRequest< Ordinal > > > &request) const
 
virtual RCP< Comm< Ordinal > > duplicate () const
 
virtual RCP< Comm< Ordinal > > split (const int color, const int key) const
 
virtual RCP< Comm< Ordinal > > createSubcommunicator (const ArrayView< const int > &ranks) const
 
Implementation of Describable interface
std::string description () const
 

Related Functions

(Note that these are not member functions.)

template<typename Ordinal >
RCP< MpiComm< Ordinal > > createMpiComm (const RCP< const OpaqueWrapper< MPI_Comm > > &rawMpiComm)
 Helper function that creates a dynamically allocated MpiComm object or returns Teuchos::null to correctly represent a null communicator.

Detailed Description

template<typename Ordinal>
class Teuchos::MpiComm< Ordinal >

Implementation of Comm that uses MPI for communication.

Template Parameters:
OrdinalThe index type for communication; same as the template parameter of Comm.

This class uses MPI (the Message Passing Interface) to implement the Comm interface. It includes constructors that take an MPI_Comm from the application.

Assertions:

Definition at line 373 of file Teuchos_DefaultMpiComm.hpp.


Constructor & Destructor Documentation

template<typename Ordinal >
Teuchos::MpiComm< Ordinal >::MpiComm ( MPI_Comm  rawMpiComm) [explicit]

Construct an MpiComm with an MPI_Comm.

This constructs an MpiComm that uses the given "raw" MPI communicator underneath. The MPI_Comm must be valid for the lifetime of this MpiComm. You are responsible for freeing the MPI_Comm (using MPI_Comm_free) if necessary.

This constructor should be used only in one of two cases: 1. When the given MPI_Comm is one of the predefined communicators that need not and must not be freed after use, like MPI_COMM_WORLD or MPI_COMM_SELF. 2. When you know that the given MPI_Comm will not be freed until after the lifetime of this MpiComm.

If you cannot be sure of either of these two conditions, you should use the version of the constructor that takes an RCP<const OpaqueWrapper<MPI_Comm> >.

Precondition:

  • rawMpiComm != MPI_COMM_NULL

Definition at line 753 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
Teuchos::MpiComm< Ordinal >::MpiComm ( const RCP< const OpaqueWrapper< MPI_Comm > > &  rawMpiComm)

Construct an MpiComm with the given wrapped MPI_Comm.

This constructs an MpiComm that uses the given "raw" MPI communicator underneath. This version of the constructor accepts the MPI_Comm wrapped in an OpaqueWrapper, which along with the RCP has the option to free the MPI_Comm (via MPI_Comm_free) after use if necessary. You are responsible when creating the OpaqueWrapper for supplying a "free" function if needed. We recommend using details::safeCommFree for the "free" function, if one is needed.

Preconditions:

  • rawMpiComm.get() != NULL
  • *rawMpiComm != MPI_COMM_NULL

Definition at line 725 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
Teuchos::MpiComm< Ordinal >::MpiComm ( const MpiComm< Ordinal > &  other)

Construct a communicator with a new context with the same properties as the original.

The newly constructed communicator will have a duplicate communication space that has the same properties (e.g. processes, attributes, topologies) as the input communicator.

Parameters:
otherThe communicator to copy from.

Preconditions:

Definition at line 780 of file Teuchos_DefaultMpiComm.hpp.


Member Function Documentation

template<typename Ordinal>
RCP<const OpaqueWrapper<MPI_Comm> > Teuchos::MpiComm< Ordinal >::getRawMpiComm ( ) const [inline]

Return the embedded wrapped opaque MPI_Comm object.

Definition at line 438 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::setErrorHandler ( const RCP< const OpaqueWrapper< MPI_Errhandler > > &  errHandler)

Set the MPI error handler for this communicator.

Parameters:
errHandler[in] The error handler to set. If null, do nothing.

MPI lets you set an error handler function specific to each communicator. (See Section 8.3 of the MPI 3.0 Standard.) MpiComm wraps this functionality using this method. You must first either create an error handler using MPI_Comm_create_errhandler() (or MPI_Errhandler_create() if you are stuck with an MPI 1 implementation), or use one of the default error handlers that the MPI standard or your MPI implementation provides. You will need to wrap the MPI error handler in an OpaqueWrapper. (See the documentation of OpaqueWrapper for the rationale behind not using MPI's opaque objects directly.)

MpiComm will not attempt to call MPI_Errhandler_free() on the error handler you provide. You are responsible for arranging that this be done. Note that MPI_Comm_create_errhandler() (which creates an error handler, given a function pointer) does not attach the error handler to an MPI_Comm, so the lifetime of the error handler is not tied to the MPI_Comm to which it is assigned. An error handler can be assigned to more than one MPI_Comm, in fact. You just need to guarantee that if you create a custom error handler, then that handler gets freed at some point. "The call to MPI_FINALIZE does not free objects created by MPI calls; these objects are freed using MPI_xxx_FREE calls" (Section 8.7, MPI 3.0 Standard). Note that it is legitimate to call MPI_Errhandler_free() right after setting the MPI_Comm's error handler; see Section 8.3.4 of the MPI 3.0 Standard ("The error handler [given to MPI_Errhandler_free] will be deallocated after all the objects associated with it (communicator, window, or file) have been deallocated"). You might instead attach your error handler as a attribute to MPI_COMM_SELF, in such a way that MPI_Errhandler_free() will be called when MPI_COMM_SELF is freed (which MPI_Finalize() does automatically). We do not take responsibility for doing any of these things; you are responsible for freeing the error handler.

Here is an example showing how to change an MpiComm's error handler. The default error handler for any MPI_Comm is MPI_ERRORS_ARE_FATAL. This handler immediately aborts if MPI encounters an error, without returning an error code from the MPI function. Suppose that instead you would like MPI functions to return an error code if MPI should encounter an error. (In that case, Teuchos' MPI wrappers will detect the returned error code and throw an exception with an appropriate error message. If MPI aborts immediately on error, Teuchos won't have the chance to detect and report the error.) If so, you may set the error handler to MPI_ERRORS_RETURN, one of MPI's built-in error handlers. Here is how you may do this for an MpiComm:

 // Suppose that you've already created this MpiComm.
 RCP<const MpiComm<int> > comm = ...; 

 // Wrap the error handler.
 RCP<const OpaqueWrapper<MPI_Errhandler> > errHandler =
   rcp (new OpaqueWrapper<MPI_Errhandler> (MPI_ERRORS_RETURN));
 // Set the MpiComm's error handler.
 comm->setErrorHandler (errHandler);

Definition at line 848 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
int Teuchos::MpiComm< Ordinal >::getRank ( ) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 866 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
int Teuchos::MpiComm< Ordinal >::getSize ( ) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 873 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::barrier ( ) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 880 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::broadcast ( const int  rootRank,
const Ordinal  bytes,
char  buffer[] 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 893 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::gather ( const Ordinal  sendBytes,
const char  sendBuffer[],
const Ordinal  recvBytes,
char  recvBuffer[],
const int  root 
) const [virtual]

Gather values from all processes to the root process.

Implements Teuchos::Comm< Ordinal >.

Definition at line 931 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::gatherAll ( const Ordinal  sendBytes,
const char  sendBuffer[],
const Ordinal  recvBytes,
char  recvBuffer[] 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 908 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::reduceAll ( const ValueTypeReductionOp< Ordinal, char > &  reductOp,
const Ordinal  bytes,
const char  sendBuffer[],
char  globalReducts[] 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 952 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::reduceAllAndScatter ( const ValueTypeReductionOp< Ordinal, char > &  reductOp,
const Ordinal  sendBytes,
const char  sendBuffer[],
const Ordinal  recvCounts[],
char  myGlobalReducts[] 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 981 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::scan ( const ValueTypeReductionOp< Ordinal, char > &  reductOp,
const Ordinal  bytes,
const char  sendBuffer[],
char  scanReducts[] 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1050 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::send ( const Ordinal  bytes,
const char  sendBuffer[],
const int  destRank 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1069 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::send ( const Ordinal  bytes,
const char  sendBuffer[],
const int  destRank,
const int  tag 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1094 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::ssend ( const Ordinal  bytes,
const char  sendBuffer[],
const int  destRank 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1110 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::ssend ( const Ordinal  bytes,
const char  sendBuffer[],
const int  destRank,
const int  tag 
) const [virtual]

Variant of ssend() that takes a message tag.

Implements Teuchos::Comm< Ordinal >.

Definition at line 1134 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
int Teuchos::MpiComm< Ordinal >::receive ( const int  sourceRank,
const Ordinal  bytes,
char  recvBuffer[] 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1193 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::readySend ( const ArrayView< const char > &  sendBuffer,
const int  destRank 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1149 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::readySend ( const Ordinal  bytes,
const char  sendBuffer[],
const int  destRank,
const int  tag 
) const [virtual]

Variant of readySend() that accepts a message tag.

Implements Teuchos::Comm< Ordinal >.

Definition at line 1176 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< CommRequest< Ordinal > > Teuchos::MpiComm< Ordinal >::isend ( const ArrayView< const char > &  sendBuffer,
const int  destRank 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1225 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< CommRequest< Ordinal > > Teuchos::MpiComm< Ordinal >::isend ( const ArrayView< const char > &  sendBuffer,
const int  destRank,
const int  tag 
) const [virtual]

Variant of isend() that takes a tag.

Implements Teuchos::Comm< Ordinal >.

Definition at line 1247 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< CommRequest< Ordinal > > Teuchos::MpiComm< Ordinal >::ireceive ( const ArrayView< char > &  Buffer,
const int  sourceRank 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1269 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< CommRequest< Ordinal > > Teuchos::MpiComm< Ordinal >::ireceive ( const ArrayView< char > &  Buffer,
const int  sourceRank,
const int  tag 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1292 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::waitAll ( const ArrayView< RCP< CommRequest< Ordinal > > > &  requests) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1534 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
void Teuchos::MpiComm< Ordinal >::waitAll ( const ArrayView< RCP< CommRequest< Ordinal > > > &  requests,
const ArrayView< RCP< CommStatus< Ordinal > > > &  statuses 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1546 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< CommStatus< Ordinal > > Teuchos::MpiComm< Ordinal >::wait ( const Ptr< RCP< CommRequest< Ordinal > > > &  request) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1570 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< Comm< Ordinal > > Teuchos::MpiComm< Ordinal >::duplicate ( ) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1588 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< Comm< Ordinal > > Teuchos::MpiComm< Ordinal >::split ( const int  color,
const int  key 
) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1608 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
RCP< Comm< Ordinal > > Teuchos::MpiComm< Ordinal >::createSubcommunicator ( const ArrayView< const int > &  ranks) const [virtual]

Implements Teuchos::Comm< Ordinal >.

Definition at line 1634 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >
std::string Teuchos::MpiComm< Ordinal >::description ( ) const [virtual]

Reimplemented from Teuchos::Describable.

Definition at line 1702 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal>
int Teuchos::MpiComm< Ordinal >::getTag ( ) const [inline, virtual]

The current tag.

Warning:
This method is ONLY for use by Teuchos developers. Users should not depend on the interface of this method. It may change or disappear at any time without warning.

Implements Teuchos::Comm< Ordinal >.

Definition at line 640 of file Teuchos_DefaultMpiComm.hpp.


Friends And Related Function Documentation

template<typename Ordinal >
RCP< MpiComm< Ordinal > > createMpiComm ( const RCP< const OpaqueWrapper< MPI_Comm > > &  rawMpiComm) [related]

Helper function that creates a dynamically allocated MpiComm object or returns Teuchos::null to correctly represent a null communicator.

Postconditions: [rawMpiComm.get()!=NULL && *rawMpiComm!=MPI_COMM_NULL] return.get()!=NULL [rawMpiComm.get()==NULL || *rawMpiComm==MPI_COMM_NULL] return.get()==NULL


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