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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (hide 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 jds 54 /*
2 aw0a 1 * 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 jds 59
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 aw0a 1
39 jds 54 /** @file
40 jds 59 * Ascend Panic - fatal error handling.
41 jds 54 * <pre>
42 aw0a 1 * To include this header file, you must include the following:
43     * #include <stdarg.h>
44 jds 54 * #include "utilities/ascConfig.h"
45     * </pre>
46 aw0a 1 */
47    
48 jds 59 #ifndef _ascpanic_h_seen
49     #define _ascpanic_h_seen
50 aw0a 1
51 jds 59 #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 aw0a 1 *
79 jds 59 * 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 aw0a 1 *
84 jds 59 * 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 aw0a 1 */
96    
97 jds 59 extern void Asc_PanicSetOutfile(CONST char *filename);
98     /**<
99     * Sets a file name for reporting of Asc_Panic() messages.
100 aw0a 1 * 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 jds 59 * previous calls to Asc_PanicSetOutfile().
105     *
106     * @param filename Pointer to the name of the file to print messages to.
107 aw0a 1 */
108    
109 jds 59 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 jds 54
124 jds 59 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