Back to index

lightning-sunbird  0.9+nobinonly
GUSIDiag.h
Go to the documentation of this file.
00001 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  
00002 // % Project  :      GUSI                        -      Grand Unified Socket Interface                    
00003 // % File            :      GUSIDiag.nw                 -      Assertions and diagnostics                    
00004 // % Author   :      Matthias Neeracher                                           
00005 // % Language :      C++                                                        
00006 // %                                                                       
00007 // % $Log: GUSIDiag.h,v $
00008 // % Revision 1.1  2001/03/11 22:35:00  sgehani%netscape.com
00009 // % First Checked In.
00010 // %                                                 
00011 // % Revision 1.12  2000/06/12 04:20:58  neeri                             
00012 // % Introduce GUSI_*printf                                                
00013 // %                                                                       
00014 // % Revision 1.11  2000/05/23 06:58:04  neeri                             
00015 // % Improve formatting                                                    
00016 // %                                                                       
00017 // % Revision 1.10  1999/08/26 05:45:01  neeri                             
00018 // % Fixes for literate edition of source code                             
00019 // %                                                                       
00020 // % Revision 1.9  1999/08/02 07:02:43  neeri                              
00021 // % Support for asynchronous errors and other socket options              
00022 // %                                                                       
00023 // % Revision 1.8  1999/05/29 06:26:42  neeri                              
00024 // % Fixed header guards                                                   
00025 // %                                                                       
00026 // % Revision 1.7  1999/04/10 04:45:47  neeri                              
00027 // % Add DCon stubs                                                        
00028 // %                                                                       
00029 // % Revision 1.6  1999/03/17 09:05:07  neeri                              
00030 // % Added GUSITimer, expanded docs                                        
00031 // %                                                                       
00032 // % Revision 1.5  1999/02/25 03:49:00  neeri                              
00033 // % Switched to DCon for logging                                          
00034 // %                                                                       
00035 // % Revision 1.4  1998/01/25 20:53:53  neeri                              
00036 // % Engine implemented, except for signals & scheduling                   
00037 // %                                                                       
00038 // % Revision 1.3  1996/12/16 02:17:20  neeri                              
00039 // % Tune messages                                                         
00040 // %                                                                       
00041 // % Revision 1.2  1996/11/24  12:52:07  neeri                             
00042 // % Added GUSIPipeSockets                                                 
00043 // %                                                                       
00044 // % Revision 1.1.1.1  1996/11/03  02:43:32  neeri                         
00045 // % Imported into CVS                                                     
00046 // %                                                                       
00047 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  
00048 //                                                                         
00049 // \chapter{Assertions and diagnostic messages}                            
00050 //                                                                         
00051 // GUSI reports on three kinds of error conditions:                        
00052 //                                                                         
00053 // \begin{itemize}                                                         
00054 // \item {\bf Internal} errors are usually caused by bugs in GUSI. They should be
00055 // considered fatal.                                                       
00056 // \item {\bf Client} errors are caused by calling GUSI routines with bad  
00057 // parameters. They are typically handled by returning an appropriate error
00058 // code.                                                                   
00059 // \item {\bf External} errors are caused by various OS and Network related
00060 // problems. Typically, they are also handled by returning an appropriate  
00061 // error code.                                                             
00062 // \end{itemize}                                                           
00063 //                                                                         
00064 // If you feel lucky, you can turn off the checking for internal and client errors,
00065 // but external errors will always be checked.                             
00066 //                                                                         
00067 // <GUSIDiag.h>=                                                           
00068 #ifndef _GUSIDiag_
00069 #define _GUSIDiag_
00070 
00071 #include <sys/cdefs.h>
00072 #include <stdarg.h>
00073 #include <string.h>
00074 
00075 #include <MacTypes.h>
00076 
00077 __BEGIN_DECLS
00078 // \section{Definition of diagnostics}                                     
00079 //                                                                         
00080 // Depending on the diagnostic level, messages get printed to the DCon console.
00081 //                                                                         
00082 // <Definition of diagnostic logfile>=                                     
00083 extern char * GUSI_diag_log;
00084 // Printing is done by passing an argument list to [[GUSI_log]]. To simplify the job
00085 // for the diagnostic macros, [[GUSI_log]] returns a [[bool]] value which is
00086 // always [[false]]. [[GUSI_break]] stops with a [[DebugStr]] call. [[GUSI_pos]] 
00087 // establishes the source code position for diagnostic messages.           
00088 // instead of logging.                                                     
00089 //                                                                         
00090 // <Definition of diagnostic logfile>=                                     
00091 bool GUSI_pos(const char * file, int line);
00092 bool GUSI_log(const char * format, ...);
00093 bool GUSI_break(const char * format, ...);
00094 // There are four levels of diagnostic handling:                           
00095 // \begin{itemize}                                                         
00096 // \item [[GUSI_DIAG_RECKLESS]] totally ignores all internal and client errors. This
00097 // setting is not recommended.                                             
00098 // \item [[GUSI_DIAG_RELAXED]] ignores internal errors, but checks client errors. This
00099 // setting is probably the best for production code.                       
00100 // \item [[GUSI_DIAG_CAUTIOUS]] checks and logs internal and client errors. This 
00101 // setting is best for GUSI client development.                            
00102 // \item [[GUSI_DIAG_PARANOID]] immediately stops at internal errors, checks and
00103 // logs client and external errors. This is the preferred setting for GUSI 
00104 // internal development.                                                   
00105 // \end{itemize}                                                           
00106 //                                                                         
00107 //                                                                         
00108 // <Definition of diagnostic levels>=                                      
00109 #define GUSI_DIAG_RECKLESS  0
00110 #define GUSI_DIAG_RELAXED   1
00111 #define GUSI_DIAG_CAUTIOUS  2
00112 #define GUSI_DIAG_PARANOID  3
00113 // [[GUSI_DIAG]] is defined to the diagnostic level. It can be overridden on a 
00114 // module by module basis, or by changing the default setting here.        
00115 // [[GUSI_MESSAGE_LEVEL]] determines how important a message has to be to print it.
00116 // [[GUSI_LOG_POS]] determines whether we want to log the code position.   
00117 //                                                                         
00118 // <Definition of diagnostic levels>=                                      
00119 #ifndef GUSI_DIAG
00120 #define GUSI_DIAG GUSI_DIAG_PARANOID
00121 #endif
00122 #ifndef GUSI_LOG_POS
00123 #define GUSI_LOG_POS 0
00124 #endif
00125 #ifndef GUSI_MESSAGE_LEVEL 
00126 #define GUSI_MESSAGE_LEVEL  3
00127 #endif
00128 // <Definition of diagnostics>=                                            
00129 #if GUSI_LOG_POS
00130 #define GUSI_POS     GUSI_pos(__FILE__, __LINE__)
00131 #define GUSI_LOG     GUSI_POS || GUSI_log
00132 #else
00133 #define GUSI_LOG     GUSI_log
00134 #endif
00135 #define GUSI_BREAK   GUSI_break
00136 // <Definition of diagnostics>=                                            
00137 #if GUSI_DIAG == GUSI_DIAG_RECKLESS
00138 // [[GUSI_DIAG_RECKLESS]] only checks for external errors.                 
00139 //                                                                         
00140 // <Diagnostics for [[GUSI_DIAG_RECKLESS]]>=                               
00141 #define GUSI_ASSERT_INTERNAL(COND, ARGLIST)             true
00142 #define GUSI_ASSERT_CLIENT(COND, ARGLIST)        true
00143 #define GUSI_ASSERT_EXTERNAL(COND, ARGLIST)             (COND)
00144 #define GUSI_SASSERT_INTERNAL(COND, MSG)         true
00145 #define GUSI_SASSERT_CLIENT(COND, MSG)                  true
00146 #define GUSI_SASSERT_EXTERNAL(COND, MSG)         (COND)
00147 #elif GUSI_DIAG == GUSI_DIAG_RELAXED
00148 // [[GUSI_DIAG_RELAXED]] ignores internal errors, but checks client errors.
00149 //                                                                         
00150 // <Diagnostics for [[GUSI_DIAG_RELAXED]]>=                                
00151 #define GUSI_ASSERT_INTERNAL(COND, ARGLIST)             true
00152 #define GUSI_ASSERT_CLIENT(COND, ARGLIST)        (COND)
00153 #define GUSI_ASSERT_EXTERNAL(COND, ARGLIST)             (COND)
00154 #define GUSI_SASSERT_INTERNAL(COND, MSG)         true
00155 #define GUSI_SASSERT_CLIENT(COND, MSG)                  (COND)
00156 #define GUSI_SASSERT_EXTERNAL(COND, MSG)         (COND)
00157 #elif GUSI_DIAG == GUSI_DIAG_CAUTIOUS
00158 // [[GUSI_DIAG_CAUTIOUS]] checks and logs internal and client errors.      
00159 //                                                                         
00160 // <Diagnostics for [[GUSI_DIAG_CAUTIOUS]]>=                               
00161 #define GUSI_ASSERT_INTERNAL(COND, ARGLIST)             ((COND) || GUSI_LOG ARGLIST)
00162 #define GUSI_ASSERT_CLIENT(COND, ARGLIST)        ((COND) || GUSI_LOG ARGLIST)
00163 #define GUSI_ASSERT_EXTERNAL(COND, ARGLIST)             (COND)
00164 #define GUSI_SASSERT_INTERNAL(COND, MSG)         ((COND) || GUSI_LOG ("%s", MSG))
00165 #define GUSI_SASSERT_CLIENT(COND, MSG)                  ((COND) || GUSI_LOG ("%s", MSG))
00166 #define GUSI_SASSERT_EXTERNAL(COND, MSG)         (COND)
00167 #elif GUSI_DIAG == GUSI_DIAG_PARANOID
00168 // [[GUSI_DIAG_PARANOID]] immediately stops at internal errors, checks and 
00169 // logs client and external errors.                                        
00170 //                                                                         
00171 // <Diagnostics for [[GUSI_DIAG_PARANOID]]>=                               
00172 #define GUSI_ASSERT_INTERNAL(COND, ARGLIST)             ((COND) || GUSI_BREAK ARGLIST)
00173 #define GUSI_ASSERT_CLIENT(COND, ARGLIST)        ((COND) || GUSI_LOG ARGLIST)
00174 #define GUSI_ASSERT_EXTERNAL(COND, ARGLIST)             ((COND) || GUSI_LOG ARGLIST)
00175 #define GUSI_SASSERT_INTERNAL(COND, MSG)         ((COND) || GUSI_BREAK ("%s", (MSG)))
00176 #define GUSI_SASSERT_CLIENT(COND, MSG)                  ((COND) || GUSI_LOG ("%s", MSG))
00177 #define GUSI_SASSERT_EXTERNAL(COND, MSG)         ((COND) || GUSI_LOG ("%s", MSG))
00178 #else
00179 #error "GUSI_DIAG defined to illegal value: " GUSI_DIAG
00180 #endif
00181 // There are 11 different diagnostic macros. [[GUSI_ASSERT_INTERNAL]],     
00182 // [[GUSI_ASSERT_CLIENT]] and [[GUSI_ASSERT_EXTERNAL]] check for internal, 
00183 // client, and external errors, respectively. Their first argument is a    
00184 // conditional expression which when [[false]] indicates that an error     
00185 // happened. [[GUSI_MESSAGE]] has the same logging status as               
00186 // [[GUSI_ASSERT_EXTERNAL]], but does not check any conditions. The [[SASSERT]]
00187 // and [[SMESSAGE]] variants do the same checking, but only take a simple  
00188 // message instead of an argument list. The [[CASSERT]] variants simply output
00189 // the condition as the message.                                           
00190 //                                                                         
00191 // <Definition of diagnostics>=                                            
00192 #define GUSI_CASSERT_INTERNAL(COND)       \
00193        GUSI_SASSERT_INTERNAL(COND, "(" #COND ") -- assertion failed.\n" )
00194 #define GUSI_CASSERT_CLIENT(COND)  \
00195        GUSI_SASSERT_CLIENT(COND,   "(" #COND ") -- assertion failed.\n" )
00196 #define GUSI_CASSERT_EXTERNAL(COND)       \
00197        GUSI_SASSERT_EXTERNAL(COND, "(" #COND ") -- assertion failed.\n" )
00198 #define GUSI_MESSAGE1(ARGLIST)            \
00199        GUSI_ASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>1, ARGLIST)
00200 #define GUSI_SMESSAGE1(MSG)               \
00201        GUSI_SASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>1, MSG)
00202 #define GUSI_MESSAGE2(ARGLIST)            \
00203        GUSI_ASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>2, ARGLIST)
00204 #define GUSI_SMESSAGE2(MSG)               \
00205        GUSI_SASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>2, MSG)
00206 #define GUSI_MESSAGE3(ARGLIST)            \
00207        GUSI_ASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>3, ARGLIST)
00208 #define GUSI_SMESSAGE3(MSG)               \
00209        GUSI_SASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>3, MSG)
00210 #define GUSI_MESSAGE4(ARGLIST)            \
00211        GUSI_ASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>4, ARGLIST)
00212 #define GUSI_SMESSAGE4(MSG)               \
00213        GUSI_SASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>4, MSG)
00214 #define GUSI_MESSAGE5(ARGLIST)            \
00215        GUSI_ASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>5, ARGLIST)
00216 #define GUSI_SMESSAGE5(MSG)               \
00217        GUSI_SASSERT_EXTERNAL(GUSI_MESSAGE_LEVEL>5, MSG)
00218 #define GUSI_MESSAGE(ARGLIST)      GUSI_MESSAGE3(ARGLIST)
00219 #define GUSI_SMESSAGE(MSG)         GUSI_SMESSAGE3(MSG)
00220 __END_DECLS
00221 
00222 #endif /* _GUSIDiag_ */