exceptions.hh

// -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
// vi: set et ts=4 sw=2 sts=2:
// $Id$

#ifndef DUNE_EXCEPTIONS_HH
#define DUNE_EXCEPTIONS_HH

#include <string>
#include <sstream>

namespace Dune {

  /*! \defgroup Exceptions Exception handling
     \ingroup Common
     \{

     The Dune-exceptions are designed to allow a simple derivation of subclasses
     and to accept a text written in the '<<' syntax.

     Example of usage:

     \code
     #include <dune/common/exceptions.hh>

     ...

     class FileNotFoundError : public Dune::IOError {};

     ...

     void fileopen (std::string name) {
     std::ifstream file;

     file.open(name.c_str());

     if (file == 0)
      DUNE_THROW(FileNotFoundError, "File " << name << " not found!");

     ...

     file.close();
     }

     ...

     int main () {
     try {
      ...
     } catch (Dune::IOError &e) {
      std::cerr << "I/O error: " << e << std::endl;
      return 1;
     } catch (Dune::Exception &e) {
      std::cerr << "Generic Dune error: " << e << std::endl;
      return 2;
     }
     }
     \endcode

     \see exceptions.hh for detailed info

   */

  /*! \file
     \brief A few common exception classes

     This file defines a common framework for generating exception
     subclasses and to throw them in a simple manner

   */

  /* forward declarations */
  class Exception;
  struct ExceptionHook;

  /*! \class Exception
     \brief Base class for Dune-Exceptions

     all Dune exceptions are derived from this class via trivial subclassing:

     \code
     class MyException : public Dune::Exception {};
     \endcode

     You should not \c throw a Dune::Exception directly but use the macro
     DUNE_THROW() instead which fills the message-buffer of the exception
     in a standard way and features a way to pass the result in the
     operator<<-style

     \see DUNE_THROW, IOError, MathError

   */
  class Exception {
  public:
    Exception ();
    void message(const std::string &msg); //!< store string in internal message buffer
    const std::string& what() const;        //!< output internal message buffer
    static void registerHook (ExceptionHook * hook); //!< add a functor which is called before a Dune::Exception is emitted (see Dune::ExceptionHook) \see Dune::ExceptionHook
    static void clearHook ();                       //!< remove all hooks
  private:
    std::string _message;
    static ExceptionHook * _hook;
  };

  /*! \brief Base class to add a hook to the Dune::Exception

     The user can add a functor which should be called before a Dune::Exception is emitted.


     Example: attach a debugger to the process, if an exception is thrown
     \code
     struct ExceptionHookDebugger : public Dune::ExceptionHook
     {
      char * process_;
      char * debugger_;
      ExceptionHookDebugger (int argc, char ** argv, std::string debugger)
      {
          process_ = strdup(argv[0]);
          debugger_ = strdup(debugger.c_str());
      }
      virtual void operator () ()
      {
          pid_t pid = getpid();
          pid_t cpid;
          cpid = fork();
          if (cpid == 0) // child
          {
              char * argv[4];
              argv[0] = debugger_;
              argv[1] = process_;
              argv[2] = new char[12];
              snprintf(argv[2], 12, "%i", int(pid));
              argv[3] = 0;
              // execute debugger
              std::cout << process_ << "\n";
              std::cout << argv[0] << " "
                        << argv[1] << " "
                        << argv[2] << std::endl;
              execv(argv[0], argv);
          }
          else // parent
          {
              // send application to sleep
              kill(pid, SIGSTOP);
          }
      }
     };
     \endcode

     This hook is registered via a static method of Dune::Exception:
     \code
     int main(int argc, char** argv) {
      Dune::MPIHelper & mpihelper = Dune::MPIHelper::instance(argc,argv);
      ExceptionHookDebugger debugger(argc, argv, "/usr/bin/ddd");
      Dune::Exception::registerHook(& debugger);
      try
      {
          ...
      }
      catch (std::string & s) {
          std::cout << mpihelper.rank() << ": ERROR: " << s << std::endl;
      }
      catch (Dune::Exception & e) {
          std::cout << mpihelper.rank() << ": DUNE ERROR: " << e.what() << std::endl;
      }
     }
     \endcode

   */
  struct ExceptionHook
  {
    virtual ~ExceptionHook() {}
    virtual void operator () () = 0;
  };

  /*
     Implementation of Dune::Exception
   */

  inline Exception::Exception ()
  {
    // call the hook if necessary
    if (_hook != 0) _hook->operator()();
  }

  inline void Exception::registerHook (ExceptionHook * hook)
  {
    _hook = hook;
  }

  inline void Exception::clearHook ()
  {
    _hook = 0;
  }

  inline void Exception::message(const std::string & msg)
  {
    _message = msg;
  }

  inline const std::string& Exception::what() const
  {
    return _message;
  }

  inline std::ostream& operator<<(std::ostream &stream, const Exception &e)
  {
    return stream << e.what();
  }

#ifndef DOXYGEN
  // the "format" the exception-type gets printed.  __FILE__ and
  // __LINE__ are standard C-defines, the GNU cpp-infofile claims that
  // C99 defines __func__ as well. __FUNCTION__ is a GNU-extension
#define THROWSPEC(E) # E << " [" << __func__ << ":" << __FILE__ << ":" << __LINE__ << "]: "
#endif // DOXYGEN

  /*! Macro to throw an exception

     \code
     #include <dune/common/exceptions.hh>
     \endcode

     \param E exception class derived from Dune::Exception
     \param m reason for this exception in ostream-notation

     Example:

     \code
     if (filehandle == 0)
      DUNE_THROW(FileError, "Could not open " << filename << " for reading!");
     \endcode

     DUNE_THROW automatically adds information about the exception thrown
     to the text.

     \note
     you can add a hook to be called before a Dune::Exception is emitted,
     e.g. to add additional information to the exception,
     or to invoke a debugger during parallel debugging. (see Dune::ExceptionHook)

   */
  // this is the magic: use the usual do { ... } while (0) trick, create
  // the full message via a string stream and throw the created object
#define DUNE_THROW(E, m) do { E th__ex; std::ostringstream th__out; \
                              th__out << THROWSPEC(E) << m; th__ex.message(th__out.str()); throw th__ex; \
} while (0)

  /*! \brief Default exception class for I/O errors

     This is a superclass for any errors dealing with file/socket I/O problems
     like

     - file not found
     - could not write file
     - could not connect to remote socket
   */
  class IOError : public Exception {};

  /*! \brief Default exception class for mathematical errors

     This is the superclass for all errors which are caused by
     mathematical problems like

     - matrix not invertible
     - not convergent
   */
  class MathError : public Exception {};

  /*! \brief Default exception class for range errors

     This is the superclass for all errors which are caused because
     the user tries to access data that was not allocated before.
     These can be problems like

     - accessing array entries behind the last entry
     - adding the fourth non zero entry in a sparse matrix
       with only three non zero entries per row

   */
  class RangeError : public Exception {};

  /*! \brief Default exception for dummy implementations

     This exception can be used for functions/methods

     - that have to be implemented but should never be called
     - that are missing
   */
  class NotImplemented : public Exception {};

  /*! \brief Default exception class for OS errors

     This class is thrown when a system-call is used and returns an
     error.

   */
  class SystemError : public Exception {};

  /*! \brief Default exception if memory allocation fails

   */
  class OutOfMemoryError : public SystemError {};

  /*! \brief Default exception if a function was called while
     the object is not in a valid state for that function.
   */
  class InvalidStateException : public Exception {};

  /*! \brief Default exception if an error in the parallel
     communication of the programm occured
     \ingroup ParallelCommunication
   */
  class ParallelError : public Exception {};

} // end namespace

#endif