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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 54 by jds, Tue Aug 2 11:20:09 2005 UTC revision 59 by jds, Sun Oct 30 01:38:20 2005 UTC
# Line 26  Line 26 
26   *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named   *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
27   *  COPYING.   *  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  /** @file
40   *  Ascend Panic - Fatal Error Handling.   *  Ascend Panic - fatal error handling.
41   *  <pre>   *  <pre>
42   *  To include this header file, you must include the following:   *  To include this header file, you must include the following:
43   *      #include <stdarg.h>   *      #include <stdarg.h>
44   *      #include "utilities/ascConfig.h"   *      #include "utilities/ascConfig.h"
  *      #include "compiler/compiler.h"  
  *      #include "compiler/ascPanic.h"  
45   *  </pre>   *  </pre>
46   */   */
47    
48  #ifndef _ASCPANIC_H  #ifndef _ascpanic_h_seen
49  #define _ASCPANIC_H  #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    
 /**  
  * <!--  Asc_Panic( status, function, format, args )                   -->  
  * <!--       int status;                                              -->  
  * <!--       CONST char *function                                     -->  
  * <!--       CONST char *format                                       -->  
  * <!--       VAR_ARGS args                                            -->  
  *  
  *  This function prints the arguments "args" using the format string  
  *  "format" to the ASCERR file handle.  The first line of the panic  
  *  message will print ``ASCEND PANIC!! in function'' if the argument  
  *  "function" is not NULL.  If ASCERR has not been initialized to a  
  *  valid file pointer, the message will not be printed.  Either way,  
  *  if an panic output file location has been specified with the  
  *  Asc_PanicSetOutfile() function, the panic message is also stored  
  *  there.  Under Windows, we also pop up a MessageBox containing the  
  *  message.  Finally, we exit the program with the status "status".<br><br>  
  *  
  *  Side Effects: Exits the program.  
  */  
66  extern void Asc_Panic(CONST int status, CONST char *function,  extern void Asc_Panic(CONST int status, CONST char *function,
67                        CONST char *format, ...);                        CONST char *format, ...);
68    /**<
69  /**   *  Prints a fatal error message, calls any registered callback
70   *  <!--  Asc_PanicSetOutfile(filename)                                -->   *  function, and (usually) exits the program.
71   *  <!--      CONST char *filename;                                    -->   *  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   *  Calling this function with a non-NULL "filename" will cause
101   *  Asc_Panic() to write panic messages to "filename" in addition to the   *  Asc_Panic() to write panic messages to "filename" in addition to the
102   *  ASCERR file handle.  Passing in a "filename" of NULL causes panic   *  ASCERR file handle.  Passing in a "filename" of NULL causes panic
103   *  messages not to be written to disk---this undoes the effect of   *  messages not to be written to disk---this undoes the effect of
104   *  previous calls to Asc_PanicSetOutfile()   *  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   */   */
 extern void Asc_PanicSetOutfile(CONST char *filename);  
143    
144  #endif  /* _ASCPANIC_H */  #endif  /* _ascpanic_h_seen */
145    

Legend:
Removed from v.54  
changed lines
  Added in v.59

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