Teuchos::GlobalMPISession Class Reference

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

#include <Teuchos_GlobalMPISession.hpp>

List of all members.

Public Member Functions
Public constructor and destructor
	GlobalMPISession (int *argc, char ***argv, std::ostream *out=&std::cout)
	Calls MPI_Init() if MPI is enabled.
	~GlobalMPISession ()
	Call MPI_Finalize() if MPI is enabled.
Static Public Member Functions
Static functions
static bool	mpiIsInitialized ()
	Return whether MPI was initialized.
static bool	mpiIsFinalized ()
	Return whether MPI was already finalized.
static int	getRank ()
	Returns the process rank relative to MPI_COMM_WORLD
static int	getNProc ()
	Returns the number of processors relative to MPI_COMM_WORLD

---

Detailed Description

Initialize, finalize, and query the global MPI session.

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:

 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 (&argc, &argv, NULL);
   // Your code goes here ...
   return 0;
 }

This saves you from needing to remember to call MPI_Init() or MPI_Finalize(). GlobalMPISession cleverly checks whether MPI has been initialized already before calling MPI_Init(), so you can use it in your libraries without needing to know whether users have called MPI_Init() yet.

This class even works if you have not built Trilinos 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 Comm and its subclasses) which allow you to use a subset of MPI functionality without needing to include mpi.h or depend on MPI in any way.

Examples:

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

Definition at line 96 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 each processor will be printed to this stream. The default is &std::cout.

If the option --teuchos-suppress-startup-banner is found, 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). You can always use this class, whether or not Teuchos was built with MPI.

Warning:

This constructor can only be called once per executable. Otherwise, an error is printed to *out and an std::exception will be thrown!

Definition at line 60 of file Teuchos_GlobalMPISession.cpp.

Teuchos::GlobalMPISession::~GlobalMPISession

(

)

Call MPI_Finalize() if MPI is enabled.

Definition at line 121 of file Teuchos_GlobalMPISession.cpp.

---

Member Function Documentation

bool Teuchos::GlobalMPISession::mpiIsInitialized

(

)

[static]

Return whether MPI was initialized.

Definition at line 135 of file Teuchos_GlobalMPISession.cpp.

bool Teuchos::GlobalMPISession::mpiIsFinalized

(

)

[static]

Return whether MPI was already finalized.

Definition at line 141 of file Teuchos_GlobalMPISession.cpp.

int Teuchos::GlobalMPISession::getRank

(

)

[static]

Returns the process rank relative to MPI_COMM_WORLD

Returns 0 if MPI is not enabled.

Note, this function can be called even if the above constructor was never called so it is safe to use no matter how MPI_Init() got called (but it must have been called somewhere).

Examples:

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

Definition at line 146 of file Teuchos_GlobalMPISession.cpp.

int Teuchos::GlobalMPISession::getNProc

(

)

[static]

Returns the number of processors relative to MPI_COMM_WORLD

Returns 1 if MPI is not enabled.

Note, this function can be called even if the above constructor was never called so it is safe to use no matter how MPI_Init() got called (but it must have been called somewhere).

Examples:

FancyOutputting_test.cpp.

Definition at line 153 of file Teuchos_GlobalMPISession.cpp.

---

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

• Teuchos_GlobalMPISession.hpp
• Teuchos_GlobalMPISession.cpp