// doc/error.dox


// Copyright 2009-2011 Microsoft Corporation

// See ../../COPYING for clarification regarding multiple authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//  http://www.apache.org/licenses/LICENSE-2.0

// THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
// WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
// MERCHANTABLITY OR NON-INFRINGEMENT.
// See the Apache 2 License for the specific language governing permissions and
// limitations under the License.

namespace kaldi {
/** \page error Kaldi logging and error-reporting

  \section error_overview Overview

  All output that consists of logging messages, warnings or errors is
  directed to the standard error in Kaldi programs.  This is so that our
  programs can be used in of pipes without such messages becoming
  "mixed up" with the program's output.  The most common way to produce logging,
  warning or error output is through the macros KALDI_LOG, KALDI_WARN and
  KALDI_ERR.  Invoking the KALDI_ERR macro will normally terminate the program
  (unless the exception is caught).  An example code fragment that illustrates
  all three of these is as follows:
  \code

  KALDI_LOG << "On iteration " << iter
            << ", objective function change was " << delta;
  if (delta < 0.0) {
    KALDI_WARN << "Negative objf change " << delta;
    if (delta < -0.1) 
      KALDI_ERR << "Convergence failure in EM";
  }
  \endcode
  Notice that these examples don't include a newline character (this gets added
  automatically).  A typical example of the messages that get produced by this is:
 \verbatim
  WARNING (copy-feats:Next():util/kaldi-table-inl.h:381) Invalid archive file format
\endverbatim
  For log messages that are not quite important enough (or are too verbose) to appear in
 normal logs, you can use KALDI_VLOG: for example,
 \code
  KALDI_VLOG(2) << "This message is not important enough to use KALDI_LOG for.";
 \endcode
 This will get printed if the argument to the \c --verbose option is greater than
 or equal to the number in parentheses, e.g. the message above would get printed
 if the user called a program with \c --verbose=2 or greater.  See \ref parse_options_implicit
 for more context on this.

 Some parts of the code print logging messages to the standard error directly; this
 is discouraged.

 \section error_assertions Assertions in Kaldi

 Assertions should ideally be done using the macro KALDI_ASSERT.  This prints more informative
 output than a normal assertion using assert(); KALDI_ASSERT prints a stack trace.  
 KALDI_ASSERT is also more reconfigurable.

 A typical assertion is: 
\code
 KALDI_ASSERT(i < M.NumRows());
\endcode
 A trick that we sometimes to get more informative assert-failure message is
 to follow the assert condition with "&& [some string]", for example:
\code
 KALDI_ASSERT(ApproxEqual(delta, objf_change) && "Probable coding error in optimization");
\endcode

 If compiled normally asserts will get checked, but not if compiled with NDEBUG defined.
 For inner-loop assertions that use a lot of CPU,
 we use the following pattern:
\code
#ifdef KALDI_PARANOID
  KALDI_ASSERT(i>=0);
#endif
\endcode
 The macro KALDI_PARANOID is on by default in the current build setup.  
  
 \section error_exceptions Exceptions thrown by KALDI_ERR

 When the KALDI_ERR macro is invoked, it prints
 the error message to the standard error, and then  throws an exception of type std::runtime_error. 
 The string held by this exception contains the error message, and also a stack trace 
 (if supported by the OS).  The normal behavior of current Kaldi programs is to catch the exception
 in a try...catch block in main(), which prints the exception's string to the standard error, and exits.
 This typically results in the error message being printed twice. 

 In some cases, the error message will be caught by Kaldi code and not re-thrown.
 This occurs in Holder code (see \ref io_sec_holders) that is called by
 Table code (see \ref io_sec_tables).  Here, exceptions thrown by Read
 functions of Kaldi objects are caught and get propagated to the Table code as
 a boolean return value (e.g. see KaldiObjectHolder::Read() ).  Depending
 on the \ref io_sec_rspecifiers "options", such as the "p" (permissive) option to the Table code,
 and depending how the Table code is called, this may or may not result in another 
 exception.

 The only other type of error other than std::runtime_error that should get
 thrown in Kaldi code under normal circumstances is probably std::alloc_error.  

 Some parts of Kaldi code currently throw std::runtime_error directly, or call assert() directly,
 but this is to be changed to the more standard KALDI_ERR and KALDI_ASSERT macros.

 \section error_compile_time_assertions Compile-time assertions in Kaldi

 It is also possible to make assertions that are checked at compile time (they
 will produce a compilation error if they fail).  This is enabled by some macros
 defined in kaldi-utils.h.  It is especially useful to make sure that templates
 have been instantiated with the right kind of types.  Examples of compile-time
 assertions are:
\code
  KALDI_COMPILE_TIME_ASSERT(kSomeConstant < 0);
  ...
  template<class T> class foo {
     foo() { KALDI_ASSERT_IS_INTEGER_TYPE(T);
  };
  ...
  template<class T> class bar {
     bar() { KALDI_ASSERT_IS_FLOATING_TYPE(T);
  }
\endcode



*/

/**
 \defgroup error_group "Functions relating to logging and error reporting"

 See \ref error_overview for an overview of how logging and errors are handled in Kaldi.

*/
}