libMesh::LibMeshInit Class Reference

The LibMeshInit class, when constructed, initializes the dependent libraries (e.g. More...

#include <libmesh.h>

Public Member Functions
	LibMeshInit (int argc, const char *const *argv, MPI_Comm COMM_WORLD_IN=MPI_COMM_WORLD, int n_threads=-1)
	Initialize the library for use, with the command line options provided. More...
	LibMeshInit (int argc, const char *const *argv, int COMM_WORLD_IN=0, int n_threads=-1)
virtual	~LibMeshInit ()
	Destructor. More...
const Parallel::Communicator &	comm () const
	Returns a Communicator created from the TIMPIInit object we hold, which will be a compatibility shim if MPI is not enabled. More...
Parallel::Communicator &	comm ()

Static Private Member Functions
static PerfLog &	perf_log ()

Private Attributes
TIMPI::TIMPIInit *	_timpi_init
Parallel::Communicator *	_comm
vtkMPIController *	_vtk_mpi_controller

Static Private Attributes
static std::terminate_handler	_old_terminate_handler

Friends
void	libmesh_abort ()
	Abort as soon as possible. More...
void	libmesh_terminate_handler ()
	A terminate handler. More...

Detailed Description

The LibMeshInit class, when constructed, initializes the dependent libraries (e.g.

MPI or PETSC) and does the command line parsing needed by libMesh. The LibMeshInit destructor closes those libraries properly.

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

All libMesh functionality should be used only when a LibMeshInit object exists. Dependent library functionality, likewise, except in codes which manually initialize those libraries before LibMeshInit creation and finalize them after LibMeshInit destruction.

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

Definition at line 91 of file libmesh.h.

Constructor & Destructor Documentation

LibMeshInit() [1/2]

libMesh::LibMeshInit::LibMeshInit	(	int	argc,
		const char *const *	argv,
		MPI_Comm	COMM_WORLD_IN = MPI_COMM_WORLD,
		int	n_threads = -1
	)

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

This will e.g. call MPI_Init if MPI is available and enabled and has not already been initialized; similar initialization may take place for Petsc, Slepc, multithreading support, libMesh Singleton objects, the libMesh::out/err IO streams, and any libMesh handlers for floating-point exceptions, signals, and/or C++ aborts.

You must create a LibMeshInit object before using any of the library functionality. This method may take an optional parameter to use a user-specified MPI communicator.

LibMeshInit() [2/2]

libMesh::LibMeshInit::LibMeshInit	(	int	argc,
		const char *const *	argv,
		int	COMM_WORLD_IN = 0,
		int	n_threads = -1
	)

~LibMeshInit()

libMesh::LibMeshInit::~LibMeshInit ( )

virtual

Destructor.

Cleans up libMesh Singleton objects, and thread manager if threading is in use. Prints reference count and performance logging information if enabled. Restores pre-LibMeshInit terminate handler and floating-point-exception handling. Finalizes any of Slepc, Petsc, and MPI which were initialized by LibMeshInit.

Definition at line 746 of file libmesh.C.

References _comm, libMesh::libMeshPrivateData::_is_initialized, _old_terminate_handler, _timpi_init, _vtk_mpi_controller, TIMPI::Communicator::barrier(), libMesh::Singleton::cleanup(), libMesh::cleanup_stream_buffers(), libMesh::PerfLog::clear(), libMesh::closed(), comm(), libMesh::command_line_names(), libMesh::ReferenceCounter::enable_print_counter_info(), libMesh::enableFPE(), libMesh::err, libMesh::GLOBAL_COMM_WORLD, libMesh::ReferenceCounter::n_objects(), libMesh::Quality::name(), libMesh::on_command_line(), libMesh::perflog, libMesh::ReferenceCounter::print_info(), and libMesh::PerfLog::print_log().

{
  // 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 LIBMESH_ENABLE_EXCEPTIONS
  if (!std::uncaught_exceptions())
#endif
    this->comm().barrier();

  // We can't delete, finalize, etc. more than once without
  // reinitializing in between
  libmesh_exceptionless_assert(!libMesh::closed());

  // Delete reference counted singleton(s)
  Singleton::cleanup();

  // Clear the thread task manager we started
  task_scheduler.reset();

  // If we have a memory leak, we want the details printed.
  if (ReferenceCounter::n_objects() != 0)
    ReferenceCounter::enable_print_counter_info();

  // Ask the \p ReferenceCounter to print its reference count
  // information, if printing is enabled.  This allows us to find
  // memory leaks.
  //
  // If we don't have any leaks, we'll print to cout, only if we've
  // been told to.  If we do, we'll print to cerr, to make sure the
  // user doesn't miss a leak that's only on a processor other than 0.
  if (ReferenceCounter::n_objects() == 0)
    ReferenceCounter::print_info ();

  // Scream specifically if we detect a memory leak
  if (ReferenceCounter::n_objects() != 0)
    {
      ReferenceCounter::print_info (libMesh::err);

      libMesh::err << "Memory leak detected!"
                   << std::endl;

#if !defined(LIBMESH_ENABLE_REFERENCE_COUNTING) || defined(NDEBUG)

      libMesh::err << "Compile in DEBUG mode with --enable-reference-counting"
                   << std::endl
                   << "for more information"
                   << std::endl;
#endif
    }

  //  print the perflog to individual processor's file.
  libMesh::perflog.print_log();

  // Now clear the logging object, we don't want it to print
  // a second time during the PerfLog destructor.
  libMesh::perflog.clear();

  // Reconnect the output streams
  // (don't do this, or we will get messages from objects
  //  that go out of scope after the following return)
  //std::cout.rdbuf(std::cerr.rdbuf());


  // Set the initialized() flag to false
  libMeshPrivateData::_is_initialized = false;

  cleanup_stream_buffers();

#ifdef LIBMESH_ENABLE_EXCEPTIONS
  // Reset the old terminate handler; maybe the user code wants to
  // keep doing C++ stuff after closing libMesh stuff.
  std::set_terminate(_old_terminate_handler);
#endif

#ifdef LIBMESH_HAVE_NETGEN
  nglib::Ng_Exit();
#endif

  if (libMesh::on_command_line("--enable-fpe"))
    libMesh::enableFPE(false);

#if defined(LIBMESH_HAVE_PETSC)
  // Let PETSc know about all the command line objects that we
  // consumed without asking them, so we don't get unused option
  // warnings about those.
  std::vector<std::string> cli_names = command_line_names();
  for (const auto & name : cli_names)
    if (!name.empty() && name[0] == '-')
      {
        // Newer PETSc can give me a double-free I'm having trouble
        // replicating; let's protect against trying to clear
        // already-used values
        PetscBool used = PETSC_FALSE;
        auto ierr = PetscOptionsUsed(NULL, name.c_str(), &used);
        CHKERRABORT(libMesh::GLOBAL_COMM_WORLD, ierr);
        if (used == PETSC_FALSE)
          {
            ierr = PetscOptionsClearValue(NULL, name.c_str());
            CHKERRABORT(libMesh::GLOBAL_COMM_WORLD, ierr);
          }
      }

  // Allow the user to bypass PETSc finalization
  if (!libMesh::on_command_line ("--disable-petsc")
#if defined(LIBMESH_HAVE_MPI)
      && !libMesh::on_command_line ("--disable-mpi")
#endif
      )
    {
      PetscErrorCode ierr = LIBMESH_PETSC_SUCCESS;
# if defined(LIBMESH_HAVE_SLEPC)
      if (libmesh_initialized_slepc)
        ierr = SlepcFinalize();
# else
      if (libmesh_initialized_petsc)
        ierr = PetscFinalize();
# endif
      CHKERRABORT(libMesh::GLOBAL_COMM_WORLD, ierr);
    }
#endif

#if defined(LIBMESH_HAVE_MPI) && defined(LIBMESH_HAVE_VTK)
  _vtk_mpi_controller->Finalize(/*finalized_externally=*/1);
  _vtk_mpi_controller->Delete();
#endif

  delete this->_comm;

#if defined(LIBMESH_HAVE_MPI)
  // Allow the user to bypass MPI finalization
  if (!libMesh::on_command_line ("--disable-mpi"))
    {
      delete this->_timpi_init;
    }
#else
  delete this->_timpi_init;
#endif
}

Member Function Documentation

comm() [1/2]

const Parallel::Communicator& libMesh::LibMeshInit::comm ( ) const

inline

Returns a Communicator created from the TIMPIInit object we hold, which will be a compatibility shim if MPI is not enabled.

Definition at line 129 of file libmesh.h.

References _comm.

Referenced by ~LibMeshInit().

{ return *_comm; }

comm() [2/2]

Parallel::Communicator& libMesh::LibMeshInit::comm ( )

inline

Definition at line 131 of file libmesh.h.

References _comm.

{ return *_comm; }

perf_log()

PerfLog & libMesh::LibMeshInit::perf_log ( )

staticprivate

Definition at line 896 of file libmesh.C.

References libMesh::perflog.

Referenced by libMesh::libmesh_terminate_handler().

{
  return libMesh::perflog;
}

Friends And Related Function Documentation

libmesh_abort

void libmesh_abort ( )

friend

Abort as soon as possible.

This cleans up stream buffers, aborts with MPI_Abort (if MPI is initialized), and falls back on std::abort afterward.

Definition at line 338 of file libmesh.C.

{
  libMesh::perflog.clear();

  // Now that we're done with output we should clean up our stream
  // buffers; if we fail to uninstall_thread_buffered_sync() when
  // needed we can end up seeing a segfault in iostreams destructors
  cleanup_stream_buffers();

  // If we have MPI and it has been initialized, we need to be sure
  // and call MPI_Abort instead of std::abort, so that the parallel
  // job can die nicely.
#if defined(LIBMESH_HAVE_MPI)
  int mpi_initialized;
  MPI_Initialized (&mpi_initialized);

  if (mpi_initialized)
    MPI_Abort(libMesh::GLOBAL_COMM_WORLD, 1);
#endif

#ifdef LIBMESH_ENABLE_EXCEPTIONS
  // The system terminate_handler may do useful things, or the user
  // may have set their own terminate handler that we want to call.
  LibMeshInit::_old_terminate_handler();
#endif

  // The last attempt to die if nothing else has killed us
  std::abort();
}

libmesh_terminate_handler

void libmesh_terminate_handler ( )

friend

A terminate handler.

libMesh sets this to handle uncaught exceptions; it can also be called manually to cleanup, print any diagnostics, do cleanup, and abort.

If an uncaught exception is a TerminationException, as thrown by libmesh_terminate(), the handler avoids any diagnostic output.

If an uncaught exception is a std::exception, its message is printed, followed by stack trace and performance log output.

Definition at line 110 of file libmesh_exceptions.C.

{
  bool quiet = false;

#ifdef LIBMESH_ENABLE_EXCEPTIONS
  // If we have an active exception, it may have an error message that
  // we should print, or it may have a type that tells us not to print
  // anything.
  std::optional<std::string> exception_message;
  std::exception_ptr ex = std::current_exception();
  if (ex)
    {
      try
        {
          std::rethrow_exception(ex);
        }
      // Capture the exception message to be used later.
      catch (const std::exception & std_ex)
        {
          exception_message = std_ex.what();
        }
      // We arrived here via TerminationException (likely from
      // libmesh_terminate()), which implies that a useful
      // error message has already been emitted.
      catch (const TerminationException &)
        {
          quiet = true;
        }
      // We're just trying to detect exception types here, not
      // actually rethrow
      catch (...)
        {
        }
    }
#endif

  if (!quiet)
    {
      libMesh::err << "libMesh terminating";
#ifdef LIBMESH_ENABLE_EXCEPTIONS
      if (exception_message)
        libMesh::err << ":\n" << *exception_message;
#endif
      libMesh::err << std::endl;

      // If this got called then we're probably crashing; let's print a
      // stack trace.  The trace files that are ultimately written depend on:
      // 1.) Who throws the exception.
      // 2.) Whether the C++ runtime unwinds the stack before the
      //     terminate_handler is called (this is implementation defined).
      //
      // The various cases are summarized in the table below:
      //
      //                        | libmesh exception | other exception
      //                        -------------------------------------
      // stack unwinds          |        A          |       B
      // stack does not unwind  |        C          |       D
      //
      // Case A: There will be two stack traces in the file: one "useful"
      //         one, and one nearly empty one due to stack unwinding.
      // Case B: You will get one nearly empty stack trace (not great, Bob!)
      // Case C: You will get two nearly identical stack traces, ignore one of them.
      // Case D: You will get one useful stack trace.
      //
      // Cases A and B (where the stack unwinds when an exception leaves
      // main) appear to be non-existent in practice.  I don't have a
      // definitive list, but the stack does not unwind for GCC on either
      // Mac or Linux.  I think there's good reasons for this behavior too:
      // it's much easier to get a stack trace when the stack doesn't
      // unwind, for example.
      libMesh::write_traceout();

      // We may care about performance data pre-crash; it would be sad to
      // throw that away.
      LibMeshInit::perf_log().print_log();
    }

  libmesh_abort();
}

Member Data Documentation

_comm

Parallel::Communicator* libMesh::LibMeshInit::_comm

private

Definition at line 143 of file libmesh.h.

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

_old_terminate_handler

std::terminate_handler libMesh::LibMeshInit::_old_terminate_handler

staticprivate

Definition at line 153 of file libmesh.h.

Referenced by libMesh::libmesh_abort(), and ~LibMeshInit().

_timpi_init

TIMPI::TIMPIInit* libMesh::LibMeshInit::_timpi_init

private

Definition at line 136 of file libmesh.h.

Referenced by ~LibMeshInit().

_vtk_mpi_controller

vtkMPIController* libMesh::LibMeshInit::_vtk_mpi_controller

private

Definition at line 149 of file libmesh.h.

Referenced by ~LibMeshInit().

---

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

• include/base/libmesh.h
• src/base/libmesh.C