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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 76 - (show annotations) (download) (as text)
Mon Dec 5 17:31:00 2005 UTC (14 years, 7 months ago) by johnpye
File MIME type: text/x-chdr
File size: 5696 byte(s)
More error_reporter calls.
Removed some C++-unfriendly var names.
Removed some debug messages.
Turned off compiler timing and relation debugging.
1 #ifndef ASC_ERROR_H
2 #define ASC_ERROR_H
3 /**
4 This file provides error reporting to a callback function via
5 ASCEND's FPRINTF(ASCERR,...) syntax. It is anticipated that
6 this would gradually be expanded to including richer reporting
7 of errors with severity and source file name and line numbers.
8
9 Usage:
10 error_reporter_start(<error-severity>,<filepath>,<linenumber>);
11 FPRINTF(ASCERR,"half of ");
12 FPRINTF(ASCERR,"your message");
13 error_reporter_end_flush();
14
15 or:
16 error_reporter_start(<error-severity>,<filepath>,<linenumber>
17 ,"format string %s %d etc",<printf-args>,...");
18
19 The first form allows you to use multiple FPRINTF statements to
20 generate your error message. The second form assumes that your
21 entire message will be contained in a single statement.
22
23 Error severities are
24 ASC_(USER|PROG)_(NOTE|WARNING|ERROR)
25 and ASC_USER_SUCCESS
26 */
27
28 #include <stdio.h>
29 #include <stdlib.h>
30 #include <stdarg.h>
31
32 /**
33 ascConfig defines ASC_FPRINTF etc, the routines to provide
34 default 'real' printf behaviour on this platform. (As
35 opposed to the sneaky stuff that FPRINTF does in this header)
36 */
37 #include "utilities/ascConfig.h"
38
39 /**
40 FPRINTF(ASCERR,...) messages will by default be treated
41 by the error_reporter as ASC_PROG_NOTE messages. These will
42 gradually need to be replaced with error_severity_t values
43 that accurately reflect the nature of the error.
44 */
45 #define FPRINTF fprintf_error_reporter
46 #define FPUTC fputc_error_reporter
47 #define PUTC fputc_error_reporter
48 #define FFLUSH fflush_error_reporter
49
50 /**
51 This nice macro on GNU C allows quick-and-dirty debug error
52 messages using the ERROR_REPORTER_DEBUG macro. On non GNU C
53 systems, you will still get the error messages, but the location
54 of the error won't be reported, because you don't support
55 variadic macros.
56 */
57 #ifdef __GNUC__
58 # define ERROR_REPORTER_DEBUG(ARGS...) error_reporter(ASC_PROG_NOTE,__FILE__,__LINE__,ARGS)
59 #else
60 # define ERROR_REPORTER_DEBUG error_reporter_note_no_line
61 int error_reporter_note_no_line(const char *fmt,...);
62 #endif
63
64 /**
65 Error severity codes. This will be used to visually
66 the seriousness of errors. ASC_PROG_ERRORs for example
67 might be red, or be highlighted with a (!) icon, etc.
68 */
69 typedef enum error_severity_enum{
70 ASC_USER_SUCCESS=0
71 ,ASC_USER_NOTE=1 /**< a note to the user */
72 ,ASC_USER_WARNING /**< the user has done something bad but tolerable */
73 ,ASC_USER_ERROR /**< the user has done something wrong */
74 ,ASC_PROG_NOTE /**< a note for the programmer */
75 ,ASC_PROG_WARNING /**< the program encounters an unexpected state */
76 ,ASC_PROG_ERROR /**< the program has failed but can ignore and continue (maybe) */
77 ,ASC_PROG_FATAL /**< fatal error, program will exit */
78 } error_severity_t;
79
80 /// An alias for ASC_PROG_ERROR
81 #define ASC_PROG_ERR ASC_PROG_ERROR
82
83 #define ERROR_REPORTER_MAX_MSG 4096 /* no particular reason */
84
85 typedef struct{
86 unsigned char iscaching; /** set to true for fprintf_error_reporter to do its work */
87 error_severity_t sev;
88 const char *filename;
89 int line;
90 char msg[ERROR_REPORTER_MAX_MSG];
91 } error_reporter_meta_t;
92
93 /**
94 This is the drop-in replacement for Asc_FPrintf. Anythin you attempt
95 to print to stderr will be captured and passed to the error_reporter_callback
96 function for handling.
97 */
98 int fprintf_error_reporter(FILE *file, const char *fmt, ...);
99
100 /**
101 If file!=stderr, this will do the usual thing. If file==stderr, it will output
102 the character via fprintf_error_reporter.
103 */
104 int fputc_error_reporter(int c, FILE *file); /* just calls fprintf_error_reporter */
105
106 /**
107 This replaces the standard 'fflush' of Asc_FFlush. If file!=stderr, it will
108 call the standard fflush. If file==stderr, it will call error_reporter_end_flush.
109 */
110 int fflush_error_reporter(FILE *file);
111
112 /**
113 Start a cached error report. This means that multiple frprintf_error_reporter calls will
114 be stored in a global string until an error_reporter_end_flush is encountered.
115 */
116 int error_reporter_start(const error_severity_t sev, const char *filename, const int line);
117
118 /**
119 Output the contents of the checked global string as an error report
120 */
121 int error_reporter_end_flush();
122
123 /**
124 This #define saves you typing the list of arguments in your
125 callback function declarations.
126 */
127 #define ERROR_REPORTER_CALLBACK_ARGS \
128 const error_severity_t sev \
129 , const char *filename, const int line \
130 , const char *fmt, const va_list args
131
132 /*
133 In you have functions which pass-through callback parameters,
134 this #define ensures that if their ordering/naming changes,
135 you won't have to go hunting and change stuff.
136 */
137 #define ERROR_REPORTER_CALLBACK_VARS \
138 sev, filename, line, fmt, args
139
140 /*
141 Define the type of the function pointer to be used for all
142 error reporting functions. The final argument is a va_list.
143 You should use 'vsnprintf' of 'vfprintf' to output your
144 message to the desired file or string, see <stdio.h> for these.
145 */
146 typedef int (*error_reporter_callback_t)(
147 ERROR_REPORTER_CALLBACK_ARGS
148 );
149
150 /**
151 Use this function directly for 'richer' reporting of
152 of error messages.
153
154 @return follows the style of fprintf
155 */
156 int error_reporter(
157 const error_severity_t sev
158 , const char *errfile, const int errline
159 , const char *fmt, ...
160 );
161
162 /**
163 This format of the error reporter is useful if you must call it
164 from another variable-argument-list function.
165 */
166 int va_error_reporter(ERROR_REPORTER_CALLBACK_ARGS);
167
168 /**
169 Set error reporting callback function using this
170 function. If left unset, errors will be printed
171 to standard error, which is effectively what the
172 hitherto FPRINTF has done.
173 */
174 void error_reporter_set_callback(
175 const error_reporter_callback_t new_callback
176 );
177
178 #endif /* ASC_ERROR_H */

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