apt-pkg/contrib/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 <stddef.h>
  50 #include <stdarg.h>
  51
  52 class GlobalError                                                       /*{{{*/
  53 {
  54 public:                                                                 /*{{{*/
  55         /** \brief a message can have one of following severity */
  56         enum MsgType {
  57                 /** \brief Message will be printed instantly as it is likely that
  58                         this error will lead to a complete crash */
  59                 FATAL = 40,
  60                 /** \brief An error does hinder the correct execution and should be corrected */
  61                 ERROR = 30,
  62                 /** \brief indicates problem that can lead to errors later on */
  63                 WARNING = 20,
  64                 /** \brief deprecation warnings, old fallback behavior, … */
  65                 NOTICE = 10,
  66                 /** \brief for developers only in areas it is hard to print something directly */
  67                 DEBUG = 0
  68         };
  69
  70         /** \brief add a fatal error message with errno to the list
  71          *
  72          *  \param Function name of the function generating the error
  73          *  \param Description format string for the error message
  74          *
  75          *  \return \b false
  76          */
  77         bool FatalE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
  78
  79         /** \brief add an Error message with errno to the list
  80          *
  81          *  \param Function name of the function generating the error
  82          *  \param Description format string for the error message
  83          *
  84          *  \return \b false
  85          */
  86         bool Errno(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
  87
  88         /** \brief add a warning message with errno to the list
  89          *
  90          *  A warning should be considered less severe than an error and
  91          *  may be ignored by the client.
  92          *
  93          *  \param Function Name of the function generates the warning.
  94          *  \param Description Format string for the warning message.
  95          *
  96          *  \return \b false
  97          */
  98         bool WarningE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
  99
 100         /** \brief add a notice message with errno to the list
 101          *
 102          *  \param Function name of the function generating the error
 103          *  \param Description format string for the error message
 104          *
 105          *  \return \b false
 106          */
 107         bool NoticeE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
 108
 109         /** \brief add a debug message with errno to the list
 110          *
 111          *  \param Function name of the function generating the error
 112          *  \param Description format string for the error message
 113          *
 114          *  \return \b false
 115          */
 116         bool DebugE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
 117
 118         /** \brief adds an errno message with the given type
 119          *
 120          * \param type of the error message
 121          * \param Function which failed
 122          * \param Description of the error
 123          */
 124         bool InsertErrno(MsgType const &type, const char* Function,
 125                          const char* Description,...) APT_PRINTF(4) APT_COLD;
 126
 127         /** \brief adds an errno message with the given type
 128          *
 129          * args needs to be initialized with va_start and terminated
 130          * with va_end by the caller. msgSize is also an out-parameter
 131          * in case the msgSize was not enough to store the complete message.
 132          *
 133          * \param type of the error message
 134          * \param Function which failed
 135          * \param Description is the format string for args
 136          * \param args list from a printf-like function
 137          * \param errsv is the errno the error is for
 138          * \param msgSize is the size of the char[] used to store message
 139          * \return true if the message was added, false if not - the caller
 140          * should call this method again in that case
 141          */
 142         bool InsertErrno(MsgType type, const char* Function,
 143                          const char* Description, va_list &args,
 144                          int const errsv, size_t &msgSize) APT_COLD;
 145
 146         /** \brief add an fatal error message to the list
 147          *
 148          *  Most of the stuff we consider as "error" is also "fatal" for
 149          *  the user as the application will not have the expected result,
 150          *  but a fatal message here means that it gets printed directly
 151          *  to stderr in addiction to adding it to the list as the error
 152          *  leads sometimes to crashes and a maybe duplicated message
 153          *  is better than "Segfault" as the only displayed text
 154          *
 155          *  \param Description Format string for the fatal error message.
 156          *
 157          *  \return \b false
 158          */
 159         bool Fatal(const char *Description,...) APT_PRINTF(2) APT_COLD;
 160
 161         /** \brief add an Error message to the list
 162          *
 163          *  \param Description Format string for the error message.
 164          *
 165          *  \return \b false
 166          */
 167         bool Error(const char *Description,...) APT_PRINTF(2) APT_COLD;
 168
 169         /** \brief add a warning message to the list
 170          *
 171          *  A warning should be considered less severe than an error and
 172          *  may be ignored by the client.
 173          *
 174          *  \param Description Format string for the message
 175          *
 176          *  \return \b false
 177          */
 178         bool Warning(const char *Description,...) APT_PRINTF(2) APT_COLD;
 179
 180         /** \brief add a notice message to the list
 181          *
 182          *  A notice should be considered less severe than an error or a
 183          *  warning and can be ignored by the client without further problems
 184          *  for some times, but he should consider fixing the problem.
 185          *  This error type can be used for e.g. deprecation warnings of options.
 186          *
 187          *  \param Description Format string for the message
 188          *
 189          *  \return \b false
 190          */
 191         bool Notice(const char *Description,...) APT_PRINTF(2) APT_COLD;
 192
 193         /** \brief add a debug message to the list
 194          *
 195          *  \param Description Format string for the message
 196          *
 197          *  \return \b false
 198          */
 199         bool Debug(const char *Description,...) APT_PRINTF(2) APT_COLD;
 200
 201         /** \brief adds an error message with the given type
 202          *
 203          * \param type of the error message
 204          * \param Description of the error
 205          */
 206         bool Insert(MsgType const &type, const char* Description,...) APT_PRINTF(3) APT_COLD;
 207
 208         /** \brief adds an error message with the given type
 209          *
 210          * args needs to be initialized with va_start and terminated
 211          * with va_end by the caller. msgSize is also an out-parameter
 212          * in case the msgSize was not enough to store the complete message.
 213          *
 214          * \param type of the error message
 215          * \param Description is the format string for args
 216          * \param args list from a printf-like function
 217          * \param msgSize is the size of the char[] used to store message
 218          * \return true if the message was added, false if not - the caller
 219          * should call this method again in that case
 220          */
 221         bool Insert(MsgType type, const char* Description,
 222                          va_list &args, size_t &msgSize) APT_COLD;
 223
 224         /** \brief is an error in the list?
 225          *
 226          *  \return \b true if an error is included in the list, \b false otherwise
 227          */
 228         inline bool PendingError() const APT_PURE {return PendingFlag;};
 229
 230         /** \brief is the list empty?
 231          *
 232          *  The default checks if the list is empty or contains only notices,
 233          *  if you want to check if also no notices happened set the parameter
 234          *  flag to \b false.
 235          *
 236          *  \param threshold minimim level considered
 237          *
 238          *  \return \b true if an the list is empty, \b false otherwise
 239          */
 240         bool empty(MsgType const &threshold = WARNING) const APT_PURE;
 241
 242         /** \brief returns and removes the first (or last) message in the list
 243          *
 244          *  \param[out] Text message of the first/last item
 245          *
 246          *  \return \b true if the message was an error, \b false otherwise
 247          */
 248         bool PopMessage(std::string &Text);
 249
 250         /** \brief clears the list of messages */
 251         void Discard();
 252
 253         /** \brief outputs the list of messages to the given stream
 254          *
 255          *  Note that all messages are discarded, also the notices
 256          *  displayed or not.
 257          *
 258          *  \param[out] out output stream to write the messages in
 259          *  \param threshold minimim level considered
 260          *  \param mergeStack
 261          */
 262         void DumpErrors(std::ostream &out, MsgType const &threshold = WARNING,
 263                         bool const &mergeStack = true);
 264
 265         /** \brief dumps the list of messages to std::cerr
 266          *
 267          *  Note that all messages are discarded, also the notices
 268          *  displayed or not.
 269          *
 270          *  \param threshold minimum level printed
 271          */
 272         void inline DumpErrors(MsgType const &threshold) {
 273                 DumpErrors(std::cerr, threshold);
 274         }
 275
 276         // mvo: we do this instead of using a default parameter in the
 277         //      previous declaration to avoid a (subtle) API break for
 278         //      e.g. sigc++ and mem_fun0
 279         /** \brief dumps the messages of type WARNING or higher to std::cerr
 280          *
 281          *  Note that all messages are discarded, displayed or not.
 282          *
 283          */
 284         void inline DumpErrors() {
 285                 DumpErrors(WARNING);
 286         }
 287
 288         /** \brief put the current Messages into the stack
 289          *
 290          *  All "old" messages will be pushed into a stack to
 291          *  them later back, but for now the Message query will be
 292          *  empty and performs as no messages were present before.
 293          *
 294          * The stack can be as deep as you want - all stack operations
 295          * will only operate on the last element in the stack.
 296          */
 297         void PushToStack();
 298
 299         /** \brief throw away all current messages */
 300         void RevertToStack();
 301
 302         /** \brief merge current and stack together */
 303         void MergeWithStack();
 304
 305         /** \brief return the deep of the stack */
 306         size_t StackCount() const APT_PURE {
 307                 return Stacks.size();
 308         }
 309
 310         GlobalError();
 311                                                                         /*}}}*/
 312 private:                                                                /*{{{*/
 313         struct Item {
 314                 std::string Text;
 315                 MsgType Type;
 316
 317                 Item(char const *Text, MsgType const &Type) :
 318                         Text(Text), Type(Type) {};
 319
 320                 friend std::ostream& operator<< (std::ostream &out, Item i) {
 321                         switch(i.Type) {
 322                         case FATAL:
 323                         case ERROR: out << "E"; break;
 324                         case WARNING: out << "W"; break;
 325                         case NOTICE: out << "N"; break;
 326                         case DEBUG: out << "D"; break;
 327                         }
 328                         return out << ": " << i.Text;
 329                 }
 330         };
 331
 332         std::list<Item> Messages;
 333         bool PendingFlag;
 334
 335         struct MsgStack {
 336                 std::list<Item> Messages;
 337                 bool const PendingFlag;
 338
 339                 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
 340                          Messages(Messages), PendingFlag(Pending) {};
 341         };
 342
 343         std::list<MsgStack> Stacks;
 344                                                                         /*}}}*/
 345 };
 346                                                                         /*}}}*/
 347
 348 // The 'extra-ansi' syntax is used to help with collisions.
 349 GlobalError *_GetErrorObj();
 350 #define _error _GetErrorObj()
 351
 352 #endif