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))
48
49class Debug
50{
51
52public:
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;
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
175private:
176 static void LogMessage(const Context &);
177
178 static Context *Current;
179};
180
183FILE *DebugStream();
185#define debug_log DebugStream()
186
188void 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
213std::ostream& ForceAlert(std::ostream& s);
214
224inline std::ostream&
225HERE(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+) */
242inline std::ostream& operator <<(std::ostream &os, const uint8_t d)
243{
244 return (os << (int)d);
245}
246
247/* Legacy debug function definitions */
248void _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 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 std::ostream & Extra(std::ostream &os)
prefixes each grouped debugs() line after the first one in the group
Definition: Stream.h:117
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
FILE * DebugStream()
Definition: debug.cc:353
void ResyncDebugLog(FILE *newDestination)
a hack for low-level file descriptor manipulations in ipcCreate()
Definition: debug.cc:513
std::ostream & HERE(std::ostream &s)
Definition: Stream.h:225
#define MAX_DEBUG_SECTIONS
Definition: Stream.h:37
void _db_rotate_log(void)
Definition: debug.cc:1155
std::ostream & operator<<(std::ostream &os, const uint8_t d)
Definition: Stream.h:242
std::ostream & ForceAlert(std::ostream &s)
Definition: debug.cc:1396

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors