Event/ers/include/ers/ers.h

Go to the documentation of this file.

/*
 *  ers.h
 *  ers
 *
 *  Created by Matthias Wiesmann on 26.01.05.
 *  Copyright 2005 CERN. All rights reserved.
 *
 */
 
/** \file ers.h This file includes all the main headers of the Error Reporting System.
 * It does not declare anything <em>per se</em>, it does contains the doxygen code to
 * generate all the general documentation for the package.
 * \author Matthias Wiesmann
 * \version 1.1 Removed dependency on System package
 * \brief ers header and documentation file
 */
 
#include "ers/Context.h"
#include "ers/Core.h"
 
#include "ers/Issue.h"
#include "ers/IssueFactory.h"
#include "ers/Stream.h"
#include "ers/StreamFactory.h"
 
#include "ers/Assertion.h"
#include "ers/InvalidReferenceIssue.h"
#include "ers/LogIssue.h"
#include "ers/NotImplemented.h"
#include "ers/Precondition.h"
#include "ers/RangeIssue.h"
 
/** \page ERSHowTo How to use the ERS package
  The goal of the Error Reporting System is to offer tool to simplify and unify error handling
  and error reporting in TDAQ applications. This package can be used at different levels. At
  the lowest level, one can simply use the existing checking macros. A more advanced way of
  using this package is to define specific Issue subclasses. \section Macros Basic macros Basic
  ERS functionality can be accessed by using simple macros. Those macros are available simply
  by including the ers/ers.h header file. \subsection AssertionMacros Assertion Macros The ERS
  package offers a set of macros to do basic checking. Those macros generally behave like the
  standard C assert macros. They have the following features:<ul> <li>Different types of
  checks: <ul> <li>Compile time checks (\c ERS_STATIC_ASSERT) those should be used to verity
  certain assertions at compile-time. For instance if you code rely on certain data structures
  having certain memory sizes, this can be checked using static assertions. <li>Preconditions
  (\c ERS_PRECONDITION) those should be used to check condition when entering functions. For
  instance if you only accept certain values for parameters precondtions should verify that
  those conditions are resepected. <li>Pointer precondition (\c ERS_PRE_CHECK_PTR) this special
  type of pre-condition checks that a pointer is valid (not null), you should this macro to
  check all pointers that a function or method receives as parameters. <li>Pointer checking (\c
  ERS_CHECK_PTR) this type of checks is used to verify general pointers internally. <li>General
  assertion (\c ERS_ASSERT) this macro can be used for checks that do not fit into any other
  category.
      </ul></li>
  <li>Macros are compiled out if macro \c N_DEBUG is defined</li>
  <li>Throws complete ERS issues, they can be caught streamed, modified etc.</li>
  <li>Preconditions and general assertions support variable number of parameters and \c fprintf
  like formatting</li> <li>Runtime assertion can detect if they are invariant conditions</li>
  </ul>
  All macros throw Issues object as exceptions with a severity_t of \c ers::error.
  The main difference between the different macros is that the Issue object they generate in
  case of violated condition contains different information fields. For instance all
  precondition macros generate issue that specify that the responsiblity for the Issue lies in
  the caller, not the callee. \see ers::Assertion \see ers::Precondition \see
  ers::InvalidReferenceIssue
 
  \subsection LoggingMacros Logging Macros
  The ERS package offers a set of macros to do logging. Those macros construct an issue and
  send them to the relevant stream. They all support multiple number of parameters with \c
  fprintf like patterns. For each debug and warning severity_t level there is an associated
  macro: \li ERS_DEBUG_0 \li ERS_DEBUG_1 \li ERS_DEBUG_2 \li ERS_DEBUG_3 \li ERS_WARN
 
  The actual behaviour of the macro can be set up either at compile or runtime.
  Debug macros with levels larger than 0 can be disabled at compile time simply by defining the
  DEBUG_LEVEL. For instance, if DEBUG_LEVEL is 1, then ERS_DEBUG_2 and ERS_DEBUG_3 are compiled
  out. At runtime the stream associated with a given severity can be disabled by associated a
  null stream with the severity. A filtering stream can also be associated with the severity
  level. The different types of streams supported by the package and the debug and warning
  macros are presented in the documentation for class ers::StreamFactory \see
  ers::StreamFactory
 
  \section Issues Building Custom Issues
  For a discussion about building custom issue, see the documentation for the Issue class.
  An example custom issue is also given in the example directory.
  \see ers::Issue
  \see ExampleIssue
  \see ExampleIssue.h
 
  \section Selecting Streams
  The ERS system use the abstraction of streams to handle issues.
  Conceptualy, a stream is simply an object that can the user can use to send (or receive)
  Issues. There is one stream associated with each severity level, those streams can be set or
  retrieved using methods of the ers::StreamFactory class. \see ers::StreamFactory
 
  \section Exit values
  The ERS system offers some facilities to give out standard compliant exit values for
  programs. That is, if a program exists because of an ers Issue, it can call the \c exit_value
  method on the issue to possibly get an appropriate exit value (as defined in sysexits.h). A
  typical main program would look like this: \code int main(int argc, char** argv) { try {
          do_stuff();
      } catch (ers::Issue &e) {
          ers::StreamFactory::dispatch(e); // we send the issue to the appropriate stream
          exit(e.exit_value());            // we get the actual exit value from the issue
      } // try / catch
  } // main
  \endcode
  \see http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=sysexits
 
  \section FAQ FAQ
  \subsection Assertion-Precondition What is the difference between an assertion and a
  precondition? An precondition is a condition that needs to be respected when \e entering a
  function, an assertion is a condition that needs to be respected \e inside a function. A
  failed precondition indicates that the problem lies outside of the function, a failed
  assertion indicates that the problem lies inside the function. \see ers::Assertion
 
  \subsection ERS_HERE What is the macro ERS_HERE?
  The macro ERS_HERE is used to insert all the context information to a ers issue.
  When constructing an issue one should always give the macro ERS_HERE as a first parameter.
  \see ers::Context
 
  \subsection factory Do I need to implement the registration and factory methods for each of
  my Issues? The registration and factory mechanism as implemented in the ExampleIssue class is
  needed for some functionality of ERS. If it is not present, the system will work but certain
  features will be disabled. In particular the absence of factory method means that ERS cannot
  dynamically build instance with the precise C++ type. For instance if you instanciate an
  CustomIssue that does not declare a factory method, if you serialise this issue to a file and
  then deserialise it, it will not have the type CustomIssue, but instead will have the type
  DefaultIssue. The same happens if an Issue is caused by another issue, the cause issue is
  cloned into the second issue, so if there is no factory method, the clone issue will have the
  generic type.
 
*/