apt: apt-pkg/contrib/error.h Source File

apt 2.3.15 commandline package manager

error.h
1// -*- mode: cpp; mode: fold -*-
2// Description /*{{{*/
3/* ######################################################################
4
5 Global Error Class - Global error mechanism
6
7 This class has a single global instance. When a function needs to
8 generate an error condition, such as a read error, it calls a member
9 in this class to add the error to a stack of errors.
10
11 By using a stack the problem with a scheme like errno is removed and
12 it allows a very detailed account of what went wrong to be transmitted
13 to the UI for display. (Errno has problems because each function sets
14 errno to 0 if it didn't have an error thus eraseing erno in the process
15 of cleanup)
16
17 Several predefined error generators are provided to handle common
18 things like errno. The general idea is that all methods return a bool.
19 If the bool is true then things are OK, if it is false then things
20 should start being undone and the stack should unwind under program
21 control.
22
23 A Warning should not force the return of false. Things did not fail, but
24 they might have had unexpected problems. Errors are stored in a FIFO
25 so Pop will return the first item..
26
27 I have some thoughts about extending this into a more general UI<->
28 Engine interface, ie allowing the Engine to say 'The disk is full' in
29 a dialog that says 'Panic' and 'Retry'.. The error generator functions
30 like errno, Warning and Error return false always so this is normal:
31 if (open(..))
32 return _error->Errno(..);
33
34 This source is placed in the Public Domain, do with it what you will
35 It was originally written by Jason Gunthorpe.
36
37 ##################################################################### */
38 /*}}}*/
39#ifndef PKGLIB_ERROR_H
40#define PKGLIB_ERROR_H
41
42#include <apt-pkg/macros.h>
43
44#include <iostream>
45#include <list>
46#include <string>
47
48#include <stdarg.h>
49#include <stddef.h>
50
51 class APT_PUBLIC GlobalError /*{{{*/
52{
53public: /*{{{*/
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,...) APT_PRINTF(3) APT_COLD;
77
85 bool Errno(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
86
97 bool WarningE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
98
106 bool NoticeE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
107
115 bool DebugE(const char *Function,const char *Description,...) APT_PRINTF(3) APT_COLD;
116
123 bool InsertErrno(MsgType const &type, const char* Function,
124 const char* Description,...) APT_PRINTF(4) APT_COLD;
125
141 bool InsertErrno(MsgType type, const char* Function,
142 const char* Description, va_list &args,
143 int const errsv, size_t &msgSize) APT_COLD;
144
158 bool Fatal(const char *Description,...) APT_PRINTF(2) APT_COLD;
159
166 bool Error(const char *Description,...) APT_PRINTF(2) APT_COLD;
167
177 bool Warning(const char *Description,...) APT_PRINTF(2) APT_COLD;
178
190 bool Notice(const char *Description,...) APT_PRINTF(2) APT_COLD;
191
198 bool Debug(const char *Description,...) APT_PRINTF(2) APT_COLD;
199
205 bool Insert(MsgType const &type, const char* Description,...) APT_PRINTF(3) APT_COLD;
206
220 bool Insert(MsgType type, const char* Description,
221 va_list &args, size_t &msgSize) APT_COLD;
222
227 inline bool PendingError() const APT_PURE {return PendingFlag;};
228
239 bool empty(MsgType const &threshold = WARNING) const APT_PURE;
240
247 bool PopMessage(std::string &Text);
248
250 void Discard();
251
260 void DumpErrors(std::ostream &out, MsgType const &threshold = WARNING,
261 bool const &mergeStack = true);
262
270 void inline DumpErrors(MsgType const &threshold) {
271 DumpErrors(std::cerr, threshold);
272 }
273
274 // mvo: we do this instead of using a default parameter in the
275 // previous declaration to avoid a (subtle) API break for
276 // e.g. sigc++ and mem_fun0
282 void inline DumpErrors() {
283 DumpErrors(WARNING);
284 }
285
295 void PushToStack();
296
298 void RevertToStack();
299
301 void MergeWithStack();
302
304 size_t StackCount() const APT_PURE {
305 return Stacks.size();
306 }
307
308 GlobalError();
309 /*}}}*/
310private: /*{{{*/
311 struct Item {
312 std::string Text;
313 MsgType Type;
314
315 Item(char const *Text, MsgType const &Type) :
316 Text(Text), Type(Type) {};
317
318 APT_HIDDEN friend std::ostream &operator<<(std::ostream &out, Item i);
319 };
320
321 APT_HIDDEN friend std::ostream &operator<<(std::ostream &out, Item i);
322
323 std::list<Item> Messages;
324 bool PendingFlag;
325
326 struct MsgStack {
327 std::list<Item> Messages;
328 bool const PendingFlag;
329
330 MsgStack(std::list<Item> const &Messages, bool const &Pending) :
331 Messages(Messages), PendingFlag(Pending) {};
332 };
333
334 std::list<MsgStack> Stacks;
335 /*}}}*/
336};
337 /*}}}*/
338
339// The 'extra-ansi' syntax is used to help with collisions.
340APT_PUBLIC GlobalError *_GetErrorObj();
341static struct {
342 inline GlobalError* operator ->() { return _GetErrorObj(); }
343} _error APT_UNUSED;
344
345#endif
GlobalError
Definition: error.h:52
GlobalError::MsgType
MsgType
a message can have one of following severity
Definition: error.h:55
GlobalError::StackCount
size_t StackCount() const APT_PURE
return the deep of the stack
Definition: error.h:304
GlobalError::DumpErrors
void DumpErrors()
dumps the messages of type WARNING or higher to std::cerr
Definition: error.h:282
GlobalError::DumpErrors
void DumpErrors(MsgType const &threshold)
dumps the list of messages to std::cerr
Definition: error.h:270
GlobalError::FatalE
bool FatalE(const char *Function, const char *Description,...) APT_PRINTF(3) APT_COLD
add a fatal error message with errno to the list