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