/[ascend]/trunk/test/assertimpl.h
ViewVC logotype

Annotation of /trunk/test/assertimpl.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (hide annotations) (download) (as text)
Sun Oct 30 01:38:20 2005 UTC (18 years, 7 months ago) by jds
File MIME type: text/x-chdr
File size: 5095 byte(s)
- prototype unit test suite based on CUnit added.
- unit tests for base/generic/general and base/generic/utilites added.
- 2nd manual rework of doxygen documentation in general and utilities.
- bug fixes (mostly general & utilities) found during test development.
- added asc_assert prototype to redirect failures to Asc_Panic() and enable decoupling assertions from NDEBUG.
- some modifications of interface & implementation to facilitate testing.
- utilities/ascPrint & utilities/ascMalloc functions now always included in base libs to minimize recompilation when an interface chooses different options.
1 jds 59 /*
2     * Assert implementation override for ASCEND unit tests
3     *
4     * Copyright (C) 2005 Jerry St.Clair
5     *
6     * This file is part of the Ascend Environment.
7     *
8     * The Ascend Environment is free software; you can redistribute it
9     * and/or modify it under the terms of the GNU General Public License as
10     * published by the Free Software Foundation; either version 2 of the
11     * License, or (at your option) any later version.
12     *
13     * The Ascend Environment is distributed in hope that it will be useful,
14     * but WITHOUT ANY WARRANTY; without even the implied warranty of
15     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16     * General Public License for more details.
17     *
18     * You should have received a copy of the GNU General Public License
19     * along with the program; if not, write to the Free Software Foundation,
20     * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
21     * COPYING.
22     */
23    
24     /** @file
25     * Assert implementation override for ASCEND unit tests.
26     * These functions override the default assert implementation to
27     * allow recovery from failed asserts during testing. When using
28     * this implementation, a failed assertion sets a global variable
29     * (g_assert_status) and issues a longjmp() out of the function.
30     *
31     * For example (in test function):
32     * <pre>
33     * g_assert_status = ast_passed;
34     * if (0 == setjmp(g_asc_test_env))
35     * call_function_containing_assertion();
36     *
37     * if (ast_passed == g_assert_status)
38     * ==> no assertions failed <==
39     * else
40     * ==> assertion failed <== </pre>
41     *
42     * If you desire that assert() reverts to standard behavior
43     * (issue a message on stderr and abort the program), call
44     * enable_longjump(FALSE).
45     *
46     * Support is also provided for trapping asc_assert() failures.
47     * This mechanism works by using a callback from Asc_Panic to
48     * issue a longjmp back to test code for asc_assert() failures.
49     * Test code should enable trapping of asc_assert, then use
50     * the global jmp_buf g_asc_test_env and setjmp() to wrap the
51     * code being tested. Functions are provided to check the whether
52     * an asc_assert() failure has occurred and reset the status.
53     *
54     * For example (in test function):
55     * <pre>
56     * asc_assert_catch(TRUE); (* enable trapping of asc_assert() *)
57     * asc_assert_reset(); (* prepare for a test *)
58     * if (0 == setjmp(g_asc_test_env)) (* setjmp using global jmpbuf & call suspect function *)
59     * call_function_containing_assertion();
60     *
61     * if (TRUE == asc_assert_failed()) (* test whether assertion failed *)
62     * ==> no assertions failed <==
63     * else
64     * ==> assertion failed <==
65     * asc_assert_catch(FALSE); (* disable trapping of asc_assert() when done *)
66     * </pre>
67     */
68    
69     #ifndef ASSERTIMPL_H_SEEN
70     #define ASSERTIMPL_H_SEEN
71    
72     /** assert status results. */
73     enum assert_status_t {
74     ast_failed,
75     ast_passed
76     };
77    
78     /**
79     * Global variable indicating status of last assert().
80     * Will be ast_passed if the assert passed, ast_failed otherwise.
81     */
82     extern enum assert_status_t g_assert_status;
83    
84     /**
85     * Global jump buffer variable to use for the call to setjmp().
86     */
87     extern jmp_buf g_asc_test_env;
88    
89     /**
90     * Change the behavior of failed assert()'s.
91     * Pass TRUE to enable alternate behavior using longjmp, FALSE
92     * to use standard behavior.
93     */
94     void enable_assert_longjmp(int TRUE_or_FALSE);
95    
96     /**
97     * Returns TRUE if an asc_assert() failed since the last call to
98     * asc_assert_reset() or asc_assert_catch(TRUE).
99     */
100     extern int asc_assert_failed(void);
101    
102     /**
103     * Resets the accounting on asc_assert().
104     * After calling this function, asc_assert_failed() will return FALSE.
105     * It should be called after a caught failed assertion.
106     */
107     extern void asc_assert_reset(void);
108    
109     /**
110     * Enables or disables trapping of asc_assert() failures.
111     * Pass TRUE to enable catching of failures, or FALSE to disable it.
112     * Note that while catching is enabled, any call to Asc_Panic() with a
113     * status code of ASCERR_ASSERTION_FAILED will be trapped as a failed
114     * exception. Other status codes will not be trapped. When an
115     * assertion is trapped, <br><br>
116     *
117     * This function registers a callback with Asc_Panic(). If another
118     * callback was already registered, it is replaced until
119     * asc_assert_catch(FALSE) is called. At that time the original
120     * callback will be restored.<br><br>
121     *
122     * If you're playing lots of games with Asc_Panic() callbacks, this
123     * function may mess you up. For example, if you register a new callback
124     * after calling this function (1) asc_assert() failures will not be
125     * trapped and (2) some previous callback can be restored when
126     * asc_assert_catch(FALSE) is called.
127     *
128     * @param TRUE_or_FALSE Pass TRUE to enable trapping of asc_assert
129     * failures, FALSE to disable.
130     */
131     extern void asc_assert_catch(int TRUE_or_FALSE);
132    
133     #endif /* ASSERTIMPL_H_SEEN */

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22