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

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

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