Trilinos_Details_LinearSolverFactory.hpp

Go to the documentation of this file.

// @HEADER
// ***********************************************************************
//
//                    Teuchos: Common Tools Package
//                 Copyright (2004) Sandia Corporation
//
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ***********************************************************************
// @HEADER

#ifndef TRILINOS_DETAILS_LINEARSOLVER_FACTORY_HPP
#define TRILINOS_DETAILS_LINEARSOLVER_FACTORY_HPP


#include "Teuchos_RCP.hpp" // includes Teuchos_ConfigDefs.hpp
#include "TeuchosRemainder_config.h"
#include <map>
#ifdef HAVE_TEUCHOSCORE_CXX11
#  include <memory> // std::shared_ptr
#endif // HAVE_TEUCHOSCORE_CXX11
#include <stdexcept>
#include <sstream>
#include <string>


// Attempted fix for Bug 6392: declare all packages'
// LinearSolverFactory registration functions here, with weak linkage.
// This works whether or not the packages in question are actually
// enabled.  In createPackageNames() below, actually call these
// functions if they are linked in.  We only need to do this if
// building with static libraries; if building with dynamic libraries,
// each package takes care of this on its own.
//
// I wrote "attempted" because it DOESN'T WORK.  It doesn't matter
// whether these or their uses are in the .cpp or .hpp file, or
// whether they are in a regular function that gets compiled or a
// templated function that might not.
#if ! defined(HAVE_TEUCHOS_DYNAMIC_LIBS) && defined(HAVE_TEUCHOS_CXX_ATTRIBUTE_WEAK)
// FIXME (mfh 21 Aug 2015) NONE of the commented-out things work.

// namespace Amesos2 {
// namespace Details {
//   extern void __attribute__((weak)) registerLinearSolverFactory ();
// } // namespace Details
// } // namespace Amesos2

// namespace Ifpack2 {
// namespace Details {
//   // extern void __attribute__((weak)) registerLinearSolverFactory ();
//   // void __attribute__((weak)) registerLinearSolverFactory ();
//   // evoid __attribute__((weak)) registerLinearSolverFactory ();
// } // namespace Details
// } // namespace Ifpack2
#endif // ! defined(HAVE_TEUCHOS_DYNAMIC_LIBS) && defined(HAVE_TEUCHOS_CXX_ATTRIBUTE_WEAK)


namespace Trilinos {

namespace Details {

template<class MV, class OP, class NormType>
class LinearSolver; // forward declaration

template<class MV, class OP, class NormType>
Teuchos::RCP<LinearSolver<MV, OP, NormType> >
getLinearSolver (const std::string& packageName, const std::string& solverName);

template<class MV, class OP, class NormType>
class LinearSolverFactory {
public:
  virtual ~LinearSolverFactory() {}
  virtual Teuchos::RCP<LinearSolver<MV, OP, NormType> >
  getLinearSolver (const std::string& solverName) = 0;
};

template<class MV, class OP, class NormType>
void
registerLinearSolverFactory (const std::string& packageName,
#ifdef HAVE_TEUCHOSCORE_CXX11
                             const std::shared_ptr<LinearSolverFactory<MV, OP, NormType> >& factory);
#else
                             const Teuchos::RCP<LinearSolverFactory<MV, OP, NormType> >& factory);
#endif // HAVE_TEUCHOSCORE_CXX11

//
// EVERYTHING BELOW THIS LINE IS AN IMPLEMENTATION DETAIL
//

namespace Impl {

bool rememberRegisteredSomeLinearSolverFactory (const std::string& packageName);

bool registeredSomeLinearSolverFactory (const std::string& packageName);

bool haveLinearSolverFactoryRunTimeRegistration ();

template<class MV, class OP, class NormType>
class LinearSolverFactoryRepository {
public:
#ifdef HAVE_TEUCHOSCORE_CXX11
  typedef std::shared_ptr<LinearSolverFactory<MV, OP, NormType> > factory_pointer_type;
#else
  typedef Teuchos::RCP<LinearSolverFactory<MV, OP, NormType> > factory_pointer_type;
#endif // HAVE_TEUCHOSCORE_CXX11

  typedef std::map<std::string, factory_pointer_type> map_type;

public:
  static factory_pointer_type
  getFactory (const std::string& packageName)
  {
    createFactories ();
    typedef typename map_type::iterator iter_type;
    iter_type it = factories_->find (packageName);
    if (it == factories_->end ()) { // didn't find package name
      return factory_pointer_type (); // null pointer
    } else { // found package name
      return it->second;
    }
  }

  static void
  registerLinearSolverFactory (const std::string& packageName,
                               const factory_pointer_type& factory)
  {
    TEUCHOS_TEST_FOR_EXCEPTION
      (factory.get () == NULL, std::invalid_argument, "Trilinos::Details::"
       "LinearSolverFactoryRepository::registerLinearSolverFactory: Input "
       "'factory' is NULL!");
    createFactories ();
    if (factories_->find (packageName) == factories_->end ()) {
      factories_->insert (std::make_pair (packageName, factory));
    }
  }

private:
  static map_type* factories_;

  static void createFactories () {
    if (factories_ == NULL) {
      factories_ = new map_type ();
      // It _is_ possible for atexit() to fail (e.g., because it ran
      // out of memory for storing callbacks).  We could throw an
      // exception here in that case, but I think it's better just
      // to let the minor memory leak happen.
      (void) atexit (freeFactories);
    }
    TEUCHOS_TEST_FOR_EXCEPTION
      (factories_ == NULL, std::logic_error, "Trilinos::Details::"
       "LinearSolverFactoryRepository::createFactories: "
       "Should never get here!  factories_ is NULL.");
  }

  static void freeFactories () {
    if (factories_ != NULL) {
      delete factories_;
      factories_ = NULL;
    }
  }
};

// This is _not_ an explicit instantiation.  C++ wants it, because
// LinearSolverFactoryRepository is a templated class with a static
// (class) member.
template<class MV, class OP, class NormType>
typename LinearSolverFactoryRepository<MV, OP, NormType>::map_type*
LinearSolverFactoryRepository<MV, OP, NormType>::factories_ = NULL;

} // namespace Impl

//
// Definitions of nonmember functions
//

template<class MV, class OP, class NormType>
void
registerLinearSolverFactory (const std::string& packageName,
#ifdef HAVE_TEUCHOSCORE_CXX11
                             const std::shared_ptr<LinearSolverFactory<MV, OP, NormType> >& factory)
#else
                             const Teuchos::RCP<LinearSolverFactory<MV, OP, NormType> >& factory)
#endif // HAVE_TEUCHOSCORE_CXX11
{
  Impl::LinearSolverFactoryRepository<MV, OP, NormType>::registerLinearSolverFactory (packageName, factory);
  Impl::rememberRegisteredSomeLinearSolverFactory (packageName);
}

template<class MV, class OP, class NormType>
Teuchos::RCP<LinearSolver<MV, OP, NormType> >
getLinearSolver (const std::string& packageName, const std::string& solverName)
{
  using Teuchos::RCP;
  using Teuchos::TypeNameTraits;
  typedef Impl::LinearSolverFactoryRepository<MV, OP, NormType> repo_type;
  typedef typename repo_type::factory_pointer_type factory_pointer_type;
  typedef LinearSolver<MV, OP, NormType> solver_type;
  const char prefix[] = "Trilinos::Details::getLinearSolver: ";

  // FIXME (mfh 21 Aug 2015) Attempted fix for Bug 6392: DOES NOT WORK.
  // (Compiles just fine, but test doesn't pass.)
#if ! defined(HAVE_TEUCHOS_DYNAMIC_LIBS) && defined(HAVE_TEUCHOS_CXX_ATTRIBUTE_WEAK)
  // if (Amesos2::Details::registerLinearSolverFactory == NULL) {
  //   std::cout << "-- Amesos2::Details::registerLinearSolverFactory is NULL" << std::endl;
  // } else {
  //   Amesos2::Details::registerLinearSolverFactory ();
  // }
  // if (Ifpack2::Details::registerLinearSolverFactory == NULL) {
  //   std::cout << "-- Ifpack2::Details::registerLinearSolverFactory is NULL" << std::endl;
  // } else {
  //   Ifpack2::Details::registerLinearSolverFactory ();
  // }
#endif // ! defined(HAVE_TEUCHOS_DYNAMIC_LIBS) && defined(HAVE_TEUCHOS_CXX_ATTRIBUTE_WEAK)

  // Whether the CMake run-time registration option is ON.  This
  // doesn't actually say whether run-time registration has happened
  // for the current combination of (MV, OP, NormType) template
  // parameters.
  const bool haveRunTimeReg =
    Impl::haveLinearSolverFactoryRunTimeRegistration ();

  const bool pkgExists = Impl::registeredSomeLinearSolverFactory (packageName);
  TEUCHOS_TEST_FOR_EXCEPTION
    (! pkgExists, std::invalid_argument, prefix << "Package \"" << packageName
     << "\" never registered a LinearSolverFactory for _any_ combination of "
     "template parameters MV, OP, and NormType.  This means either that the "
     "package name is invalid, or that the package is not enabled.  "
     "Trilinos_ENABLE_LINEAR_SOLVER_FACTORY_REGISTRATION = "
     << (haveRunTimeReg ? "ON" : "OFF") << ".");

  factory_pointer_type factory = repo_type::getFactory (packageName);
  TEUCHOS_TEST_FOR_EXCEPTION
    (factory.get () == NULL, std::invalid_argument, prefix << "Package \"" <<
     packageName << "\" is valid, but it never registered a LinearSolverFactory"
     " for template parameters "
     "MV = " << TypeNameTraits<MV>::name () << ", "
     "OP = " << TypeNameTraits<OP>::name () << ", "
     "NormType = " << TypeNameTraits<NormType>::name () << ".  "
     "Trilinos_ENABLE_LINEAR_SOLVER_FACTORY_REGISTRATION = "
     << (haveRunTimeReg ? "ON" : "OFF") << ".");

  RCP<solver_type> solver = factory->getLinearSolver (solverName);
  TEUCHOS_TEST_FOR_EXCEPTION
    (solver.is_null (), std::invalid_argument, prefix << "Invalid solver name "
     "\"" << solverName << "\".  However, package \"" << packageName << "\" is "
     "valid, and it did register a LinearSolverFactory for template parameters "
     "MV = " << TypeNameTraits<MV>::name () << ", "
     "OP = " << TypeNameTraits<OP>::name () << ", "
     "NormType = " << TypeNameTraits<NormType>::name () << ".  "
     "Trilinos_ENABLE_LINEAR_SOLVER_FACTORY_REGISTRATION = "
     << (haveRunTimeReg ? "ON" : "OFF") << ".");

  return solver;
}

} // namespace Details
} // namespace Trilinos

#endif // TRILINOS_DETAILS_LINEARSOLVER_FACTORY_HPP