trunk/test/assertimpl.h

/*  ASCEND modelling environment
    Copyright (C) 2005 Jerry St.Clair
    Copyright (C) 2006 Carnegie Mellon University

    This program 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, or (at your option)
    any later version.

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