apt  0.9.14
error.h
1 // -*- mode: cpp; mode: fold -*-
2 // Description /*{{{*/
3 // $Id: error.h,v 1.8 2001/05/07 05:06:52 jgg Exp $
4 /* ######################################################################
5 
6  Global Erorr Class - Global error mechanism
7 
8  This class has a single global instance. When a function needs to
9  generate an error condition, such as a read error, it calls a member
10  in this class to add the error to a stack of errors.
11 
12  By using a stack the problem with a scheme like errno is removed and
13  it allows a very detailed account of what went wrong to be transmitted
14  to the UI for display. (Errno has problems because each function sets
15  errno to 0 if it didn't have an error thus eraseing erno in the process
16  of cleanup)
17 
18  Several predefined error generators are provided to handle common
19  things like errno. The general idea is that all methods return a bool.
20  If the bool is true then things are OK, if it is false then things
21  should start being undone and the stack should unwind under program
22  control.
23 
24  A Warning should not force the return of false. Things did not fail, but
25  they might have had unexpected problems. Errors are stored in a FIFO
26  so Pop will return the first item..
27 
28  I have some thoughts about extending this into a more general UI<->
29  Engine interface, ie allowing the Engine to say 'The disk is full' in
30  a dialog that says 'Panic' and 'Retry'.. The error generator functions
31  like errno, Warning and Error return false always so this is normal:
32  if (open(..))
33  return _error->Errno(..);
34 
35  This source is placed in the Public Domain, do with it what you will
36  It was originally written by Jason Gunthorpe.
37 
38  ##################################################################### */
39  /*}}}*/
40 #ifndef PKGLIB_ERROR_H
41 #define PKGLIB_ERROR_H
42 
43 #include <apt-pkg/macros.h>
44 
45 #include <iostream>
46 #include <list>
47 #include <string>
48 
49 #include <stdarg.h>
50 
51 class GlobalError /*{{{*/
52 {
53 public: /*{{{*/
55  enum MsgType {
58  FATAL = 40,
60  ERROR = 30,
62  WARNING = 20,
64  NOTICE = 10,
66  DEBUG = 0
67  };
68 
76  bool FatalE(const char *Function,const char *Description,...) __like_printf(3) __cold;
77 
85  bool Errno(const char *Function,const char *Description,...) __like_printf(3) __cold;
86 
97  bool WarningE(const char *Function,const char *Description,...) __like_printf(3) __cold;
98 
106  bool NoticeE(const char *Function,const char *Description,...) __like_printf(3) __cold;
107 
115  bool DebugE(const char *Function,const char *Description,...) __like_printf(3) __cold;
116 
123  bool InsertErrno(MsgType const &type, const char* Function,
124  const char* Description,...) __like_printf(4) __cold;
125 
141  bool InsertErrno(MsgType type, const char* Function,
142  const char* Description, va_list &args,
143  int const errsv, size_t &msgSize);
144 
158  bool Fatal(const char *Description,...) __like_printf(2) __cold;
159 
166  bool Error(const char *Description,...) __like_printf(2) __cold;
167 
177  bool Warning(const char *Description,...) __like_printf(2) __cold;
178 
190  bool Notice(const char *Description,...) __like_printf(2) __cold;
191 
198  bool Debug(const char *Description,...) __like_printf(2) __cold;
199 
205  bool Insert(MsgType const &type, const char* Description,...) __like_printf(3) __cold;
206 
220  bool Insert(MsgType type, const char* Description,
221  va_list &args, size_t &msgSize) __cold;
222 
227  inline bool PendingError() const {return PendingFlag;};
228 
239  bool empty(MsgType const &trashhold = WARNING) const;
240 
247  bool PopMessage(std::string &Text);
248 
250  void Discard();
251 
261  void DumpErrors(std::ostream &out, MsgType const &threshold = WARNING,
262  bool const &mergeStack = true);
263 
271  void inline DumpErrors(MsgType const &threshold) {
272  DumpErrors(std::cerr, threshold);
273  }
274 
275  // mvo: we do this instead of using a default parameter in the
276  // previous declaration to avoid a (subtle) API break for
277  // e.g. sigc++ and mem_fun0
283  void inline DumpErrors() {
285  }
286 
296  void PushToStack();
297 
299  void RevertToStack();
300 
302  void MergeWithStack();
303 
305  size_t StackCount() const {
306  return Stacks.size();
307  }
308 
309  GlobalError();
310  /*}}}*/
311 private: /*{{{*/
312  struct Item {
313  std::string Text;
314  MsgType Type;
315 
316  Item(char const *Text, MsgType const &Type) :
317  Text(Text), Type(Type) {};
318 
319  friend std::ostream& operator<< (std::ostream &out, Item i) {
320  switch(i.Type) {
321  case FATAL:
322  case ERROR: out << "E"; break;
323  case WARNING: out << "W"; break;
324  case NOTICE: out << "N"; break;
325  case DEBUG: out << "D"; break;
326  }
327  return out << ": " << i.Text;
328  }
329  };
330 
331  std::list<Item> Messages;
332  bool PendingFlag;
333 
334  struct MsgStack {
335  std::list<Item> const Messages;
336  bool const PendingFlag;
337 
338  MsgStack(std::list<Item> const &Messages, bool const &Pending) :
339  Messages(Messages), PendingFlag(Pending) {};
340  };
341 
342  std::list<MsgStack> Stacks;
343  /*}}}*/
344 };
345  /*}}}*/
346 
347 // The 'extra-ansi' syntax is used to help with collisions.
348 GlobalError *_GetErrorObj();
349 #define _error _GetErrorObj()
350 
351 #endif
void PushToStack()
put the current Messages into the stack
Definition: error.cc:245
bool Notice(const char *Description,...) __like_printf(2) __cold
add a notice message to the list
bool Error(const char *Description,...) __like_printf(2) __cold
add an Error message to the list
size_t StackCount() const
return the deep of the stack
Definition: error.h:305
An error does hinder the correct execution and should be corrected.
Definition: error.h:60
deprecation warnings, old fallback behavior, …
Definition: error.h:64
void DumpErrors()
dumps the messages of type WARNING or higher to std::cerr
Definition: error.h:283
void MergeWithStack()
merge current and stack together
Definition: error.cc:261
bool empty(MsgType const &trashhold=WARNING) const
is the list empty?
Definition: error.cc:229
bool InsertErrno(MsgType const &type, const char *Function, const char *Description,...) __like_printf(4) __cold
adds an errno message with the given type
Definition: error.cc:85
MsgType
a message can have one of following severity
Definition: error.h:55
bool NoticeE(const char *Function, const char *Description,...) __like_printf(3) __cold
add a notice message with errno to the list
bool Fatal(const char *Description,...) __like_printf(2) __cold
add an fatal error message to the list
void DumpErrors(MsgType const &threshold)
dumps the list of messages to std::cerr
Definition: error.h:271
Message will be printed instantly as it is likely that this error will lead to a complete crash...
Definition: error.h:58
bool WarningE(const char *Function, const char *Description,...) __like_printf(3) __cold
add a warning message with errno to the list
indicates problem that can lead to errors later on
Definition: error.h:62
bool DebugE(const char *Function, const char *Description,...) __like_printf(3) __cold
add a debug message with errno to the list
for developers only in areas it is hard to print something directly
Definition: error.h:66
Definition: error.h:51
bool Debug(const char *Description,...) __like_printf(2) __cold
add a debug message to the list
bool Errno(const char *Function, const char *Description,...) __like_printf(3) __cold
add an Error message with errno to the list
bool Warning(const char *Description,...) __like_printf(2) __cold
add a warning message to the list
bool FatalE(const char *Function, const char *Description,...) __like_printf(3) __cold
add a fatal error message with errno to the list
bool PopMessage(std::string &Text)
returns and removes the first (or last) message in the list
Definition: error.cc:185
void Discard()
clears the list of messages
Definition: error.cc:223
bool Insert(MsgType const &type, const char *Description,...) __like_printf(3) __cold
adds an error message with the given type
Definition: error.cc:143
void RevertToStack()
throw away all current messages
Definition: error.cc:252
bool PendingError() const
is an error in the list?
Definition: error.h:227