src/common/dmessage.h

/*
 *  dmessage.h
 *  panlib
 *
 *  Depends on <stdio.h>
 *
 *  Debug and error message logging and recovery.
 *
 *  Created by gward on Thu May 10 2001.
 *  Modified by plonghurst on Thursday Feb 15 2007.
 *  Copyright (c) 2001 Anyhere Software. All rights reserved.
 *
 */

#ifndef _DMESSAGE_H_
#define _DMESSAGE_H_

#ifdef __cplusplus
extern "C" {
#endif

/********************
 * Type Definitions *
 ********************/

/***********************************************************************
 * Debug message classes
 *
 *  If you are unsure what class to report, guess on the high side, which
 *  is less serious.  For example, report an error like DMCdata even
 *  when you think it's DMCsystem, unless you really know.
 *  That way, more serious errors will be recorded from higher in the call
 *  tree.  The vast majority of errors fall into the DMCdata class.
 */
typedef enum {
                DMCassert,              /* assertion failure */
                DMCmemory,              /* out of memory */
                DMCsystem,              /* system error */
                DMCparameter,           /* program parameter error */
                DMCresource,            /* file/resource unavailable */
                DMCdata,                /* data error */
                DMCinput,               /* input error */
                DMCwarning,             /* warning message */
                DMCinfo,                /* informative output */
                DMCtrace,               /* trace point */
                DMCnerr                 /* no error (terminator) */
} DMsgClass;

/***********************************************************************
 * Message flags:  record, write to logfile, send to stderr,
 *                      alert user, exit program, abort
 */
typedef enum {
                DMFrecord=01, DMFlog=02, DMFstderr=04,
                DMFalert=010, DMFexit=020, DMFabort=040
} DMsgFlag;

/************************
 * Functions and Macros *
 ************************/

/***********************************************************************
 * int
 * dmessage(int cls, const char *msg, const char *file, int line);
 *
 *  Basic call interface to debug message handler.  The file name
 *  and line number are generally taken from the ANSI-C __FILE__
 *  and __LINE__ predefined macros.  The message class are taken
 *  from the list above, and the message should not contain newlines.
 *  All DMsgClass classes except DMCassert are recoverable and
 *  dmessage() will return.  The return value is an or'ing of
 *  DMsgFlags according to what was done.
 */
#ifdef __cplusplus
extern int      dmessage(DMsgClass cls, const char *msg,
                        const char *file = NULL, int line = 0);
#else
extern int      dmessage(DMsgClass cls, const char *msg,
                        const char *file, int line);
#endif

/***********************************************************************
 * int
 * DMESG(int cls, const char *msg)
 *
 *  Basic macro call for message reporting.  What actually happens to
 *  the message depends on the current settings, controlled by
 *  global variables described in the next section.
 */
#define DMESG(cls, msg)         dmessage(cls, msg, __FILE__, __LINE__)

/***********************************************************************
 * int
 * DTEST(int cnd, int cls, const char *msg)
 *
 *  Conditional call to DMESG() for convenience.  Zero is returned if
 *  the condition (cnd) evaluates to zero, and a collection of DMsgFlags
 *  saying what was done if the condition evaluates to non-zero.
 */
#define DTEST(cnd, cls, msg)    ((cnd) ? DMESG(cls, msg) : 0)

/***********************************************************************
 * int
 * DMESGF(int cls, const char *fmt, va_list..)
 *
 *  Formatting version of DMESG() takes printf(3) format string
 *  and a variable argument list to format the message.
 */
#define DMESGF(cls, fmt, val)   (sprintf(dmessage_buf, fmt, val), \
                                        DMESG(cls, dmessage_buf))

/***********************************************************************
 * int
 * DTESTF(int cnd, DMsgClass cls, const char *fmt, va_list..)
 *
 *  Formatting version of DTEST() takes printf(3) format string
 *  and a variable argument list to format the message, but only
 *  if the condition (cnd) evaluates to non-zero.
 */
#define DTESTF(cnd, cls, fmt, val) \
                                ((cnd) ? DMESGF(cls, fmt, val) : 0)

/***********************************************************************
 * int
 * DRESET()
 *
 *  Reset last error message class.  Call before potential error-
 *  producing subroutine, then call DMESC() or DMESCF() afterwards.
 */
#define DRESET()        (dmessage_last_class = DMCnerr)

/***********************************************************************
 * int
 * DMESC(int cls, const char *msg)
 *
 *  Report only if this error is a higher priority than any since
 *  DRESET() was last called.
 */
#define DMESC(cls, msg)         DTEST((cls) < dmessage_last_class, \
                                        cls, msg)
 
/***********************************************************************
 * int
 * DMESCF(int cls, const char *fmt, va_list..)
 *
 *  Formatting version of DMESC() takes printf(3) format string, but
 *  only reports if this error is higher priority than any since
 *  DRESET() was last called.
 */
#define DMESCF(cls, fmt, val)   DTESTF((cls) < dmessage_last_class, \
                                        cls, fmt, val)

/***********************************************************************
 * void
 * DASSERT(int cnd)
 *
 *  Replacement for assert() macro; calls DTEST() with DMCassert class
 *  if asc yeilds 0.  If NDEBUG is defined, the macro becomes a no-op.
 */
#ifdef NDEBUG
#define DASSERT(asc)            ((void)0)
#else
#if defined(__STDC__) || defined(__cplusplus)
#define DASSERT(asc)            ((void)DTESTF(!(asc), DMCassert, \
                                        "assertion failed ! (%s)", #asc))
#else
#define DASSERT(asc)            ((void)DTESTF(!(asc), DMCassert, \
                                        "assertion failed ! (%s)", "asc"))
#endif
#endif

/*********************
 * Global Variabless *
 *********************/

/***********************************************************************
 * char                 dmessage_buf[DM_BUF_LEN]
 *
 *  Buffer to hold formatted message contents temporarily.
 */
#define DM_BUF_LEN      1024

extern char             dmessage_buf[DM_BUF_LEN];

/***********************************************************************
 * const char *         dmessage_class_name[]
 *
 *  The name of each of class in DMsgClass.
 */
extern const char *     dmessage_class_name[];

/***********************************************************************
 * int                  dmessage_class_flags[]
 *
 *  Flags indicating what to do with each message class.  By default,
 *  the most recent message will be stored in the dmessage_last[] array
 *  (DMFrecord), but if other flags are set, the message will be sent
 *  other places as well.  These flags are available to be altered by the
 *  controlling application, and will not be changed from their initial
 *  defaults (DMFrecord at minimum) by any of the dmessage routines.
 *  Beware:  if the DMrecord flag is turned off for a given class and
 *  dmessage() fails to do anything, it will return zero and
 *  the DTEST() and DTESTF() macro calls may return zero even
 *  though their condition evaluated to non-zero.  This problem is
 *  avoided by keeping DMrecord set for all classes.
 */
extern int              dmessage_class_flags[];

/***********************************************************************
 * int                  dmessage_class_done[]
 *
 *  Flags indicating what was last done with each message class.
 *  In other words, the last result of dmessage() for each class.
 */
extern int              dmessage_class_done[];

/***********************************************************************
 * const char *         dmessage_file[]
 *
 *  Most recent file reported for each error class.
 */
extern const char *     dmessage_file[];

/***********************************************************************
 * int                  dmessage_line[]
 *
 *  Most recent line number reported for each error class.
 */
extern int              dmessage_line[];

/***********************************************************************
 * const char *         dmessage_record[]
 *
 *  Most recent message for each class with the DMFrecord flag set,
 *  exactly as passed to dmessage().  If no message of
 *  a given class has been reported, then the corresponding
 *  dmessage_record pointer will be NULL.
 */
extern const char *     dmessage_record[];

/***********************************************************************
 * int                  dmessage_last_class
 *
 *  The lowest class message reported so far, set to DMCnerr initially.
 *  The DMESG_LAST macro provides convenient access to most recent error.
 */
extern DMsgClass        dmessage_last_class;

#define DMESG_LAST      (dmessage_record[dmessage_last_class])

/***********************************************************************
 * FILE *               dmessage_logfp
 *
 *  Pointer to open log file.  Each message is preceeded by the file
 *  name, line number, and class for log file and stderr output.  Data
 *  is flushed after each message.  If this pointer is NULL (the default),
 *  then logging is disabled even for classes with the DMFlog flag set.
 */
extern FILE *           dmessage_logfp;

/***********************************************************************
 * int                  (*dmessage_call)(DMsgClass cls, const char *msg,
 *                                      const char *file, int line)
 *
 *  Pointer to function called by dmessage() to share error handling.
 *  If assigned, this function is called with the same arguments passed
 *  to dmessage(), independent of the class flag settings.  The returned
 *  value is then used as a mask on the class flags to turn off some or
 *  all of the default actions.  The flagged actions are considered
 *  "done" and set accordingly in the dmessage_class_done global.
 *  Defaults to NULL.
 */
extern int              (*dmessage_call)(DMsgClass cls, const char *msg,
                                        const char *file, int line);

/***********************************************************************
 * int                  (*dmessage_alert)(const char *msg)
 *
 *  Pointer to function called by dmessage() to alert user.
 *  The function should return non-zero if the user was notified,
 *  or zero if the message could not be displayed for some reason.
 *  Defaults to NULL, which results in no DMFalert action.
 */
extern int              (*dmessage_alert)(const char *msg);

/***********************************************************************
 * void                 (*dmessage_exit)(int status)
 *
 *  Pointer to function called by dmessage() for classes with the
 *  DMFexit flag set, which is usually reserved for the DMCmemory class.
 *  Defaults to system exit() function, but may be reassigned by the
 *  controlling application.  Assigning a value of NULL causes dmessage()
 *  to return from these calls, which might result in a memory fault if
 *  your program does not check for NULL pointer values.  In general,
 *  library authors should NOT assume the DMCmemory class calls exit().
 */
extern void             (*dmessage_exit)(int status);

/***********************************************************************
 * void                 (*dmessage_abort)()
 *
 *  Pointer to function called by dmessage() for classes with the
 *  DMFabort flag set, which is usually reserved for the DMCassert class.
 *  Defaults to system abort() function, but may be reassigned by the
 *  controlling application.  Assigning a value of NULL causes dmessage()
 *  to return from these calls, which will probably prove disasterous.
 *  A better idea if the program wants to continue is to use setjmp() and
 *  longjmp() to recover control at a lower point in the call tree.  If
 *  assigned, this call should never return.
 */
extern void             (*dmessage_abort)();

#ifdef __cplusplus
}
#endif

#endif /* ! _DMESSAGE_H_ */
Revision:	2.1
Committed:	Wed Aug 14 20:05:23 2024 UTC (8 months, 2 weeks ago) by greg
Content type:	text/plain
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	feat(rxpict): Added new C++ picture rendering tool with multi-processing and spectral output
#	User	Rev	Content
1	greg	2.1	/*
2			* dmessage.h
3			* panlib
4			*
5			* Depends on <stdio.h>
6			*
7			* Debug and error message logging and recovery.
8			*
9			* Created by gward on Thu May 10 2001.
10			* Modified by plonghurst on Thursday Feb 15 2007.
11			* Copyright (c) 2001 Anyhere Software. All rights reserved.
12			*
13			*/
14
15			#ifndef _DMESSAGE_H_
16			#define _DMESSAGE_H_
17
18			#ifdef __cplusplus
19			extern "C" {
20			#endif
21
22			/********************
23			* Type Definitions *
24			********************/
25
26			/***********************************************************************
27			* Debug message classes
28			*
29			* If you are unsure what class to report, guess on the high side, which
30			* is less serious. For example, report an error like DMCdata even
31			* when you think it's DMCsystem, unless you really know.
32			* That way, more serious errors will be recorded from higher in the call
33			* tree. The vast majority of errors fall into the DMCdata class.
34			*/
35			typedef enum {
36			DMCassert, /* assertion failure */
37			DMCmemory, /* out of memory */
38			DMCsystem, /* system error */
39			DMCparameter, /* program parameter error */
40			DMCresource, /* file/resource unavailable */
41			DMCdata, /* data error */
42			DMCinput, /* input error */
43			DMCwarning, /* warning message */
44			DMCinfo, /* informative output */
45			DMCtrace, /* trace point */
46			DMCnerr /* no error (terminator) */
47			} DMsgClass;
48
49			/***********************************************************************
50			* Message flags: record, write to logfile, send to stderr,
51			* alert user, exit program, abort
52			*/
53			typedef enum {
54			DMFrecord=01, DMFlog=02, DMFstderr=04,
55			DMFalert=010, DMFexit=020, DMFabort=040
56			} DMsgFlag;
57
58			/************************
59			* Functions and Macros *
60			************************/
61
62			/***********************************************************************
63			* int
64			* dmessage(int cls, const char msg, const char file, int line);
65			*
66			* Basic call interface to debug message handler. The file name
67			* and line number are generally taken from the ANSI-C __FILE__
68			* and __LINE__ predefined macros. The message class are taken
69			* from the list above, and the message should not contain newlines.
70			* All DMsgClass classes except DMCassert are recoverable and
71			* dmessage() will return. The return value is an or'ing of
72			* DMsgFlags according to what was done.
73			*/
74			#ifdef __cplusplus
75			extern int dmessage(DMsgClass cls, const char *msg,
76			const char *file = NULL, int line = 0);
77			#else
78			extern int dmessage(DMsgClass cls, const char *msg,
79			const char *file, int line);
80			#endif
81
82			/***********************************************************************
83			* int
84			* DMESG(int cls, const char *msg)
85			*
86			* Basic macro call for message reporting. What actually happens to
87			* the message depends on the current settings, controlled by
88			* global variables described in the next section.
89			*/
90			#define DMESG(cls, msg) dmessage(cls, msg, __FILE__, __LINE__)
91
92			/***********************************************************************
93			* int
94			* DTEST(int cnd, int cls, const char *msg)
95			*
96			* Conditional call to DMESG() for convenience. Zero is returned if
97			* the condition (cnd) evaluates to zero, and a collection of DMsgFlags
98			* saying what was done if the condition evaluates to non-zero.
99			*/
100			#define DTEST(cnd, cls, msg) ((cnd) ? DMESG(cls, msg) : 0)
101
102			/***********************************************************************
103			* int
104			* DMESGF(int cls, const char *fmt, va_list..)
105			*
106			* Formatting version of DMESG() takes printf(3) format string
107			* and a variable argument list to format the message.
108			*/
109			#define DMESGF(cls, fmt, val) (sprintf(dmessage_buf, fmt, val), \
110			DMESG(cls, dmessage_buf))
111
112			/***********************************************************************
113			* int
114			* DTESTF(int cnd, DMsgClass cls, const char *fmt, va_list..)
115			*
116			* Formatting version of DTEST() takes printf(3) format string
117			* and a variable argument list to format the message, but only
118			* if the condition (cnd) evaluates to non-zero.
119			*/
120			#define DTESTF(cnd, cls, fmt, val) \
121			((cnd) ? DMESGF(cls, fmt, val) : 0)
122
123			/***********************************************************************
124			* int
125			* DRESET()
126			*
127			* Reset last error message class. Call before potential error-
128			* producing subroutine, then call DMESC() or DMESCF() afterwards.
129			*/
130			#define DRESET() (dmessage_last_class = DMCnerr)
131
132			/***********************************************************************
133			* int
134			* DMESC(int cls, const char *msg)
135			*
136			* Report only if this error is a higher priority than any since
137			* DRESET() was last called.
138			*/
139			#define DMESC(cls, msg) DTEST((cls) < dmessage_last_class, \
140			cls, msg)
141
142			/***********************************************************************
143			* int
144			* DMESCF(int cls, const char *fmt, va_list..)
145			*
146			* Formatting version of DMESC() takes printf(3) format string, but
147			* only reports if this error is higher priority than any since
148			* DRESET() was last called.
149			*/
150			#define DMESCF(cls, fmt, val) DTESTF((cls) < dmessage_last_class, \
151			cls, fmt, val)
152
153			/***********************************************************************
154			* void
155			* DASSERT(int cnd)
156			*
157			* Replacement for assert() macro; calls DTEST() with DMCassert class
158			* if asc yeilds 0. If NDEBUG is defined, the macro becomes a no-op.
159			*/
160			#ifdef NDEBUG
161			#define DASSERT(asc) ((void)0)
162			#else
163			#if defined(__STDC__) \|\| defined(__cplusplus)
164			#define DASSERT(asc) ((void)DTESTF(!(asc), DMCassert, \
165			"assertion failed ! (%s)", #asc))
166			#else
167			#define DASSERT(asc) ((void)DTESTF(!(asc), DMCassert, \
168			"assertion failed ! (%s)", "asc"))
169			#endif
170			#endif
171
172			/*********************
173			* Global Variabless *
174			*********************/
175
176			/***********************************************************************
177			* char dmessage_buf[DM_BUF_LEN]
178			*
179			* Buffer to hold formatted message contents temporarily.
180			*/
181			#define DM_BUF_LEN 1024
182
183			extern char dmessage_buf[DM_BUF_LEN];
184
185			/***********************************************************************
186			* const char * dmessage_class_name[]
187			*
188			* The name of each of class in DMsgClass.
189			*/
190			extern const char * dmessage_class_name[];
191
192			/***********************************************************************
193			* int dmessage_class_flags[]
194			*
195			* Flags indicating what to do with each message class. By default,
196			* the most recent message will be stored in the dmessage_last[] array
197			* (DMFrecord), but if other flags are set, the message will be sent
198			* other places as well. These flags are available to be altered by the
199			* controlling application, and will not be changed from their initial
200			* defaults (DMFrecord at minimum) by any of the dmessage routines.
201			* Beware: if the DMrecord flag is turned off for a given class and
202			* dmessage() fails to do anything, it will return zero and
203			* the DTEST() and DTESTF() macro calls may return zero even
204			* though their condition evaluated to non-zero. This problem is
205			* avoided by keeping DMrecord set for all classes.
206			*/
207			extern int dmessage_class_flags[];
208
209			/***********************************************************************
210			* int dmessage_class_done[]
211			*
212			* Flags indicating what was last done with each message class.
213			* In other words, the last result of dmessage() for each class.
214			*/
215			extern int dmessage_class_done[];
216
217			/***********************************************************************
218			* const char * dmessage_file[]
219			*
220			* Most recent file reported for each error class.
221			*/
222			extern const char * dmessage_file[];
223
224			/***********************************************************************
225			* int dmessage_line[]
226			*
227			* Most recent line number reported for each error class.
228			*/
229			extern int dmessage_line[];
230
231			/***********************************************************************
232			* const char * dmessage_record[]
233			*
234			* Most recent message for each class with the DMFrecord flag set,
235			* exactly as passed to dmessage(). If no message of
236			* a given class has been reported, then the corresponding
237			* dmessage_record pointer will be NULL.
238			*/
239			extern const char * dmessage_record[];
240
241			/***********************************************************************
242			* int dmessage_last_class
243			*
244			* The lowest class message reported so far, set to DMCnerr initially.
245			* The DMESG_LAST macro provides convenient access to most recent error.
246			*/
247			extern DMsgClass dmessage_last_class;
248
249			#define DMESG_LAST (dmessage_record[dmessage_last_class])
250
251			/***********************************************************************
252			* FILE * dmessage_logfp
253			*
254			* Pointer to open log file. Each message is preceeded by the file
255			* name, line number, and class for log file and stderr output. Data
256			* is flushed after each message. If this pointer is NULL (the default),
257			* then logging is disabled even for classes with the DMFlog flag set.
258			*/
259			extern FILE * dmessage_logfp;
260
261			/***********************************************************************
262			* int (dmessage_call)(DMsgClass cls, const char msg,
263			* const char *file, int line)
264			*
265			* Pointer to function called by dmessage() to share error handling.
266			* If assigned, this function is called with the same arguments passed
267			* to dmessage(), independent of the class flag settings. The returned
268			* value is then used as a mask on the class flags to turn off some or
269			* all of the default actions. The flagged actions are considered
270			* "done" and set accordingly in the dmessage_class_done global.
271			* Defaults to NULL.
272			*/
273			extern int (dmessage_call)(DMsgClass cls, const char msg,
274			const char *file, int line);
275
276			/***********************************************************************
277			* int (dmessage_alert)(const char msg)
278			*
279			* Pointer to function called by dmessage() to alert user.
280			* The function should return non-zero if the user was notified,
281			* or zero if the message could not be displayed for some reason.
282			* Defaults to NULL, which results in no DMFalert action.
283			*/
284			extern int (dmessage_alert)(const char msg);
285
286			/***********************************************************************
287			* void (*dmessage_exit)(int status)
288			*
289			* Pointer to function called by dmessage() for classes with the
290			* DMFexit flag set, which is usually reserved for the DMCmemory class.
291			* Defaults to system exit() function, but may be reassigned by the
292			* controlling application. Assigning a value of NULL causes dmessage()
293			* to return from these calls, which might result in a memory fault if
294			* your program does not check for NULL pointer values. In general,
295			* library authors should NOT assume the DMCmemory class calls exit().
296			*/
297			extern void (*dmessage_exit)(int status);
298
299			/***********************************************************************
300			* void (*dmessage_abort)()
301			*
302			* Pointer to function called by dmessage() for classes with the
303			* DMFabort flag set, which is usually reserved for the DMCassert class.
304			* Defaults to system abort() function, but may be reassigned by the
305			* controlling application. Assigning a value of NULL causes dmessage()
306			* to return from these calls, which will probably prove disasterous.
307			* A better idea if the program wants to continue is to use setjmp() and
308			* longjmp() to recover control at a lower point in the call tree. If
309			* assigned, this call should never return.
310			*/
311			extern void (*dmessage_abort)();
312
313			#ifdef __cplusplus
314			}
315			#endif
316
317			#endif /* ! _DMESSAGE_H_ */