/[ascend]/trunk/base/generic/utilities/ascPanic.h
ViewVC logotype

Contents of /trunk/base/generic/utilities/ascPanic.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (show annotations) (download) (as text)
Sun Oct 30 01:38:20 2005 UTC (14 years, 11 months ago) by jds
File MIME type: text/x-chdr
File size: 5923 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 * Ascend Panic
3 * by Mark Thomas
4 * Created: 1997.05.15
5 * Version: $Revision: 1.1 $
6 * Version control file: $RCSfile: ascPanic.h,v $
7 * Date last modified: $Date: 1997/07/18 11:43:23 $
8 * Last modified by: $Author: mthomas $
9 *
10 * This file is part of the Ascend Language Interpreter.
11 *
12 * Copyright (C) 1997 Carnegie Mellon University
13 *
14 * The Ascend Language Interpreter is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The Ascend Language Interpreter is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with the program; if not, write to the Free Software Foundation,
26 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27 * COPYING.
28 */
29
30 /* ChangeLog
31 *
32 * 10/13/2005 Added PanicCallbackFunc and Asc_PanicSetCallback() to
33 * support callback functionality & ability to cancel exit
34 * for use in unit test. Added asc_assert() for handling
35 * of assertions through Asc_Panic() & potential decoupling
36 * of assertions from NDEBUG (J.D. St.Clair)
37 */
38
39 /** @file
40 * Ascend Panic - fatal error handling.
41 * <pre>
42 * To include this header file, you must include the following:
43 * #include <stdarg.h>
44 * #include "utilities/ascConfig.h"
45 * </pre>
46 */
47
48 #ifndef _ascpanic_h_seen
49 #define _ascpanic_h_seen
50
51 #ifdef ASC_NO_ASSERTIONS
52
53 #define asc_assert(x) ((void)0)
54 /**< If assertions turned off, asc_assert() does nothing. */
55
56 #else /* assertions enabled */
57
58 #define asc_assert(cond) \
59 ((cond) ? (void)0 : Asc_Panic(ASCERR_ASSERTION_FAILED, NULL, \
60 "Assertion failed in %s:%d: '%s'", \
61 __FILE__, __LINE__, #cond))
62 /**< Our assert macro. Uses Asc_Panic() to report & handle assertion failure. */
63
64 #endif /* ASC_NO_ASSERTIONS */
65
66 extern void Asc_Panic(CONST int status, CONST char *function,
67 CONST char *format, ...);
68 /**<
69 * Prints a fatal error message, calls any registered callback
70 * function, and (usually) exits the program.
71 * This is the fatal error handler for the ASCEND system. It prints
72 * the printf-style variable arguments using the specified format to
73 * ASCERR file handle. The message is formatted with a header
74 * (e.g. 'ASCEND PANIC!!) and the name of the function (if non-NULL),
75 * followed by the variables & format passed as arguments. ASCERR
76 * should have been initialized to a valid file stream or else the
77 * message will not be printed (checked by assertion).<br><br>
78 *
79 * If a valid file name has been previously set using
80 * Asc_PanicSetOutfile(), the message is printed to this file also.
81 * Under Windows, a MessageBox will also be displayed with the
82 * message.<br><br>
83 *
84 * If a callback has been set using Asc_PanicSetCallback(), the
85 * registered function will be called with the specified status.
86 * If the callback returns non-NULL, then exit() is called to end
87 * the program. This is the default behavior. If the callback
88 * is able to resolve the problem, then it should return zero and
89 * Asc_Panic() will just return. This will be useful mostly for
90 * testing purposes, and should be used with caution.
91 *
92 * @param status Status code passed by the calling function.
93 * @param function Pointer to the name of the calling function.
94 * @param format printf-style format string for VAR_ARGS to follow.
95 */
96
97 extern void Asc_PanicSetOutfile(CONST char *filename);
98 /**<
99 * Sets a file name for reporting of Asc_Panic() messages.
100 * Calling this function with a non-NULL "filename" will cause
101 * Asc_Panic() to write panic messages to "filename" in addition to the
102 * ASCERR file handle. Passing in a "filename" of NULL causes panic
103 * messages not to be written to disk---this undoes the effect of
104 * previous calls to Asc_PanicSetOutfile().
105 *
106 * @param filename Pointer to the name of the file to print messages to.
107 */
108
109 typedef int (*PanicCallbackFunc)(int);
110 /**<
111 * Signature of the callback function called by Asc_Panic().
112 * The function takes a single argument, the status code passed
113 * to Asc_Panic() by the original caller. The function should
114 * return non-zero if Asc_Panic() should exit() the program, the
115 * default behavior. If the function is able to resolve the problem
116 * somehow, returning 0 will instruct Asc_Panic() to just return.<br><br>
117 *
118 * This functionality is provided primarily for internal testing
119 * purposes. It should be used with extreme caution in release
120 * code. Asc_Panic() is called from all over ASCEND for many
121 * error conditions, and current calls assume no return.
122 */
123
124 extern PanicCallbackFunc Asc_PanicSetCallback(PanicCallbackFunc func);
125 /**<
126 * Registers a callback function to be called by Asc_Panic().
127 * This allows the user to specify a cleanup function to be
128 * called during a fatal error. See PanicCallbackFunc for
129 * more information on the callback function.
130 *
131 * @param func Pointer to the new function to call during an Asc_Panic().
132 * @return A pointer to the previously-registered callback, or NULL
133 * if none was registered.
134 */
135
136 extern void Asc_PanicDisplayMessageBox(int TRUE_or_FALSE);
137 /**<
138 * Controls whether a MessageBox is displayed by Asc_Panic() on Windows.
139 * If TRUE_or_FALSE is non-zero then the MessageBox is displayed (the
140 * default). Pass FALSE to disable display of the MessageBox.
141 * On other platforms, has no effect.
142 */
143
144 #endif /* _ascpanic_h_seen */
145

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