qassert.h

00001 /*****************************************************************************
00002 * Product:  QP/C/C++
00003 * Last Updated for Version: 4.0.04
00004 * Date of the Last Update:  Apr 09, 2009
00005 *
00006 *                    Q u a n t u m     L e a P s
00007 *                    ---------------------------
00008 *                    innovating embedded systems
00009 *
00010 * Copyright (C) 2002-2009 Quantum Leaps, LLC. All rights reserved.
00011 *
00012 * This software may be distributed and modified under the terms of the GNU
00013 * General Public License version 2 (GPL) as published by the Free Software
00014 * Foundation and appearing in the file GPL.TXT included in the packaging of
00015 * this file. Please note that GPL Section 2[b] requires that all works based
00016 * on this software must also be made publicly available under the terms of
00017 * the GPL ("Copyleft").
00018 *
00019 * Alternatively, this software may be distributed and modified under the
00020 * terms of Quantum Leaps commercial licenses, which expressly supersede
00021 * the GPL and are specifically designed for licensees interested in
00022 * retaining the proprietary status of their code.
00023 *
00024 * Contact information:
00025 * Quantum Leaps Web site:  http://www.quantum-leaps.com
00026 * e-mail:                  info@quantum-leaps.com
00027 *****************************************************************************/
00028 #ifndef qassert_h
00029 #define qassert_h
00030 
00031 /**
00032 * \file
00033 * \ingroup qep qf qk qs
00034 * \brief Customizable QP assertions.
00035 *
00036 * Defines customizable and memory-efficient assertions applicable to
00037 * embedded systems. This header file can be used in C, C++, and mixed C/C++
00038 * programs.
00039 *
00040 * \note The preprocessor switch Q_NASSERT disables checking assertions.
00041 * In particular macros \ref Q_ASSERT, \ref Q_REQUIRE, \ref Q_ENSURE,
00042 * \ref Q_INVARIANT, and \ref Q_ERROR do NOT evaluate the test condition
00043 * passed as the argument to these macros. One notable exception is the
00044 * macro \ref Q_ALLEGE, that still evaluates the test condition, but does
00045 * not report assertion failures when the switch Q_NASSERT is defined.
00046 */
00047 #ifdef Q_NASSERT          /* Q_NASSERT defined--assertion checking disabled */
00048 
00049     #define Q_DEFINE_THIS_FILE
00050     #define Q_DEFINE_THIS_MODULE(name_)
00051     #define Q_ASSERT(test_)    ((void)0)
00052     #define Q_ALLEGE(test_)    ((void)(test_))
00053     #define Q_ERROR()          ((void)0)
00054 
00055 #else                  /* Q_NASSERT not defined--assertion checking enabled */
00056 
00057     #ifdef __cplusplus
00058         extern "C" {
00059     #endif
00060 
00061     /** callback invoked in case the condition passed to \ref Q_ASSERT,
00062     * \ref Q_REQUIRE, \ref Q_ENSURE, \ref Q_ERROR, or \ref Q_ALLEGE
00063     * evaluates to FALSE.
00064     *
00065     * \param file file name where the assertion failed
00066     * \param line line number at which the assertion failed
00067     */
00068     /*lint -sem(Q_onAssert, r_no)                Q_onAssert() never returns */
00069     void Q_onAssert(char const Q_ROM * const Q_ROM_VAR file, int line);
00070 
00071     #ifdef __cplusplus
00072         }
00073     #endif
00074 
00075     /** Place this macro at the top of each C/C++ module to define the file
00076     * name string using __FILE__ (NOTE: __FILE__ might contain lengthy path
00077     * name). This file name will be used in reporting assertions in this file.
00078     */
00079     #define Q_DEFINE_THIS_FILE \
00080         static char const Q_ROM Q_ROM_VAR l_this_file[] = __FILE__;
00081 
00082     /** Place this macro at the top of each C/C++ module to define the module
00083     * name as the argument \a name_. This file name will be used in reporting
00084     * assertions in this file.
00085     */
00086     #define Q_DEFINE_THIS_MODULE(name_) \
00087         static char const Q_ROM Q_ROM_VAR l_this_file[] = #name_;
00088 
00089     /** General purpose assertion that makes sure the \a test_ argument is
00090     * TRUE. Calls the Q_onAssert() callback if the \a test_ evaluates
00091     * to FALSE.
00092     * \note the \a test_ is NOT evaluated if assertions are
00093     * disabled with the Q_NASSERT switch.
00094     */
00095     #define Q_ASSERT(test_) \
00096         if (test_) { \
00097         } \
00098         else (Q_onAssert(l_this_file, __LINE__))
00099 
00100     /** General purpose assertion that ALWAYS evaluates the \a test_
00101     * argument and calls the Q_onAssert() callback if the \a test_
00102     * evaluates to FALSE.
00103     * \note the \a test_ argument IS always evaluated even when assertions are
00104     * disabled with the Q_NASSERT macro. When the Q_NASSERT macro is
00105     * defined, the Q_onAssert() callback is NOT called, even if the
00106     * \a test_ evaluates to FALSE.
00107     */
00108     #define Q_ALLEGE(test_)    Q_ASSERT(test_)
00109 
00110     /** Assertion that always calls the Q_onAssert() callback if
00111     * ever executed.
00112     * \note can be disabled with the Q_NASSERT switch.
00113     */
00114     #define Q_ERROR() \
00115         (Q_onAssert(l_this_file, __LINE__))
00116 
00117 #endif                                                         /* Q_NASSERT */
00118 
00119 /** Assertion that checks for a precondition. This macro is equivalent to
00120 * \ref Q_ASSERT, except the name provides a better documentation of the
00121 * intention of this assertion.
00122 */
00123 #define Q_REQUIRE(test_)   Q_ASSERT(test_)
00124 
00125 /** Assertion that checks for a postcondition. This macro is equivalent to
00126 * \ref Q_ASSERT, except the name provides a better documentation of the
00127 * intention of this assertion.
00128 */
00129 #define Q_ENSURE(test_)    Q_ASSERT(test_)
00130 
00131 /** Assertion that checks for an invariant. This macro is equivalent to
00132 * \ref Q_ASSERT, except the name provides a better documentation of the
00133 * intention of this assertion.
00134 */
00135 #define Q_INVARIANT(test_) Q_ASSERT(test_)
00136 
00137 /** Compile-time assertion exploits the fact that in C/C++ a dimension of
00138 * an array cannot be negative. The following declaration causes a compilation
00139 * error if the compile-time expression (\a test_) is not TRUE. The assertion
00140 * has no runtime side effects.
00141 */
00142 #define Q_ASSERT_COMPILE(test_) \
00143     extern char Q_assert_compile[(test_) ? 1 : -1]
00144 
00145 #endif                                                         /* qassert_h */