Debug.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2018 The Squid Software Foundation and contributors
3  *
4  * Squid software is distributed under GPLv2+ license and includes
5  * contributions from numerous individuals and organizations.
6  * Please see the COPYING and CONTRIBUTORS files for details.
7  */
8 
9 /* DEBUG: section 00 Debug Routines */
10 
11 #ifndef SQUID_DEBUG_H
12 #define SQUID_DEBUG_H
13 
14 #include "base/Here.h"
15 // XXX should be mem/forward.h once it removes dependencies on typedefs.h
16 #include "mem/AllocatorProxy.h"
17 
18 #include <iostream>
19 #undef assert
20 #include <sstream>
21 #include <iomanip>
22 #if defined(assert)
23 #undef assert
24 #endif
25 
26 #if PURIFY
27 #define assert(EX) ((void)0)
28 #elif defined(NODEBUG)
29 #define assert(EX) ((void)0)
30 #elif STDC_HEADERS
31 #define assert(EX) ((EX)?((void)0):xassert( # EX , __FILE__, __LINE__))
32 #else
33 #define assert(EX) ((EX)?((void)0):xassert("EX", __FILE__, __LINE__))
34 #endif
35 
36 /* context-based debugging, the actual type is subject to change */
37 typedef int Ctx;
38 Ctx ctx_enter(const char *descr);
39 void ctx_exit(Ctx ctx);
40 
41 /* defined debug section limits */
42 #define MAX_DEBUG_SECTIONS 100
43 
44 /* defined names for Debug Levels */
45 #define DBG_CRITICAL 0
46 #define DBG_IMPORTANT 1
47 /* levels 2-8 are still being discussed amongst the developers */
48 #define DBG_DATA 9
50 #define DBG_PARSE_NOTE(x) (opt_parse_cfg_only?0:(x))
52 class Debug
53 {
54 
55 public:
57  class Context
58  {
59  public:
60  Context(const int aSectionLevel, const int aLevel);
61 
62  int level;
64 
65  private:
66  friend class Debug;
67  void rewind(const int aSection, const int aLevel);
68  void formatStream();
70  std::ostringstream buf;
71  bool forceAlert;
72  };
73 
75  static bool Enabled(const int section, const int level)
76  {
77  return level <= Debug::Levels[section];
78  }
79 
80  static char *debugOptions;
81  static char *cache_log;
82  static int rotateNumber;
84  static int override_X;
85  static int log_stderr;
86  static bool log_syslog;
87 
88  static void parseOptions(char const *);
89 
91  static int Level() { return Current ? Current->level : 1; }
93  static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
94 
96  static std::ostringstream &Start(const int section, const int level);
98  static void Finish();
99 
101  static void ForceAlert();
102 private:
103  static Context *Current;
104 };
105 
108 FILE *DebugStream();
110 #define debug_log DebugStream()
111 
113 void StopUsingDebugLog();
114 
116 void ResyncDebugLog(FILE *newDestination);
117 
118 /* Debug stream
119  *
120  * Unit tests can enable full debugging to stderr for one
121  * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
122  * section number before any header
123  */
124 #define debugs(SECTION, LEVEL, CONTENT) \
125  do { \
126  const int _dbg_level = (LEVEL); \
127  if (Debug::Enabled((SECTION), _dbg_level)) { \
128  std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
129  if (_dbg_level > DBG_IMPORTANT) { \
130  _dbo << (SECTION) << ',' << _dbg_level << "| " \
131  << Here() << ": "; \
132  } \
133  _dbo << CONTENT; \
134  Debug::Finish(); \
135  } \
136  } while (/*CONSTCOND*/ 0)
137 
141 std::ostream& ForceAlert(std::ostream& s);
142 
152 inline std::ostream&
153 HERE(std::ostream& s)
154 {
155  return s;
156 }
157 
158 /*
159  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
160  *
161  * debugs(1,1, MYNAME << "WARNING: some message");
162  */
163 #ifdef __PRETTY_FUNCTION__
164 #define MYNAME __PRETTY_FUNCTION__ << " "
165 #else
166 #define MYNAME __FUNCTION__ << " "
167 #endif
168 
169 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
170 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
171 {
172  return (os << (int)d);
173 }
174 
175 /* Legacy debug function definitions */
176 void _db_init(const char *logfile, const char *options);
177 void _db_set_syslog(const char *facility);
178 void _db_rotate_log(void);
179 
184 class Raw
185 {
186 public:
187  Raw(const char *label, const char *data, const size_t size):
188  level(-1), label_(label), data_(data), size_(size), useHex_(false) {}
189 
191  Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
192 
194  Raw &hex() { useHex_ = true; return *this; }
195 
202  std::ostream &print(std::ostream &os) const;
203 
207  int level;
208 
209 private:
210  void printHex(std::ostream &os) const;
211 
212  const char *label_;
213  const char *data_;
214  size_t size_;
215  bool useHex_;
216 };
217 
218 inline
219 std::ostream &operator <<(std::ostream &os, const Raw &raw)
220 {
221  return raw.print(os);
222 }
223 
225 template <class Pointer>
226 class RawPointerT {
227 public:
228  RawPointerT(const char *aLabel, const Pointer &aPtr):
229  label(aLabel), ptr(aPtr) {}
230  const char *label;
231  const Pointer &ptr;
232 };
233 
235 template <class Pointer>
237 RawPointer(const char *label, const Pointer &ptr)
238 {
239  return RawPointerT<Pointer>(label, ptr);
240 }
241 
243 template <class Pointer>
244 inline std::ostream &
245 operator <<(std::ostream &os, const RawPointerT<Pointer> &pd)
246 {
247  os << pd.label << '=';
248  if (pd.ptr)
249  return os << *pd.ptr;
250  else
251  return os << "[nil]";
252 }
253 
255 template <class Integer>
256 class AsHex
257 {
258 public:
259  explicit AsHex(const Integer n): raw(n) {}
260  Integer raw;
261 };
262 
263 template <class Integer>
264 inline std::ostream &
265 operator <<(std::ostream &os, const AsHex<Integer> number)
266 {
267  const auto oldFlags = os.flags();
268  os << std::hex << std::showbase << number.raw;
269  os.setf(oldFlags);
270  return os;
271 }
272 
274 template <class Integer>
275 inline AsHex<Integer> asHex(const Integer n) { return AsHex<Integer>(n); }
276 
277 #endif /* SQUID_DEBUG_H */
278 
static void parseOptions(char const *)
Definition: debug.cc:459
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:840
static int rotateNumber
Definition: Debug.h:82
std::ostream manipulator to print integers as hex numbers prefixed by 0x
Definition: Debug.h:256
Raw & hex()
print data using two hex digits per byte (decoder: xxd -r -p)
Definition: Debug.h:194
Integer raw
the integer to print
Definition: Debug.h:260
void _db_rotate_log(void)
Definition: debug.cc:502
static bool log_syslog
Definition: Debug.h:86
std::ostream & print(std::ostream &os) const
Definition: debug.cc:882
void _db_set_syslog(const char *facility)
Definition: stub_debug.cc:55
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:808
Raw(const char *label, const char *data, const size_t size)
Definition: Debug.h:187
AsHex(const Integer n)
Definition: Debug.h:259
void _db_init(const char *logfile, const char *options)
Definition: debug.cc:484
static int Level()
minimum level required by the current debugs() call
Definition: Debug.h:91
Definition: Debug.h:52
std::ostringstream buf
debugs() output sink
Definition: Debug.h:70
Ctx ctx_enter(const char *descr)
Definition: debug.cc:711
static int override_X
Definition: Debug.h:84
void const char HLPCB void * data
Definition: stub_helper.cc:16
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:88
int sectionLevel
maximum debugging level allowed during the call
Definition: Debug.h:63
meta-information for debugs() or a similar debugging call
Definition: Debug.h:57
bool useHex_
whether hex() has been called
Definition: Debug.h:215
static int log_stderr
Definition: Debug.h:85
static char * debugOptions
Definition: Debug.h:80
static Context * Current
deepest active context; nil outside debugs()
Definition: Debug.h:103
static char * cache_log
Definition: Debug.h:81
size_t size_
data length
Definition: Debug.h:214
Context * upper
previous or parent record in nested debugging calls
Definition: Debug.h:69
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Debug.h:170
AsHex< Integer > asHex(const Integer n)
a helper to ease AsHex object creation
Definition: Debug.h:275
debugs objects pointed by possibly nil pointers: label=object
Definition: Debug.h:226
std::ostream & HERE(std::ostream &s)
Definition: Debug.h:153
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:862
Raw & minLevel(const int aLevel)
limit data printing to at least the given debugging level
Definition: Debug.h:191
static FILE * logfile
void StopUsingDebugLog()
start logging to stderr (instead of cache.log, if any)
Definition: debug.cc:82
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:793
number
Definition: testStatHist.cc:16
void ctx_exit(Ctx ctx)
Definition: debug.cc:727
const char * label
Definition: Debug.h:230
void printHex(std::ostream &os) const
print data bytes using hex notation
Definition: debug.cc:870
const Pointer & ptr
the name or description of the being-debugged object
Definition: Debug.h:231
int level
Definition: Debug.h:207
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Debug.h:83
Definition: Debug.h:184
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Debug.h:75
static int SectionLevel()
maximum level currently allowed
Definition: Debug.h:93
FILE * DebugStream()
Definition: debug.cc:77
RawPointerT(const char *aLabel, const Pointer &aPtr)
Definition: Debug.h:228
int level
minimum debugging level required by the debugs() call
Definition: Debug.h:62
RawPointerT< Pointer > RawPointer(const char *label, const Pointer &ptr)
convenience wrapper for creating RawPointerT<> objects
Definition: Debug.h:237
const char * label_
optional data name or ID; triggers size printing
Definition: Debug.h:212
void Start(const Comm::ConnectionPointer &conn, IDCB *callback, void *cbdata)
Definition: Ident.cc:237
int size
Definition: ModDevPoll.cc:77
#define false
Definition: GnuRegex.c:233
int Ctx
Definition: Debug.h:37
#define MAX_DEBUG_SECTIONS
Definition: Debug.h:42
bool forceAlert
the current debugs() will be a syslog ALERT
Definition: Debug.h:71
const char * data_
raw data to be printed
Definition: Debug.h:213

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors