CppAD: A C++ Algorithmic Differentiation Package  20130102
cppad_assert.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_CPPAD_ASSERT_INCLUDED
00003 # define CPPAD_CPPAD_ASSERT_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-12 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Eclipse Public License Version 1.0.
00011 
00012 A copy of this license is included in the COPYING file of this distribution.
00013 Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
00014 -------------------------------------------------------------------------- */
00015 
00016 /*!
00017 \defgroup cppad_assert_hpp cppad_assert.hpp
00018 \{
00019 \file cppad_assert.hpp
00020 Define the CppAD error checking macros (all of which begin with CPPAD_ASSERT_)
00021 */
00022 
00023 /*
00024 -------------------------------------------------------------------------------
00025 $begin cppad_assert$$
00026 $spell
00027      CppAD
00028      exp
00029      const
00030      bool
00031 $$
00032 
00033 $index assert, error macro $$
00034 $index error, assert macro$$
00035 $index macro, error assert$$
00036 
00037 $section CppAD Assertions During Execution$$
00038 
00039 $head Syntax$$
00040 $codei%CPPAD_ASSERT_KNOWN(%exp%, %msg%)
00041 %$$
00042 $codei%CPPAD_ASSERT_UNKNOWN(%exp%)%$$
00043 
00044 
00045 $head Purpose$$
00046 These CppAD macros are used to detect and report errors.
00047 They are documented here because they correspond to the C++
00048 source code that the error is reported at.
00049 
00050 $head NDEBUG$$
00051 $index NDEBUG$$
00052 If the preprocessor symbol 
00053 $cref/NDEBUG/Faq/Speed/NDEBUG/$$ is defined,
00054 these macros do nothing; i.e., they are optimized out.
00055 
00056 $head Restriction$$
00057 The CppAD user should not uses these macros.
00058 You can however write your own macros that do not begin with $code CPPAD$$
00059 and that call the $cref/CppAD error handler/ErrorHandler/$$.
00060 
00061 $subhead Known$$
00062 $index CPPAD_ASSERT_KNOWN$$
00063 The $code CPPAD_ASSERT_KNOWN$$ macro is used to check for an error
00064 with a known cause.
00065 For example, many CppAD routines uses these macros
00066 to make sure their arguments conform to their specifications.
00067 
00068 $subhead Unknown$$
00069 $index CPPAD_ASSERT_UNKNOWN$$
00070 The $code CPPAD_ASSERT_UNKNOWN$$ macro is used to check that the 
00071 CppAD internal data structures conform as expected.
00072 If this is not the case, CppAD does not know why the error has 
00073 occurred; for example, the user may have written past the end
00074 of an allocated array.
00075 
00076 $head Exp$$
00077 The argument $icode exp$$ is a C++ source code expression
00078 that results in a $code bool$$ value that should be true.
00079 If it is false, an error has occurred.
00080 This expression may be execute any number of times 
00081 (including zero times) so it must have not side effects.
00082 
00083 $head Msg$$
00084 The argument $icode msg$$ has prototype
00085 $codei%
00086      const char *%msg%
00087 %$$
00088 and contains a $code '\0'$$ terminated character string.
00089 This string is a description of the error 
00090 corresponding to $icode exp$$ being false.
00091 
00092 $head Error Handler$$
00093 These macros use the 
00094 $cref/CppAD error handler/ErrorHandler/$$ to report errors.
00095 This error handler can be replaced by the user.
00096 
00097 $end
00098 ------------------------------------------------------------------------------
00099 */
00100 
00101 # include <cassert>
00102 # include <iostream>
00103 # include <cppad/error_handler.hpp>
00104 
00105 # ifdef _OPENMP
00106 # include <omp.h>
00107 # endif
00108 
00109 
00110 /*!
00111 \def CPPAD_ASSERT_KNOWN(exp, msg)
00112 Check that \a exp is true, if not print \a msg and terminate execution.
00113 
00114 The C++ expression \a exp is expected to be true.
00115 If it is false,
00116 the CppAD use has made an error that is described by \a msg.
00117 If the preprocessor symbol \a NDEBUG is not defined,
00118 and \a exp is false,
00119 this macro will report the source code line number at
00120 which this expected result occurred.
00121 In addition, it will print the specified error message \a msg.
00122 */
00123 # ifdef NDEBUG
00124 # define CPPAD_ASSERT_KNOWN(exp, msg)  // do nothing
00125 # else
00126 # define CPPAD_ASSERT_KNOWN(exp, msg)           \
00127 {    if( ! ( exp ) )                         \
00128      CppAD::ErrorHandler::Call(              \
00129           true       ,                    \
00130           __LINE__   ,                    \
00131           __FILE__   ,                    \
00132           #exp       ,                    \
00133           msg        );                   \
00134 }
00135 # endif
00136 
00137 /*!
00138 \def CPPAD_ASSERT_UNKNOWN(exp)
00139 Check that \a exp is true, if not terminate execution.
00140 
00141 The C++ expression \a exp is expected to be true.
00142 If it is false,
00143 CppAD has detected an error but does not know the cause of the error.
00144 If the preprocessor symbol \a NDEBUG is not defined,
00145 and \a exp is false,
00146 this macro will report the source code line number at
00147 which this expected result occurred.
00148 */
00149 # ifdef NDEBUG
00150 # define CPPAD_ASSERT_UNKNOWN(exp)      // do nothing
00151 # else
00152 # define CPPAD_ASSERT_UNKNOWN(exp)              \
00153 {    if( ! ( exp ) )                         \
00154      CppAD::ErrorHandler::Call(              \
00155           false      ,                    \
00156           __LINE__   ,                    \
00157           __FILE__   ,                    \
00158           #exp       ,                    \
00159           ""         );                   \
00160 }
00161 # endif
00162 
00163 /*!
00164 \def CPPAD_ASSERT_NARG_NRES(op, n_arg, n_res)
00165 Check that operator \a op has the specified number of of arguments and results.
00166 
00167 If \a NDEBUG is not defined and either the number of arguments 
00168 or the number of results are not as expected,
00169 execution is terminated and the source code line number is reported.
00170 */
00171 # define CPPAD_ASSERT_NARG_NRES(op, n_arg, n_res)   \
00172      CPPAD_ASSERT_UNKNOWN( NumArg(op) == n_arg ) \
00173      CPPAD_ASSERT_UNKNOWN( NumRes(op) == n_res ) 
00174 
00175 /*!
00176 \def CPPAD_ASSERT_FIRST_CALL_NOT_PARALLEL
00177 Check that the first call to a routine is not during parallel execution mode. 
00178 
00179 If \c NDEBUG is defined, this macro has no effect
00180 (not even the definition of (\c assert_first_call).
00181 Otherwise, the variable 
00182 \code
00183      static bool assert_first_call
00184 \endcode
00185 is defined and if the first call is executed in parallel mode,
00186 execution is terminated and the source code line number is reported.
00187 */
00188 # ifdef NDEBUG
00189 # define CPPAD_ASSERT_FIRST_CALL_NOT_PARALLEL
00190 # else
00191 # define CPPAD_ASSERT_FIRST_CALL_NOT_PARALLEL                           \
00192      static bool assert_first_call = true;                              \
00193      if( assert_first_call )                                            \
00194      {    CPPAD_ASSERT_KNOWN(                                           \
00195           ! (CppAD::thread_alloc::in_parallel() ),                      \
00196           "In parallel mode and parallel_setup has not been called."    \
00197           );                                                            \
00198           assert_first_call = false;                                    \
00199      }
00200 # endif
00201 
00202 /*! \} */
00203 # endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines