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	/*
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 */