Stream.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2022 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_SRC_DEBUG_STREAM_H
12 #define SQUID_SRC_DEBUG_STREAM_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 /* defined debug section limits */
37 #define MAX_DEBUG_SECTIONS 100
38 
39 /* defined names for Debug Levels */
40 #define DBG_CRITICAL 0
41 #define DBG_IMPORTANT 1
42 /* levels 2-8 are still being discussed amongst the developers */
43 #define DBG_DATA 9
45 #define DBG_PARSE_NOTE(x) (opt_parse_cfg_only?0:(x))
47 class DebugMessageHeader;
48 
49 class Debug
50 {
51 
52 public:
54  class Context
55  {
56  public:
57  Context(const int aSectionLevel, const int aLevel);
58 
59  int section;
60  int level;
62 
63  private:
64  friend class Debug;
65  friend class DebugMessageHeader;
66 
67  void rewind(const int aSection, const int aLevel);
68  void formatStream();
70  std::ostringstream buf;
71  bool forceAlert;
72 
76  };
77 
79  static bool Enabled(const int section, const int level)
80  {
81  return level <= Debug::Levels[section];
82  }
83 
84  static char *debugOptions;
85  static char *cache_log;
86  static int rotateNumber;
88  static int override_X;
89  static bool log_syslog;
90 
91  // TODO: Convert all helpers to use debugs() and NameThisHelper() APIs.
95  static void NameThisHelper(const char *name);
96 
99  static void NameThisKid(int kidIdentifier);
100 
101  static void parseOptions(char const *);
102 
104  static int Level() { return Current ? Current->level : 1; }
106  static int SectionLevel() { return Current ? Current->sectionLevel : 1; }
107 
109  static std::ostringstream &Start(const int section, const int level);
111  static void Finish();
112 
114  static void ForceAlert();
115 
117  static std::ostream& Extra(std::ostream &os) { return os << "\n "; }
118 
120  static void ForgetSaved();
121 
125  static void PrepareToDie();
126 
128  static void LogWaitingForIdle();
129 
130  /* cache_log channel */
131 
135  static void BanCacheLogUse();
136 
140  static void UseCacheLog();
141 
144  static void StopCacheLogUse();
145 
146  /* stderr channel */
147 
152  static void EnsureDefaultStderrLevel(int maxDefault);
153 
156  static void ResetStderrLevel(int maxLevel);
157 
160  static void SettleStderr();
161 
164  static bool StderrEnabled();
165 
166  /* syslog channel */
167 
169  static void ConfigureSyslog(const char *facility);
170 
173  static void SettleSyslog();
174 
175 private:
176  static void LogMessage(const Context &);
177 
178  static Context *Current;
179 };
180 
183 FILE *DebugStream();
185 #define debug_log DebugStream()
186 
188 void ResyncDebugLog(FILE *newDestination);
189 
190 /* Debug stream
191  *
192  * Unit tests can enable full debugging to stderr for one
193  * debug section; to enable this, #define ENABLE_DEBUG_SECTION to the
194  * section number before any header
195  */
196 #define debugs(SECTION, LEVEL, CONTENT) \
197  do { \
198  const int _dbg_level = (LEVEL); \
199  if (Debug::Enabled((SECTION), _dbg_level)) { \
200  std::ostream &_dbo = Debug::Start((SECTION), _dbg_level); \
201  if (_dbg_level > DBG_IMPORTANT) { \
202  _dbo << (SECTION) << ',' << _dbg_level << "| " \
203  << Here() << ": "; \
204  } \
205  _dbo << CONTENT; \
206  Debug::Finish(); \
207  } \
208  } while (/*CONSTCOND*/ 0)
209 
213 std::ostream& ForceAlert(std::ostream& s);
214 
224 inline std::ostream&
225 HERE(std::ostream& s)
226 {
227  return s;
228 }
229 
230 /*
231  * MYNAME is for use at debug levels 0 and 1 where HERE is too messy.
232  *
233  * debugs(1,1, MYNAME << "WARNING: some message");
234  */
235 #ifdef __PRETTY_FUNCTION__
236 #define MYNAME __PRETTY_FUNCTION__ << " "
237 #else
238 #define MYNAME __FUNCTION__ << " "
239 #endif
240 
241 /* some uint8_t do not like streaming control-chars (values 0-31, 127+) */
242 inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
243 {
244  return (os << (int)d);
245 }
246 
247 /* Legacy debug function definitions */
248 void _db_rotate_log(void);
249 
250 #endif /* SQUID_SRC_DEBUG_STREAM_H */
251 
meta-information of a Finish()ed debugs() message
Definition: debug.cc:107
int section
debugs() section
Definition: debug.cc:113
int level
debugs() level
Definition: debug.cc:114
meta-information for debugs() or a similar debugging call
Definition: Stream.h:55
int section
the debug section of the debugs() call
Definition: Stream.h:59
bool waitingForIdle
Definition: Stream.h:75
Context * upper
previous or parent record in nested debugging calls
Definition: Stream.h:69
int sectionLevel
maximum debugging level allowed during the call
Definition: Stream.h:61
std::ostringstream buf
debugs() output sink
Definition: Stream.h:70
int level
minimum debugging level required by the debugs() call
Definition: Stream.h:60
bool forceAlert
the current debugs() will be a syslog ALERT
Definition: Stream.h:71
void formatStream()
configures default formatting for the debugging stream
Definition: debug.cc:1301
void rewind(const int aSection, const int aLevel)
Optimization: avoids new Context creation for every debugs().
Definition: debug.cc:1284
Context(const int aSectionLevel, const int aLevel)
Definition: debug.cc:1271
Definition: Stream.h:50
static void ResetStderrLevel(int maxLevel)
Definition: debug.cc:699
static bool StderrEnabled()
Definition: debug.cc:725
static bool log_syslog
Definition: Stream.h:89
static void parseOptions(char const *)
Definition: debug.cc:1090
static void PrepareToDie()
Definition: debug.cc:561
static void ForgetSaved()
silently erases saved early debugs() messages (if any)
Definition: debug.cc:552
static bool Enabled(const int section, const int level)
whether debugging the given section and the given level produces output
Definition: Stream.h:79
static Context * Current
deepest active context; nil outside debugs()
Definition: Stream.h:178
static void NameThisKid(int kidIdentifier)
Definition: debug.cc:405
static int SectionLevel()
maximum level currently allowed
Definition: Stream.h:106
static void LogMessage(const Context &)
broadcasts debugs() message to the logging channels
Definition: debug.cc:776
static int override_X
Definition: Stream.h:88
static void SettleSyslog()
Definition: debug.cc:1140
static int Levels[MAX_DEBUG_SECTIONS]
Definition: Stream.h:87
static void Finish()
logs output buffer created in Start() and closes debugging context
Definition: debug.cc:1351
static std::ostream & Extra(std::ostream &os)
prefixes each grouped debugs() line after the first one in the group
Definition: Stream.h:117
static void NameThisHelper(const char *name)
Definition: debug.cc:382
static char * debugOptions
Definition: Stream.h:84
static void UseCacheLog()
Definition: debug.cc:1120
static char * cache_log
Definition: Stream.h:85
static std::ostringstream & Start(const int section, const int level)
opens debugging context and returns output buffer
Definition: debug.cc:1327
static void BanCacheLogUse()
Definition: debug.cc:1113
static void ConfigureSyslog(const char *facility)
enables logging to syslog (using the specified facility, when not nil)
Definition: debug.cc:1078
static void StopCacheLogUse()
Definition: debug.cc:1127
static int Level()
minimum level required by the current debugs() call
Definition: Stream.h:104
static int rotateNumber
Definition: Stream.h:86
static void EnsureDefaultStderrLevel(int maxDefault)
Definition: debug.cc:691
static void SettleStderr()
Definition: debug.cc:705
static void LogWaitingForIdle()
Logs messages of Finish()ed debugs() calls that were queued earlier.
Definition: debug.cc:1312
static void ForceAlert()
configures the active debugging context to write syslog ALERT
Definition: debug.cc:1388
std::ostream & HERE(std::ostream &s)
Definition: Stream.h:225
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:513
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:1396
#define MAX_DEBUG_SECTIONS
Definition: Stream.h:37
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Stream.h:242
FILE * DebugStream()
Definition: debug.cc:353
void _db_rotate_log(void)
Definition: debug.cc:1155

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors