Initialize, finalize, and query the global MPI session. More...

#include <Teuchos_GlobalMPISession.hpp>

Public Member Functions
Public constructor and destructor
	GlobalMPISession (int argc, char *argv, std::ostream out=&std::cout)
	Calls `MPI_Init()` if MPI is enabled. More...

	~GlobalMPISession ()
	Call `MPI_Finalize()` if MPI is enabled. More...

Static Public Member Functions
Static functions
static void	abort ()
	abort the program More...

static bool	mpiIsInitialized ()
	Return whether MPI was initialized. More...

static bool	mpiIsFinalized ()
	Return whether MPI was already finalized. More...

static int	getRank ()
	The rank of the calling process in `MPI_COMM_WORLD`. More...

static int	getNProc ()
	The number of processes in `MPI_COMM_WORLD`. More...

static void	barrier ()
	Call MPI_Barrier() on `MPI_COMM_WORLD`. More...

static int	sum (int localVal)
	Sum a set of integers across processes. More...

static void	allGather (int localVal, const ArrayView< int > &allVals)
	Global all-to-all of a set of integers across processes. More...

Detailed Description

Initialize, finalize, and query the global MPI session.

int main () {
  (void) MPI_Init (&argc, &argv);
  // Your code goes here ...
  (void) MPI_Finalize ();
  return 0;
}

you would write:

#include <Teuchos_GlobalMPISession.hpp>
int main () {
  Teuchos::GlobalMPISession mpiSession(&argc, &argv, NULL);
  // Your code goes here ...
  return 0;
}

This saves you from needing to remember to call MPI_Init() or MPI_Finalize(). Also, having the GlobalMPISession object's constructor call MPI_Finalize() allows destructors from other objects to call MPI functions. That wold never be possible if you were to directly call MPI_Finalize() at the end of main().

This class even works if you have not built Teuchos with MPI support. In that case, it behaves as if MPI_COMM_WORLD had one process, which is always the calling process. Thus, you can use this class to insulate your code from needing to know about MPI. You don't even have to include mpi.h, as long as your code doesn't directly use MPI routines or types. Teuchos implements wrappers for MPI communicators (see the Teuchos::Comm class and its subclasses in the TeuchosComm subpackage) which allow you to use a very very small subset of MPI functionality without needing to include mpi.h or depend on MPI in any way.

This class also contains the most minimal of other static member functions that are needed for only the most simplistic of tasks needed by other TeuchosCore software. For example, you can do a barrier or sum an int across processes. These are needed by the most basic operations involving output or determining success or failure across processes for unit tests.

GlobalMPISession's static functions cleverly checks whether MPI has been initialized already before calling any MPI functions. Therefore, you can use it in your libraries without requiring that a GlobalMPISession object was created in main().

This class insulates basic main() program type of code from having to know if MPI is enabled or not. The typical use case is to replace an explicit call to MPI_Init() in your main() routine with creation of a GlobalMPISession instance. The instance's destructor (which in this case will be called at the end of main()) then calls MPI_Finalize(). So, instead of writing:

Examples:: ArrayRCP_test.cpp, CommandLineProcessor/cxx_main.cpp, FancyOutputting_test.cpp, and test/MemoryManagement/RCP_test.cpp.

Definition at line 113 of file Teuchos_GlobalMPISession.hpp.

Constructor & Destructor Documentation

Teuchos::GlobalMPISession::GlobalMPISession	(	int *	argc,
		char ***	argv,
		std::ostream *	out = `&std::cout`
	)

Calls MPI_Init() if MPI is enabled.

Parameters

argc	[in] Address of the argument passed into `main(argc,argv)`. Same as the first argument of MPI_Init().
argv	[in] Address of the argument passed into `main(argc,argv)`. Same as the second argument of MPI_Init().
out	[in] If `out != NULL`, then a small message on will be printed to this stream on each process in `MPI_COMM_WORLD`. The default is `&std::cout`.

If the command-line arguments include the option –teuchos-suppress-startup-banner, the this option will be removed from argv[] before being passed to MPI_Init(...), and the startup output message to *out will be suppressed.

If Teuchos was not built with MPI support, the constructor just prints a startup banner (unless the banner was suppressed – see previous paragraph).

Warning: The default third parameter may result in a lot of lines printed to std::cout, if MPI_COMM_WORLD is large! Users should generally pass in NULL for the third argument. On the other hand, it can be useful to see that startup banner, just to know that MPI is working.; If MPI_Initialized() returns true before calling this constructor, then a error message is printed to *out std::terminate() is called. This is the only sane behavior for this constuctor. The very nature of the GlboalMPISession object is to be constructed at the tope of main() outside of a try {} block. If MPI can't be initialized, then the only thing to do is to abort the program. It would not be reasonble to simply not not call MPI_Initialize() becuase this would ignore the input arguments that the user (you) should be expecting to be read.; Any other MPI functions called direclty from within this constructor will result in an error message to be printed and for abort to be called.

Definition at line 75 of file Teuchos_GlobalMPISession.cpp.

Teuchos::GlobalMPISession::~GlobalMPISession ( )

Call MPI_Finalize() if MPI is enabled.

Definition at line 187 of file Teuchos_GlobalMPISession.cpp.

Member Function Documentation

void Teuchos::GlobalMPISession::abort ( )

static

abort the program

Calls MPI_Abort for HAVE_MPI Otherwise calls std::abort

Definition at line 211 of file Teuchos_GlobalMPISession.cpp.

bool Teuchos::GlobalMPISession::mpiIsInitialized ( )

static

Return whether MPI was initialized.

This is always true if the constructor returned. If the constructor was not called, it may or may not be true, depending on whether the user called MPI_Init() themselves. If the constructor was called but threw an exception, then some MPI function returned an error code.

Definition at line 220 of file Teuchos_GlobalMPISession.cpp.

bool Teuchos::GlobalMPISession::mpiIsFinalized ( )

static

Return whether MPI was already finalized.

This is always true if the destructor was called. If the destructor was not called, it may or may not be true, depending on whether the user called MPI_Init() themselves.

Definition at line 226 of file Teuchos_GlobalMPISession.cpp.

int Teuchos::GlobalMPISession::getRank ( )

static

The rank of the calling process in MPI_COMM_WORLD.

Returns: 0 if MPI has not yet been initialized, else the rank of the calling process in MPI_COMM_WORLD.

You may call this method even if the constructor was never called. Thus, it is safe to use no matter how MPI_Init() was called. However, MPI_Init() must have been called somehow in order for this method to return a sensible result.

Examples:: CommandLineProcessor/cxx_main.cpp, and test/MemoryManagement/RCP_test.cpp.

Definition at line 232 of file Teuchos_GlobalMPISession.cpp.

int Teuchos::GlobalMPISession::getNProc ( )

static

The number of processes in MPI_COMM_WORLD.

Returns: 1 if MPI has not yet been initialized, else the number of processes in MPI_COMM_WORLD.

You may call this method even if the constructor was never called. Thus, it is safe to use no matter how MPI_Init() was called. However, MPI_Init() must have been called somehow in order for this method to return a sensible result.

Examples:: FancyOutputting_test.cpp.

Definition at line 239 of file Teuchos_GlobalMPISession.cpp.

void Teuchos::GlobalMPISession::barrier ( )

static

Call MPI_Barrier() on MPI_COMM_WORLD.

This method must be called collectively on all processes in MPI_COMM_WORLD.

Note: Users should invoke barrier through the Teuchos::Comm interface. We only expose this method for Teuchos-internal functionality.

Definition at line 245 of file Teuchos_GlobalMPISession.cpp.

int Teuchos::GlobalMPISession::sum ( int localVal )

static

Sum a set of integers across processes.

This performs an MPI_Allreduce() of localVal over MPI_COMM_WORLD, and returns the result (which is the same on all processes).

This method must be called collectively on all processes in MPI_COMM_WORLD.

Parameters

localVal [in] Value on local process to sum across processes.

Returns: The global sum (on all processes).

Note: Users should invoke reductions through the Teuchos::Comm interface. We only expose this method for Teuchos-internal functionality.

Definition at line 254 of file Teuchos_GlobalMPISession.cpp.

void Teuchos::GlobalMPISession::allGather	(	int	localVal,
		const ArrayView< int > &	allVals
	)

static

Global all-to-all of a set of integers across processes.

This performs an MPI_Allgather() of localVal over MPI_COMM_WORLD, and writes the results (which are the same on all processes) to allVals.

This method must be called collectively on all processes in MPI_COMM_WORLD.

Parameters

localVal	[in] Value on local process to pass to all processes.
allVals	[out] Array (length getNProc()) that gives the value of localVal for each process. On output, allVals[k] is localVal for process k.

Definition at line 267 of file Teuchos_GlobalMPISession.cpp.

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation