Merge branch 'release-2.140.101'
[feisty_meow.git] / nucleus / library / loggers / critical_events.h
1 #ifndef CRITICAL_EVENTS_GROUP
2 #define CRITICAL_EVENTS_GROUP
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : critical_events                                                   *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1989-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include <basis/astring.h>
19
20 namespace loggers {
21
22 //! This macro wraps the notion of stopping in the debugger.
23 #ifndef _MSC_VER
24   #define CAUSE_BREAKPOINT
25 //hmmm: need a unix equivalent for this.  supporting gcc might be enough.
26 #else
27   #ifdef __MINGW32__
28     extern "C" {
29 //      #include <ddk/winddi.h>
30 //for debugbreak.  does this cause other problems?
31     }
32     #define CAUSE_BREAKPOINT 
33 //    #define CAUSE_BREAKPOINT __debugbreak()
34   #else
35     #define CAUSE_BREAKPOINT __debugbreak()
36   #endif
37 #endif
38
39 //! Tests the value "check" to ensure that it's not zero.
40 /*! This can be used instead of an ASSERT macro to check conditions in
41 builds with ERRORS_ARE_FATAL turned on.  This macro is orthogonal to the
42 build being built with debugging or release features. */
43 #ifdef ERRORS_ARE_FATAL
44   #define REQUIRE(check) if (!check) CAUSE_BREAKPOINT;
45 #else
46   #define REQUIRE(check)
47 #endif
48
49 // now more dangerous or potent guards...
50
51 //! an extra piece of information used, if available, in bounds_halt below.
52 //#define BH_ERROR_ADDITION ((basis::astring(" in ") + _global_argv[0]).s())
53
54 //! Verifies that "value" is between "low" and "high", inclusive.
55 /*! "Value" must be an object for which greater than and less than are defined.
56 The static_class_name() method and func definition are used to tag the
57 complaint that is emitted when problems are detected.  Note that if
58 CATCH_ERRORS is defined, then the program is _halted_ if the value is out
59 of bounds.  Otherwise, the "to_return" value is returned. */
60 //#ifdef CATCH_ERRORS
61 //  #define bounds_halt(value, low, high, to_return) { 
62 //    if (((value) < (low)) || ((value) > (high))) { 
63 //      critical_events::implement_bounds_halt(static_class_name(), func, #value, #low, 
64 //          #high, BH_ERROR_ADDITION); 
65 //      return to_return; 
66 //    } 
67 //  }
68 //#else
69 //  #define bounds_halt(a, b, c, d) bounds_return(a, b, c, d)
70 //#endif
71
72 //////////////
73
74 //! Provide some macros that will automatically add the file and line number.
75 /*! These use the functions below to report different types of error
76 situations and in some cases, exit the program. */
77 #define non_continuable_error(c, f, i) \
78   critical_events::FL_non_continuable_error(__FILE__, __LINE__, c, f, i, \
79       "A Non-Continuable Runtime Problem Has Occurred")
80 #define continuable_error(c, f, i) \
81   critical_events::FL_continuable_error(__FILE__, __LINE__, c, f, i, \
82       "Runtime Problem Information")
83 #define console_error(c, f, i) \
84   critical_events::FL_console_error(__FILE__, __LINE__, c, f, i)
85 #define deadly_error(c, f, i) \
86   critical_events::FL_deadly_error(__FILE__, __LINE__, c, f, i)
87 #define out_of_memory_now(c, f) \
88   critical_events::FL_out_of_memory_now(__FILE__, __LINE__, c, f)
89
90 //////////////
91
92 //! Provides a means of logging events for runtime problems.
93
94 class critical_events : public virtual basis::root_object
95 {
96 public:
97   virtual ~critical_events() {}
98
99   // super handy system inter-operation functions...
100
101   static basis::un_int system_error();
102     //!< gets the most recent system error reported on this thread.
103
104   static basis::astring system_error_text(basis::un_int error_to_show);
105     //!< returns the OS's string form of the "error_to_show".
106     /*!< this often comes from the value reported by system_error(). */
107
108   // some noisemaking methods...
109
110   //! Prints out a message to the standard error file stream.
111   static void write_to_console(const char *message);
112
113   //! shows the message in "info", with an optional "title" on the message.
114   /*! the message is sent to the program wide logger, if one is expected to
115   exist in this program. */
116   static void alert_message(const char *info, const char *title = "Alert Message");
117   static void alert_message(const basis::astring &info);  // uses default title.
118   static void alert_message(const basis::astring &info, const basis::astring &title);  // use "title".
119
120   static void write_to_critical_events(const char *message);
121     //!< sends the "message" to the critical events log file.
122     /*!< Prints out a message to the specially named file that captures all
123     serious events written to error logging functions.  If you use the
124     functions in this file, you are likely already writing to this log. */
125
126   static void set_critical_events_directory(const basis::astring &directory);
127     //!< sets the internal location where the critical events will be logged.
128     /*!< this is postponed to a higher level, although the default
129     will work too. */
130
131   static basis::astring critical_events_directory();
132     //!< returns the current location where critical events are written.
133
134   // this section implements the error macros.
135
136   //! Prints out an error message and then exits the program.
137   /*! The parameters describe the location where the error was detected.  This
138   call should only be used in test programs or where absolutely necessary
139   because it causes an almost immediate exit from the program!  deadly_error
140   should be reserved for when the program absolutely has to exit right then,
141   because this function will actually enforce a crash / abort / break into
142   debugger action rather than just calling exit(). */
143   static void FL_deadly_error(const char *file, int line, const char *classname,
144       const char *function_name, const char *info);
145   //! A version that takes strings instead of char pointers.
146   static void FL_deadly_error(const basis::astring &file, int line,
147       const basis::astring &classname, const basis::astring &function_name,
148       const basis::astring &info);
149
150   //! Describes an error like deadly_error, but does not exit the program.
151   static void FL_continuable_error(const char *file, int line,
152       const char *classname, const char *function_name, const char *info,
153       const char *title);
154
155   //! A version using astring instead of char pointers.
156   static void FL_continuable_error(const basis::astring &file, int line,
157       const basis::astring &classname, const basis::astring &function_name,
158       const basis::astring &info, const basis::astring &title);
159
160   //! Shows the same information as continuable_error, but causes an exit.
161   /*! This is a friendlier program exit than deadly_error.  This version can
162   be used when the program must stop, possibly because of a precondition failure
163   or a problem in input data or basically whatever.  it is not intended to
164   abort or break into the debugger, but to simply exit(). */
165   static void FL_non_continuable_error(const char *file, int line,
166       const char *classname, const char *function_name, const char *info,
167       const char *title);
168
169   //! A version using astring instead of char pointers.
170   static void FL_non_continuable_error(const basis::astring &file, int line,
171       const basis::astring &classname, const basis::astring &function_name,
172       const basis::astring &info, const basis::astring &title);
173
174   //! Causes the program to exit due to a memory allocation failure.
175   static void FL_out_of_memory_now(const char *file, int line,
176       const char *classname, const char *function_name);
177   
178   //! Prints out an error message to the standard error file stream.
179   static void FL_console_error(const char *file, int line, const char *error_class,
180       const char *error_function, const char *info);
181
182   //! Used to build our particular type of error message.
183   /*! It writes an error message into "guards_message_space" using our stylized
184   object::method formatting. */
185   static void make_error_message(const char *file, int line,
186       const char *error_class, const char *error_function,
187       const char *info, char *guards_message_space);
188
189   //! Provides the real implementation of bounds_halt to save code space.
190   static void implement_bounds_halt(const char *the_class_name, const char *func,
191       const char *value, const char *low, const char *high,
192       const char *error_addition);
193
194 private:
195   static basis::astring &hidden_critical_events_dir();
196
197   static void FL_continuable_error_real(const char *file, int line,
198       const char *error_class, const char *error_function, const char *info,
199       const char *title);
200 };
201
202 } //namespace.
203
204 #endif
205