trunk/test/assertimpl.h

/*
 *  Assert implementation override for ASCEND unit tests
 *
 *  Copyright (C) 2005 Jerry St.Clair
 *
 *  This file is part of the Ascend Environment.
 *
 *  The Ascend Environment is free software; you can redistribute it
 *  and/or modify it under the terms of the GNU General Public License as
 *  published by the Free Software Foundation; either version 2 of the
 *  License, or (at your option) any later version.
 *
 *  The Ascend Environment is distributed in hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.
 */

/** @file
 *  Assert implementation override for ASCEND unit tests.
 *  These functions override the default assert implementation to
 *  allow recovery from failed asserts during testing.  When using 
 *  this implementation, a failed assertion sets a global variable
 *  (g_assert_status) and issues a longjmp() out of the function.
 *
 *  For example (in test function):
 *                                                  <pre>
 *    g_assert_status = ast_passed;
 *    if (0 == setjmp(g_asc_test_env))
 *      call_function_containing_assertion();
 *
 *    if (ast_passed == g_assert_status)
 *      ==> no assertions failed <==
 *    else
 *      ==> assertion failed <==                   </pre>
 *
 *  If you desire that assert() reverts to standard behavior
 *  (issue a message on stderr and abort the program), call
 *  enable_longjump(FALSE).
 *
 *  Support is also provided for trapping asc_assert() failures.
 *  This mechanism works by using a callback from Asc_Panic to
 *  issue a longjmp back to test code for asc_assert() failures.
 *  Test code should enable trapping of asc_assert, then use
 *  the global jmp_buf g_asc_test_env and setjmp() to wrap the
 *  code being tested.  Functions are provided to check the whether
 *  an asc_assert() failure has occurred and reset the status.
 *
 *  For example (in test function):
 *  <pre>
 *    asc_assert_catch(TRUE);           (* enable trapping of asc_assert() *)
 *    asc_assert_reset();               (* prepare for a test *)
 *    if (0 == setjmp(g_asc_test_env))  (* setjmp using global jmpbuf & call suspect function *)
 *      call_function_containing_assertion();
 *
 *    if (TRUE == asc_assert_failed())  (* test whether assertion failed *)
 *      ==> no assertions failed <==
 *    else
 *      ==> assertion failed <==
 *    asc_assert_catch(FALSE);          (* disable trapping of asc_assert() when done *)
 *  </pre>
 */

#ifndef ASSERTIMPL_H_SEEN
#define ASSERTIMPL_H_SEEN

/** assert status results. */
enum assert_status_t {
  ast_failed,
  ast_passed
};

/**
 *  Global variable indicating status of last assert().
 *  Will be ast_passed if the assert passed, ast_failed otherwise.
 */
extern enum assert_status_t g_assert_status;

/**
 *  Global jump buffer variable to use for the call to setjmp().
 */
extern jmp_buf g_asc_test_env;

/**
 *  Change the behavior of failed assert()'s.
 *  Pass TRUE to enable alternate behavior using longjmp, FALSE
 *  to use standard behavior.
 */
void enable_assert_longjmp(int TRUE_or_FALSE);

/** 
 *  Returns TRUE if an asc_assert() failed since the last call to
 *  asc_assert_reset() or asc_assert_catch(TRUE).
 */
extern int asc_assert_failed(void);

/** 
 *  Resets the accounting on asc_assert().
 *  After calling this function, asc_assert_failed() will return FALSE.
 *  It should be called after a caught failed assertion.
 */
extern void asc_assert_reset(void);

/** 
 *  Enables or disables trapping of asc_assert() failures.
 *  Pass TRUE to enable catching of failures, or FALSE to disable it.
 *  Note that while catching is enabled, any call to Asc_Panic() with a
 *  status code of ASCERR_ASSERTION_FAILED will be trapped as a failed
 *  exception.  Other status codes will not be trapped.  When an
 *  assertion is trapped, <br><br>
 *
 *  This function registers a callback with Asc_Panic().  If another
 *  callback was already registered, it is replaced until
 *  asc_assert_catch(FALSE) is called.  At that time the original
 *  callback will be restored.<br><br>
 *
 *  If you're playing lots of games with Asc_Panic() callbacks, this
 *  function may mess you up.  For example, if you register a new callback
 *  after calling this function (1) asc_assert() failures will not be 
 *  trapped and (2) some previous callback can be restored when
 *  asc_assert_catch(FALSE) is called.
 *
 *  @param TRUE_or_FALSE Pass TRUE to enable trapping of asc_assert
 *                       failures, FALSE to disable.
 */
extern void asc_assert_catch(int TRUE_or_FALSE);

#endif  /* ASSERTIMPL_H_SEEN */
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 */