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

Contents of /trunk/test/assertimpl.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (show annotations) (download) (as text)
Sun Oct 30 01:38:20 2005 UTC (15 years, 1 month 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 /*
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