ErrLog.hh

#ifndef ERRLOG_HH
#define ERRLOG_HH

//--------------------------------------------------------------------------
// Description:
//	Class ErrLogger:
//		Interface description for the abstract logging interface
//
// BaBar Usage:
//
//	BaBar policy for using ErrLogger is to interact with it only
//	through the ErrMsg macro.
//
//	ErrMsg(severity) << "the message" << endmsg;
//
//	The error message must be terminated by endmsg as above.
//
//	The ErrMsg macro returns an ostream& so that it is possible
//	to include any constructs that can be sent to cout or cerr.
//	For example, the string classes and user-defined operator<<
//	are available to users while using ErrMsg.
//
// General Usage:
//
//	Available constructs are a logging call:
//
//		ErrLog::msg(severity, facility, code) << "Foo" << endmsg;
//
//	and a test to see if a particular logging call will do anything:
//
//		if (ErrLog::logging(severity, facility, code)) ...
//
//	All error messages should be completed with "endmsg".  For multiple-
//	line messages use '\n' for line breaks in preference to endl.  The 
//      endmsg command will supply a final "endl" for error loggers for which
//      it's appropriate (e.g., if writing to the console).  Users should in 
//      particular NOT terminate messages with "some text" << endl << endmsg;.
//
//
//	"severity" is a member of an enum; see the definition below
//	"facility" names the source of the message; in the ErrMsg() form,
//                 this is set to be the filename and line number
//	"code"     an integer distinguishing the individual errors possible;
//	           no meanings are predefined at this level
//
//
// Environment:
//	Software developed for the BaBar Detector at the SLAC B-Factory.
//
// Author List:
//      Bob Jacobsen	(original author)
//	Scott Metzler	(addition of ErrStream)
//	Gregory Dubois-Felsmann   (ErrOpt; conversion of "code" to int)
//      $Id: ErrLog.hh,v 1.1.1.1 2005/03/29 17:04:19 steinke Exp $
//
// Copyright Information:
//	Copyright (C) 1998  Lawrence Berkeley National Laboratory
//	Copyright (C) 1998-2004  California Institute of Technology
//
//------------------------------------------------------------------------

//-----------------
// C/C++ Headers --
//-----------------
#include <assert.h>
#include <iostream>

//------------------------------------
// Collaborating Class Declarations --
//------------------------------------
class ErrStream;
class ErrOptParser;
template <class T> class ErrOptRef;


// Use the ErrMsg and ErrLogging macros for interacting with the error logger
// in a syntactically economical way.

// The next two macros allow the substitution of the value of the 
// __LINE__ macro as a quoted character string instead of an integer.
// As odd as this may seem, it's a well-established ISO C trick.

// 1) replaced by its argument, treated as a quoted string, without any
//    nested expansions applied (they are suppressed by the "#" operator).
#define ERRLINE_HACK_1(line)   #line

// 2) allows its argument (which will be "__LINE__") to have macro expansion
//    performed on it.  Hence HACK_2(__LINE__) becomes, e.g., HACK_1(76).
#define ERRLINE_HACK_2(line)   ERRLINE_HACK_1(line)


#ifdef ErrMsg
#undef ErrMsg
#endif
#define ErrMsg(sev) ErrLog::msg( ErrLog::sev, __FILE__ "(" ERRLINE_HACK_2(__LINE__) ")", 0 )

#ifdef ErrLogging
#undef ErrLogging
#endif
#define ErrLogging(sev) ErrLog::logging( ErrLog::sev, __FILE__ "(" ERRLINE_HACK_2(__LINE__) ")", 0 )

// [June 2002 note]  The old versions of these macros expanded to 
// ( ErrLog::sev, __FILE__, __LINE__ ) and so invoked the (..., int) forms
// of msg() and logging().  But at run time these forms were immediately
// vectored, by converting the code to a string, into the (..., const char*)
// forms, in which then in practice in all relevant ErrLog implementations the
// "code" string, containing the line number, was appended to the facility.
//
// The new forms of these macros preserve this behavior -- the line number
// is concatenated to the file name -- on the theory that the line number
// makes a silly code number and that the file+line combination is 
// reasonable to treat as a unit.


// The actual class

class ErrLog {
public:

  /**
   *  Message severity levels.
   */
  enum Severity { debugging=-1, 
		  trace=0, 
		  routine, 
		  warning, 
		  error,
		  severe,
		  fatal, 
		  MinSeverity=debugging,
		  MaxSeverity=fatal };

  //	fatal:		A condition exists that casts doubt on the integrity
  //                    of processing and the reliability of any results.
  //                    No recovery strategy can be attempted, because the
  //                    state of the program may be indeterminate.
  //
  //                    It is intended that "fatal" errors be reported
  //                    primarily when it is likely that the condition was
  //                    caused by incorrect code, or when the root cause cannot
  //                    be determined.  Dealing with the error is likely to
  //                    require debugging or other expert investigation.
  // 
  //                    In most implementations, this will be configured to
  //                    result in application termination with ::abort() 
  //                    immediately after the error message is completed with
  //                    "endmsg", producing a core dump usable to obtain a
  //                    traceback.
  //
  //			Programmers should generally not call ::abort() or
  //                    ::exit() themselves following the message.

  //    severe:         A condition exists such that the general ability of
  //                    the program to continue work is compromised: the
  //                    present computation and most or all subsequent ones
  //                    are likely to fail or produce erroneous results.
  //
  //                    It is intended that "severe" errors be reported 
  //                    primarily when external conditions (command line
  //                    arguments, control files, data files, the contents of
  //                    databases) are identified to be incompatible with
  //                    proceeding.  The programmer should ensure that the
  //                    message written is as informative as possible.
  //
  //                    In most implementations, this will be configured to
  //                    result in application termination immediately after
  //                    the error message is completed with "endmsg" and
  //                    delivered, with a non-zero exit status.  The ErrLog
  //                    implementation is free to determine the exit status
  //                    to use, from the range 1-126.  It may take the "code"
  //                    value from the ErrLog::msg( , , code ) into account.
  //
  //			Programmers should generally not call ::abort() or
  //                    ::exit() themselves following the message.

  //	error:		A condition exists such that requested result or
  //			action can not be produced.  However, future 
  //                    processing may be able to succeed.

  //	warning:	The result is produced, but may not be
  //			what's desired due to an unexpected condition

  //	routine:	Nothing known to be wrong with the result;
  //			messages that are always produced in normal
  //			operation

  //	trace:		Messages about the flow of program control
  //			and which optional operations took place.
  //			(This is the default if nothing is defined)
  
  //	debugging:	Information in addition to the above


  /**
   *  This constant is the exit code to be used when a message severity
   *  is such that an exit(!=0) -- as opposed to an abort() -- is merited,
   *  but no message-specific exit code can be determined from the 
   *  message parameters.
   */
  enum { DefaultExitCode=125 };

//-----------------------------------------------------------------------
// Static public member functions ---------------------------------------
//-----------------------------------------------------------------------

public:

  // These member functions are the public interface to error logging.

  /**
   *  Returns a stream to which to write a message, with the parameters
   *  given.  The message must be terminated later by performing the
   *  "<< endmsg" operation on the resulting stream.  Actual output may
   *  not occur until the endmsg is executed.  The meaning of the "facility"
   *  and "code" parameters is not defined by the ErrLog base class, nor is
   *  is guaranteed that their values will be reflected in any output
   *  generated for the message.
   *
   *  The "facility" pointer must be guaranteed by the caller to remain
   *  valid until the message is completed with "endmsg".  (I.e., this
   *  function is not guaranteed to make a copy of the string.)
   */
  static std::ostream& msg( ErrLog::Severity severity, 
		       const char* facility, 
		       int code );

  /** 
   *  DEPRECATED
   *  Backward-compatibility function for an old API.
   *  Calls through to msg( severity, facilty + code, 0 )
   *  Do not use in new code.
   */
  static std::ostream& msg( ErrLog::Severity severity, 
			    const char* facility, 
			    const char* code );

  /**
   *  Tests whether actual logging output is enabled for a specific set
   *  of message parameters.  This function should be used before sending
   *  complex output to the result of ErrMsg() or ErrLog::msg(), to avoid
   *  the cost of executing the stream insertion operations (binary-to-
   *  string conversions) for the message, only to discard their output.
   */
  inline
  static bool logging( ErrLog::Severity severity, 
		       const char* facility, 
		       int code );

  /** 
   *  DEPRECATED
   *  Backward-compatibility function for an old API.
   *  Calls through to logging( severity, facilty + code, 0 )
   *  Do not use in new code.
   */
  static bool logging( ErrLog::Severity severity, 
		       const char* facility, 
		       const char* code );


  // The following are options controlling the global configuration of
  // the static "front end" to error logging.

  /**
   *  Disables the automatic warning message generated when a new ErrLog::msg()
   *  call is made before the previous one has been terminated with "endmsg".
   *  The use of this option is *strongly* discouraged; the correct response
   *  to such warnings is to fix the nested messages.
   */
  static void turnOffWarnings();


  // The following are utility functions that are probably of interest only
  // implementations (i.e., could be protected) but expose no internals and
  // are harmless, and maybe useful, to make public.

  /**
   *  Returns a static string corresponding to the enum member name of a
   *  severity level.  I.e., severityName(ErrLog::error) == "error".
   */
  static const char* severityName( ErrLog::Severity );

  /**
   *  Returns a single uppercase letter corresponding to the enum member name
   *  of a severity level.  I.e., severityName(ErrLog::error) == 'E'.
   */
  static char        severityLetter( ErrLog::Severity );



//-----------------------------------------------------------------------
// Instance public member functions -------------------------------------
//-----------------------------------------------------------------------

public:

  /**
   *  Provides parsing of a comma-delimited list of error logger
   *  behavior control options, in getsubopt() format.  The effects of
   *  the parsing depend on the specific ErrLog implementation and are
   *  established by it at constructor time using the _errOptParser()
   *  and _configureOptions() methods.
   */ 
  bool parseOpts( const char* optarg );


//-----------------------------------------------------------------------
// Friendship declarations ----------------------------------------------
//-----------------------------------------------------------------------

  friend class ErrStream;


//-----------------------------------------------------------------------
// Instance protected member functions ----------------------------------
//-----------------------------------------------------------------------

protected:

  // These members provide a basic set of functions for dealing with a
  // specific instance of ErrLog or a subclass.  They are really intended
  // only for use in configuring the active instance just after it's been
  // created.

  /**
   *  Protected constructor, for use in initializing subclasses.
   *
   *  @param minSeverity Minimum severity of messages that will be logged
   *                     by the default implementation.
   */
  ErrLog( ErrLog::Severity minSeverity = ErrLog::debugging );

  /**
   *  A virtual destructor is provided, but note that the quasi-singleton
   *  design of this class cannot guarantee that the active ErrLog instance
   *  will be deleted at application termination.
   */
  virtual ~ErrLog();

  // Functions used with ErrOptParser.

  virtual bool _configureOptions();
  ErrOptParser& _errOptParser() { return *_itsErrOptParser; }


//-----------------------------------------------------------------------
// Instance protected virtual member functions --------------------------
//-----------------------------------------------------------------------

protected:

  // These members provide the polymorphic interface for customizing the
  // behavior of an ErrLogger implementation.

  /** 
   *  Establishes an std::ostream that is to be used for logging message text,
   *  to be terminated with "endmsg".  Pure virtual.
   */
  virtual ErrStream& doMsg( ErrLog::Severity severity, 
			    const char* facility, 
			    int code ) = 0;

  /**
   *  Callback from ErrStream when a message has been completed, allowing
   *  the logger to decide what to do.
   *
   *  @param text   The full formatted message text, if the ErrStream is a
   *                "buffering" stream, or 0 (null pointer) if it is a
   *                "wrapper" stream, with output actually appearing as 
   *                each stream-output (<<) operation happens.
   *  @param stream The ErrStream to which the message had been directed.
   *                It's provided so that end-of-message output (std::endl or
   *                something more) can be written if appropriate.
   */
  virtual void doEndmsg( const char* text, ErrStream& stream ) = 0;

  /**
   *  Tests whether a message will actually be logged for a particular
   *  set of message parameters.  A default implementation is provided,
   *  based only on a test of the severity w.r.t. a minimum level, a
   *  static member of the ErrLog base class.
   *
   *  The sort of thing a subclass might do here is apply a "verbosity"
   *  control in addition to the severity test, perhaps suppressing
   *  repeated messages with the same parameters.
   */
  virtual bool doLogging( ErrLog::Severity severity, 
			  const char* facility, 
			  int code );


//-----------------------------------------------------------------------
// Static protected member functions ------------------------------------
//-----------------------------------------------------------------------

protected:

  // These members provide tools for ErrLog implementations to use.

  /** 
   *  ErrLog is a form of singleton.  Polymorphism of its static methods is
   *  arranged by calling implementation instances through this pointer.
   */
  inline static ErrLog* _implementation() { return _implInstance; }

  /** 
   *  ErrLog is a form of singleton.  The constructor of any subclass must
   *  register itself as the active instance by calling this function.
   */
  inline static void _setImplementation( ErrLog* implementation );

  /**
   *  Get the appropriate default stream for a given severity level.
   *  The facility and code arguments are not used.
   */
  static ErrStream* _getDefaultStream( ErrLog::Severity, const char*, int );

  /**
   *  Apply the logging test for a given severity level.
   *  The facility and code arguments are not used.
   */
  inline static bool _getDefaultLogging( ErrLog::Severity, const char*, int );

  /**
   *  Write a set of message parameters through into an ErrStream.
   *  This function exists so that subclasses of ErrLog can benefit
   *  from its friendship relationship with ErrStream.
   */
  static void _setParameters( ErrStream&, 
			      ErrLog::Severity, const char*, int );

  /**
   *  Evaluated and executes the default termination strategy for errors:
   *  abort() on fatal, exit(!=0) on severe, with the exit code derived from
   *  the message's "code" value.
   */
  static void _defaultTermination( ErrLog::Severity severity, 
				   int code );

  /**
   *  Tests the anticipated behavior of the default termination strategy.
   *  Available for use by implementations that need to know whether a
   *  termination will result before deciding on the disposition of a
   *  message.
   *
   *  @return 0 if termination will not occur, non-zero if it will.
   *          Negative if by signal (SIGABRT), positive if by exit(!=0).
   *
   *  @see QtrErrLog
   */
  static int _getDefaultTermination( ErrLog::Severity severity, 
				     int code );

//-----------------------------------------------------------------------
// Static private member functions --------------------------------------
//-----------------------------------------------------------------------

private:

  // These functions provide implementation details.

  static void _executeDefaultTermination( int value );


//-----------------------------------------------------------------------
// Static protected member data -----------------------------------------
//-----------------------------------------------------------------------

protected:

  // data members for the static front end and default implementation
  // These appear to be used in implementations.  A future cleanup pass
  // may be able to convert them all to private.
  static ErrStream* _myStreamCout;
  static ErrStream* _myStreamCerr;
  static ErrStream* _myDevnull;
  static Severity _minSeverity;


//-----------------------------------------------------------------------
// Static private member data -------------------------------------------
//-----------------------------------------------------------------------

private:

  // Singleton polymorphic implementation instance.
  static ErrLog* _implInstance;

  // data members for the static front end and default implementation
  static bool  _nestedWarnings;

private:

  bool _useStdio;

  // Contained by reference to avoid introducing header file dependencies:
  ErrOptRef<bool>* _useStdioOpt;
  ErrOptParser* _itsErrOptParser;

  // dis-allow copy construction and assignment
  ErrLog( const ErrLog& );
  ErrLog& operator=( const ErrLog& );

};


// Friends of ErrStream that are needed in implementing the "endmsg" feature.

void endmsg(ErrStream& es); // declare
std::ostream& operator<<(std::ostream& os, void (*fp)(ErrStream & es) );


// --------------------------------------------------------------------------
// Inline implementations ---------------------------------------------------
// --------------------------------------------------------------------------

inline bool 
ErrLog::logging( ErrLog::Severity severity, 
		 const char* facility, 
		 int code )
{
  return ( _implementation() != 0
	   ? _implementation()->doLogging( severity, facility, code )
	   : ErrLog::_getDefaultLogging( severity, facility, code )   );
}


inline void
ErrLog::_setImplementation( ErrLog* implementation )
{
  // "There can only be one" (or zero -- we can reset to the default).
  assert( implementation == 0 || _implementation() == 0 );

  // If the assertion is compiled away, this call is simply ignored.
  if ( implementation == 0 || _implementation() == 0 ) {
    _implInstance = implementation;
  }
}


inline bool 
ErrLog::_getDefaultLogging( ErrLog::Severity severity,
			    const char*,    // unused
			    int )           // unused
{
  return ( severity >= _minSeverity );
}

#endif // ERRLOG_HH