TIMPI::TIMPIInit Class Reference

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.
	TIMPIInit (int argc, const char *const *argv, int mpi_thread_requested=0, bool handle_mpi_errors=false)
virtual	~TIMPIInit ()
	Destructor.
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.
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 44 of file timpi_init.C.

                                                    :
  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;
    }
}

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

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 125 of file timpi_init.C.

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

References _comm, and _ref.

~TIMPIInit()

TIMPI::TIMPIInit::~TIMPIInit ( )

virtual

Destructor.

Finalizes MPI if that was initialized by TIMPIInit.

Definition at line 136 of file timpi_init.C.

{
  // Every processor had better be ready to exit at the same time.
  // 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.
 
  // We could be destructing here because we're unwinding the stack
  // due to a thrown exception, though.  It's possible that an
  // application is catching exceptions outside of the LibMeshInit
  // scope, or that we're using a C++ compiler that does unwinding
  // for uncaught exceptions (the standard says whether to go straight
  // to terminate() or unwind first is "implementation-defined").  If
  // *that* is the case then we can't safely communicate with other
  // processors that might not all be unwinding too.
#ifdef TIMPI_ENABLE_EXCEPTIONS
  if (!std::uncaught_exceptions())
#endif
    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
}

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

Member Function Documentation

comm() [1/2]

Communicator & TIMPI::TIMPIInit::comm ( )

inline

Definition at line 102 of file timpi_init.h.

{ return *_comm; }

References _comm.

comm() [2/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.

{ return *_comm; }

References _comm.

Referenced by ~TIMPIInit().

Member Data Documentation

_comm

std::unique_ptr<Communicator> TIMPI::TIMPIInit::_comm

private

Definition at line 105 of file timpi_init.h.

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

_ref

std::unique_ptr<SemiPermanent::Ref> TIMPI::TIMPIInit::_ref

private

Definition at line 108 of file timpi_init.h.

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

err_handler_set

bool TIMPI::TIMPIInit::err_handler_set

private

Definition at line 114 of file timpi_init.h.

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

i_initialized_mpi

bool TIMPI::TIMPIInit::i_initialized_mpi

private

Definition at line 111 of file timpi_init.h.

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

my_errhandler

MPI_Errhandler TIMPI::TIMPIInit::my_errhandler

private

Definition at line 113 of file timpi_init.h.

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

---

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

• src/utilities/include/timpi/timpi_init.h
• src/utilities/src/timpi_init.C