Teuchos Package Browser (Single Doxygen Collection) Version of the Day
Static Private Member Functions | Static Private Attributes
Teuchos::GlobalMPISession Class Reference

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

#include <Teuchos_GlobalMPISession.hpp>

List of all members.

Static Private Member Functions

static void initialize (std::ostream *out)
static void justInTimeInitialize ()

Static Private Attributes

static bool haveMPIState_ = false
static bool mpiIsFinalized_ = false
static int rank_ = 0
static int nProc_ = 1

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 functions

static bool mpiIsInitialized ()
 Return whether MPI was initialized.
static bool mpiIsFinalized ()
 Return whether MPI was already finalized.
static int getRank ()
 The rank of the calling process in MPI_COMM_WORLD.
static int getNProc ()
 The number of processes in MPI_COMM_WORLD.
static void barrier ()
 Call MPI_Barrier() on MPI_COMM_WORLD.
static int sum (int localVal)
 Sum a set of integers across processes.
static void allGather (int localVal, const ArrayView< int > &allVals)
 Global all-to-all of a set of integers across processes.

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 the 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 the most minimal of other members 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 determiing success or failure across processes for unit tests.

Definition at line 102 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.
This constructor may only be called once per executable. Otherwise, it prints an error message to *out and throws an std::runtime_error exception.

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.

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 136 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 142 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.

Definition at line 148 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.

Definition at line 155 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 161 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 170 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 183 of file Teuchos_GlobalMPISession.cpp.

void Teuchos::GlobalMPISession::initialize ( std::ostream *  out) [static, private]

Definition at line 199 of file Teuchos_GlobalMPISession.cpp.

void Teuchos::GlobalMPISession::justInTimeInitialize ( ) [static, private]

Definition at line 247 of file Teuchos_GlobalMPISession.cpp.


Member Data Documentation

bool Teuchos::GlobalMPISession::haveMPIState_ = false [static, private]

Definition at line 242 of file Teuchos_GlobalMPISession.hpp.

bool Teuchos::GlobalMPISession::mpiIsFinalized_ = false [static, private]

Definition at line 243 of file Teuchos_GlobalMPISession.hpp.

int Teuchos::GlobalMPISession::rank_ = 0 [static, private]

Definition at line 244 of file Teuchos_GlobalMPISession.hpp.

int Teuchos::GlobalMPISession::nProc_ = 1 [static, private]

Definition at line 245 of file Teuchos_GlobalMPISession.hpp.


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