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

#include <Teuchos_DefaultMpiComm.hpp>

Inheritance diagram for Teuchos::MpiComm< Ordinal >:

Public Member Functions
int	getTag () const
	The current tag.
Static Public Attributes
static int const	minTag_ = 26000
static int const	maxTag_ = 26099
Private Member Functions
void	setupMembersFromComm ()
	Set internal data members once the rawMpiComm_ data member is valid.
void	assertRank (const int rank, const std::string &rankName) const
	MpiComm ()
Private Attributes
RCP< const OpaqueWrapper < MPI_Comm > >	rawMpiComm_
	The "raw" MPI_Comm (communicator).
int	rank_
	The rank of the calling process.
int	size_
	The number of processes in the communicator.
int	tag_
	The current tag, to use for all MPI functions that need it.
RCP< const OpaqueWrapper < MPI_Errhandler > >	customErrorHandler_
	MPI error handler. If null, MPI uses the default error handler.
Static Private Attributes
static int	tagCounter_ = MpiComm<Ordinal>::minTag_
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.
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 RCP< const OpaqueWrapper< MPI_Comm > > &rawMpiComm, const int defaultTag)
	Construct an MpiComm with a wrapped MPI_Comm and a default tag.
	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

Detailed Description

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

Implementation of Comm that uses MPI for communication.

Template Parameters:

Ordinal The 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:

getRawMpiComm().get() != NULL
*getRawMpiComm() != MPI_COMM_NULL
getSize() > 0
0 <= getRank() && getRank() < getSize()

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 803 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 748 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >

Teuchos::MpiComm< Ordinal >::MpiComm	(	const RCP< const OpaqueWrapper< MPI_Comm > > &	rawMpiComm,
		const int	defaultTag
	)

Construct an MpiComm with a wrapped MPI_Comm and a default tag.

This constructor has the same meaning as the one-argument constructor that takes RCP<const OpaqueWrapper<MPI_Comm> >, except that it sets the default message tag on all processes to defaultTag. This avoids the MPI_Bcast that the other two constructors do.

This constructor is declared private for now, because it is an implementation detail of duplicate(). We may choose to expose it in the future.

Preconditions:

rawMpiComm.get() != NULL
*rawMpiComm != MPI_COMM_NULL
defaultTag is the same on all processes in the given communicator

Definition at line 777 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:

other The communicator to copy from.

Preconditions:

other.getRawMpiComm().get() != NULL && *other.getRawMpiComm() != NULL

Definition at line 830 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal>

Teuchos::MpiComm< Ordinal >::MpiComm ( ) [private]

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 460 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 898 of file Teuchos_DefaultMpiComm.hpp.

template<typename Ordinal >

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

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

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

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

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

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

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

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

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

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

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

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

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

void Teuchos::MpiComm< Ordinal >::assertRank	(	const int	rank,
		const std::string &	rankName
	)		const `[private]`

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Related Functions

Constructors

Implementation of Comm interface

Implementation of Describable interface

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

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