The TIMPIInit class, when constructed, initializes any dependent libraries (e.g. More...

#include <timpi_init.h>

Public Member Functions
	TIMPIInit (int argc, const char const argv, int mpi_thread_requested=0, bool handle_mpi_errors=false, MPI_Comm COMM_WORLD_IN=MPI_COMM_WORLD)
	Initialize the library for use, with the command line options provided. More...

	TIMPIInit (int argc, const char const argv, int mpi_thread_requested=0, bool handle_mpi_errors=false)

virtual	~TIMPIInit ()
	Destructor. More...

const Communicator &	comm () const
	Returns the Communicator created by this object, which will be a compatibility shim if MPI is not enabled, or a wrapper for the user-input MPI_Comm if we were constructed with one, or a wrapper for MPI_COMM_WORLD by default. More...

Communicator &	comm ()

Private Attributes
std::unique_ptr< Communicator >	_comm

std::unique_ptr< SemiPermanent::Ref >	_ref

bool	i_initialized_mpi

MPI_Errhandler	my_errhandler

bool	err_handler_set

Detailed Description

The TIMPIInit class, when constructed, initializes any dependent libraries (e.g.

MPI).

For many users, a single TIMPIInit object should be created at the start of your main() function.

Since "it is best not to perform much more than a return rc after calling MPI_Finalize", applications which want to do anything after TIMPIInit destruction should manage MPI initialization and finalization manually.

Definition at line 57 of file timpi_init.h.

Constructor & Destructor Documentation

◆ TIMPIInit() [1/2]

TIMPI::TIMPIInit::TIMPIInit	(	int	argc,
		const char const	argv,
		int	mpi_thread_requested = `0`,
		bool	handle_mpi_errors = `false`,
		MPI_Comm	COMM_WORLD_IN = `MPI_COMM_WORLD`
	)

Initialize the library for use, with the command line options provided.

This will e.g. call MPI_Init_thread if MPI is available and enabled and has not already been initialized.

mpi_thread_requested should be set to 0 when MPI_THREAD_SINGLE is desired, 1 when MPI_THREAD_FUNNELED initialization is desired, 2 when MPI_THREAD_SERIALIZED is desaired, and 3 when MPI_THREAD_MULTIPLE is desired

handle_mpi_errors should be set to true to use the "timpi_not_implemented()" behavior (e.g. throwing an exception) as an MPI error handler, which can aid in debugging.

When building with MPI, this method may take an optional parameter to use a user-specified MPI communicator.

Definition at line 41 of file timpi_init.C.

References _comm, _ref, err_handler_set, i_initialized_mpi, my_errhandler, and TIMPI_MPI_Handler().

                                                     :
   i_initialized_mpi(false),
   err_handler_set(false)
 {
   // Check whether the calling program has already initialized
   // MPI, and avoid duplicate Init/Finalize
   int flag;
   timpi_call_mpi(MPI_Initialized (&flag));
 
   if (!flag)
     {
       int mpi_thread_provided;
 
       timpi_call_mpi
         (MPI_Init_thread (&argc, const_cast<char ***>(&argv),
                           mpi_thread_requested, &mpi_thread_provided));
 
       if (mpi_thread_provided < mpi_thread_requested)
         {
           // Ideally, if an MPI stack tells us it's unsafe for us
           // to use threads, we should scream and die or at least
           // disable threads.
           //
           // In practice, we've encountered one MPI stack (an mvapich2
           // configuration) that returned MPI_THREAD_SINGLE as a
           // proper warning, two stacks that handle
           // MPI_THREAD_FUNNELED properly, and two current stacks plus
           // a couple old stacks that return MPI_THREAD_SINGLE but
           // support threaded runs anyway, so we just emit a warning.
           //
           std::string thread_type;
           switch (mpi_thread_requested)
             {
             case 0:
               thread_type = "MPI_THREAD_SINGLE";
               break;
             case 1:
               thread_type = "MPI_THREAD_FUNNELED";
               break;
             case 2:
               thread_type = "MPI_THREAD_SERIALIZED";
               break;
             case 3:
               thread_type = "MPI_THREAD_MULTIPLE";
               break;
             default:
               timpi_error_msg("Unsupported mpi thread requested '" << mpi_thread_requested << "'");
             }
 
           timpi_warning("Warning: MPI failed to guarantee " << thread_type << "\n"
                            << "for a threaded run.\n"
                            << std::endl);
         }
       this->i_initialized_mpi = true;
     }
 
   // Duplicate the input communicator for internal use
   // And get a Communicator copy too, to use
   // as a default for that API
   this->_comm = std::make_unique<Communicator>(COMM_WORLD_IN);
 
   // Let SemiPermanent know we need its objects for a while
   this->_ref = std::make_unique<SemiPermanent::Ref>();
 
   // Set up an MPI error handler if requested.  This helps us get
   // into a debugger with a proper stack when an MPI error occurs.
   if (handle_mpi_errors)
     {
       timpi_call_mpi
         (MPI_Comm_create_errhandler(TIMPI_MPI_Handler, &my_errhandler));
       timpi_call_mpi
         (MPI_Comm_set_errhandler(COMM_WORLD_IN, my_errhandler));
       timpi_call_mpi
         (MPI_Comm_set_errhandler(MPI_COMM_WORLD, my_errhandler));
       err_handler_set = true;
     }
 }

◆ TIMPIInit() [2/2]

TIMPI::TIMPIInit::TIMPIInit	(	int	argc,
		const char const	argv,
		int	mpi_thread_requested = `0`,
		bool	handle_mpi_errors = `false`
	)

Definition at line 122 of file timpi_init.C.

References _comm, and _ref.

 {
   this->_comm = std::make_unique<Communicator>(); // So comm() doesn't dereference null
   this->_ref = std::make_unique<SemiPermanent::Ref>();
 }

◆ ~TIMPIInit()

TIMPI::TIMPIInit::~TIMPIInit ( )

virtual

Destructor.

Finalizes MPI if that was initialized by TIMPIInit.

Definition at line 133 of file timpi_init.C.

References _comm, _ref, TIMPI::Communicator::barrier(), comm(), err_handler_set, i_initialized_mpi, and my_errhandler.

 {
   // Every processor had better be ready to exit at the same time.
   // This would be a timpi_parallel_only() function, except that
   // timpi_parallel_only() uses timpi_assert() which throws an
   // exception which causes compilers to scream about exceptions
   // inside destructors.
 
   // Even if we're not doing parallel_only debugging, we don't want
   // one processor to try to exit until all others are done working.
   this->comm().barrier();
 
   // Trigger any SemiPermanent cleanup before potentially finalizing MPI
   _ref.reset();
 
 #ifdef TIMPI_HAVE_MPI
   if (err_handler_set)
     {
       unsigned int error_code =
         MPI_Errhandler_free(&my_errhandler);
       if (error_code != MPI_SUCCESS)
         {
           std::cerr <<
             "Failure when freeing MPI_Errhandler! Continuing..." <<
             std::endl;
         }
     }
 
   this->_comm.reset();
 
   if (this->i_initialized_mpi)
     {
       // We can't just timpi_assert here because destructor,
       // but we ought to report any errors
       int error_code = MPI_Finalize();
       if (error_code != MPI_SUCCESS)
         {
           char error_string[MPI_MAX_ERROR_STRING+1];
           int error_string_len;
           MPI_Error_string(error_code, error_string,
                            &error_string_len);
           std::cerr << "Failure from MPI_Finalize():\n"
                     << error_string << std::endl;
         }
     }
 #else
   this->_comm.reset();
 #endif
 }

Member Function Documentation

◆ comm() [1/2]

const Communicator& TIMPI::TIMPIInit::comm ( ) const

inline

Returns the Communicator created by this object, which will be a compatibility shim if MPI is not enabled, or a wrapper for the user-input MPI_Comm if we were constructed with one, or a wrapper for MPI_COMM_WORLD by default.

Definition at line 100 of file timpi_init.h.

References _comm.

Referenced by main(), and ~TIMPIInit().

100 { return *_comm; }

TIMPI::TIMPIInit::_comm

std::unique_ptr< Communicator > _comm

Definition: timpi_init.h:105